Unduh file dari Hub

Perpustakaan huggingface_hub menyediakan fungsi untuk mengunduh file dari repositori yang disimpan di Hub. Anda dapat menggunakan fungsi-fungsi ini secara mandiri atau mengintegrasikannya ke dalam perpustakaan Anda sendiri, sehingga lebih memudahkan pengguna Anda untuk berinteraksi dengan Hub. Panduan ini akan menunjukkan cara:

• Unduh dan simpan satu file ke cache.
• Unduh dan simpan cache seluruh repositori.
• Unduh file ke folder lokal.

Unduh satu file

Fungsi hf_hub_download() adalah fungsi utama untuk mengunduh file dari Hub. Fungsi ini mengunduh file jarak jauh, meng-cache-nya di disk (dengan cara yang sadar versi), dan mengembalikan jalur file lokalnya.

Filepath yang dikembalikan adalah penunjuk ke cache lokal HF. Oleh karena itu, penting untuk tidak memodifikasi file agar cache tidak rusak. Jika Anda ingin mengetahui lebih lanjut tentang cara file di-cache, silakan lihat panduan caching kami.

Dari versi terbaru

Pilih file untuk diunduh menggunakan parameter repo_id, repo_type, dan filename. Secara default, file akan dianggap sebagai bagian dari repo model.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
'/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'

# Download from a dataset
>>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset")
'/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py'

Dari versi tertentu

Secara default, versi terbaru dari cabang main yang diunduh. Namun, dalam beberapa kasus Anda ingin mengunduh file pada versi tertentu (misalnya dari cabang tertentu, PR, tag, atau hash commit). Untuk melakukannya, gunakan parameter revision:

# Download from the `v1.0` tag
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0")

# Download from the `test-branch` branch
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch")

# Download from Pull Request #3
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3")

# Download from a specific commit hash
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a")

Catatan: Saat menggunakan hash commit, hash tersebut harus berupa hash berpanjang penuh, bukan hash commit 7 karakter.

Membangun URL unduhan

Jika Anda ingin membuat URL yang digunakan untuk mengunduh file dari repo, Anda dapat menggunakan hf_hub_url() yang mengembalikan sebuah URL. Perhatikan bahwa fungsi ini digunakan secara internal oleh hf_hub_download().

Unduh seluruh repositori

snapshot_download() mengunduh seluruh repositori pada revisi tertentu. Secara internal, fungsi ini menggunakan hf_hub_download(), yang berarti semua file yang diunduh juga di-cache di disk lokal Anda. Unduhan dilakukan secara bersamaan untuk mempercepat proses.

Untuk mengunduh seluruh repositori, cukup berikan repo_id dan repo_type:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'

# Or from a dataset
>>> snapshot_download(repo_id="google/fleurs", repo_type="dataset")
'/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34'

snapshot_download() mengunduh revisi terbaru secara default. Jika Anda ingin revisi repositori tertentu, gunakan parameter revision:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1")

Filter file untuk diunduh

snapshot_download() menyediakan cara mudah untuk mengunduh repositori. Namun, Anda tidak selalu ingin mengunduh seluruh konten repositori. Misalnya, Anda mungkin ingin mencegah pengunduhan semua file .bin jika Anda tahu hanya akan menggunakan bobot .safetensors. Anda dapat melakukannya menggunakan parameter allow_patterns dan ignore_patterns.

Parameter ini menerima satu pola atau daftar pola. Pola adalah Standard Wildcards (pola globbing) seperti yang didokumentasikan di sini. Pencocokan pola didasarkan pada fnmatch.

Sebagai contoh, Anda dapat menggunakan allow_patterns untuk hanya mengunduh file konfigurasi JSON:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json")

Di sisi lain, ignore_patterns dapat mengecualikan file tertentu dari proses unduhan. Contoh berikut mengabaikan ekstensi file .msgpack dan .h5:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"])

Terakhir, Anda dapat menggabungkan keduanya untuk memfilter unduhan Anda secara presisi. Berikut adalah contoh untuk mengunduh semua file json dan markdown kecuali vocab.json.

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json")

