瞭解快取

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 環境變數進行自定義。

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

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

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

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

Blobs

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

Snapshots

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 雜湊用作查詢資料儲存偏移量的鍵。

在最頂層，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 !

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 快取系統最簡單的方法是使用 hf cache scan 命令列。此命令掃描快取並列印一份報告，其中包含儲存庫 ID、儲存庫型別、磁碟使用情況、引用和完整本地路徑等資訊。

以下片段顯示了一個資料夾中的掃描報告，其中快取了 4 個模型和 2 個數據集。

➜ hf cache scan
REPO ID                     REPO TYPE SIZE ON DISK NB FILES LAST_ACCESSED LAST_MODIFIED REFS                LOCAL PATH
--------------------------- --------- ------------ -------- ------------- ------------- ------------------- -------------------------------------------------------------------------
glue                        dataset         116.3K       15 4 days ago    4 days ago    2.4.0, main, 1.17.0 /home/wauplin/.cache/huggingface/hub/datasets--glue
google/fleurs               dataset          64.9M        6 1 week ago    1 week ago    refs/pr/1, main     /home/wauplin/.cache/huggingface/hub/datasets--google--fleurs
Jean-Baptiste/camembert-ner model           441.0M        7 2 weeks ago   16 hours ago  main                /home/wauplin/.cache/huggingface/hub/models--Jean-Baptiste--camembert-ner
bert-base-cased             model             1.9G       13 1 week ago    2 years ago                       /home/wauplin/.cache/huggingface/hub/models--bert-base-cased
t5-base                     model            10.1K        3 3 months ago  3 months ago  main                /home/wauplin/.cache/huggingface/hub/models--t5-base
t5-small                    model           970.7M       11 3 days ago    3 days ago    refs/pr/1, main     /home/wauplin/.cache/huggingface/hub/models--t5-small

Done in 0.0s. Scanned 6 repo(s) for a total of 3.4G.
Got 1 warning(s) while scanning. Use -vvv to print details.

要獲取更詳細的報告，請使用 --verbose 選項。對於每個儲存庫，您將獲得所有已下載修訂版的列表。如上所述，在 2 個修訂版之間未更改的檔案透過符號連結共享。這意味著儲存庫在磁碟上的大小預計將小於其每個修訂版大小的總和。例如，這裡 bert-base-cased 有 2 個修訂版，分別為 1.4G 和 1.5G，但總磁碟使用量僅為 1.9G。

