了解快取

huggingface_hub 將本地磁碟用作兩種快取，以避免重複下載項目。第一種是基於檔案的快取，它會快取從 Hub 下載的單個檔案，並確保在儲存庫（repo）更新時不會重複下載相同的檔案。第二種是區塊（chunk）快取，每個區塊代表檔案中的一個位元組範圍，並確保跨檔案共享的區塊僅被下載一次。

本指南涵蓋了 huggingface_hub 提供的 Python 特有快取管理工具。有關 Hugging Face Hub 快取系統運作方式（與語言無關）的概覽，請參閱關於本地快取的 Hub 文件。

基於檔案的快取

Hugging Face Hub 快取系統旨在作為依賴於 Hub 的各個函式庫之間共享的中央快取。它在 v0.8.0 版本中進行了更新，以防止在不同修訂版本（revision）之間重複下載相同的檔案。

快取系統的設計如下

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

預設的 <CACHE_DIR> 是 ~/.cache/huggingface/hub。但是，它可以透過所有方法中的 cache_dir 引數自訂，或者透過指定 HF_HOME 或 HF_HUB_CACHE 環境變數來自訂。

模型（models）、資料集（datasets）和空間（spaces）共享一個共同的根目錄。每個儲存庫都包含儲存庫類型、命名空間（組織或使用者名稱，如果存在）以及儲存庫名稱

<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

現在所有從 Hub 下載的檔案都將存放在這些資料夾中。快取機制可確保：如果檔案已存在且未更新，則不會重複下載；但如果檔案已更新，且您要求的是最新檔案，它將下載最新檔案（同時保留先前的檔案，以防您再次需要它）。

為了實現這一點，所有資料夾都包含相同的骨架

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

每個資料夾旨在包含以下內容

Refs (引用)

refs 資料夾包含指示給定引用之最新修訂版本（revision）的檔案。例如，如果我們之前從儲存庫的 main 分支獲取過檔案，refs 資料夾將包含一個名為 main 的檔案，該檔案本身將包含當前 head 的提交識別碼（commit identifier）。

如果 main 的最新提交識別碼是 aaaaaa，那麼它將包含 aaaaaa。

如果該分支更新了新的提交，識別碼為 bbbbbb，那麼從該引用重新下載檔案將會更新 refs/main 檔案使其包含 bbbbbb。

Blobs (大型檔案)

blobs 資料夾包含我們下載的實際檔案。每個檔案的名稱都是它們的雜湊值（hash）。

Snapshots (快照)

snapshots 資料夾包含指向上述 blobs 的符號連結（symlinks）。它本身由多個資料夾組成：每個已知的修訂版本都有一個！

在上面的解釋中，我們最初從 aaaaaa 修訂版本獲取檔案，然後從 bbbbbb 修訂版本獲取檔案。在這種情況下，我們現在 snapshots 資料夾中會有兩個資料夾：aaaaaa 和 bbbbbb。

在這些資料夾中的每一個，都存有與我們下載檔案名稱相同的符號連結。例如，如果我們下載了修訂版本 aaaaaa 的 README.md 檔案，我們將擁有以下路徑

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

該 README.md 檔案實際上是一個指向具有該檔案雜湊值的 blob 的符號連結。

透過以這種方式建立骨架，我們開啟了檔案共享機制：如果在修訂版本 bbbbbb 中獲取了同一個檔案，它將具有相同的雜湊值，並且不需要重新下載該檔案。

.no_exist (進階)

除了 blobs、refs 和 snapshots 資料夾外，您可能還會在快取中發現一個 .no_exist 資料夾。此資料夾用於追蹤您嘗試下載過但 Hub 上不存在的檔案。其結構與 snapshots 資料夾相同，每個已知修訂版本都有一個子資料夾

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

與 snapshots 資料夾不同，這裡的檔案是單純的空檔案（不是符號連結）。在此範例中，檔案 "config_that_does_not_exist.json" 在 Hub 的 "aaaaaa" 修訂版本中並不存在。由於它僅儲存空檔案，此資料夾對磁碟空間的佔用微乎其微。

現在您可能會想，為什麼這些資訊有用呢？在某些情況下，框架會嘗試載入模型的選用檔案（optional files）。儲存選用檔案不存在的紀錄可以加快模型載入速度，因為它節省了每個潛在選用檔案的一次 HTTP 請求。例如，這在 transformers 中就有應用，每個 tokenizer 都可以支援額外的檔案。第一次在您的電腦上載入 tokenizer 時，它會快取哪些選用檔案存在（以及哪些不存在），以便讓下次初始化的載入時間更快。

