Hub Python Library documentation
Variabel lingkungan
Variabel lingkungan
huggingface_hub dapat dikonfigurasi menggunakan variabel lingkungan.
Jika Anda belum familiar dengan variabel lingkungan, berikut adalah artikel umum tentangnya di macOS dan Linux serta di Windows.
Halaman ini akan memandu Anda melalui semua variabel lingkungan yang spesifik untuk huggingface_hub beserta artinya.
Semua variabel lingkungan dibaca pada saat impor
huggingface_hub. Setiap modifikasi yang dilakukan setelahnya tidak akan dipertimbangkan. Pastikan Anda mengatur variabel lingkungan Anda sebelum mengimporhuggingface_hub.
Umum
HF_INFERENCE_ENDPOINT
Untuk mengatur url dasar api inferensi. Anda mungkin ingin mengatur variabel ini jika organisasi Anda menunjuk ke API Gateway alih-alih langsung ke api inferensi.
Bergaya default ke "https://api-inference.huggingface.co".
HF_HOME
Untuk mengatur di mana huggingface_hub akan menyimpan data secara lokal. Secara khusus, token Anda dan cache akan disimpan di folder ini.
Bergaya default ke "~/.cache/huggingface" kecuali XDG_CACHE_HOME disetel.
HF_HUB_CACHE
Untuk mengatur di mana repositori dari Hub akan di-cache secara lokal (model, dataset, dan spaces).
Bergaya default ke "$HF_HOME/hub" (misalnya "~/.cache/huggingface/hub" secara default).
HF_XET_CACHE
Untuk mengatur di mana Xet menyimpan cache shard dan data staging upload secara lokal. Lihat penyimpanan cache Xet untuk detail lebih lanjut.
Bergaya default ke "$HF_HOME/xet" (misalnya "~/.cache/huggingface/xet" secara default).
HF_ASSETS_CACHE
Untuk mengatur di mana aset yang dibuat oleh pustaka hilir akan di-cache secara lokal. Aset tersebut dapat berupa data yang telah diproses, file yang diunduh dari GitHub, log, dan seterusnya.
Bergaya default ke "$HF_HOME/assets" (misalnya "~/.cache/huggingface/assets" secara default).
HF_TOKEN
Untuk mengatur User Access Token guna autentikasi ke Hub. Jika diset, nilai ini akan menimpa token yang disimpan di mesin (di $HF_TOKEN_PATH atau "$HF_HOME/token" jika yang pertama tidak diset).
Untuk detail lebih lanjut tentang autentikasi, lihat bagian ini.
HF_TOKEN_PATH
Untuk mengatur di mana huggingface_hub harus menyimpan User Access Token. Secara default menggunakan "$HF_HOME/token" (misalnya ~/.cache/huggingface/token secara default).
HF_HUB_VERBOSITY
Atur tingkat kecermatan logger huggingface_hub. Harus salah satu dari {"debug", "info", "warning", "error", "critical"}.
Bawaan adalah "warning".
Untuk detail lebih lanjut, lihat referensi logging.
HF_HUB_ETAG_TIMEOUT
Nilai integer untuk mendefinisikan jumlah detik yang ditunggu untuk respons server saat mengambil metadata terbaru dari repo sebelum mengunduh file. Jika permintaan melebihi batas waktu, huggingface_hub akan menggunakan file yang di-cache secara lokal. Pengaturan nilai yang lebih rendah mempercepat alur kerja untuk mesin dengan koneksi lambat yang sudah memiliki file di cache. Nilai yang lebih tinggi menjamin pemanggilan metadata berhasil dalam lebih banyak kasus. Bawaan adalah 10 detik.
HF_HUB_DOWNLOAD_TIMEOUT
Nilai integer untuk mendefinisikan jumlah detik yang ditunggu untuk respons server saat mengunduh file. Jika permintaan melebihi batas waktu, TimeoutError akan dilempar. Mengatur nilai yang lebih tinggi bermanfaat pada mesin dengan koneksi lambat. Nilai yang lebih kecil membuat proses gagal lebih cepat dalam kasus gangguan jaringan total. Bawaan adalah 10 detik.
Xet
Variabel lingkungan Xet lainnya
HF_XET_CHUNK_CACHE_SIZE_BYTES
Variabel ini tidak lagi memiliki efek apa pun. hf_xet tidak lagi menggunakan cache chunk lokal untuk unduhan, dan mengatur variabel ini tidak akan mengaktifkannya. Lihat xet-core#715 untuk detailnya.
HF_XET_SHARD_CACHE_SIZE_LIMIT
Untuk mengatur ukuran cache shard Xet secara lokal. Meningkatkan nilai ini akan meningkatkan efisiensi unggahan karena chunk yang dirujuk dalam file shard yang di-cache tidak diunggah ulang. Perhatikan bahwa batas lunak default kemungkinan sudah cukup untuk sebagian besar beban kerja.
Bawaan ke 16000000000 (16GB).
HF_XET_NUM_CONCURRENT_RANGE_GETS
Variabel ini tidak lagi digunakan. Sejak hf_xet 1.3.0, konkurensi unduhan dikendalikan secara adaptif.
Nilai Boolean
Variabel lingkungan berikut mengharapkan nilai boolean. Variabel akan dianggap
sebagai True jika nilainya salah satu dari {"1", "ON", "YES", "TRUE"} (tidak membedakan huruf besar/kecil). Nilai lain
(atau tidak terdefinisi) akan dianggap sebagai False.
HF_DEBUG
Jika disetel, level log untuk logger huggingface_hub akan disetel ke DEBUG. Selain itu, semua permintaan yang dibuat oleh pustaka HF akan dicatat sebagai perintah cURL yang setara untuk memudahkan debugging dan reproduksibilitas.
HF_HUB_OFFLINE
Jika disetel, tidak akan ada panggilan HTTP yang dibuat ke Hugging Face Hub. Jika Anda mencoba mengunduh file, hanya file yang sudah di-cache yang akan diakses. Jika tidak ada file cache yang terdeteksi, sebuah error akan dilempar. Hal ini berguna jika jaringan Anda lambat dan Anda tidak peduli untuk memiliki versi terbaru dari sebuah file.
Jika HF_HUB_OFFLINE=1 diset sebagai variabel lingkungan dan Anda memanggil metode apa pun dari HfApi, pengecualian OfflineModeIsEnabled akan dilempar.
Catatan: meskipun versi terbaru dari sebuah file sudah di-cache, pemanggilan hf_hub_download tetap memicu permintaan HTTP untuk memeriksa apakah versi baru tersedia. Pengaturan HF_HUB_OFFLINE=1 akan melewati panggilan ini sehingga mempercepat waktu pemuatan Anda.
Jika Anda ingin memeriksa apakah mode offline diaktifkan atau tidak, Anda dapat menggunakan helper is_offline_mode().
HF_HUB_DISABLE_IMPLICIT_TOKEN
Autentikasi tidak wajib untuk setiap permintaan ke Hub. Misalnya, meminta detail tentang model "gpt2" tidak memerlukan autentikasi. Namun, jika pengguna telah masuk, perilaku default akan selalu mengirim token untuk memudahkan pengalaman pengguna (tidak pernah menerima HTTP 401 Unauthorized) saat mengakses repositori privat atau bergerbang. Demi privasi, Anda dapat menonaktifkan perilaku ini dengan mengatur HF_HUB_DISABLE_IMPLICIT_TOKEN=1. Dalam hal ini, token hanya akan dikirim untuk panggilan dengan “akses tulis” (contoh: membuat commit).
Catatan: menonaktifkan pengiriman token secara implisit dapat menimbulkan efek samping yang aneh. Misalnya, jika Anda ingin mendaftar semua model di Hub, model privat Anda tidak akan terdaftar. Anda perlu secara eksplisit melewatkan argumen token=True dalam skrip Anda.
HF_HUB_DISABLE_PROGRESS_BARS
Untuk tugas yang memakan waktu lama, huggingface_hub menampilkan bilah progres secara default (menggunakan tqdm).
Anda dapat menonaktifkan semua bilah progres sekaligus dengan mengatur HF_HUB_DISABLE_PROGRESS_BARS=1.
HF_HUB_DISABLE_SYMLINKS
Jika disetel, huggingface_hub tidak akan pernah membuat symlink di cache. Sebagai gantinya, file akan diduplikasi atau dipindahkan langsung ke direktori snapshot. Ini adalah fitur untuk pengguna lanjutan yang membuat direktori cache berjalan dalam mode terdegradasi di mana file berukuran besar akhirnya diduplikasi di hard drive Anda.
Salah satu contoh kasus penggunaan adalah ketika drive jaringan bersama (misalnya NAS) digunakan sebagai HF_HUB_CACHE di antara mesin yang menjalankan sistem operasi berbeda. Symlink yang dibuat di Linux tidak selalu dapat dilintasi di Windows, yang menyebabkan error. Mengatur HF_HUB_DISABLE_SYMLINKS=1 menghindari masalah ini dengan mengorbankan deduplikasi ruang disk.
HF_HUB_DISABLE_SYMLINKS_WARNING
Jika Anda menggunakan mesin Windows, disarankan untuk mengaktifkan mode developer atau menjalankan huggingface_hub dalam mode admin. Jika tidak, huggingface_hub tidak akan dapat membuat
symlinks di sistem cache Anda. Anda tetap dapat menjalankan skrip apa pun, tetapi pengalaman pengguna
Anda akan menurun karena beberapa file besar mungkin berakhir terduplikasi di hard drive Anda. Pesan
peringatan akan muncul untuk memberi tahu Anda tentang perilaku ini. Atur HF_HUB_DISABLE_SYMLINKS_WARNING=1
untuk menonaktifkan peringatan ini.
Untuk detail lebih lanjut, lihat batasan cache.
HF_HUB_DISABLE_EXPERIMENTAL_WARNING
Beberapa fitur huggingface_hub bersifat eksperimental. Artinya, Anda dapat menggunakannya, tetapi kami tidak menjamin bahwa fitur tersebut akan tetap dipelihara di masa depan. Secara khusus, kami mungkin memperbarui API atau perilaku fitur semacam itu tanpa siklus deprecation. Pesan peringatan akan muncul saat Anda menggunakan fitur eksperimental untuk memberi tahu Anda tentang hal ini. Jika Anda merasa nyaman untuk men-debug potensi masalah yang muncul dari penggunaan fitur eksperimental, Anda dapat mengatur HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1 untuk menonaktifkan peringatan tersebut.
Jika Anda menggunakan fitur eksperimental, silakan beri tahu kami! Umpan balik Anda dapat membantu kami merancang dan memperbaikinya.
HF_HUB_DISABLE_TELEMETRY
Secara default, beberapa data dikumpulkan oleh pustaka HF (transformers, datasets, gradio,..) untuk memantau penggunaan, men-debug masalah, dan membantu memprioritaskan fitur.
Setiap pustaka mendefinisikan kebijakan masing-masing (yaitu penggunaan apa yang dipantau) tetapi implementasi intinya terjadi di huggingface_hub (lihat send_telemetry).
Anda dapat mengatur HF_HUB_DISABLE_TELEMETRY=1 sebagai variabel lingkungan untuk menonaktifkan telemetri secara global.
HF_HUB_DISABLE_UPDATE_CHECK
Secara default, CLI hf memeriksa PyPI untuk rilis yang lebih baru saat startup (paling sering sekali setiap 24 jam) dan mencetak peringatan satu baris berwarna kuning ke stderr ketika tersedia, yang menyarankan hf update. Pemeriksaan ini sudah menjadi no-op pada versi dev dan pre-release.
Ini juga memeriksa (paling sering sekali setiap 24 jam, sepenuhnya secara lokal) apakah skill hf-cli terpasang dan dihasilkan oleh versi yang sedang berjalan, serta menyarankan hf skills add / hf skills update jika belum. Pemeriksaan ini hanya mencetak petunjuk, tidak pernah menyentuh direktori skill Anda.
Sebelum menjalankan ekstensi CLI yang terpasang, sistem memeriksa (paling banyak sekali setiap 24 jam per ekstensi) apakah ada commit yang lebih baru di GitHub, dan menyarankan hf extensions update <name> jika ada. hf extensions list menggunakan pemeriksaan yang sama untuk kolom LATEST-nya.
Set HF_HUB_DISABLE_UPDATE_CHECK=1 untuk melewati permintaan-permintaan ini dan membisukan semua petunjuk tersebut. Berguna di lingkungan CI offline atau ketika Anda lebih memilih output shell yang lebih tenang.
HF_HUB_DISABLE_XET
Atur untuk menonaktifkan penggunaan hf-xet, meskipun tersedia di lingkungan Python Anda. Hal ini karena hf-xet akan digunakan secara otomatis jika ditemukan, sehingga pengaturan ini memungkinkan penonaktifan eksplisit. Jika Anda menonaktifkan Xet, pertimbangkan untuk membuat laporan masalah dan menyertakan informasi diagnostik untuk membantu kami memahami mengapa Xet tidak berfungsi bagi Anda.
HF_HUB_ENABLE_HF_TRANSFER
Ini adalah variabel lingkungan yang sudah tidak digunakan lagi. Sekarang Hugging Face Hub sepenuhnya didukung oleh backend penyimpanan Xet, semua transfer file dilakukan melalui paket biner
hf-xet. Paket ini menyediakan transfer yang efisien menggunakan strategi deduplikasi berbasis chunk dan terintegrasi dengan mulus denganhuggingface_hub. Artinyahf_transfertidak bisa digunakan lagi. Jika Anda tertarik dengan performa yang lebih tinggi, lihat bagianHF_XET_HIGH_PERFORMANCE
HF_HUB_DISABLE_SHARED_BLOBS
Setel ke 1 untuk menonaktifkan blob store bersama di seluruh cache. Secara default, file Xet yang berhasil diunduh disimpan di <CACHE_DIR>/blobs/<prefix>/<xet_hash> dan dibuat symlink ke cache repo, sehingga file yang identik hanya disimpan sekali di disk di antara berbagai repo dan dapat digunakan kembali tanpa perlu mengambil ulang. Optimasi ini diaktifkan secara default, tetapi dinonaktifkan jika Xet tidak tersedia (misalnya jika HF_HUB_DISABLE_XET=1 disetel) atau jika symlink tidak didukung secara lokal. Dalam kasus tersebut, sistem secara diam-diam kembali ke penyimpanan lokal repo biasa. Lihat panduan caching untuk detailnya.
HF_XET_HIGH_PERFORMANCE
Setel hf-xet untuk beroperasi dengan pengaturan yang ditingkatkan guna memaksimalkan sumber daya jaringan dan disk pada mesin. Mengaktifkan mode kinerja tinggi akan mencoba menjenuhkan bandwidth jaringan mesin ini dan memanfaatkan semua core CPU untuk aktivitas unggah/unduh paralel.
Anggap ini serupa dengan variabel lingkungan HF_HUB_ENABLE_HF_TRANSFER=1 lama, tetapi diterapkan pada hf-xet.
Untuk mempelajari lebih lanjut tentang manfaat penyimpanan Xet dan hf_xet, lihat bagian ini.
HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY
Variabel ini tidak lagi digunakan. Sejak hf_xet 1.3.0, file selalu ditulis ke disk lokal secara berurutan (lihat penulis file di v1.3.0).
Variabel lingkungan yang tidak didukung lagi
Untuk menstandarkan semua variabel lingkungan dalam ekosistem Hugging Face, beberapa variabel telah ditandai sebagai tidak lagi didukung (deprecated). Meskipun masih berfungsi, variabel-variabel tersebut tidak lagi memiliki prioritas lebih tinggi dibandingkan penggantiannya. Tabel berikut merangkum variabel yang tidak lagi didukung beserta alternatifnya yang sesuai:
| Variabel yang Tidak Lagi Digunakan | Penggantian |
|---|---|
HUGGINGFACE_HUB_CACHE | HF_HUB_CACHE |
HUGGINGFACE_ASSETS_CACHE | HF_ASSETS_CACHE |
HUGGING_FACE_HUB_TOKEN | HF_TOKEN |
Dari alat eksternal
Beberapa variabel lingkungan tidak spesifik untuk huggingface_hub tetapi tetap diperhitungkan saat disetel.
DO_NOT_TRACK
Nilai Boolean. Setara dengan HF_HUB_DISABLE_TELEMETRY. Ketika diatur ke true, telemetri dinonaktifkan secara global di ekosistem Python Hugging Face (transformers, diffusers, gradio, dll.). Lihat https://donottrack.sh/ untuk detail lebih lanjut.
NO_COLOR
Nilai Boolean. Saat diatur, CLI hf tidak akan mencetak warna ANSI apa pun.
Lihat no-color.org.
XDG_CACHE_HOME
Hanya digunakan ketika HF_HOME tidak disetel!
Ini adalah cara default untuk mengatur di mana data non-esensial (ter-cache) yang spesifik pengguna harus ditulis pada mesin linux.
Jika HF_HOME tidak disetel, home default akan menjadi "$XDG_CACHE_HOME/huggingface"
bukan "~/.cache/huggingface".