Memahami penyangga

huggingface_hub menggunakan cache berbasis file lokal untuk menyimpan file individual yang diunduh dari Hub dan menghindari pengunduhan ulang file yang tidak berubah ketika sebuah repo diperbarui. Selain itu, hf_xet menyimpan cache shard dan data staging untuk mengoptimalkan unggahan (lihat Penyimpanan cache Xet).

Panduan ini membahas alat manajemen cache khusus Python yang disediakan oleh huggingface_hub. Untuk gambaran umum yang tidak bergantung pada bahasa tentang cara kerja sistem cache Hugging Face Hub, lihat dokumentasi Hub tentang caching lokal.

Penyimpanan sementara berbasis file

Sistem cache Hugging Face Hub dirancang sebagai cache pusat yang dibagikan di antara pustaka yang bergantung pada Hub. Sistem ini telah diperbarui di v0.8.0 untuk mencegah pengunduhan ulang file yang sama di antara revisi.

Sistem penyangga dirancang sebagai berikut:

<CACHE_DIR>
├─ <MODELS>
├─ <DATASETS>
├─ <SPACES>
├─ <KERNELS>

Nilai default <CACHE_DIR> adalah ~/.cache/huggingface/hub. Namun, ini dapat dikustomisasi dengan argumen cache_dir pada semua metode, atau dengan menentukan variabel lingkungan HF_HOME atau HF_HUB_CACHE.

Model, dataset, spaces, dan kernel berbagi akar yang sama. Masing-masing repositori ini berisi jenis repositori, namespace (organisasi atau nama pengguna) jika ada, dan nama repositori:

<CACHE_DIR>
├─ models--julien-c--EsperBERTo-small
├─ models--lysandrejik--arxiv-nlp
├─ models--bert-base-cased
├─ datasets--glue
├─ datasets--huggingface--DataMeasurementsFiles
├─ spaces--dalle-mini--dalle-mini

Di dalam folder-folder inilah semua file akan diunduh dari Hub. Caching memastikan bahwa sebuah file tidak diunduh dua kali jika file tersebut sudah ada dan tidak diperbarui; namun jika file tersebut telah diperbarui, dan Anda meminta file terbaru, maka file terbaru akan diunduh (sementara file sebelumnya tetap utuh dalam hal Anda membutuhkannya lagi).

Untuk mencapai hal ini, semua folder memiliki kerangka yang sama:

<CACHE_DIR>
├─ datasets--glue
│  ├─ refs
│  ├─ blobs
│  ├─ snapshots
│  ├─ trees
...

Setiap folder dirancang untuk berisi hal-hal berikut:

Referensi

Folder refs berisi file yang menunjukkan revisi terbaru dari referensi yang diberikan. Misalnya, jika sebelumnya kita mengambil file dari cabang main sebuah repositori, folder refs akan berisi file bernama main, yang di dalamnya berisi pengidentifikasi commit dari head saat ini.

Jika commit terbaru dari main memiliki aaaaaa sebagai identifikator, maka commit tersebut akan berisi aaaaaa.

Jika cabang yang sama tersebut diperbarui dengan commit baru yang memiliki bbbbbb sebagai identifikator, maka mengunduh ulang file dari referensi tersebut akan memperbarui file refs/main agar berisi bbbbbb.

Blobs

Folder blobs berisi file-file yang sebenarnya telah kami unduh. Nama setiap file adalah hash-nya.

Snapshot

Folder snapshots berisi symlink ke blob yang disebutkan di atas. Folder ini sendiri terdiri dari beberapa folder: satu untuk setiap revisi yang dikenal!

Pada penjelasan di atas, kami awalnya mengambil file dari revisi aaaaaa, sebelum mengambil file dari revisi bbbbbb. Dalam situasi ini, sekarang akan ada dua folder di folder snapshots: aaaaaa dan bbbbbb.

Di masing-masing folder ini, terdapat symlink aktif yang memiliki nama file yang telah kami unduh. Misalnya, jika kami telah mengunduh file README.md pada revisi aaaaaa, maka kami akan memiliki path berikut:

<CACHE_DIR>/<REPO_NAME>/snapshots/aaaaaa/README.md

File README.md itu sebenarnya adalah symlink yang mengarah ke blob yang memiliki hash dari file tersebut.

Dengan membuat kerangka dengan cara ini, kami membuka mekanisme untuk berbagi file: jika file yang sama diambil pada revisi bbbbbb, file tersebut akan memiliki hash yang sama dan tidak perlu diunduh ulang.

Pohon

Folder trees menyimpan cache daftar file yang terdapat dalam sebuah repositori pada commit tertentu. Karena commit bersifat immutable, daftar filenya tidak pernah berubah. Artinya, daftar ini dapat di-cache selamanya tanpa perlu diverifikasi ulang terhadap Hub.

Setiap daftar cache diberi nama berdasarkan hash commit dan disimpan sebagai file JSON, misalnya trees/aaaaaa.json. Untuk setiap file dalam repositori pada commit tersebut, daftar ini mencatat apa yang diperlukan untuk mengunduh file: path-nya, ukurannya, dan hash-nya. Ini adalah informasi yang sama yang akan dikembalikan oleh Hub, tetapi biasanya membutuhkan satu panggilan jaringan per file untuk mengambilnya.