➜ hf cache scan -v
REPO ID                     REPO TYPE REVISION                                 SIZE ON DISK NB FILES LAST_MODIFIED REFS        LOCAL PATH
--------------------------- --------- ---------------------------------------- ------------ -------- ------------- ----------- ----------------------------------------------------------------------------------------------------------------------------
glue                        dataset   9338f7b671827df886678df2bdd7cc7b4f36dffd        97.7K       14 4 days ago    main, 2.4.0 /home/wauplin/.cache/huggingface/hub/datasets--glue/snapshots/9338f7b671827df886678df2bdd7cc7b4f36dffd
glue                        dataset   f021ae41c879fcabcf823648ec685e3fead91fe7        97.8K       14 1 week ago    1.17.0      /home/wauplin/.cache/huggingface/hub/datasets--glue/snapshots/f021ae41c879fcabcf823648ec685e3fead91fe7
google/fleurs               dataset   129b6e96cf1967cd5d2b9b6aec75ce6cce7c89e8        25.4K        3 2 weeks ago   refs/pr/1   /home/wauplin/.cache/huggingface/hub/datasets--google--fleurs/snapshots/129b6e96cf1967cd5d2b9b6aec75ce6cce7c89e8
google/fleurs               dataset   24f85a01eb955224ca3946e70050869c56446805        64.9M        4 1 week ago    main        /home/wauplin/.cache/huggingface/hub/datasets--google--fleurs/snapshots/24f85a01eb955224ca3946e70050869c56446805
Jean-Baptiste/camembert-ner model     dbec8489a1c44ecad9da8a9185115bccabd799fe       441.0M        7 16 hours ago  main        /home/wauplin/.cache/huggingface/hub/models--Jean-Baptiste--camembert-ner/snapshots/dbec8489a1c44ecad9da8a9185115bccabd799fe
bert-base-cased             model     378aa1bda6387fd00e824948ebe3488630ad8565         1.5G        9 2 years ago               /home/wauplin/.cache/huggingface/hub/models--bert-base-cased/snapshots/378aa1bda6387fd00e824948ebe3488630ad8565
bert-base-cased             model     a8d257ba9925ef39f3036bfc338acf5283c512d9         1.4G        9 3 days ago    main        /home/wauplin/.cache/huggingface/hub/models--bert-base-cased/snapshots/a8d257ba9925ef39f3036bfc338acf5283c512d9
t5-base                     model     23aa4f41cb7c08d4b05c8f327b22bfa0eb8c7ad9        10.1K        3 1 week ago    main        /home/wauplin/.cache/huggingface/hub/models--t5-base/snapshots/23aa4f41cb7c08d4b05c8f327b22bfa0eb8c7ad9
t5-small                    model     98ffebbb27340ec1b1abd7c45da12c253ee1882a       726.2M        6 1 week ago    refs/pr/1   /home/wauplin/.cache/huggingface/hub/models--t5-small/snapshots/98ffebbb27340ec1b1abd7c45da12c253ee1882a
t5-small                    model     d0a119eedb3718e34c648e594394474cf95e0617       485.8M        6 4 weeks ago               /home/wauplin/.cache/huggingface/hub/models--t5-small/snapshots/d0a119eedb3718e34c648e594394474cf95e0617
t5-small                    model     d78aea13fa7ecd06c29e3e46195d6341255065d5       970.7M        9 1 week ago    main        /home/wauplin/.cache/huggingface/hub/models--t5-small/snapshots/d78aea13fa7ecd06c29e3e46195d6341255065d5

Done in 0.0s. Scanned 6 repo(s) for a total of 3.4G.
Got 1 warning(s) while scanning. Use -vvv to print details.

grep 示例

由於輸出是表格格式，您可以將其與任何類似 grep 的工具結合使用來過濾條目。以下是一個示例，用於在基於 Unix 的機器上僅過濾來自“t5-small”模型的修訂版。

➜ eval "hf cache scan -v" | grep "t5-small"
t5-small                    model     98ffebbb27340ec1b1abd7c45da12c253ee1882a       726.2M        6 1 week ago    refs/pr/1   /home/wauplin/.cache/huggingface/hub/models--t5-small/snapshots/98ffebbb27340ec1b1abd7c45da12c253ee1882a
t5-small                    model     d0a119eedb3718e34c648e594394474cf95e0617       485.8M        6 4 weeks ago               /home/wauplin/.cache/huggingface/hub/models--t5-small/snapshots/d0a119eedb3718e34c648e594394474cf95e0617
t5-small                    model     d78aea13fa7ecd06c29e3e46195d6341255065d5       970.7M        9 1 week ago    main        /home/wauplin/.cache/huggingface/hub/models--t5-small/snapshots/d78aea13fa7ecd06c29e3e46195d6341255065d5

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

清理您的快取

掃描快取很有趣，但接下來您真正想做的通常是刪除某些部分以釋放驅動器上的空間。這可以使用 cache delete CLI 命令來完成。還可以透過程式設計方式使用 delete_revisions() 助手，該助手來自掃描快取時返回的 HFCacheInfo 物件。

刪除策略

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

刪除修訂的策略如下

包含修訂符號連結的 snapshot 資料夾將被刪除。
僅由要刪除的修訂版指向的 blob 檔案也將被刪除。
如果修訂版連結到 1 個或更多 refs，則引用將被刪除。
如果某個儲存庫的所有修訂版都被刪除，則整個快取的儲存庫將被刪除。

修訂雜湊在所有儲存庫中都是唯一的。這意味著在刪除修訂時，您不需要提供任何 repo_id 或 repo_type。

如果在快取中找不到修訂版，它將被靜默忽略。此外，如果嘗試刪除檔案或資料夾時找不到它們，則會記錄警告但不會引發錯誤。刪除將繼續針對 DeleteCacheStrategy 物件中包含的其他路徑。