要測試檔案是否已在本地快取（不發出任何 HTTP 請求），您可以使用 try_to_load_from_cache() 工具函式。它會回傳檔案路徑（如果存在且已快取）、物件 _CACHED_NO_EXIST（如果已快取不存在狀態）或 None（如果快取狀況未知）。

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
    ...

實際情況

實際上，您的快取看起來應該像下面的樹狀結構

    [  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

CACHEDIR.TAG

huggingface_hub 會在快取目錄內自動建立一個 CACHEDIR.TAG 檔案。此標籤遵循 快取目錄標記標準 (Cache Directory Tagging Standard)，告知備份工具（例如 Borg、restic、rsync）該目錄包含可重新下載的快取數據，可以安全地從備份中排除。

限制

為了擁有高效的快取系統，huggingface-hub 使用了符號連結。然而，並非所有機器都支援符號連結。這在 Windows 上是一個已知的限制。在這種情況下，huggingface_hub 不會使用 blobs/ 目錄，而是將檔案直接儲存在 snapshots/ 目錄中。這種解決方案允許使用者以完全相同的方式從 Hub 下載並快取檔案。用於檢查和刪除快取的工具（見下文）也受支援。但是，如果下載了同一個 repo 的多個修訂版本，單一檔案可能會被多次下載，這使得快取系統的效率降低。

如果您想在 Windows 機器上受益於基於符號連結的快取系統，您需要啟動開發者模式或以管理員身份執行 Python。

如果您想主動使用不使用符號連結的快取模式（例如在不支援符號連結的共享檔案系統中），您可以將 HF_HUB_DISABLE_SYMLINKS 環境變數設定為 1。檔案將直接複製到 snapshots/ 中，而不是符號連結到 blobs/。

當不支援符號連結時，會向使用者顯示一條警告訊息，提醒他們正在使用降級版的快取系統。您可以透過將 HF_HUB_DISABLE_SYMLINKS_WARNING 環境變數設定為 true 來停用此警告。

基於區塊的快取 (Xet)

為了提供更有效率的檔案傳輸，hf_xet 在現有的 huggingface_hub 快取中增加了一個 xet 目錄，建立了額外的快取層以實現基於區塊的重複資料刪除。此快取保存了區塊（檔案中不可變的位元組範圍，大小約 64KB）和分片（將檔案映射到區塊的數據結構）。有關 Xet 儲存系統的更多資訊，請參閱此章節。

xet 目錄預設位於 ~/.cache/huggingface/xet，包含兩個用於上傳和下載的快取。它具有以下結構

<CACHE_DIR>
├─ xet
│  ├─ environment_identifier
│  │  ├─ chunk_cache
│  │  ├─ shard_cache
│  │  ├─ staging

environment_identifier 目錄是一個編碼後的字串（在您的機器上可能顯示為 https___cas_serv-tGqkUaZf_CBPHQ6h）。這在開發過程中使用，允許快取的本地版本和生產版本同時並存。當從位於不同儲存區域的儲存庫下載時也會用到它。您可能會在 xet 目錄中看到多個此類項目，每個項目對應不同的環境，但它們的內部結構是相同的。

內部目錄的用途如下

chunk-cache 包含快取的數據區塊，用於加速下載。
shard-cache 包含快取的分片，用於上傳路徑。
staging 是一個旨在支援可續傳上傳的工作區。

這些內容在下文中說明。

請注意，xet 快取系統與 hf_xet 的其他部分一樣，完全整合於 huggingface_hub 中。如果您使用現有的 API 來與快取資產互動，則無需更新您的工作流程。xet 快取是建立在現有 hf_xet 區塊去重和 huggingface_hub 快取系統之上的最佳化層。

chunk_cache

此快取用於下載路徑。快取目錄結構基於來自內容定址儲存 (CAS) 的 base-64 編碼雜湊值，CAS 是每個啟用了 Xet 的儲存庫的後盾。CAS 雜湊值用作查找數據存儲偏移量的關鍵字（key）。注意：從 hf_xet 1.2.0 開始，chunk_cache 預設是停用的。要啟用它，請在啟動 Python 進程之前將 HF_XET_CHUNK_CACHE_SIZE_BYTES 環境變數設置為適當的大小。

在最頂層，base 64 編碼的 CAS 雜湊的前兩個字母用於在 chunk_cache 中建立子目錄（共享這前兩個字母的關鍵字會分組於此）。內層包含以完整關鍵字命名的子目錄。最基層是快取項目，它們是包含已快取區塊的塊範圍（ranges of blocks）。

<CACHE_DIR>
├─ xet
│  ├─ chunk_cache
│  │  ├─ A1
│  │  │  ├─ A1GerURLUcISVivdseeoY1PnYifYkOaCCJ7V5Q9fjgxkZWZhdWx0
│  │  │  │  ├─ AAAAAAEAAAA5DQAAAAAAAIhRLjDI3SS5jYs4ysNKZiJy9XFI8CN7Ww0UyEA9KPD9
│  │  │  │  ├─ AQAAAAIAAABzngAAAAAAAPNqPjd5Zby5aBvabF7Z1itCx0ryMwoCnuQcDwq79jlB

請求檔案時，hf_xet 首先會與 Xet 儲存的內容定址儲存 (CAS) 通訊以獲取重構資訊。重構資訊包含下載完整檔案所需的 CAS 關鍵字資訊。

在執行對 CAS 關鍵字的請求之前，會先查詢 chunk_cache。如果快取中的關鍵字與 CAS 關鍵字匹配，則沒有理由再對該內容發出請求。hf_xet 會改用儲存在目錄中的區塊。

由於 chunk_cache 純粹是最佳化而非保證，hf_xet 採用了計算效率高的逐出策略（eviction policy）。當 chunk_cache 已滿（見下文 限制與局限性）時，hf_xet 在選擇逐出對象時會實施隨機逐出策略。這顯著降低了管理穩健快取系統（例如 LRU）的開銷，同時仍能提供快取區塊的大部分好處。

shard_cache

此快取用於向 Hub 上傳內容時。目錄結構是扁平的，僅由分片（shard）檔案組成，每個檔案使用 ID 作為分片名稱。

<CACHE_DIR>
├─ xet
│  ├─ shard_cache
│  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb
│  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  ├─ ceeeb7ea4cf6c0a8d395a2cf9c08871211fbbd17b9b5dc1005811845307e6b8f.mdb
│  │  ├─ e8535155b1b11ebd894c908e91a1e14e3461dddd1392695ddc90ae54a548d8b2.mdb

shard_cache 包含的分片來源如下

本地產生並成功上傳到 CAS
作為全局重複資料刪除算法的一環從 CAS 下載

分片提供了檔案與區塊之間的映射。上傳期間，每個檔案都會被切分為區塊，並儲存區塊的雜湊值。隨後會諮詢快取中的每個分片。如果分片包含正要上傳的本地檔案中的區塊雜湊值，那麼該區塊就可以被捨棄，因為它已經儲存在 CAS 中了。

所有分片的過期時間為下載後的 3-4 週。過期的分片在上傳路徑中不會被載入，並在過期一週後刪除。

staging (暫存區)

當上傳在將新內容提交到儲存庫之前中斷時，您將需要恢復（resume）檔案傳輸。然而，在發生中斷之前，可能已經成功上傳了一些區塊。

為了讓您不必從頭開始，staging 目錄在上傳期間充當工作區，存儲已成功上傳區塊的元數據。staging 目錄具有以下形狀

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

隨著檔案的處理和區塊的成功上傳，它們的元數據會以分片形式儲存在 xorb-metadata 中。在恢復上傳工作階段時，每個檔案會再次被處理，並諮詢此目錄中的分片。任何成功上傳過的內容都會被跳過，而任何新內容都會被上傳（並且其元數據會被存儲）。

同時，shard-session 存儲已處理檔案的檔案和區塊資訊。在上傳成功完成後，這些分片中的內容會被移至更持久的 shard-cache。

限制與局限性

chunk_cache 的大小限制為 10GB，而 shard_cache 的軟上限為 4GB。依設計，這兩種快取都沒有提供高階 API，但可以透過 HF_XET_CHUNK_CACHE_SIZE_BYTES 和 HF_XET_SHARD_CACHE_SIZE_LIMIT 環境變數來設定其大小。

這些快取主要用於利於檔案的重構（下載）或上傳。若要與資產本身互動，建議您使用 huggingface_hub 快取系統 API。

如果您需要回收快取所佔用的空間或需要除錯任何潛在的快取相關問題，只需執行 rm -rf ~/<cache_dir>/xet 即可完全移除 xet 快取，其中 <cache_dir> 是您的 Hugging Face 快取位置，通常為 ~/.cache/huggingface

完整的 xet 快取目錄樹範例

<CACHE_DIR>
├─ xet
│  ├─ chunk_cache
│  │  ├─ L1
│  │  │  ├─ L1GerURLUcISVivdseeoY1PnYifYkOaCCJ7V5Q9fjgxkZWZhdWx0
│  │  │  │  ├─ AAAAAAEAAAA5DQAAAAAAAIhRLjDI3SS5jYs4ysNKZiJy9XFI8CN7Ww0UyEA9KPD9
│  │  │  │  ├─ AQAAAAIAAABzngAAAAAAAPNqPjd5Zby5aBvabF7Z1itCx0ryMwoCnuQcDwq79jlB
│  ├─ shard_cache
│  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb
│  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  ├─ ceeeb7ea4cf6c0a8d395a2cf9c08871211fbbd17b9b5dc1005811845307e6b8f.mdb
│  │  ├─ e8535155b1b11ebd894c908e91a1e14e3461dddd1392695ddc90ae54a548d8b2.mdb
│  ├─ staging
│  │  ├─ shard-session
│  │  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  │  ├─ xorb-metadata
│  │  │  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb

要了解更多關於 Xet 儲存的資訊，請參閱此章節。

快取資產

除了快取來自 Hub 的檔案外，下游函式庫通常還需要快取與 HF 相關但不由 huggingface_hub 直接處理的其他檔案（例如：從 GitHub 下載的檔案、預處理數據、日誌……）。為了快取這些稱為 assets 的檔案，可以使用 cached_assets_path()。這個精簡的輔助工具會根據請求它的函式庫名稱以及選用的命名空間和子資料夾名稱，以統一的方式在 HF 快取中生成路徑。其目標是讓每個下游函式庫以自己的方式管理其資產（例如：不強制限制結構），只要它保留在正確的 assets 資料夾中即可。這些函式庫隨後可以利用 huggingface_hub 的工具來管理快取，特別是透過 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 !

[!TIP][cached_assets_path()](/docs/huggingface_hub/v1.16.2/en/package_reference/cache#huggingface_hub.cached_assets_path) 是推薦的資產儲存方式，但非強制性。如果您的函式庫已經使用自己的快取，請放心使用！

資產實際情況

實際上，您的資產快取看起來應該像下面的樹狀結構

    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/
                └── (...)

管理您的檔案型快取

檢查您的快取

目前，快取檔案永遠不會從您的本地目錄中刪除：當您下載分支的新修訂版本時，先前的檔案會被保留，以防您再次需要它們。因此，檢查您的快取目錄以了解哪些儲存庫和修訂版本佔用了最多的磁碟空間會非常有用。huggingface_hub 提供了您可以從 hf CLI 或 Python 使用的工具。

從終端檢查快取

執行 hf cache ls 來探索本地儲存的內容。預設情況下，此命令會按儲存庫匯總資訊

➜ 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.

加入 --revisions 來列出每個快取的快照，並鏈接過濾器以關注重要的內容。過濾器能理解易於閱讀的大小和時間單位，因此像 size>1GB 或 accessed>30d 這樣的運算式開箱即可運作

➜ 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.

需要機器友善的輸出？使用 --format json 獲取結構化物件，或使用 --format csv 獲取試算表格式。或者使用 --quiet 僅列印識別碼（每行一個），以便將其傳輸（pipe）到其他工具。使用 --sort 按 accessed（訪問時間）、modified（修改時間）、name（名稱）或 size（大小）排序項目（附加 :asc 或 :desc 以控制順序），並使用 --limit 將結果限制在前 N 個項目。當您需要檢查儲存在 HF_HOME 之外的快取時，請結合使用這些選項與 --cache-dir。

使用常用的 shell 工具進行過濾

表格形式的輸出意味著您可以繼續使用已知的工具。例如，下面的程式碼片段會找出與 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

從 Python 檢查快取

對於更高級的用法，請使用 scan_cache_dir()，這是 CLI 工具所調用的 Python 工具函式。

您可以使用它來獲取圍繞 4 個資料類別（dataclasses）結構化的詳細報告

HFCacheInfo：由 scan_cache_dir() 回傳的完整報告
CachedRepoInfo：關於已快取儲存庫的資訊
CachedRevisionInfo：關於儲存庫內已快取修訂版本（例如「snapshot」）的資訊
CachedFileInfo：關於快照中已快取檔案的資訊

這是一個簡單的用法示例。詳情請參見參考文件。

>>> 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(...),
        ...
    ],
)

