Kembalikan level saat ini untuk logger root HuggingFace Hub.

HuggingFace Hub memiliki tingkat log berikut:

• huggingface_hub.logging.CRITICAL, huggingface_hub.logging.FATAL
• huggingface_hub.logging.ERROR
• huggingface_hub.logging.WARNING, huggingface_hub.logging.WARN
• huggingface_hub.logging.INFO
• huggingface_hub.logging.DEBUG

Menetapkan level untuk logger root HuggingFace Hub.

Mengatur tingkat detail ke logging.INFO.

Mengatur tingkat detail ke logging.DEBUG.

Mengatur tingkat detail ke logging.WARNING.

Mengatur tingkat detail ke logging.ERROR.

Nonaktifkan propagasi output log pustaka. Perhatikan bahwa propagasi log dinonaktifkan secara default.

Aktifkan propagasi output log pustaka. Silakan nonaktifkan handler default HuggingFace Hub untuk mencegah pencatatan log ganda jika logger root telah dikonfigurasi.

Mengembalikan logger dengan nama yang ditentukan. Fungsi ini tidak dimaksudkan untuk diakses secara langsung oleh pengguna pustaka.

>>> from huggingface_hub import logging

>>> logger = logging.get_logger(__name__)
>>> logging.set_verbosity_info()

Periksa apakah bilah progres dinonaktifkan secara global atau untuk grup tertentu.

Fungsi ini mengembalikan apakah bilah progres dinonaktifkan untuk grup tertentu atau secara global. Fungsi ini memeriksa variabel lingkungan HF_HUB_DISABLE_PROGRESS_BARS terlebih dahulu, lalu pengaturan programatik.

Nonaktifkan bilah progres secara global atau untuk grup tertentu.

Fungsi ini memperbarui status bilah progres berdasarkan nama grup. Jika nama grup tidak diberikan, semua bilah progres dinonaktifkan. Operasi ini menghormati pengaturan variabel lingkungan HF_HUB_DISABLE_PROGRESS_BARS.

Berfungsi sebagai panggilan biasa maupun sebagai context manager: disable_progress_bars() # menonaktifkan hingga enable_progress_bars() with disable_progress_bars(): # menonaktifkan untuk blok, mengaktifkan kembali saat keluar …

Aktifkan bilah progres secara global atau untuk grup tertentu.

Fungsi ini mengatur bilah progres menjadi aktif untuk grup yang ditentukan atau secara global jika tidak ada grup yang ditentukan. Operasi ini tunduk pada pengaturan lingkungan HF_HUB_DISABLE_PROGRESS_BARS.

Atur pabrik klien HTTP yang akan digunakan oleh huggingface_hub.

Client factory adalah metode yang mengembalikan objek httpx2.Client. Pada pemanggilan pertama get_session(), client factory akan digunakan untuk membuat objek httpx2.Client baru yang akan dibagikan di antara semua pemanggilan yang dilakukan oleh huggingface_hub.

Hal ini dapat berguna jika Anda menjalankan skrip dalam lingkungan tertentu yang memerlukan konfigurasi khusus (misalnya, proxy atau sertifikat kustom).

Gunakan get_session() untuk mendapatkan httpx2.Client yang dikonfigurasi dengan benar.

Dapatkan objek httpx2.Client, menggunakan pabrik transport dari pengguna.

Klien ini dibagikan di antara semua panggilan yang dibuat oleh huggingface_hub. Oleh karena itu, Anda tidak harus menutupnya secara manual.

Gunakan set_client_factory() untuk menyesuaikan httpx2.Client.

Tutup httpx2.Client global yang digunakan oleh huggingface_hub.

Jika Client ditutup, ia akan dibuat ulang pada panggilan berikutnya ke get_session().

Berguna, misalnya, jika sertifikat SSL telah diperbarui.

Atur pabrik klien HTTP asinkron yang akan digunakan oleh huggingface_hub.

Pabrik klien asinkron adalah metode yang mengembalikan objek httpx2.AsyncClient. Ini dapat berguna jika Anda menjalankan skrip dalam lingkungan tertentu yang memerlukan konfigurasi khusus (misalnya proxy atau sertifikat kustom). Gunakan get_async_session() untuk mendapatkan httpx2.AsyncClient yang dikonfigurasi dengan benar.