從終端清理快取

從 HF 快取系統中刪除某些修訂的最簡單方法是使用 hf cache delete CLI 工具。該命令有兩種模式。預設情況下，會向用戶顯示一個 TUI（終端使用者介面），供使用者選擇要刪除的修訂版。此 TUI 目前處於測試階段，因為它尚未在所有平臺上進行測試。如果 TUI 在您的機器上不起作用，您可以使用 --disable-tui 標誌將其停用。

使用 TUI

這是預設模式。要使用它，您首先需要透過執行以下命令安裝額外的依賴項

pip install huggingface_hub["cli"]

然後執行命令

hf cache delete

您現在應該會看到一個可以選擇/取消選擇的修訂列表

指令

按鍵盤箭頭鍵 <up> 和 <down> 移動游標。
按 <space> 切換（選擇/取消選擇）專案。
選擇修訂版後，第一行將更新，顯示將釋放多少空間。
按 <enter> 確認您的選擇。
如果要取消操作並退出，可以選擇第一個專案（“以下都不選擇”）。如果選擇了此專案，無論選擇其他哪些專案，刪除過程都將取消。否則，您也可以按 <ctrl+c> 退出 TUI。

選擇要刪除的修訂版並按 <enter> 後，將提示最後一條確認訊息。再次按 <enter>，刪除將生效。如果要取消，輸入 n。

✗ hf cache delete --dir ~/.cache/huggingface/hub
? Select revisions to delete: 2 revision(s) selected.
? 2 revisions selected counting for 3.1G. Confirm deletion ? Yes
Start deletion.
Done. Deleted 1 repo(s) and 0 revision(s) for a total of 3.1G.

不使用 TUI

如上所述，TUI 模式目前處於測試階段，是可選的。它可能在您的機器上無法正常工作，或者您覺得它不方便。

另一種方法是使用 --disable-tui 標誌。該過程非常相似，您將被要求手動審查要刪除的修訂列表。但是，此手動步驟不會直接在終端中進行，而是在動態生成的臨時檔案中進行，您可以手動編輯該檔案。

此檔案在開頭包含您所需的所有說明。在您喜歡的文字編輯器中開啟它。要選擇/取消選擇修訂版，只需使用 # 符號註釋/取消註釋它。完成手動審查並編輯檔案後，您可以儲存它。返回終端並按 <enter>。預設情況下，它將計算更新後的修訂列表將釋放多少空間。您可以繼續編輯檔案或使用 "y" 確認。

hf cache delete --disable-tui

命令檔案示例

# INSTRUCTIONS
# ------------
# This is a temporary file created by running `hf cache delete` with the
# `--disable-tui` option. It contains a set of revisions that can be deleted from your
# local cache directory.
#
# Please manually review the revisions you want to delete:
#   - Revision hashes can be commented out with '#'.
#   - Only non-commented revisions in this file will be deleted.
#   - Revision hashes that are removed from this file are ignored as well.
#   - If `CANCEL_DELETION` line is uncommented, the all cache deletion is cancelled and
#     no changes will be applied.
#
# Once you've manually reviewed this file, please confirm deletion in the terminal. This
# file will be automatically removed once done.
# ------------

# KILL SWITCH
# ------------
# Un-comment following line to completely cancel the deletion process
# CANCEL_DELETION
# ------------

# REVISIONS
# ------------
# Dataset chrisjay/crowd-speech-africa (761.7M, used 5 days ago)
    ebedcd8c55c90d39fd27126d29d8484566cd27ca # Refs: main # modified 5 days ago

# Dataset oscar (3.3M, used 4 days ago)
#    916f956518279c5e60c63902ebdf3ddf9fa9d629 # Refs: main # modified 4 days ago

# Dataset wikiann (804.1K, used 2 weeks ago)
    89d089624b6323d69dcd9e5eb2def0551887a73a # Refs: main # modified 2 weeks ago

# Dataset z-uo/male-LJSpeech-italian (5.5G, used 5 days ago)
#    9cfa5647b32c0a30d0adfca06bf198d82192a0d1 # Refs: main # modified 5 days ago

從 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 庫