Hugging Face's logo

Hub Python Library documentation

Mengunduh file

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Mengunduh file

Unduh satu file

hf_hub_download

huggingface_hub.hf_hub_download

< >

( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = Noneuser_agent: dict | str | None = Noneforce_download: bool = Falseetag_timeout: float = 10token: bool | str | None = Nonelocal_files_only: bool = Falseheaders: dict[str, str] | None = Noneendpoint: str | None = Nonetqdm_class: type[tqdm.std.tqdm] | None = Nonedry_run: bool = False ) → str or DryRunFileInfo

Parameter

  • repo_id (str) — Nama pengguna atau organisasi dan nama repo yang dipisahkan oleh /.
  • filename (str) — Nama file di repo.
  • subfolder (str, opsional) — Nilai opsional yang sesuai dengan folder di dalam repo model.
  • repo_type (str, opsional) — Atur ke "dataset", "space" atau "kernel" jika mengunduh dari repo dataset, space, atau kernel, None atau "model" jika mengunduh dari model. Default adalah None.
  • revision (str, opsional) — ID revisi Git opsional yang dapat berupa nama cabang, tag, atau hash commit.
  • library_name (str, opsional) — Nama pustaka yang sesuai dengan objek tersebut.
  • library_version (str, opsional) — Versi dari pustaka.
  • cache_dir (str, Path, opsional) — Path ke folder tempat file cache disimpan.
  • local_dir (str atau Path, opsional) — Jika disediakan, file yang diunduh akan ditempatkan di bawah direktori ini.
  • user_agent (dict, str, opsional) — Informasi user-agent dalam bentuk kamus atau string.
  • force_download (bool, opsional, default False) — Apakah file harus diunduh meskipun sudah ada di cache lokal.
  • etag_timeout (float, opsional, default 10) — Saat mengambil ETag, berapa detik menunggu server mengirim data sebelum menyerah, yang diteruskan ke httpx2.request.
  • token (str, bool, opsional) — Token yang akan digunakan untuk unduhan.
    • Jika True, token dibaca dari folder konfigurasi HuggingFace.
    • Jika berupa string, digunakan sebagai token autentikasi.
  • local_files_only (bool, opsional, defaultnya False) — Jika True, hindari mengunduh file dan kembalikan path ke file cache lokal jika ada.
  • headers (dict, opsional) — Header tambahan yang akan dikirim bersama permintaan.
  • endpoint (str, opsional) — Endpoint Hub untuk mengirim permintaan. Bawaan adalah nilai dari HF_ENDPOINT.
  • tqdm_class (tqdm, opsional) — Jika disediakan, menimpa perilaku bawaan untuk progress bar. Argumen yang diteruskan harus mewarisi dari tqdm.auto.tqdm atau setidaknya meniru perilakunya. Bawaannya adalah progress bar kustom HF yang dapat dinonaktifkan dengan mengatur variabel lingkungan HF_HUB_DISABLE_PROGRESS_BARS.
  • dry_run (bool, opsional, defaultnya False) — Jika True, lakukan dry run tanpa benar-benar mengunduh file. Mengembalikan objek DryRunFileInfo yang berisi informasi tentang apa yang akan diunduh.

Mengembalikan

str atau DryRunFileInfo

  • Jika dry_run=False: Jalur lokal file atau, jika jaringan mati, versi terakhir file yang di-cache di disk.
  • Jika dry_run=True: Objek DryRunFileInfo yang berisi informasi unduhan.

Membuang

RepositoryNotFoundError atau RevisionNotFoundError atau ~utils.RemoteEntryNotFoundError atau LocalEntryNotFoundError atau EnvironmentError atau OSError atau ValueError

  • RepositoryNotFoundError — Jika repositori yang akan diunduh tidak dapat ditemukan. Hal ini mungkin karena repositori tersebut tidak ada, atau karena repositori tersebut disetel ke private dan Anda tidak memiliki akses.
  • RevisionNotFoundError — Jika revisi yang akan diunduh tidak dapat ditemukan.
  • ~utils.RemoteEntryNotFoundError — Jika file yang akan diunduh tidak dapat ditemukan.
  • LocalEntryNotFoundError — Jika jaringan dinonaktifkan atau tidak tersedia dan file tidak ditemukan di cache.
  • EnvironmentError — Jika token=True tetapi token tidak dapat ditemukan.
  • OSError — Jika ETag tidak dapat ditentukan.
  • ValueError — Jika nilai beberapa parameter tidak valid.