Cache ini ditulis oleh snapshot_download(). Saat pertama kali Anda mengunduh sebuah commit, daftar file diambil sekali dan disimpan di sini. Pada unduhan berikutnya untuk commit yang sama, daftar dibaca dari disk alih-alih diambil ulang. Akibatnya, menjalankan ulang unduhan ketika semuanya sudah di-cache hanya membutuhkan satu panggilan jaringan: yang diperlukan untuk menyelesaikan nama branch atau tag menjadi hash commit.

Kedua snapshot_download() dan hf_hub_download() membaca cache ini untuk menghindari panggilan jaringan. Ketika Anda mengunduh file dengan commit hash sebagai revisi (ini persis yang dilakukan snapshot_download() secara internal untuk setiap file), metadata unduhan dibaca dari daftar file yang di-cache dan panggilan jaringan per file dilewati. Ini berarti hf_hub_download() untuk satu file juga diuntungkan oleh daftar file yang disimpan oleh snapshot_download() sebelumnya untuk commit yang sama.

Karena daftar file yang di-cache menjelaskan secara persis apa yang harus berisi sebuah commit, snapshot_download() juga dapat menentukan apakah snapshot lokal sudah lengkap. Jika Hub tidak dapat dijangkau (Anda offline, koneksi gagal, atau Anda meneruskan local_files_only=True) dan beberapa file yang diharapkan tidak ada di snapshot lokal, snapshot_download() akan melempar IncompleteSnapshotError alih-alih mengembalikan folder parsial. Sebelumnya, snapshot yang tidak lengkap dikembalikan secara diam-diam, yang dapat membuat Anda bekerja dengan file yang hilang tanpa menyadarinya. File yang dikecualikan oleh allow_patterns atau ignore_patterns tidak dihitung sebagai hilang. Pengecualian ini mengekspos jalur ke snapshot yang tidak lengkap melalui atribut snapshot_path-nya, sehingga Anda masih dapat menemukan file yang di-cache secara parsial jika diperlukan.

.no_exist (lanjutan)

Selain folder blobs, refs dan snapshots, Anda mungkin juga menemukan folder .no_exist di cache Anda. Folder ini melacak file yang pernah Anda coba unduh sekali tetapi tidak ada di Hub. Strukturnya sama dengan folder snapshots dengan 1 subfolder per revisi yang diketahui:

<CACHE_DIR>/<REPO_NAME>/.no_exist/aaaaaa/config_that_does_not_exist.json

Berbeda dengan folder snapshots, file di sini adalah file kosong sederhana (tanpa symlink). Dalam contoh ini, file "config_that_does_not_exist.json" tidak ada di Hub untuk revisi "aaaaaa". Karena folder ini hanya menyimpan file kosong, ukurannya dapat diabaikan dari segi penggunaan disk.

Jadi, Anda mungkin bertanya-tanya, mengapa informasi ini relevan? Dalam beberapa kasus, sebuah framework mencoba memuat file opsional untuk sebuah model. Menyimpan informasi bahwa file opsional tidak ada membuat proses pemuatan model lebih cepat karena menghemat 1 panggilan HTTP per file opsional yang mungkin ada. Hal ini misalnya terjadi di transformers di mana setiap tokenizer dapat mendukung file tambahan. Saat pertama kali Anda memuat tokenizer di mesin Anda, sistem akan meng-cache file opsional mana yang ada (dan mana yang tidak ada) untuk mempercepat waktu pemuatan pada inisialisasi berikutnya.

Untuk menguji apakah sebuah file di-cache secara lokal (tanpa membuat permintaan HTTP apa pun), Anda dapat menggunakan helper try_to_load_from_cache(). Fungsi ini akan mengembalikan filepath (jika ada dan di-cache), objek _CACHED_NO_EXIST (jika ketiadaannya di-cache) atau None (jika belum diketahui).

from huggingface_hub import try_to_load_from_cache, _CACHED_NO_EXIST

filepath = try_to_load_from_cache()
if isinstance(filepath, str):
    # file exists and is cached
    ...
elif filepath is _CACHED_NO_EXIST:
    # non-existence of file is cached
    ...
else:
    # file is not cached
    ...

Dalam praktiknya