Unduh file ke folder lokal

Secara default, kami merekomendasikan penggunaan sistem cache untuk mengunduh file dari Hub. Anda dapat menentukan lokasi cache khusus menggunakan parameter cache_dir di hf_hub_download() dan snapshot_download(), atau dengan mengatur variabel lingkungan HF_HOME.

Namun, jika Anda perlu mengunduh file ke folder tertentu, Anda dapat meneruskan parameter local_dir ke fungsi unduhan. Hal ini berguna untuk membuat alur kerja lebih mendekati apa yang ditawarkan oleh perintah git. File yang diunduh akan mempertahankan struktur file aslinya di dalam folder yang ditentukan. Misalnya, jika filename="data/train.csv" dan local_dir="path/to/folder", filepath yang dihasilkan akan menjadi "path/to/folder/data/train.csv".

Folder .cache/huggingface/ dibuat di akar direktori lokal Anda yang berisi metadata tentang file yang diunduh. Hal ini mencegah pengunduhan ulang file jika file tersebut sudah mutakhir. Jika metadata telah berubah, maka versi file baru akan diunduh. Hal ini membuat local_dir dioptimalkan untuk menarik hanya perubahan terbaru.

Setelah unduhan selesai, Anda dapat dengan aman menghapus folder .cache/huggingface/ jika tidak lagi membutuhkannya. Namun, perhatikan bahwa menjalankan ulang skrip Anda tanpa folder ini dapat menyebabkan waktu pemulihan yang lebih lama, karena metadata akan hilang. Tenang, data lokal Anda akan tetap utuh dan tidak terpengaruh.

Jangan khawatir tentang folder .cache/huggingface/ saat meng-commit perubahan ke Hub! Folder ini diabaikan secara otomatis oleh git dan upload_folder().

Unduh dari CLI

Anda dapat menggunakan perintah hf download dari terminal untuk mengunduh file langsung dari Hub. Secara internal, perintah ini menggunakan helper hf_hub_download() dan snapshot_download() yang sama seperti yang dijelaskan di atas dan mencetak path yang dikembalikan ke terminal.

>>> hf download gpt2 config.json
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json

Anda dapat mengunduh beberapa file sekaligus, yang menampilkan bilah progres dan mengembalikan jalur snapshot tempat file-file tersebut berada:

>>> hf download gpt2 config.json model.safetensors
Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10

Anda juga dapat menunjuk ke repo (dan opsionalnya revisi dan file) menggunakan satu URI hf://. URI mengikuti tata bahasa hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (lihat referensi HF URIs untuk sintaks lengkap) dan menggantikan opsi --repo-type dan --revision, yang tidak dapat diset bersamaan dengannya:

# Download a single file from a dataset at a given revision
>>> hf download hf://datasets/google/fleurs@refs/pr/1/fleurs.py

# Download a subfolder (note the trailing slash)
>>> hf download hf://datasets/google/fleurs/data/

# Download an entire repo
>>> hf download hf://datasets/google/fleurs

Untuk detail lebih lanjut tentang perintah unduhan CLI, silakan merujuk ke panduan CLI.

Mode uji coba

Dalam beberapa kasus, Anda mungkin ingin memeriksa file mana yang akan diunduh sebelum benar-benar mengunduhnya. Anda dapat memeriksa ini menggunakan parameter --dry-run. Parameter ini mendaftar semua file yang akan diunduh di repo dan memeriksa apakah file tersebut sudah diunduh atau belum. Hal ini memberikan gambaran tentang berapa banyak file yang harus diunduh dan ukuran masing-masing file.

Berikut adalah contoh, memeriksa pada satu file:

>>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run
[dry-run] Will download 1 files (out of 1) totalling 655.2M
File                           Bytes to download
------------------------------ -----------------
onnx/decoder_model_merged.onnx 655.2M

Dan jika file sudah di-cache:

>>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run
[dry-run] Will download 0 files (out of 1) totalling 0.0.
File                           Bytes to download
------------------------------ -----------------
onnx/decoder_model_merged.onnx -

Anda juga dapat menjalankan dry-run pada seluruh repositori:

>>> hf download openai-community/gpt2 --dry-run
[dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00,  6.26it/s]
[dry-run] Will download 11 files (out of 26) totalling 5.6G.
File                              Bytes to download
--------------------------------- -----------------
.gitattributes                    -
64-8bits.tflite                   125.2M
64-fp16.tflite                    248.3M
64.tflite                         495.8M
README.md                         -
config.json                       -
flax_model.msgpack                497.8M
generation_config.json            -
merges.txt                        -
model.safetensors                 548.1M
onnx/config.json                  -
onnx/decoder_model.onnx           653.7M
onnx/decoder_model_merged.onnx    655.2M
onnx/decoder_with_past_model.onnx 653.7M
onnx/generation_config.json       -
onnx/merges.txt                   -
onnx/special_tokens_map.json      -
onnx/tokenizer.json               -
onnx/tokenizer_config.json        -
onnx/vocab.json                   -
pytorch_model.bin                 548.1M
rust_model.ot                     702.5M
tf_model.h5                       497.9M
tokenizer.json                    -
tokenizer_config.json             -
vocab.json                        -

Dan dengan penyaringan file:

>>> hf download openai-community/gpt2 --include "*.json"  --dry-run
[dry-run] Fetching 11 files: 100%|█████████████| 11/11 [00:00<00:00, 80518.92it/s]
[dry-run] Will download 0 files (out of 11) totalling 0.0.
File                         Bytes to download
---------------------------- -----------------
config.json                  -
generation_config.json       -
onnx/config.json             -
onnx/generation_config.json  -
onnx/special_tokens_map.json -
onnx/tokenizer.json          -
onnx/tokenizer_config.json   -
onnx/vocab.json              -
tokenizer.json               -
tokenizer_config.json        -
vocab.json                   -

Terakhir, Anda juga dapat melakukan dry-run secara programatik dengan meneruskan dry_run=True ke hf_hub_download() dan snapshot_download(). Fungsi tersebut akan mengembalikan DryRunFileInfo (atau daftar DryRunFileInfo) yang berisi, untuk setiap file, commit hash, nama file, dan ukuran file, serta apakah file tersebut sudah di-cache dan apakah file akan diunduh. Dalam praktiknya, file akan diunduh jika belum di-cache atau jika force_download=True diteruskan.

Unduhan lebih cepat

Manfaatkan unduhan yang lebih cepat melalui hf_xet, pengikatan Python ke pustaka xet-core yang memungkinkan deduplikasi berbasis chunk untuk unduhan dan unggahan yang lebih cepat. hf_xet terintegrasi dengan mulus ke huggingface_hub, tetapi menggunakan pustaka Rust xet-core dan penyimpanan Xet alih-alih LFS.

hf_xet menggunakan sistem penyimpanan Xet, yang memecah file menjadi chunk yang tidak dapat diubah (immutable), menyimpan kumpulan chunk tersebut (disebut block atau xorb) secara remote, dan mengambilnya untuk merakit ulang file saat diminta. Saat mengunduh, setelah memastikan pengguna memiliki otorisasi untuk mengakses file, hf_xet akan menanyakan layanan content-addressable (CAS) Xet dengan hash LFS SHA256 untuk file ini guna menerima metadata rekonstruksi (range di dalam xorb) untuk merakit file-file tersebut, beserta presigned URL untuk mengunduh xorb secara langsung. Kemudian hf_xet akan mengunduh range xorb yang diperlukan secara efisien dan akan menulis file ke disk.

Untuk mengaktifkannya, cukup instal versi terbaru dari huggingface_hub:

pip install -U "huggingface_hub"

Sejak huggingface_hub 0.32.0, ini juga akan menginstal hf_xet.

Semua API huggingface_hub lainnya akan tetap berfungsi tanpa modifikasi apa pun. Untuk mempelajari lebih lanjut tentang manfaat penyimpanan Xet dan hf_xet, lihat bagian ini.

Catatan: hf_transfer sebelumnya digunakan dengan backend penyimpanan LFS dan sekarang tidak lagi didukung; gunakan hf_xet sebagai gantinya.