Unduh file tertentu jika belum ada di cache lokal.

Tata letak file cache baru terlihat seperti ini:

  • Direktori cache berisi satu subfolder per repo_id (dibedakan berdasarkan jenis repo)
  • di dalam setiap folder repo:
    • refs adalah daftar pasangan revisi terakhir yang diketahui => commit_hash
    • blobs berisi blob file yang sebenarnya (diidentifikasi oleh git-sha atau sha256, tergantung pada apakah file tersebut merupakan file LFS atau bukan)
    • snapshots berisi satu subfolder per commit, di mana setiap “commit” berisi subset file yang telah di-resolve pada commit tersebut. Setiap nama file adalah symlink ke blob pada commit tersebut.
[  96]  .
└── [ 160]  models--julien-c--EsperBERTo-small
    ├── [ 160]  blobs
    │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
    ├── [  96]  refs
    │   └── [  40]  main
    └── [ 128]  snapshots
        ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
        │   ├── [  52]  README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
        │   └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        └── [ 128]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48
            ├── [  52]  README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
            └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd

Jika local_dir disediakan, struktur file dari repo akan direplikasi di lokasi ini. Saat menggunakan opsi ini, cache_dir tidak akan digunakan dan folder .cache/huggingface/ akan dibuat di akar local_dir untuk menyimpan beberapa metadata terkait file yang diunduh. Meskipun mekanisme ini tidak sekuat sistem cache utama, ini dioptimalkan untuk menarik versi terbaru dari repositori secara rutin.

hf_hub_url

huggingface_hub.hf_hub_url

< >

( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Noneendpoint: str | None = None )

Parameter

  • repo_id (str) — Nama namespace (pengguna atau organisasi) dan nama repo yang dipisahkan oleh /.
  • filename (str) — Nama file di repo.
  • subfolder (str, opsional) — Nilai opsional yang sesuai dengan folder di dalam repo.
  • repo_type (str, opsional) — Atur ke "dataset", "space" atau "kernel" jika mengunduh dari repo dataset, space, atau kernel, None atau "model" jika mengunduh dari model. Default adalah None.
  • revision (str, opsional) — ID revisi Git opsional yang dapat berupa nama cabang, tag, atau hash commit.
  • endpoint (str, opsional) — Endpoint Hub untuk mengirim permintaan. Bawaan adalah nilai dari HF_ENDPOINT.

Konstruksi URL file dari informasi yang diberikan.

Alamat yang dipecahkan dapat berupa url yang di-hosting di huggingface.co, atau tautan ke Cloudfront (sebuah Content Delivery Network, atau CDN) untuk file besar yang ukurannya lebih dari beberapa MB.

Contoh:

>>> from huggingface_hub import hf_hub_url

>>> hf_hub_url(
...     repo_id="julien-c/EsperBERTo-small", filename="pytorch_model.bin"
... )
'https://huggingface.co/julien-c/EsperBERTo-small/resolve/main/pytorch_model.bin'

Catatan:

Cloudfront direplikasi di seluruh dunia sehingga unduhan jauh lebih cepat bagi pengguna akhir (dan juga menurunkan biaya bandwidth kami).

Cloudfront secara agresif meng-cache file secara default (TTL default adalah 24 jam), namun ini bukan masalah di sini karena kami menerapkan sistem versioning berbasis git di huggingface.co, yang berarti kami menyimpan file di S3/Cloudfront dengan cara yang dapat diidentifikasi berdasarkan konten (yaitu, nama file adalah hash-nya). Penggunaan nama file yang dapat diidentifikasi berdasarkan konten berarti cache tidak akan pernah basi.

Dalam hal penampungan sisi klien dari pustaka ini, kami mendasarkan penampungan kami pada tag entitas objek (ETag), yaitu pengidentifikasi versi tertentu dari sebuah sumber daya [1]_. ETag sebuah objek adalah: git-sha1-nya jika disimpan di git, atau sha256-nya jika disimpan di git-lfs.

Referensi:

Unduh snapshot dari repo

