# Migrasi ke huggingface_hub v1.0

Rilis v1.0 merupakan tonggak penting bagi pustaka `huggingface_hub`. Rilis ini menandai komitmen kami terhadap stabilitas API dan kematangan pustaka. Kami telah melakukan beberapa peningkatan dan perubahan yang bersifat merusak (breaking changes) untuk membuat pustaka ini lebih tangguh dan lebih mudah digunakan.

Panduan ini ditujukan untuk membantu Anda memigrasikan kode yang sudah ada ke versi baru. Jika Anda memiliki pertanyaan atau umpan balik, silakan beri tahu kami dengan [membuka masalah di GitHub](https://github.com/huggingface/huggingface_hub/issues).

## Python 3.9+

`huggingface_hub` sekarang membutuhkan Python 3.9 atau lebih tinggi. Python 3.8 tidak lagi didukung.

## Migrasi HTTPX

Perpustakaan `huggingface_hub` sekarang menggunakan [`httpx`](https://www.python-httpx.org/) alih-alih `requests` untuk permintaan HTTP. Perubahan ini dilakukan untuk meningkatkan kinerja dan mendukung permintaan sinkron dan asinkron dengan cara yang sama. Oleh karena itu, kami menghapus dependensi `requests` dan `aiohttp`.

### Perubahan yang merusak

Ini adalah perubahan besar yang memengaruhi seluruh pustaka. Meskipun kami telah berusaha membuat perubahan ini se-transparan mungkin, Anda mungkin perlu memperbarui kode Anda dalam beberapa kasus. Berikut adalah daftar perubahan yang merusak (breaking changes) yang diperkenalkan dalam proses tersebut:

- **Konfigurasi proxy**: proxy "per metode" tidak lagi didukung. Proxy harus dikonfigurasi secara global menggunakan variabel lingkungan `HTTP_PROXY` dan `HTTPS_PROXY`.
- **Backend HTTP kustom**: Fungsi `configure_http_backend` telah dihapus. Anda sekarang harus menggunakan [set_client_factory()](/docs/huggingface_hub/v2.4.0/id/package_reference/utilities#huggingface_hub.set_client_factory) dan [set_async_client_factory()](/docs/huggingface_hub/v2.4.0/id/package_reference/utilities#huggingface_hub.set_async_client_factory) untuk mengonfigurasi klien HTTP.
- **Penanganan error**: error HTTP tidak lagi diwarisi dari `requests.HTTPError`, melainkan dari `httpx.HTTPError`. Kami merekomendasikan untuk menangkap [HfHubHTTPError](/docs/huggingface_hub/v2.4.0/id/package_reference/utilities#huggingface_hub.errors.HfHubHTTPError) (diimpor dengan `from huggingface_hub.utils import HfHubHTTPError`), yang merupakan subkelas dari `requests.HTTPError` di v0.x dan dari `httpx.HTTPError` di v1.x. Menangkap dari error `huggingface_hub` memastikan kode Anda kompatibel dengan versi lama dan baru dari pustaka ini.
- **SSLError**: `httpx` tidak memiliki konsep `SSLError`. Sekarang ini adalah `httpx.ConnectError` generik.
- **`LocalEntryNotFoundError`**: Kesalahan ini tidak lagi mewarisi dari `HTTPError`. Kami kini mendefinisikan `EntryNotFoundError` (baru) yang diwarisi oleh kedua `LocalEntryNotFoundError` (jika file tidak ditemukan di cache lokal) dan `RemoteEntryNotFoundError` (jika file tidak ditemukan di repo di Hub). Hanya kesalahan remote yang mewarisi dari `HTTPError`.
- **`InferenceClient`**: `InferenceClient` kini dapat digunakan sebagai context manager. Hal ini sangat berguna saat streaming token dari model bahasa untuk memastikan koneksi ditutup dengan benar.
- **`AsyncInferenceClient`**: Parameter `trust_env` telah dihapus dari konstruktor `AsyncInferenceClient`. Variabel lingkungan dipercaya secara default oleh `httpx`. Jika Anda secara eksplisit tidak ingin mempercayai lingkungan, Anda harus mengonfigurasinya dengan [set_async_client_factory()](/docs/huggingface_hub/v2.4.0/id/package_reference/utilities#huggingface_hub.set_async_client_factory).

Untuk detail lebih lanjut, Anda dapat memeriksa [PR #3328](https://github.com/huggingface/huggingface_hub/pull/3328) yang memperkenalkan `httpx`.

### Mengapa `httpx`?

Migrasi dari `requests` ke `httpx` membawa beberapa peningkatan utama yang meningkatkan kinerja, keandalan, dan kemudahan pemeliharaan pustaka:

**Keamanan Thread dan Pemanfaatan Ulang Koneksi**: `httpx` dirancang aman untuk thread, sehingga memungkinkan kita untuk memanfaatkan ulang klien yang sama secara aman di antara beberapa thread. Pemanfaatan ulang koneksi ini mengurangi overhead dari pembentukan koneksi baru untuk setiap permintaan HTTP, sehingga meningkatkan kinerja terutama saat melakukan permintaan yang sering ke Hub.

**Dukungan HTTP/2**: `httpx` menyediakan dukungan HTTP/2 secara native, yang menawarkan efisiensi lebih baik saat melakukan beberapa permintaan ke server yang sama (tepat sesuai kasus penggunaan kami). Hal ini berujung pada latensi yang lebih rendah dan konsumsi sumber daya yang berkurang dibandingkan HTTP/1.1.

**API Sinkron/Asinkron Terpadu**: Berbeda dengan konfigurasi sebelumnya yang menggunakan dependensi `requests` (sinkron) dan `aiohttp` (asinkron) secara terpisah, `httpx` menyediakan klien sinkron dan asinkron dengan perilaku yang identik. Hal ini memastikan bahwa `InferenceClient` dan `AsyncInferenceClient` memiliki fungsionalitas yang konsisten serta menghilangkan perbedaan perilaku halus yang sebelumnya ada di antara kedua implementasi tersebut.

**Penanganan Error SSL yang Lebih Baik**: `httpx` menangani error SSL dengan lebih baik, sehingga memudahkan dan membuat proses debugging masalah koneksi lebih andal.

**Arsitektur yang Siap untuk Masa Depan**: `httpx` dipelihara secara aktif dan dirancang untuk aplikasi Python modern. Sebaliknya, `requests` berada dalam mode pemeliharaan dan tidak akan menerima pembaruan mayor seperti peningkatan thread-safety atau dukungan HTTP/2.

**Penanganan Variabel Lingkungan yang Lebih Baik**: `httpx` menyediakan penanganan variabel lingkungan yang lebih konsisten di kedua konteks sync dan async, menghilangkan inkonsistensi sebelumnya di mana `requests` secara default membaca variabel lingkungan lokal sementara `aiohttp` tidak.

Transisi ke `httpx` menempatkan `huggingface_hub` dengan backend HTTP yang modern, efisien, dan mudah dipelihara. Meskipun sebagian besar pengguna seharusnya mengalami operasi yang mulus, peningkatan di bawahnya menyediakan kinerja dan keandalan yang lebih baik untuk semua interaksi Hub.

## `hf_transfer`

Karena semua repositori di Hub kini sudah mendukung Xet dan `hf_xet` adalah cara default untuk mengunduh/mengunggah file, kami telah menghapus dukungan untuk paket opsional `hf_transfer`. Variabel lingkungan `HF_HUB_ENABLE_HF_TRANSFER` diabaikan. Gunakan [`HF_XET_HIGH_PERFORMANCE`](../package_reference/environment_variables) sebagai gantinya.

## Kelas `Repository`

Kelas `Repository` telah dihapus di v1.0. Kelas ini adalah pembungkus tipis di sekitar CLI `git` untuk mengelola repositori. Anda masih dapat menggunakan `git` secara langsung di terminal, tetapi pendekatan yang direkomendasikan adalah menggunakan API berbasis HTTP di pustaka `huggingface_hub` untuk pengalaman yang lebih mulus, terutama saat berurusan dengan file besar.

Berikut adalah pemetaan dari kelas `Repository` lama ke kelas `HfApi` baru:

| Metode `Repository`                        | metode `HfApi`                                        |
| ------------------------------------------ | ----------------------------------------------------- |
| `repo.clone_from`                          | `snapshot_download`                                   |
| `repo.git_add` + `git_commit` + `git_push` | [upload_file()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.upload_file), [upload_folder()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.upload_folder), [create_commit()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.create_commit) |
| `repo.git_tag`                             | `create_tag`                                          |
| `repo.git_branch`                          | `create_branch`                                       |

## Kelas `HfFolder`

`HfFolder` digunakan untuk mengelola token akses pengguna. Gunakan [login()](/docs/huggingface_hub/v2.4.0/id/package_reference/authentication#huggingface_hub.login) untuk menyimpan token baru, [logout()](/docs/huggingface_hub/v2.4.0/id/package_reference/authentication#huggingface_hub.logout) untuk menghapusnya, dan [whoami()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.whoami) untuk memeriksa pengguna yang terkait dengan token saat ini. Terakhir, gunakan `get_token()` untuk mengambil token pengguna dalam sebuah skrip.

## kelas `InferenceApi`

`InferenceApi` adalah kelas untuk berinteraksi dengan Inference API. Sekarang disarankan untuk menggunakan kelas [InferenceClient](/docs/huggingface_hub/v2.4.0/id/package_reference/inference_client#huggingface_hub.InferenceClient) sebagai gantinya.

## Fitur lain yang tidak didukung lagi

Beberapa metode dan parameter telah dihapus di v1.0. Yang tercantum di bawah ini sudah tidak didukung lagi dengan pesan peringatan di v0.x.

- `constants.hf_cache_home` telah dihapus. Silakan gunakan `HF_HOME` sebagai gantinya.
- Parameter `use_auth_token` telah dihapus dari semua metode. Silakan gunakan `token` sebagai gantinya.
- Metode `get_token_permission` telah dihapus.
- Metode `update_repo_visibility` telah dihapus. Silakan gunakan `update_repo_settings` sebagai gantinya.
- Parameter `is_write_action` telah dihapus dari `build_hf_headers` serta `write_permission` dari `login`. Konsep "izin tulis" telah dihapus dan tidak lagi relevan mengingat token bergranularitas halus kini menjadi pendekatan yang direkomendasikan.
- Parameter `new_session` di `login` telah diganti namanya menjadi `skip_if_logged_in` untuk kejelasan yang lebih baik.
- Parameter `resume_download`, `force_filename`, dan `local_dir_use_symlinks` telah dihapus dari `hf_hub_download` dan `snapshot_download`.
- Parameter `library`, `language`, `tags`, dan `task` telah dihapus dari `list_models`.

## Perintah cache CLI

Manajemen cache dari CLI telah dirancang ulang untuk mengikuti alur kerja yang terinspirasi dari Docker. `huggingface-cli` yang sudah tidak didukung telah dihapus, dan `hf` (diperkenalkan di v0.34) menggantikannya dengan CLI resource-action yang lebih jelas. Perintah `hf cache scan` dan `hf cache delete` lama juga dihapus di v1.0 dan digantikan dengan trio baru di bawah ini:

- `hf cache ls` menampilkan entri cache dalam tabel ringkas, JSON, atau CSV. Gunakan `--revisions` untuk memeriksa revisi individual, tambahkan ekspresi `--filter` seperti `size>1GB` atau `accessed>30d`, dan kombinasikan dengan `--quiet` jika Anda hanya membutuhkan identifikator.
- `hf cache rm` menghapus entri cache yang dipilih. Sampaikan satu atau beberapa ID repo (misalnya `model/bert-base-uncased`) atau hash revisi, dan secara opsional tambahkan `--dry-run` untuk pratinjau atau `--yes` untuk melewati prompt konfirmasi. Ini menggantikan kedua alur kerja TUI interaktif dan `--disable-tui` dari perintah sebelumnya.
- `hf cache prune` menjalankan tugas pembersihan umum, yaitu menghapus revisi yang tidak dirujuk dalam satu kali eksekusi. Tambahkan `--dry-run` atau `--yes` dengan cara yang sama seperti pada `hf cache rm`.

Terakhir, ekstra `[cli]` telah dihapus - CLI sekarang disertakan bersama paket inti `huggingface_hub`.

## Dukungan TensorFlow dan Keras 2.x

Semua kode dan dependensi terkait TensorFlow telah dihapus di v1.0. Ini mencakup perubahan pemecah berikut:

- `huggingface_hub[tensorflow]` tidak lagi menjadi dependensi tambahan yang didukung
- Fungsi utilitas `split_tf_state_dict_into_shards` dan `get_tf_storage_size` telah dihapus.
- Versi `tensorflow`, `fastai`, dan `fastcore` tidak lagi disertakan dalam header bawaan.

Integrasi Keras 2.x juga telah dihapus. Ini mencakup kelas `KerasModelHubMixin` serta utilitas `save_pretrained_keras`, `from_pretrained_keras`, dan `push_to_hub_keras`. Keras 2.x adalah pustaka legacy yang tidak lagi dipelihara. Pendekatan yang direkomendasikan adalah menggunakan Keras 3.x yang terintegrasi erat dengan Hub (yaitu, pustaka ini berisi metode bawaan untuk memuat/mengirim ke Hub). Jika Anda masih ingin bekerja dengan Keras 2.x, Anda harus menurunkan versi `huggingface_hub` ke versi v0.x.

## Nilai yang dikembalikan oleh `upload_file` dan `upload_folder`

Fungsi [upload_file()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.upload_file) dan [upload_folder()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) kini mengembalikan URL dari commit yang dibuat di Hub. Sebelumnya, fungsi-fungsi tersebut mengembalikan URL dari file atau folder. Hal ini dilakukan untuk menyelaraskan dengan nilai pengembalian dari [create_commit()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.create_commit), [delete_file()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.delete_file), dan [delete_folder()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_api#huggingface_hub.HfApi.delete_folder).