驗證您的快取

huggingface_hub 可以驗證您的快取檔案是否與 Hub 上的校驗碼（checksums）匹配。使用 hf cache verify CLI 來驗證特定儲存庫之特定修訂版本的檔案一致性

>>> 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.

驗證特定的已快取修訂版本

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

有關用法詳情和完整選項列表，請參閱 hf cache verify CLI 參考文件。

清理您的快取

掃描快取很有趣，但您通常接下來真正想做的是刪除某些部分以釋放硬碟空間。這可以使用 hf cache rm 和 hf cache prune CLI 命令來實現。您也可以透過程式化方式，使用從掃描快取時回傳的 HFCacheInfo 物件中的 delete_revisions() 工具函式。

刪除策略

要刪除某些快取，您需要傳遞要刪除的修訂版本列表。工具將根據此列表定義一個釋放空間的策略。它會回傳一個 DeleteCacheStrategy 物件，該物件描述了將刪除哪些檔案和資料夾。DeleteCacheStrategy 會告訴您預計將釋放多少空間。一旦您同意刪除，就必須執行它以使刪除生效。為了避免誤差，您不能手動編輯策略物件。

刪除修訂版本的策略如下

包含修訂版本符號連結的 snapshot 資料夾將被刪除。
僅被選定刪除之修訂版本所指向的 blobs 檔案也將一併刪除。
如果一個修訂版本連結到一個或多個 refs，這些引用也會被刪除。
如果儲存庫中的所有修訂版本都被刪除，則整個已快取儲存庫都會被刪除。

