瞭解快取

huggingface_hub 利用本地磁碟作為兩個快取，這避免了重複下載。第一個快取是基於檔案的快取，它快取從 Hub 下載的單個檔案，並確保在儲存庫更新時不會重複下載相同的檔案。第二個快取是基於塊的快取，其中每個塊代表檔案的一個位元組範圍，並確保跨檔案共享的塊只下載一次。

基於檔案的快取

Hugging Face Hub 的快取系統旨在成為跨依賴 Hub 的庫的共享中央快取。它已在 v0.8.0 中更新，以防止在修訂版本之間重複下載相同的檔案。

快取系統的設計如下

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

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

模型、資料集和 Space 共享一個公共根目錄。這些儲存庫中的每一個都包含儲存庫型別、名稱空間（組織或使用者名稱，如果存在）以及儲存庫名稱。

<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 資料夾包含指示給定引用的最新修訂版本的檔案的資料夾。例如，如果我們之前從儲存庫的 main 分支獲取了一個檔案，refs 資料夾將包含一個名為 main 的檔案，該檔案本身將包含當前頭部的提交識別符號。

如果 main 的最新提交的識別符號是 aaaaaa，則它將包含 aaaaaa。

如果該同一分支更新了一個新提交，其識別符號為 bbbbbb，那麼從該引用重新下載檔案將更新 refs/main 檔案以包含 bbbbbb。

Blob

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

快照

snapshots 資料夾包含指向上述 blob 的符號連結。它本身由幾個資料夾組成：每個已知修訂版本一個資料夾！

在上面的解釋中，我們最初從 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" 不存在於修訂版本 "aaaaaa" 的 Hub 上。由於它只儲存空檔案，因此從磁碟使用量來看，此資料夾可以忽略不計。

那麼，您可能會問，為什麼這些資訊如此重要？在某些情況下，框架會嘗試載入模型的可選檔案。儲存可選檔案不存在可以使模型載入速度更快，因為它節省了每個可能的可選檔案的 1 次 HTTP 呼叫。例如，在 transformers 中，每個分詞器都可以支援其他檔案。當您第一次在計算機上載入分詞器時，它會快取哪些可選檔案存在（哪些不存在），以便在下次初始化時加快載入速度。

要測試檔案是否已本地快取（無需發出任何 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

侷限性

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

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

當不支援符號連結時，會向用戶顯示警告訊息，以提醒他們正在使用降級版本的快取系統。透過將 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

此快取用於下載路徑。快取目錄結構基於支援每個 Xet 啟用儲存庫的內容定址儲存（CAS）的 base-64 編碼雜湊。CAS 雜湊用作查詢資料儲存位置的偏移量的鍵。注意：從 hf_xet 1.2.0 開始，chunk_cache 預設停用。要啟用它，請在啟動 Python 程序之前將 HF_XET_CHUNK_CACHE_SIZE_BYTES 環境變數設定為適當的大小。

在最高級別，base 64 編碼的 CAS 雜湊的前兩個字母用於在 chunk_cache 中建立子目錄（共享這兩個字母的鍵在此分組）。內部級別由目錄名稱為完整鍵的子目錄組成。在基礎是包含快取塊的塊範圍的快取項。

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

請求檔案時，hf_xet 首先與 Xet 儲存的內容定址儲存（CAS）通訊以獲取重建資訊。重建資訊包含有關下載整個檔案所需的 CAS 鍵的資訊。

在執行 CAS 鍵請求之前，會諮詢 chunk_cache。如果快取中的鍵與 CAS 鍵匹配，則無需為該內容發出請求。hf_xet 使用目錄中儲存的塊。

由於 chunk_cache 純粹是最佳化，而非保證，因此 hf_xet 使用計算效率高的淘汰策略。當 chunk_cache 已滿（參見下面的 限制與侷限性）時，hf_xet 在選擇淘汰候選者時實施隨機淘汰策略。這大大降低了管理健壯快取系統（例如 LRU）的開銷，同時仍然提供了大部分快取塊的好處。

shard_cache

此快取用於將內容上傳到 Hub。該目錄是扁平的，只包含分片檔案，每個分片使用一個 ID 作為分片名稱。

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

shard_cache 包含的分片是

本地生成併成功上傳到 CAS
作為全域性去重演算法的一部分從 CAS 下載

分片提供了檔案和塊之間的對映。在上傳期間，每個檔案都會被分塊，並儲存塊的雜湊值。然後會查詢快取中的每個分片。如果分片包含本地上傳檔案中的塊雜湊值，則該塊可以被丟棄，因為它已儲存在 CAS 中。

所有分片的過期日期為從下載之日起 3-4 周。過期的分片在上傳時不載入，並在過期一週後刪除。

staging

當上傳在提交新內容到儲存庫之前終止時，您需要恢復檔案傳輸。但是，一些塊可能在中斷前已成功上傳。

為了避免從頭開始，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 快取中生成路徑。目標是讓每個下游庫以自己的方式管理其資產（例如，不對結構做任何規定），只要它保留在正確的資產資料夾中。然後，這些庫可以利用 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.4.0/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 只打印識別符號（每行一個），以便您可以將它們透過管道傳輸到其他工具中。使用 --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 個數據類的詳細報告

HFCacheInfo：scan_cache_dir() 返回的完整報告
CachedRepoInfo：有關快取倉庫的資訊
CachedRevisionInfo：有關倉庫中快取的修訂版（例如“快照”）的資訊
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 上的校驗和匹配。使用 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 資料夾。
同時刪除僅被要刪除的修訂版引用的 blob 檔案。
如果一個修訂版連結到 1 個或多個 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 PATH 配對。

要批次清理分離的快照，請執行 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 庫

瞭解快取

基於檔案的快取

引用

Blob

快照

.no_exist（高階）

實踐中

侷限性

基於塊的快取（Xet）

chunk_cache

shard_cache

staging

限制與約束

快取資產

實踐中的資產

管理您的基於檔案的快取

檢查您的快取

驗證您的快取

清理您的快取