Berbeda dengan httpx2.Client yang dibagikan di antara semua panggilan yang dibuat oleh huggingface_hub, httpx2.AsyncClient tidak dibagikan. Disarankan untuk menggunakan async context manager untuk memastikan klien ditutup dengan benar saat konteks berakhir.

Kembalikan objek httpx2.AsyncClient, menggunakan pabrik transport dari pengguna.

Gunakan set_async_client_factory() untuk menyesuaikan httpx2.AsyncClient.

Berbeda dengan httpx2.Client yang dibagikan di antara semua panggilan yang dibuat oleh huggingface_hub, httpx2.AsyncClient tidak dibagikan. Disarankan untuk menggunakan async context manager untuk memastikan klien ditutup dengan benar saat konteks berakhir.

Versi internal dari response.raise_for_status() yang akan memperhalus HTTPError potensial. Pengecualian yang dilemparkan akan menjadi instance dari HfHubHTTPError.

Helper ini dimaksudkan sebagai metode unik untuk raise_for_status saat melakukan panggilan ke Hugging Face Hub.

Membuat pengecualian ketika permintaan gagal:

• RepositoryNotFoundError Jika repositori yang akan diunduh tidak dapat ditemukan. Hal ini mungkin terjadi karena repositori tidak ada, karena repo_type tidak diatur dengan benar, atau karena repositori bersifat private dan Anda tidak memiliki akses.
• GatedRepoError Jika repositori ada tetapi bersifat gated dan pengguna tidak ada dalam daftar yang diotorisasi.
• RevisionNotFoundError Jika repositori ada tetapi revisi tidak dapat ditemukan.
• EntryNotFoundError Jika repositori ada tetapi entri (misalnya file yang diminta) tidak dapat ditemukan.
• BadRequestError Jika permintaan gagal dengan error HTTP 400 BadRequest.
• HfHubHTTPError Jika permintaan gagal karena alasan yang tidak tercantum di atas.

Mengembalikan apakah kita berada dalam mode offline untuk Hub.

Saat mode offline diaktifkan, semua permintaan HTTP yang dibuat dengan get_session akan memicu pengecualian OfflineModeIsEnabled.

from huggingface_hub import is_offline_mode

def list_files(repo_id: str):
    if is_offline_mode():
        ... # list files from local cache (degraded experience but still functional)
    else:
        ... # list files from Hub (complete experience)

HTTPError untuk diwarisi oleh setiap HTTP Error kustom yang dilempar di HF Hub.

Setiap HTTPError dikonversi setidaknya menjadi HfHubHTTPError. Jika ada informasi yang dikirim kembali oleh server, informasi tersebut akan ditambahkan ke pesan error.

Detail yang ditambahkan:

• Request ID diambil dari header dengan urutan prioritas: “X-Request-Id”, “X-Amzn-Trace-Id”, “X-Amz-Cf-Id”.
• Pesan kesalahan server dari header “X-Error-Message”.
• Pesan kesalahan server jika kami dapat menemukannya di badan respons.

    import httpx2
    from huggingface_hub.utils import get_session, hf_raise_for_status, HfHubHTTPError

    response = get_session().post(...)
    try:
        hf_raise_for_status(response)
    except HfHubHTTPError as e:
        print(str(e)) # formatted message
        e.request_id, e.server_message # details returned by server

        # Complete the error message with additional information once it's raised
        e.append_to_message("
ate_commit` expects the repository to exist.")
        raise

Dilempar saat mencoba mengakses URL hf.co dengan nama repositori yang tidak valid, atau dengan nama repositori privat yang tidak dapat diakses oleh pengguna.

>>> from huggingface_hub import model_info
>>> model_info("<non_existent_repository>")
(...)
huggingface_hub.errors.RepositoryNotFoundError: 401 Client Error. (Request ID: PvMw_VjBMjVdMz53WKIzP)

Repository Not Found for url: https://huggingface.co/api/models/%3Cnon_existent_repository%3E.
Please make sure you specified the correct `repo_id` and `repo_type`.
If the repo is private, make sure you are authenticated and your token has the required permissions.
Invalid username or password.

Dilempar saat mencoba mengakses repositori bergerbang yang pengguna tidak terdaftar dalam daftar yang diotorisasi.

Catatan: diturunkan dari RepositoryNotFoundError untuk memastikan kompatibilitas mundur.

>>> from huggingface_hub import model_info
>>> model_info("<gated_repository>")
(...)
huggingface_hub.errors.GatedRepoError: 403 Client Error. (Request ID: ViT1Bf7O_026LGSQuVqfa)

Cannot access gated repo for url https://huggingface.co/api/models/ardent-figment/gated-model.
Access to model ardent-figment/gated-model is restricted and you are not in the authorized list.
Visit https://huggingface.co/ardent-figment/gated-model to ask for access.

Dilempar saat mencoba mengakses URL hf.co dengan repositori yang valid tetapi revisi yang tidak valid.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', 'config.json', revision='<non-existent-revision>')
(...)
huggingface_hub.errors.RevisionNotFoundError: 404 Client Error. (Request ID: Mwhe_c3Kt650GcdKEFomX)

Revision Not Found for url: https://huggingface.co/bert-base-cased/resolve/%3Cnon-existent-revision%3E/config.json.

Dilempar oleh HfApi.resolve_revision() ketika sebuah revisi tidak dapat dipecahkan menjadi hash commit: Hub tidak dapat dijangkau (mode offline, error koneksi, timeout, downtime Hub, …) dan tidak ada entri yang cocok ditemukan di cache lokal.

Dilempar oleh hf_raise_for_status ketika server mengembalikan error HTTP 400.

>>> resp = httpx2.post("hf.co/api/check", ...)
>>> hf_raise_for_status(resp, endpoint_name="check")
huggingface_hub.errors.BadRequestError: Bad request for check endpoint: {details} (Request ID: XXX)

Dilempar ketika entri tidak ditemukan, baik secara lokal maupun jarak jauh.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.RemoteEntryNotFoundError (...)
>>> hf_hub_download('bert-base-cased', '<non-existent-file>', local_files_only=True)
(...)
huggingface_hub.utils.errors.LocalEntryNotFoundError (...)

Dilempar saat mencoba mengakses URL hf.co dengan repositori dan revisi yang valid tetapi nama file yang tidak valid.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.EntryNotFoundError: 404 Client Error. (Request ID: 53pNl6M0MxsnG5Sw8JA6x)

Entry Not Found for url: https://huggingface.co/bert-base-cased/resolve/main/%3Cnon-existent-file%3E.

Muncul saat mencoba mengakses file atau snapshot yang tidak ada di disk ketika jaringan dinonaktifkan atau tidak tersedia (masalah koneksi). Entri tersebut mungkin ada di Hub.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-cached-file>',  local_files_only=True)
(...)
huggingface_hub.errors.LocalEntryNotFoundError: Cannot find the requested files in the disk cache and outgoing traffic has been disabled. To enable hf.co look-ups and downloads online, set 'local_files_only' to False.

Dilempar oleh snapshot_download() ketika Hub tidak dapat dijangkau (offline, masalah koneksi, atau local_files_only=True) dan snapshot cache diketahui tidak lengkap: beberapa file yang terdaftar dalam daftar tree cache repositori tidak ada di snapshot lokal.

Ini adalah subkelas dari LocalEntryNotFoundError untuk kompatibilitas mundur.

Atribut snapshot_path menyimpan jalur ke snapshot lokal yang belum lengkap, sehingga pustaka hilir dapat menemukan file yang di-cache terbaru meskipun diketahui belum lengkap.

Dilempar oleh get_cached_repo_tree() ketika tidak ada daftar tree yang di-cache untuk revisi yang diminta.

Daftar pohon terisi sebagai efek samping dari snapshot_download().

Dilempar ketika permintaan dibuat tetapi HF_HUB_OFFLINE=1 diset sebagai variabel lingkungan.

Mengirim telemetri yang membantu melacak penggunaan berbagai pustaka HF.

Data penggunaan ini membantu kami men-debug masalah dan memprioritaskan fitur baru. Namun, kami memahami bahwa tidak semua orang ingin berbagi informasi tambahan, dan kami menghargai privasi Anda. Anda dapat menonaktifkan pengumpulan telemetri dengan mengatur HF_HUB_DISABLE_TELEMETRY=1 sebagai variabel lingkungan. Telemetri juga dinonaktifkan dalam mode offline (yaitu saat mengatur HF_HUB_OFFLINE=1).

Pengumpulan telemetri dijalankan di thread terpisah untuk meminimalkan dampak bagi pengguna.

>>> from huggingface_hub.utils import send_telemetry

# Send telemetry without library information
>>> send_telemetry("ping")

# Send telemetry to subtopic with library information
>>> send_telemetry("gradio/local_link", library_name="gradio", library_version="3.22.1")

# Send telemetry with additional data
>>> send_telemetry(
...     topic="examples",
...     library_name="transformers",
...     library_version="4.26.0",
...     user_agent={"pipeline": "text_classification", "framework": "flax"},
... )

Validasi nilai yang diterima sebagai argumen untuk metode publik apa pun dari huggingface_hub.

Tujuan dari dekorator ini adalah untuk menyelaraskan validasi argumen yang digunakan ulang di mana pun. Secara default, semua validator yang didefinisikan akan diuji.

Validator:

• validate_repo_id(): repo_id harus berupa "repo_name" atau "namespace/repo_name". Namespace adalah nama pengguna atau organisasi.
• ~utils.smoothly_deprecate_legacy_arguments: Abaikan proxies saat mengunduh file (seharusnya diatur secara global).

>>> from huggingface_hub.utils import validate_hf_hub_args

>>> @validate_hf_hub_args
... def my_cool_method(repo_id: str):
...     print(repo_id)

>>> my_cool_method(repo_id="valid_repo_id")
valid_repo_id

>>> my_cool_method("other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

>>> my_cool_method(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

Pengecualian umum yang dilempar oleh validator huggingface_hub.

Mewarisi dari ValueError.

Validasi bahwa repo_id valid.

Hal ini tidak dimaksudkan untuk menggantikan validasi yang tepat yang dilakukan di Hub, melainkan untuk menghindari inkonsistensi lokal setiap kali memungkinkan (contoh: meneruskan repo_type di dalam repo_id dilarang).

Aturan:

• Antara 1 dan 96 karakter.
• “repo_name” atau “namespace/repo_name”
• [a-zA-Z0-9] atau ”-”, ”_”, ”.”
• ”—” dan ”..” dilarang

Valid: "foo", "foo/bar", "123", "Foo-BAR_foo.bar123"

Tidak valid: "datasets/foo/bar", ".repo_id", "foo--bar", "foo.git"

>>> from huggingface_hub.utils import validate_repo_id
>>> validate_repo_id(repo_id="valid_repo_id")
>>> validate_repo_id(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

Dibahas di https://github.com/huggingface/huggingface_hub/issues/1008. Di moon-landing (repository internal):

• https://github.com/huggingface/moon-landing/blob/main/server/lib/Names.ts#L27
• https://github.com/huggingface/moon-landing/blob/main/server/views/components/NewRepoForm/NewRepoForm.svelte#L138

Nonaktifkan argumen lama secara mulus dalam basis kode huggingface_hub.

Fungsi ini mengabaikan beberapa argumen yang sudah tidak didukung lagi dari kwargs dan memberi tahu pengguna bahwa argumen tersebut diabaikan. Tujuannya adalah untuk menghindari kerusakan pada kode yang sudah ada sambil memandu pengguna ke cara baru dalam melakukan hal tersebut.

Daftar argumen yang tidak didukung lagi:

• proxies: Untuk mengatur proxy, pengguna harus menggunakan variabel lingkungan HTTP_PROXY atau mengonfigurasi httpx2.Client secara manual menggunakan fungsi set_client_factory().

  Di huggingface_hub 0.x, proxies adalah kamus yang diteruskan langsung ke requests.request. Sejak huggingface_hub 1.x, proxies per-request tidak lagi didukung. Secara khusus, tidak mungkin lagi mengonfigurasi proxy pada basis per-request. Solusinya adalah dengan mengonfigurasinya secara global menggunakan fungsi set_client_factory() atau menggunakan variabel lingkungan HTTP_PROXY.

  Untuk detail lebih lanjut, lihat:

  • https://httpx2.pydantic.dev/advanced/proxies/

• resume_download: tidak lagi didukung dan tidak ada pengganti. huggingface_hub selalu melanjutkan unduhan setiap kali memungkinkan.

• force_filename: tidak didukung lagi tanpa pengganti. Nama file selalu sama dengan di Hub.

• local_dir_use_symlinks: tidak didukung lagi tanpa pengganti. Unduhan ke direktori lokal tidak lagi menggunakan symlink.