# 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](#xet-caching)).

> [!TIP]
> 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](https://huggingface.co/docs/hub/local-cache).

## 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 tipe 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
```

Semua file kini akan diunduh dari Hub ke dalam folder-folder tersebut. 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 dipertahankan dalam keadaan 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()](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.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()](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.snapshot_download) dan [hf_hub_download()](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.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()](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.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()](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.hf_hub_download) untuk satu file juga diuntungkan oleh daftar file yang disimpan oleh [snapshot_download()](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.snapshot_download) sebelumnya untuk commit yang sama.

Karena daftar file yang di-cache menjelaskan secara persis apa yang harus berisi sebuah commit, [snapshot_download()](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.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()](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.snapshot_download) akan melempar [IncompleteSnapshotError](/docs/huggingface_hub/main/id/package_reference/utilities#huggingface_hub.errors.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 pada `transformers` di mana setiap tokenizer dapat mendukung file tambahan. Pada saat pertama kali Anda memuat tokenizer di mesin Anda, sistem akan meng-cache file opsional mana yang ada (dan mana yang tidak) 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()](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.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).

```python
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:

```text
    [  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`](https://bford.info/cachedir/) 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](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) 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`](../package_reference/environment_variables#hfhubdisablesymlinks) menjadi `1`. Berkas akan disalin langsung ke `snapshots/` alih-alih membuat symlink ke `blobs/`.

Jika 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`](../package_reference/environment_variables#hfhubdisablesharedblobs) untuk sepenuhnya keluar dari fitur ini.

## Pin revisi (lanjutan)

> [!TIP]
> Jika Anda mengintegrasikan Hub ke dalam pustaka ML, satu panggilan [snapshot_download()](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.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()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision) menyelesaikan revisi sekali dan mengembalikan [ResolvedRevision](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.ResolvedRevision):

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

[ResolvedRevision](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.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:

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

Helper unduhan ([hf_hub_download()](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.hf_hub_download), [snapshot_download()](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.snapshot_download), [get_cached_repo_tree()](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.get_cached_repo_tree)) mendeteksi [ResolvedRevision](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.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:

```py
>>> 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](#refs)). Ini berarti bahwa jika Hub tidak dapat dijangkau kemudian (mode offline, error koneksi, timeout, downtime Hub), [HfApi.resolve_revision()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision) secara transparan kembali ke nilai yang di-cache. Jika tidak ada yang di-cache, [RevisionResolutionError](/docs/huggingface_hub/main/id/package_reference/utilities#huggingface_hub.errors.RevisionResolutionError) akan dilempar.

Hash commit hanya memiliki makna untuk repo tempat ia di-resolve, dan helper download menggunakannya apa adanya. Oleh karena itu, [ResolvedRevision](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.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](/docs/huggingface_hub/main/id/package_reference/file_download#huggingface_hub.ResolvedRevision) kembali ke [HfApi.resolve_revision()](/docs/huggingface_hub/main/id/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision): ia mengingat repo mana yang dimilikinya dan me-resolve ulang revisi yang awalnya diminta (`"main"` di sini) untuk repo baru.

```py
>>> 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](https://huggingface.co/docs/hub/xet/index) 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](#file-based-caching).

Direktori `xet`, yang secara default berada di `~/.cache/huggingface/xet`, dapat dikonfigurasi dengan [`HF_XET_CACHE`](../package_reference/environment_variables#hfxetcache). Strukturnya adalah sebagai berikut:

```bash
<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](https://huggingface.co/docs/hub/storage-regions) 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.

```sh
<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`](../package_reference/environment_variables#hfxetshardcachesizelimit). 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`](https://huggingface.co/docs/huggingface_hub/guides/manage-cache).

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`:

```sh
<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](https://huggingface.co/docs/hub/xet/index) 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()](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.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 cara 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.

```py
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 !
```

> [!TIP]
> [cached_assets_path()](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.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:

```text
    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: saat 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:

```text
➜ 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:

```text
➜ 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`:

```text
➜ 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()](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.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](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.HFCacheInfo): laporan lengkap yang dikembalikan oleh [scan_cache_dir()](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.scan_cache_dir)
- [CachedRepoInfo](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.CachedRepoInfo): informasi tentang repositori yang di-cache
- [CachedRevisionInfo](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.CachedRevisionInfo): informasi tentang revisi yang di-cache (misalnya "snapshot") di dalam repositori
- [CachedFileInfo](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.CachedFileInfo): informasi tentang file yang di-cache dalam sebuah snapshot

Berikut adalah contoh penggunaan sederhana. Lihat referensi untuk detailnya.

```py
>>> 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:

```bash
>>> 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:

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

> [!TIP]
> Periksa [referensi CLI `hf cache verify`](../package_reference/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 data 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()](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.HFCacheInfo.delete_revisions) dan [delete_files()](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.HFCacheInfo.delete_files) secara programatik dari objek [HFCacheInfo](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.HFCacheInfo) yang dikembalikan saat memindai cache.

**Strategi penghapusan**

Untuk menghapus sebagian cache, Anda perlu meneruskan daftar revisi yang akan dihapus. Alat ini akan mendefinisikan strategi untuk membebaskan ruang berdasarkan daftar tersebut. Alat ini mengembalikan objek [DeleteCacheStrategy](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.DeleteCacheStrategy) yang menjelaskan file dan folder mana yang akan dihapus. [DeleteCacheStrategy](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.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()](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.HFCacheInfo.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.

> [!TIP]
> 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.

> [!WARNING]
> 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](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.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:

```text
➜ 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:

```bash
>>> 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 satu panggilan. Tambahkan `--dry-run` untuk melihat pratinjau dampaknya, atau `--yes` untuk melewati prompt konfirmasi saat membuat skrip:

```text
➜ 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, berikan 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.

```text
➜ 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:

```text
➜ 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()](/docs/huggingface_hub/main/id/package_reference/cache#huggingface_hub.HFCacheInfo.delete_revisions) secara programatik. Berikut adalah contoh sederhana. Lihat referensi untuk detailnya.

```py
>>> 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()
```