Pada praktiknya, cache Anda harus terlihat seperti pohon berikut:

    [  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
        └── [  96]  trees
            ├── [ 521]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f.json
            └── [ 521]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48.json

CACHEDIR.TAG

huggingface_hub secara otomatis membuat file CACHEDIR.TAG di dalam direktori cache. Tag ini mengikuti Cache Directory Tagging Standard dan memberi tahu alat backup (misalnya Borg, restic, rsync) bahwa direktori tersebut berisi data cache yang dapat diunduh ulang dan dapat dikecualikan dari backup dengan aman.

Keterbatasan

Agar sistem cache efisien, huggingface-hub menggunakan symlink. Namun, symlink tidak didukung di semua mesin. Ini adalah keterbatasan yang dikenal, terutama di Windows. Dalam kasus ini, huggingface_hub tidak menggunakan direktori blobs/ tetapi menyimpan file secara langsung di direktori snapshots/. Workaround ini memungkinkan pengguna untuk mengunduh dan meng-cache file dari Hub dengan cara yang persis sama. Alat untuk memeriksa dan menghapus cache (lihat di bawah) juga didukung. Namun, sistem cache menjadi kurang efisien karena satu file mungkin diunduh beberapa kali jika beberapa revisi dari repo yang sama diunduh.

Jika Anda ingin memanfaatkan sistem cache berbasis symlink pada mesin Windows, Anda perlu mengaktifkan Developer Mode atau menjalankan Python sebagai administrator.

Jika Anda ingin secara proaktif menggunakan mode cache tanpa symlink (misalnya pada sistem berkas bersama yang tidak menangani symlink dengan baik), Anda dapat mengatur variabel lingkungan HF_HUB_DISABLE_SYMLINKS menjadi 1. Berkas akan disalin langsung ke snapshots/ alih-alih membuat symlink ke blobs/.

Ketika symlink tidak didukung, pesan peringatan ditampilkan kepada pengguna untuk memberi tahu bahwa mereka menggunakan versi cache-system yang terdegradasi. Peringatan ini dapat dinonaktifkan dengan mengatur variabel lingkungan HF_HUB_DISABLE_SYMLINKS_WARNING ke true.

Blobs bersama antar repositori

Secara default, file Xet juga dideduplikasi antar repositori. File Xet yang diunduh melalui hf_xet disimpan sekali di <CACHE_DIR>/blobs/<prefix>/<xet_hash>, dan entri blobs/<etag> repositori tersebut adalah symlink relatif ke file tersebut. Ketika repositori lain membutuhkan file yang sama, ia akan mendapatkan symlink alih-alih mengunduh: tidak ada byte yang ditransfer dan tidak ada ruang ekstra yang digunakan. Tata letak snapshot tidak berubah. File penanda mengidentifikasi store, sehingga direktori blobs yang tidak dibuat oleh huggingface_hub tidak akan pernah disentuh.

Setiap file bersama memiliki manifest <xet_hash>.refs yang mencantumkan blob repo yang menggunakannya. hf cache rm membacanya untuk memeriksa hanya file bersama yang terdampak oleh penghapusan, dan hf cache prune menghapus file bersama yang tidak lagi digunakan oleh repo mana pun yang di-cache. Manifest ini hanya berupa petunjuk: setiap entri diperiksa terhadap sistem file, dan file dengan metadata yang hilang atau tidak dapat dibaca akan dipertahankan. Pembersihan lebih memilih meninggalkan data yang dapat dikembalikan daripada merusak entri cache yang valid.

Ukuran per-repo tetap logis, sehingga file bersama dihitung untuk setiap repo yang menggunakannya. size_on_disk di seluruh cache bersifat fisik: setiap file bersama dihitung sekali, termasuk file yang tidak lagi digunakan oleh repo mana pun.

Klien lama (huggingface_hub, huggingface.js, hf-hub, llama.cpp, dan apa pun yang mengikuti symlink) tetap membaca dan mengunduh secara normal, di folder repo yang sama. Dua keterbatasan:

huggingface_hub<=1.31 meninggalkan file bersama dari repo yang dihapus di dalam store, di mana hf cache ls menandainya dan hf cache prune menghapusnya. Alat penghapusan cache klien lain mungkin justru menghapus file bersama yang masih digunakan oleh repo lain; file yang terpengaruh akan diunduh ulang saat digunakan berikutnya. Gunakan huggingface_hub yang mutakhir untuk hf cache rm, hf cache prune, dan penghapusan programatik.
Pemindai cache mereka mungkin melaporkan direktori blobs tingkat atas sebagai entri yang tidak dikenal.

Store memerlukan tata letak cache berbasis symlink dan dinonaktifkan oleh HF_HUB_DISABLE_XET=1. Kegagalan apa pun dalam berbagi file, seperti sistem file yang tidak didukung, error izin, atau direktori blobs yang sudah ada tanpa penanda, akan secara diam-diam kembali ke penyimpanan lokal repo biasa. Atur HF_HUB_DISABLE_SHARED_BLOBS=1 untuk sepenuhnya keluar dari fitur ini.

Pin revisi (lanjutan)

Jika Anda mengintegrasikan Hub ke dalam pustaka ML, satu panggilan snapshot_download() tetap menjadi pendekatan yang direkomendasikan: panggilan ini menyelesaikan revisi sekali, mengunduh semuanya secara paralel, dan meng-cache daftar file. Yang berikut hanya berguna untuk pustaka kompleks yang mengunduh dan memuat banyak komponen secara terpisah (config, weights, tokenizer, processor, adapters, …) dan tidak dapat menggunakan satu panggilan tunggal.

Ketika sebuah pustaka mengunduh beberapa file satu per satu, setiap panggilan harus menyelesaikan revision="main" menjadi hash commit lagi. Hal ini memakan satu panggilan HTTP per file dan, yang lebih buruk, dua panggilan yang dibuat beberapa detik terpisah dapat mendarat pada dua commit yang berbeda jika repositori diperbarui di antaranya.

HfApi.resolve_revision() menyelesaikan revisi sekali dan mengembalikan ResolvedRevision:

>>> from huggingface_hub import resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')

ResolvedRevision adalah subclass dari str, sehingga dapat diteruskan ke metode huggingface_hub mana pun yang menerima argumen revision. Nilai string-nya adalah apa yang diminta pengguna pada awalnya ("main" di sini, sehingga pesan error mudah dibaca), sedangkan .resolved menyimpan hash commit:

>>> revision == "main"
True
>>> revision.resolved
'607a30d783dfa663caf39e06633721c8d4cfcd7e'

Helper unduhan (hf_hub_download(), snapshot_download(), get_cached_repo_tree()) mendeteksi ResolvedRevision dan menggunakan hash commit secara langsung. Setiap file dijamin berasal dari commit yang sama, dan setelah file di-cache, tidak ada panggilan HTTP yang diperlukan sama sekali:

>>> from huggingface_hub import hf_hub_download
>>> config = hf_hub_download("openai-community/gpt2", "config.json", revision=revision)
>>> weights = hf_hub_download("openai-community/gpt2", "model.safetensors", revision=revision)

Pemetaan revision -> commit hash juga ditulis ke folder refs/ dari cache (lihat Refs). Ini berarti bahwa jika Hub tidak dapat dijangkau kemudian (mode offline, error koneksi, timeout, downtime Hub), HfApi.resolve_revision() secara transparan kembali ke nilai yang di-cache. Jika tidak ada yang di-cache, RevisionResolutionError akan dilempar.

Hash commit hanya memiliki makna untuk repo tempat ia di-resolve, dan helper download menggunakannya apa adanya. Oleh karena itu, ResolvedRevision hanya boleh diteruskan ke repo tempat ia di-resolve. Jika sebuah library juga mengunduh dari repo lain (model dasar, adapter, komponen yang berada di repo-nya sendiri, …), ia memerlukan revisi yang di-resolve untuk repo tersebut. Cukup teruskan ResolvedRevision kembali ke HfApi.resolve_revision(): ia mengingat repo mana yang dimilikinya dan me-resolve ulang revisi yang awalnya diminta ("main" di sini) untuk repo baru.

>>> other_revision = resolve_revision("openai-community/gpt2-medium", revision=revision)  # resolves "main" again
>>> other_revision.resolved
'6dcaa7a952f72f9298047fd5137cd6e4f05f41da'
>>> config = hf_hub_download("openai-community/gpt2-medium", "config.json", revision=other_revision)

Caching Xet

Untuk menyediakan unggahan yang lebih efisien, hf_xet menambahkan direktori xet ke cache huggingface_hub yang sudah ada. Direktori ini menyimpan shard (struktur data yang memetakan file ke chunk) dan data staging yang digunakan untuk deduplikasi dan pelanjutan unggahan. Untuk informasi lebih lanjut tentang sistem penyimpanan Xet, lihat bagian ini.

hf_xet tidak lagi menggunakan cache chunk lokal untuk unduhan. Pengaturan HF_XET_CHUNK_CACHE_SIZE_BYTES tidak mengaktifkannya. File yang diunduh masih di-cache di cache berbasis file.

Direktori xet, yang secara default berada di ~/.cache/huggingface/xet, dapat dikonfigurasi dengan HF_XET_CACHE. Strukturnya adalah sebagai berikut:

<CACHE_DIR>
├─ xet
│  ├─ environment_identifier
│  │  ├─ shard-cache
│  │  ├─ staging

Direktori environment_identifier adalah string terenkripsi (di mesin Anda, direktori ini mungkin muncul sebagai https___cas_serv-tGqkUaZf_CBPHQ6h). Hal ini digunakan selama pengembangan sehingga memungkinkan versi cache lokal dan produksi ada berdampingan secara bersamaan. Ini juga digunakan saat mengunduh dari repositori yang berada di region penyimpanan yang berbeda. Anda mungkin melihat beberapa entri seperti ini di direktori xet, masing-masing sesuai dengan lingkungan yang berbeda, tetapi struktur internalnya sama.

Direktori internal berfungsi untuk tujuan berikut:

shard-cache berisi shard yang di-cache dan digunakan pada jalur unggah.
staging adalah ruang kerja yang dirancang untuk mendukung unggahan yang dapat dilanjutkan.

Hal-hal ini didokumentasikan di bawah.

Cache shard dan data staging dikelola oleh hf_xet sebagai lapisan optimasi untuk unggahan. Untuk mengelola file yang diunduh, gunakan API cache berbasis file dari huggingface_hub.

shard-cache

Cache ini digunakan saat mengunggah konten ke Hub. Direktori ini datar, hanya terdiri dari file shard, di mana masing-masing menggunakan ID sebagai nama shard.

<CACHE_DIR>
├─ xet
│  ├─ environment_identifier
│  │  ├─ shard-cache
│  │  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb
│  │  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  │  ├─ ceeeb7ea4cf6c0a8d395a2cf9c08871211fbbd17b9b5dc1005811845307e6b8f.mdb
│  │  │  ├─ e8535155b1b11ebd894c908e91a1e14e3461dddd1392695ddc90ae54a548d8b2.mdb

shard-cache berisi shard yang:

Dihasilkan secara lokal dan berhasil diunggah ke CAS
Diunduh dari CAS sebagai bagian dari algoritma deduplikasi global

Shards menyediakan pemetaan antara file dan chunk. Selama proses unggah, setiap file dipecah menjadi chunk dan hash dari chunk tersebut disimpan. Setiap shard di cache kemudian diperiksa. Jika sebuah shard berisi hash chunk yang juga ada di file lokal yang sedang diunggah, maka chunk tersebut dapat dibuang karena sudah tersimpan di CAS.

Semua shard memiliki tanggal kedaluwarsa 3-4 minggu sejak diunduh. Shard yang sudah kedaluwarsa tidak dimuat saat upload dan dihapus satu minggu setelah kedaluwarsa.

staging

Ketika unggahan berakhir sebelum konten baru dikomit ke repositori, Anda perlu melanjutkan transfer file. Namun, dimungkinkan bahwa beberapa chunk berhasil diunggah sebelum interupsi terjadi.

Agar Anda tidak perlu memulai ulang dari awal, direktori staging berfungsi sebagai ruang kerja selama proses unggah, menyimpan metadata untuk chunk yang berhasil diunggah. Direktori staging memiliki bentuk sebagai berikut:

<CACHE_DIR>
├─ xet
│  ├─ environment_identifier
│  │  ├─ staging
│  │  │  ├─ shard-session
│  │  │  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  │  │  ├─ xorb-metadata
│  │  │  │  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb

Saat file diproses dan chunk berhasil diunggah, metadata-nya disimpan di xorb-metadata sebagai shard. Saat sesi unggah dilanjutkan, setiap file diproses kembali dan shard di direktori ini diperiksa. Konten yang berhasil diunggah akan dilewati, dan konten baru akan diunggah (dan metadata-nya disimpan).

Sementara itu, shard-session menyimpan informasi file dan chunk untuk file yang diproses. Setelah unggahan berhasil diselesaikan, konten dari shard-shard ini dipindahkan ke shard-cache yang lebih persisten.

Batas dan Keterbatasan

shard-cache memiliki batas lunak 16GB, yang dapat dikonfigurasi melalui variabel lingkungan HF_XET_SHARD_CACHE_SIZE_LIMIT. Tidak ada API tingkat tinggi untuk mengelola cache ini.

Cache shard dan data staging digunakan untuk mengoptimalkan unggahan. Untuk berinteraksi dengan aset itu sendiri, disarankan untuk menggunakan API sistem cache huggingface_hub.

Jika Anda perlu memulihkan ruang yang digunakan oleh Xet atau perlu men-debug masalah terkait cache, cukup hapus cache xet sepenuhnya dengan menjalankan rm -rf ~/<cache_dir>/xet di mana <cache_dir> adalah lokasi cache Hugging Face Anda, biasanya ~/.cache/huggingface

Contoh pohon direktori cache xet:

<CACHE_DIR>
├─ xet
│  ├─ environment_identifier
│  │  ├─ shard-cache
│  │  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb
│  │  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  │  ├─ ceeeb7ea4cf6c0a8d395a2cf9c08871211fbbd17b9b5dc1005811845307e6b8f.mdb
│  │  │  ├─ e8535155b1b11ebd894c908e91a1e14e3461dddd1392695ddc90ae54a548d8b2.mdb
│  │  ├─ staging
│  │  │  ├─ shard-session
│  │  │  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  │  │  ├─ xorb-metadata
│  │  │  │  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb

Untuk mempelajari lebih lanjut tentang Xet Storage, lihat bagian ini.

Meng-cache aset

Selain meng-cache file dari Hub, pustaka turunan sering kali perlu meng-cache file lain yang terkait dengan HF tetapi tidak ditangani secara langsung oleh huggingface_hub (contoh: file yang diunduh dari GitHub, data yang telah diproses, log,…). Untuk meng-cache file-file tersebut, yang disebut assets, Anda dapat menggunakan cached_assets_path(). Helper kecil ini menghasilkan path di cache HF secara terpadu berdasarkan nama pustaka yang memintanya dan, secara opsional, berdasarkan namespace dan nama subfolder. Tujuannya adalah agar setiap pustaka turunan dapat mengelola asset-nya dengan caranya sendiri (misalnya, tidak ada aturan tentang struktur) selama tetap berada di folder asset yang tepat. Pustaka-pustaka tersebut kemudian dapat memanfaatkan alat dari huggingface_hub untuk mengelola cache, khususnya memindai dan menghapus bagian dari asset melalui perintah CLI.

from huggingface_hub import cached_assets_path

assets_path = cached_assets_path(library_name="datasets", namespace="SQuAD", subfolder="download")
something_path = assets_path / "something.json" # Do anything you like in your assets folder !

cached_assets_path() adalah cara yang direkomendasikan untuk menyimpan aset, tetapi tidak wajib. Jika pustaka Anda sudah menggunakan cache-nya sendiri, silakan gunakan!

Aset dalam praktik

Pada praktiknya, cache aset Anda harus terlihat seperti pohon berikut:

    assets/
    └── datasets/
    │   ├── SQuAD/
    │   │   ├── downloaded/
    │   │   ├── extracted/
    │   │   └── processed/
    │   ├── Helsinki-NLP--tatoeba_mt/
    │       ├── downloaded/
    │       ├── extracted/
    │       └── processed/
    └── transformers/
        ├── default/
        │   ├── something/
        ├── bert-base-cased/
        │   ├── default/
        │   └── training/
    hub/
    └── models--julien-c--EsperBERTo-small/
        ├── blobs/
        │   ├── (...)
        │   ├── (...)
        ├── refs/
        │   └── (...)
        └── [ 128]  snapshots/
            ├── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/
            │   ├── (...)
            └── bbc77c8132af1cc5cf678da3f1ddf2de43606d48/
                └── (...)

Kelola cache berbasis file Anda

Periksa cache Anda

Saat ini, file yang di-cache tidak pernah dihapus dari direktori lokal Anda: ketika Anda mengunduh revisi baru dari sebuah branch, file sebelumnya tetap disimpan dalam hal Anda membutuhkannya lagi. Oleh karena itu, dapat berguna untuk memeriksa direktori cache Anda guna mengetahui repo dan revisi mana yang menggunakan ruang disk paling banyak. huggingface_hub menyediakan helper yang dapat Anda gunakan dari CLI hf atau dari Python.

Periksa cache dari terminal

Jalankan hf cache ls untuk menjelajahi apa yang disimpan secara lokal. Secara default, perintah ini mengagregasi informasi berdasarkan repositori:

➜ hf cache ls
ID                                   SIZE   LAST_ACCESSED LAST_MODIFIED REFS
------------------------------------ ------- ------------- ------------- -------------------
dataset/glue                         116.3K 4 days ago     4 days ago     2.4.0 main 1.17.0
dataset/google/fleurs                 64.9M 1 week ago     1 week ago     main refs/pr/1
model/Jean-Baptiste/camembert-ner    441.0M 2 weeks ago    16 hours ago   main
model/bert-base-cased                  1.9G 1 week ago     2 years ago
model/t5-base                          10.1K 3 months ago   3 months ago   main
model/t5-small                        970.7M 3 days ago     3 days ago     main refs/pr/1

Found 6 repo(s) for a total of 12 revision(s) and 3.4G on disk.

Tambahkan --revisions untuk menampilkan setiap snapshot yang di-cache, lalu gunakan filter berantai untuk fokus pada hal yang penting. Filter memahami ukuran dan durasi yang ramah pengguna, sehingga ekspresi seperti size>1GB atau accessed>30d langsung berfungsi:

➜ hf cache ls --revisions --filter "size>1GB" --filter "accessed>30d"
ID                                   REVISION            SIZE   LAST_MODIFIED REFS
------------------------------------ ------------------ ------- ------------- -------------------
model/bert-base-cased                6d1d7a1a2a6cf4c2    1.9G  2 years ago
model/t5-small                       1c610f6b3f5e7d8a    1.1G  3 months ago  main

Found 2 repo(s) for a total of 2 revision(s) and 3.0G on disk.

Butuh output yang ramah mesin? Gunakan --format json untuk mendapatkan objek terstruktur atau --format csv untuk spreadsheet. Sebagai alternatif, --quiet hanya mencetak identifier (satu per baris) sehingga Anda dapat memipenya ke tooling lain. Gunakan --sort untuk mengurutkan entri berdasarkan accessed, modified, name, atau size (tambahkan :asc atau :desc untuk mengontrol urutan), dan --limit untuk membatasi hasil ke N entri teratas. Gabungkan opsi-opsi ini dengan --cache-dir ketika Anda perlu memeriksa cache yang disimpan di luar HF_HOME.

Filter dengan alat shell umum

Output tabular berarti Anda dapat terus menggunakan alat yang sudah Anda kenal. Misalnya, potongan kode di bawah ini menemukan semua revisi yang di-cache terkait t5-small:

➜ eval "hf cache ls --revisions" | grep "t5-small"
model/t5-small                       1c610f6b3f5e7d8a    1.1G  3 months ago  main
model/t5-small                       8f3ad1c90fed7a62    820.1M 2 weeks ago   refs/pr/1

Periksa cache dari Python

Untuk penggunaan yang lebih lanjut, gunakan scan_cache_dir() yang merupakan utilitas python yang dipanggil oleh alat CLI.

Anda dapat menggunakannya untuk mendapatkan laporan terperinci yang disusun di sekitar 4 dataclass:

HFCacheInfo: laporan lengkap yang dikembalikan oleh scan_cache_dir()
CachedRepoInfo: informasi tentang repositori yang di-cache
CachedRevisionInfo: informasi tentang revisi yang di-cache (misalnya “snapshot”) di dalam repositori
CachedFileInfo: informasi tentang file yang di-cache dalam sebuah snapshot

Berikut adalah contoh penggunaan sederhana. Lihat referensi untuk detailnya.

>>> from huggingface_hub import scan_cache_dir

>>> hf_cache_info = scan_cache_dir()
HFCacheInfo(
    size_on_disk=3398085269,
    repos=frozenset({
        CachedRepoInfo(
            repo_id='t5-small',
            repo_type='model',
            repo_path=PosixPath(...),
            size_on_disk=970726914,
            nb_files=11,
            last_accessed=1662971707.3567169,
            last_modified=1662971107.3567169,
            revisions=frozenset({
                CachedRevisionInfo(
                    commit_hash='d78aea13fa7ecd06c29e3e46195d6341255065d5',
                    size_on_disk=970726339,
                    snapshot_path=PosixPath(...),
                    # No `last_accessed` as blobs are shared among revisions
                    last_modified=1662971107.3567169,
                    files=frozenset({
                        CachedFileInfo(
                            file_name='config.json',
                            size_on_disk=1197
                            file_path=PosixPath(...),
                            blob_path=PosixPath(...),
                            blob_last_accessed=1662971707.3567169,
                            blob_last_modified=1662971107.3567169,
                        ),
                        CachedFileInfo(...),
                        ...
                    }),
                ),
                CachedRevisionInfo(...),
                ...
            }),
        ),
        CachedRepoInfo(...),
        ...
    }),
    warnings=[
        CorruptedCacheException("Snapshots dir doesn't exist in cached repo: ..."),
        CorruptedCacheException(...),
        ...
    ],
)

Verifikasi cache Anda

huggingface_hub dapat memverifikasi bahwa file cache Anda cocok dengan checksum di Hub. Gunakan CLI hf cache verify untuk memvalidasi konsistensi file untuk revisi tertentu dari repositori tertentu:

>>> hf cache verify meta-llama/Llama-3.2-1B-Instruct
✅ Verified 13 file(s) for 'meta-llama/Llama-3.2-1B-Instruct' (model) in ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct/snapshots/9213176726f574b556790deb65791e0c5aa438b6
  All checksums match.

Verifikasi revisi cache tertentu:

>>> hf cache verify meta-llama/Llama-3.1-8B-Instruct --revision 0e9e39f249a16976918f6564b8830bc894c89659

Periksa referensi CLI hf cache verify untuk detail lebih lanjut tentang penggunaan dan daftar lengkap opsi.

Bersihkan cache Anda

Memindai cache Anda memang menarik, tetapi yang biasanya ingin Anda lakukan selanjutnya adalah menghapus sebagian cache untuk membebaskan ruang di drive Anda. Hal ini dapat dilakukan menggunakan perintah CLI hf cache rm dan hf cache prune. Anda juga dapat menggunakan helper delete_revisions() dan delete_files() secara programatik dari objek HFCacheInfo yang dikembalikan saat memindai cache.

Strategi penghapusan

Untuk menghapus sebagian cache, Anda perlu meneruskan daftar revisi yang akan dihapus. Alat ini akan menentukan strategi untuk membebaskan ruang berdasarkan daftar ini. Alat ini mengembalikan objek DeleteCacheStrategy yang menjelaskan file dan folder mana yang akan dihapus. DeleteCacheStrategy memungkinkan Anda mengetahui berapa banyak ruang yang diperkirakan akan dibebaskan. Setelah Anda menyetujui penghapusan, Anda harus mengeksekusinya agar penghapusan tersebut berlaku. Untuk menghindari ketidaksesuaian, Anda tidak dapat mengedit objek strategi secara manual.

Strategi untuk menghapus revisi adalah sebagai berikut:

folder snapshot yang berisi symlink revisi dihapus.
file blobs yang hanya ditargetkan oleh revisi yang akan dihapus juga akan dihapus.
jika sebuah revisi terhubung ke satu atau lebih refs, referensi akan dihapus.
jika semua revisi dari sebuah repo dihapus, seluruh repositori yang di-cache akan dihapus.

Menghapus file individual dengan delete_files() mengikuti logika yang sama: entri snapshot dihapus, dan blob-nya dihapus hanya jika tidak ada file cache lain yang merujuknya. Refs dan folder snapshot tetap dipertahankan.

Hash revisi bersifat unik di seluruh repositori. hf cache rm karenanya menerima pengidentifikasi repositori (misalnya model/bert-base-uncased) atau hash revisi polos; saat meneruskan hash, Anda tidak perlu menentukan repositori secara terpisah.

Jika revisi tidak ditemukan di cache, revisi tersebut akan diabaikan secara diam-diam. Selain itu, jika file atau folder tidak ditemukan saat upaya penghapusan, peringatan akan dicatat tetapi tidak ada error yang dilempar. Penghapusan akan dilanjutkan untuk path lain yang terkandung dalam objek DeleteCacheStrategy.

Bersihkan cache dari terminal

Gunakan hf cache rm untuk menghapus permanen repositori atau revisi dari cache Anda. Sampaikan satu atau lebih pengidentifikasi repositori (misalnya model/bert-base-uncased) atau hash revisi:

➜ hf cache rm model/bert-base-cased
About to delete 1 repo(s) totalling 1.9G.
  - model/bert-base-cased (entire repo)
Proceed with deletion? [y/N]: y
Deleted 1 repo(s) and 1 revision(s); freed 1.9G.

Anda juga dapat menggunakan hf cache rm dalam kombinasi dengan hf cache ls --quiet untuk menghapus massal entri yang diidentifikasi oleh filter:

>>> hf cache rm $(hf cache ls --filter "accessed>1y" -q) -y
About to delete 2 repo(s) totalling 5.31G.
  - model/meta-llama/Llama-3.2-1B-Instruct (entire repo)
  - model/hexgrad/Kokoro-82M (entire repo)
Deleted 2 repo(s) and 2 revision(s); freed 5.31G.

Campurkan repositori dan revisi dalam panggilan yang sama. Tambahkan --dry-run untuk melihat pratinjau dampaknya, atau --yes untuk melewati prompt konfirmasi saat membuat skrip:

➜ hf cache rm model/t5-small 8f3ad1c --dry-run
About to delete 1 repo(s) and 1 revision(s) totalling 1.1G.
  - model/t5-small:
      8f3ad1c [main] 1.1G
Dry run: no files were deleted.

Untuk menghapus satu file alih-alih seluruh repositori, misalnya satu kuantisasi GGUF, lalu lewati URI file hf://. File tersebut dihapus dari setiap revisi repositori yang di-cache, dan blob-nya dihapus hanya jika tidak ada file cache lain yang masih merujuknya. Revisi tetap dapat digunakan, dan file yang dihapus akan diunduh kembali saat dibutuhkan berikutnya. Path harus cocok persis: folder dan pola glob tidak didukung.

➜ hf cache rm hf://models/unsloth/gemma-3-27b-it-GGUF/gemma-3-27b-it-Q4_K_M.gguf --dry-run
About to delete 1 file(s) totalling 16.5G.
  - model/unsloth/gemma-3-27b-it-GGUF@3f4b5c1d2e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c/gemma-3-27b-it-Q4_K_M.gguf
Dry run: no files were deleted.

Saat bekerja di luar lokasi cache default, gunakan perintah tersebut bersama dengan --cache-dir PATH.

Untuk membersihkan sampah cache secara massal, jalankan hf cache prune. Perintah ini secara otomatis menghapus revisi yang tidak lagi dirujuk oleh branch atau tag, file .incomplete yang tersisa dari unduhan yang terputus, serta blob bersama yang tidak lagi dirujuk oleh repo mana pun yang di-cache:

➜ hf cache prune
About to delete 3 unreferenced revision(s) and 2 incomplete download(s) (2.4G total).
  - model/t5-small:
      1c610f6b [refs/pr/1] 820.1M
      d4ec9b72 [(detached)] 640.5M
  - dataset/google/fleurs:
      2b91c8dd [(detached)] 937.6M
Proceed? [y/N]: y
Deleted 3 unreferenced revision(s) and 2 incomplete download(s); freed 2.4G.

File .incomplete adalah blob parsial yang tersisa ketika unduhan terputus. File ini tidak dilacak oleh pemindaian berbasis revisi, sehingga hf cache ls hanya menandainya dengan petunjuk (Found X incomplete download(s) ...) sementara hf cache prune adalah perintah yang benar-benar menghapusnya. hf cache rm tidak pernah menyentuh file tersebut, kecuali saat menghapus seluruh repo.

Kedua perintah mendukung --dry-run, --yes, dan --cache-dir sehingga Anda dapat pratinjau, mengotomatiskan, dan menargetkan direktori cache alternatif sesuai kebutuhan.

Bersihkan cache dari Python

Untuk fleksibilitas yang lebih besar, Anda juga dapat menggunakan metode delete_revisions() secara programatik. Berikut adalah contoh sederhana. Lihat referensi untuk detailnya.

>>> from huggingface_hub import scan_cache_dir

>>> delete_strategy = scan_cache_dir().delete_revisions(
...     "81fd1d6e7847c99f5862c9fb81387956d99ec7aa"
...     "e2983b237dccf3ab4937c97fa717319a9ca1a96d",
...     "6c0e6080953db56375760c0471a8c5f2929baf11",
... )
>>> print("Will free " + delete_strategy.expected_freed_size_str)
Will free 8.6G

>>> delete_strategy.execute()

Update on GitHub

Hub Python Library

Memahami penyangga

Penyimpanan sementara berbasis file

Referensi

Blobs

Snapshot

Pohon

.no_exist (lanjutan)

Dalam praktiknya

CACHEDIR.TAG

Keterbatasan

Blobs bersama antar repositori

Pin revisi (lanjutan)

Caching Xet

shard-cache

staging

Batas dan Keterbatasan

Meng-cache aset

Aset dalam praktik

Kelola cache berbasis file Anda

Periksa cache Anda

Verifikasi cache Anda

Bersihkan cache Anda