huggingface_hub.snapshot_download

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneetag_timeout: float = 10force_download: bool = Falsetoken: bool | str | None = Nonelocal_files_only: bool = Falseallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonemax_workers: int = 8tqdm_class: type[tqdm.asyncio.tqdm_asyncio] | None = Noneheaders: dict[str, str] | None = Noneendpoint: str | None = Nonedry_run: bool = False ) → str or list of DryRunFileInfo

Parameter

  • repo_id (str) — Nama pengguna atau organisasi dan nama repo yang dipisahkan oleh /.
  • repo_type (str, opsional) — Atur ke "dataset", "space" atau "kernel" jika mengunduh dari repo dataset, space, atau kernel, None atau "model" jika mengunduh dari model. Default adalah None.
  • revision (str, opsional) — ID revisi Git opsional, yang dapat berupa nama cabang, tag, atau hash commit.
  • cache_dir (str, Path, opsional) — Path ke folder tempat file cache disimpan.
  • local_dir (str atau Path, opsional) — Jika disediakan, file yang diunduh akan ditempatkan di bawah direktori ini.
  • library_name (str, opsional) — Nama pustaka yang sesuai dengan objek tersebut.
  • library_version (str, opsional) — Versi dari pustaka.
  • user_agent (str, dict, opsional) — Informasi user-agent dalam bentuk kamus atau string.
  • etag_timeout (float, opsional, default 10) — Saat mengambil ETag, berapa detik menunggu server mengirim data sebelum menyerah, yang diteruskan ke httpx2.request.
  • force_download (bool, opsional, default False) — Apakah file harus diunduh meskipun sudah ada di cache lokal.
  • token (str, bool, opsional) — Token yang akan digunakan untuk unduhan.
    • Jika True, token dibaca dari folder konfigurasi HuggingFace.
    • Jika berupa string, digunakan sebagai token autentikasi.
  • headers (dict, opsional) — Header tambahan yang akan disertakan dalam permintaan. Header tersebut memiliki prioritas lebih tinggi dibandingkan header lainnya.
  • endpoint (str, opsional) — Endpoint Hub untuk mengirim permintaan. Bawaan adalah nilai dari HF_ENDPOINT.
  • local_files_only (bool, opsional, default False) — Jika True, jangan unduh file apa pun meskipun file tersebut tidak ada di cache_dir atau local_dir.
  • allow_patterns (list[str] atau str, opsional) — Jika disediakan, hanya file yang cocok dengan setidaknya satu pola yang akan diunduh.
  • ignore_patterns (list[str] atau str, opsional) — Jika diberikan, file yang cocok dengan salah satu pola tidak diunduh.
  • max_workers (int, opsional) — Jumlah thread konkuren untuk mengunduh file (1 thread = 1 unduhan file). Nilai defaultnya adalah 8.
  • tqdm_class (tqdm, opsional) — Jika diberikan, menimpa perilaku bawaan untuk progress bar. Argumen yang dilewatkan harus mewarisi dari tqdm.auto.tqdm atau setidaknya meniru perilakunya. Perhatikan bahwa tqdm_class tidak dilewatkan ke setiap unduhan individual. Bawaannya adalah progress bar HF khusus yang dapat dinonaktifkan dengan mengatur variabel lingkungan HF_HUB_DISABLE_PROGRESS_BARS.
  • dry_run (bool, opsional, defaultnya False) — Jika True, lakukan dry run tanpa benar-benar mengunduh file. Mengembalikan daftar objek DryRunFileInfo yang berisi informasi tentang apa yang akan diunduh.

Mengembalikan

str atau list dari DryRunFileInfo

  • Jika dry_run=False: Jalur snapshot lokal.
  • Jika dry_run=True: Daftar objek DryRunFileInfo yang berisi informasi unduhan.

Membuang

RepositoryNotFoundError atau RevisionNotFoundError atau IncompleteSnapshotError atau EnvironmentError atau OSError atau ValueError

  • RepositoryNotFoundError — Jika repositori yang akan diunduh tidak dapat ditemukan. Hal ini mungkin karena repositori tersebut tidak ada atau karena repositori tersebut disetel ke private dan Anda tidak memiliki akses.
  • RevisionNotFoundError — Jika revisi yang akan diunduh tidak dapat ditemukan.
  • IncompleteSnapshotError — Jika Hub tidak dapat dijangkau (offline, masalah koneksi, atau local_files_only=True) dan snapshot yang di-cache tidak memiliki beberapa file yang diminta.
  • EnvironmentError — Jika token=True dan token tidak dapat ditemukan.
  • OSError — jika ETag tidak dapat ditentukan.
  • ValueError — Jika nilai beberapa parameter tidak valid.