修訂版本雜湊值在所有儲存庫中都是唯一的。因此 hf cache rm 既接受儲存庫識別碼（例如 model/bert-base-uncased），也接受裸的修訂版本雜湊值；傳遞雜湊值時，您不需要另外指定儲存庫。

如果快取中找不到某個修訂版本，它將被靜默忽略。此外，如果嘗試刪除時找不到檔案或資料夾，系統會記錄一條警告，但不會拋出錯誤。刪除作業會繼續處理 DeleteCacheStrategy 物件中包含的其他路徑。

從終端清理快取

使用 hf cache rm 從快取中永久刪除儲存庫或修訂版本。傳遞一個或多個儲存庫識別碼（例如 model/bert-base-uncased）或修訂版本雜湊值

➜ 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.

您還可以結合使用 hf cache rm 和 hf cache ls --quiet 來批量刪除經由過濾器識別的項目

>>> 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)
Delete repo: ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct
Delete repo: ~/.cache/huggingface/hub/models--hexgrad--Kokoro-82M
Cache deletion done. Saved 5.31G.
Deleted 2 repo(s) and 2 revision(s); freed 5.31G.

在同一個調用中混合儲存庫和修訂版本。加入 --dry-run 來預覽影響，或者在編寫腳本時加入 --yes 來跳過確認提示

➜ 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.

在預設快取位置之外作業時，請將命令與 --cache-dir 路徑 配對使用。

要批量清理孤立的（detached）快照，請執行 hf cache prune。它會自動選擇不再被分支或標籤引用的修訂版本

➜ hf cache prune
About to delete 3 unreferenced revision(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); freed 2.4G.

這兩個命令都支援 --dry-run、--yes 和 --cache-dir，因此您可以根據需要預覽、自動化並定位備用快取目錄。

從 Python 清理快取

為了獲得更大的靈活性，您也可以透過程式化方式使用 delete_revisions() 方法。這是一個簡單的例子。詳情請見參考文件。

>>> 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()
Cache deletion done. Saved 8.6G.

在 GitHub 上更新

Hub Python 函式庫

了解快取

基於檔案的快取

Refs (引用)

Blobs (大型檔案)

Snapshots (快照)

.no_exist (進階)

實際情況

CACHEDIR.TAG

限制

基於區塊的快取 (Xet)

chunk_cache

shard_cache

staging (暫存區)

限制與局限性

快取資產

資產實際情況

管理您的檔案型快取

檢查您的快取

驗證您的快取

清理您的快取