了解缓存

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 库