Unduh file repo.

Unduh seluruh snapshot file dari repositori pada revisi yang ditentukan. Ini berguna ketika Anda menginginkan semua file dari repositori karena Anda tidak tahu file mana yang akan Anda butuhkan a priori. Semua file berada di dalam folder untuk menjaga path dan nama file relatif terhadap folder tersebut. Anda juga dapat memfilter file mana yang akan diunduh dengan menggunakan allow_patterns dan ignore_patterns.

Jika local_dir disediakan, struktur file dari repo akan direplikasi di lokasi ini. Saat menggunakan opsi ini, cache_dir tidak akan digunakan, dan folder .cache/huggingface/ akan dibuat di akar local_dir untuk menyimpan beberapa metadata terkait file yang diunduh. Meskipun mekanisme ini tidak sekuat sistem cache utama, ini dioptimalkan untuk menarik versi terbaru dari repositori secara rutin.

Alternatifnya adalah meng-clone repo, tetapi ini memerlukan git dan git-lfs yang terinstal dan dikonfigurasi dengan benar. Selain itu, tidak mungkin memfilter file mana yang akan diunduh saat meng-clone repositori menggunakan git.

Baca pohon repo yang di-cache

huggingface_hub.get_cached_repo_tree

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = None ) → list[RepoFile]

Parameter

  • repo_id (str) — Nama pengguna atau organisasi dan nama repo yang dipisahkan oleh /.
  • repo_type (str, opsional) — Atur ke "dataset", "space" atau "kernel" jika mendaftar dari repo dataset, space, atau kernel, None atau "model" jika mendaftar dari model. Default adalah None.
  • revision (str, opsional) — ID revisi Git opsional, yang dapat berupa nama branch, tag, atau hash commit. Secara default menggunakan branch default. Nama branch/tag dipecahkan menjadi hash commit menggunakan cache lokal (refs/).
  • cache_dir (str, Path, opsional) — Path ke folder tempat file cache disimpan. Bawaan ke nilai HF_HUB_CACHE.
  • local_dir (str atau Path, opsional) — Jika disediakan, baca daftar pohon yang di-cache oleh unduhan local_dir (dari local_dir/.cache/huggingface/) alih-alih cache utama. Revisi branch/tag tetap dipecahkan menjadi hash commit menggunakan cache utama (cache_dir).

Mengembalikan

list[RepoFile]

Daftar objek RepoFile yang di-cache untuk revisi ini.

Membuang

CachedRepoTreeNotFoundError

  • CachedRepoTreeNotFoundError — Jika tidak ada daftar tree yang di-cache untuk revisi yang diminta (misalnya, repo tidak pernah diunduh pada revisi ini).

Kembalikan daftar pohon yang di-cache dari sebuah repo pada revisi tertentu, tanpa panggilan jaringan apa pun.

Daftar pohon adalah himpunan file (beserta metadata unduhannya) dari sebuah repo pada commit tertentu. Daftar ini diisi ke disk sebagai efek samping dari snapshot_download() (lihat file cache trees/<commit_hash>.json) dan digunakan untuk melewati panggilan jaringan pada unduhan berikutnya. Fungsi ini mengekspos cache tersebut secara langsung.

Jika Anda memerlukan daftar pohon saat ini dari repositori di Hub, gunakan list_repo_tree() sebagai gantinya.

Contoh:

>>> from huggingface_hub import get_cached_repo_tree
>>> files = get_cached_repo_tree("openai-community/gpt2")
>>> [f.path for f in files]
['.gitattributes', 'config.json', 'model.safetensors', ...]

Menyelesaikan revisi

Selesaikan nama branch/tag menjadi hash commit sekali, lalu lewati hasilnya untuk mengunci setiap unduhan ke commit yang sama. Lihat HfApi.resolve_revision() dan panduan sistem cache.

ResolvedRevision

kelas huggingface_hub.ResolvedRevision

< >

( resolved: strinitial: str | None = Nonerepo_id: str | None = Nonerepo_type: str | None = None )

Parameter

  • initial (str atau None) — Revisi yang awalnya diminta oleh pengguna. Jika None, nilai string secara default menjadi "main".
  • resolved (str) — Hash commit yang initial selesaikan.

