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.

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 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 method” 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() dan 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 (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().

Untuk detail lebih lanjut, Anda dapat memeriksa PR #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 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(), upload_folder(), create_commit()
repo.git_tag	create_tag
repo.git_branch	create_branch

Kelas HfFolder

HfFolder digunakan untuk mengelola token akses pengguna. Gunakan login() untuk menyimpan token baru, logout() untuk menghapusnya, dan 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 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 “write permission” telah dihapus dan tidak lagi relevan mengingat token fine-grained 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 tidak lagi 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() dan 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(), delete_file(), dan delete_folder().

Update on GitHub