Revisi git yang sudah dipecahkan menjadi hash commit.

ResolvedRevision adalah subkelas str, sehingga dapat diteruskan ke metode huggingface_hub mana pun yang menerima argumen revision. Nilai string-nya adalah revisi yang awalnya diminta oleh pengguna (mis. "main", "refs/pr/4"), yang membuat URL dan pesan kesalahan tetap mudah dibaca, sementara .resolved menyimpan hash commit yang ditunjuknya.

Instances dibangun oleh HfApi.resolve_revision(), yang juga meng-cache pemetaan revision -> commit hash di cache lokal (folder refs/).

Hash commit hanya memiliki makna untuk repo yang menjadi acuan resolusinya, sehingga sebuah instance juga mengingat repo tersebut. Melakukan resolusi ulang untuk repo lain bukanlah sebuah error: revisi yang awalnya diminta akan diresolusi kembali (lihat HfApi.resolve_revision()).

Contoh:

>>> from huggingface_hub import resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')
>>> revision == "main"  # it's a string
True
>>> revision.resolved
'607a30d783dfa663caf39e06633721c8d4cfcd7e'

Dapatkan metadata tentang file

get_hf_file_metadata

huggingface_hub.get_hf_file_metadata

< >

( url: strtoken: bool | str | None = Nonetimeout: float | None = 10library_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneheaders: dict[str, str] | None = Noneendpoint: str | None = Noneretry_on_errors: bool = False )

Parameter

  • url (str) — URL file, misalnya yang dikembalikan oleh hf_hub_url().
  • token (str atau bool, opsional) — Token yang akan digunakan untuk unduhan. Jika True, token dibaca dari folder konfigurasi HuggingFace. Jika False atau None, tidak ada token yang diberikan. Jika berupa string, string tersebut digunakan sebagai token autentikasi.
    • Jika True, token dibaca dari folder konfigurasi HuggingFace.
    • Jika False atau None, tidak ada token yang disediakan.
    • Jika berupa string, digunakan sebagai token autentikasi.
  • timeout (float, opsional, default 10) — Berapa detik yang ditunggu untuk server mengirim metadata sebelum menyerah.
  • library_name (str, opsional) — Nama pustaka yang sesuai dengan objek tersebut.
  • library_version (str, opsional) — Versi dari pustaka.
  • user_agent (dict, str, opsional) — Informasi user-agent dalam bentuk kamus atau string.
  • headers (dict, opsional) — Header tambahan yang akan dikirim bersama permintaan.
  • endpoint (str, opsional) — Endpoint dari Hub. Defaultnya adalah https://huggingface.co.
  • retry_on_errors (bool, opsional, default False) — Apakah akan mencoba ulang saat terjadi kesalahan (429, 5xx, timeout, kesalahan jaringan). Jika False, tidak ada percobaan ulang untuk fallback cepat ke cache lokal.

Ambil metadata dari file yang di-versikan di Hub untuk url tertentu.

HfFileMetadata

kelas huggingface_hub.HfFileMetadata

< >

( commit_hash: str | Noneetag: str | Nonelocation: strsize: int | Nonexet_file_data: huggingface_hub.utils._xet.XetFileData | None )

Parameter

  • commit_hash (str, opsional) — commit_hash yang terkait dengan file.
  • etag (str, opsional) — Etag file di server.
  • location (str) — Lokasi untuk mengunduh file. Bisa berupa url Hub atau bukan (CDN).
  • size (size) — Ukuran file. Untuk file LFS, berisi ukuran file LFS yang sebenarnya, bukan pointer.
  • xet_file_data (XetFileData, opsional) — Informasi Xet untuk file. Ini hanya diset jika file disimpan menggunakan penyimpanan Xet.

Struktur data yang berisi informasi tentang file yang di-versikan di Hub.

Dikembalikan oleh get_hf_file_metadata() berdasarkan URL.

Penyimpanan sementara

Metode yang ditampilkan di atas dirancang untuk bekerja dengan sistem cache yang mencegah unduhan ulang file. Sistem cache diperbarui pada v0.8.0 menjadi sistem cache pusat yang dibagikan di antara pustaka yang bergantung pada Hub.

Baca panduan sistem cache untuk presentasi terperinci tentang caching di HF.

Update on GitHub

←CLI Mixin & metode serialisasi→