了解缓存

huggingface_hub 利用本地磁盘作为两个缓存，以避免再次重新下载项目。第一个缓存是基于文件的缓存，它缓存从 Hub 下载的单个文件，并确保在仓库更新时不会再次下载相同的文件。第二个缓存是块缓存，其中每个块代表文件中的一个字节范围，并确保跨文件共享的块仅下载一次。

基于文件的缓存

Hugging Face Hub 缓存系统旨在成为依赖 Hub 的库之间共享的中央缓存。它已在 v0.8.0 中更新，以防止在修订版本之间重新下载相同的文件。

缓存系统设计如下：

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

<CACHE_DIR> 通常是您的用户主目录。但是，可以通过所有方法上的 cache_dir 参数或通过指定 HF_HOME 或 HF_HUB_CACHE 环境变量来自定义它。

模型、数据集和 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 文件夹包含指示给定引用的最新修订版本的文件。例如，如果我们之前从仓库的 main 分支获取了一个文件，则 refs 文件夹将包含一个名为 main 的文件，该文件本身将包含当前 head 的提交标识符。

如果 main 的最新提交的标识符为 aaaaaa，则它将包含 aaaaaa。

如果同一个分支使用新的提交进行了更新，该提交的标识符为 bbbbbb，则从该引用重新下载文件将更新 refs/main 文件以包含 bbbbbb。

Blobs

blobs 文件夹包含我们已下载的实际文件。每个文件的名称都是其哈希值。

Snapshots

snapshots 文件夹包含指向上面提到的 blobs 的符号链接。它本身由多个文件夹组成：每个已知修订版本一个！

在上面的解释中，我们最初从 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 文件夹相同，每个已知修订版本都有 1 个子文件夹

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

与 snapshots 文件夹不同，文件是简单的空文件（没有符号链接）。在此示例中，文件 "config_that_does_not_exist.json" 在 Hub 上对于修订版本 "aaaaaa" 不存在。由于它仅存储空文件，因此该文件夹在磁盘使用方面可以忽略不计。

那么现在您可能想知道，为什么此信息甚至相关？在某些情况下，框架尝试为模型加载可选文件。保存可选文件的不存在性可以更快地加载模型，因为它为每个可能的可选文件节省了 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>
├─ chunk_cache
├─ shard_cache

与 hf_xet 的其余部分一样，xet 缓存与 huggingface_hub 完全集成。如果您使用现有 API 与缓存资产进行交互，则无需更新您的工作流程。xet 缓存构建在现有 hf_xet 基于块的去重和 huggingface_hub 缓存系统之上的优化层。

chunk-cache 目录包含用于加速下载的缓存数据块，而 shard-cache 目录包含在上传路径上使用的缓存分片。

chunk_cache

此缓存用于下载路径。缓存目录结构基于内容寻址存储 (CAS) 中的 base-64 编码哈希，该存储支持每个启用 Xet 的仓库。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 周的到期日期。过期的分片在上传期间不会加载，并在过期后一周删除。

限制和局限性

chunk_cache 的大小限制为 10GB，而 shard_cache 在技术上没有限制（实际上，shard 的大小和使用方式决定了限制缓存是不必要的）。

根据设计，这两个缓存都没有高级 API。这些缓存主要用于方便文件的重建（下载）或上传。要与 assets 本身进行交互，建议您使用 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

要了解有关 Xet Storage 的更多信息，请参阅此部分。

缓存 assets

除了缓存来自 Hub 的文件外，下游库通常还需要缓存其他与 HF 相关但不直接由 huggingface_hub 处理的文件（例如：从 GitHub 下载的文件、预处理数据、日志等）。为了缓存这些称为 assets 的文件，可以使用 cached_assets_path()。这个小助手基于请求它的库的名称，以及可选的命名空间和子文件夹名称，以统一的方式在 HF 缓存中生成路径。目标是让每个下游库以自己的方式管理其 assets（例如，没有关于结构的规则），只要它位于正确的 assets 文件夹中即可。然后，这些库可以利用 huggingface_hub 中的工具来管理缓存，特别是从 CLI 命令扫描和删除部分 assets。

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 的推荐方式，但不是强制性的。如果您的库已经使用自己的缓存，请随意使用它！

Assets 实践

实际上，您的 assets 缓存应该看起来像以下目录树

    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 提供了一个助手来执行此操作，可以通过 huggingface-cli 或 Python 脚本使用。

从终端扫描缓存

扫描 HF 缓存系统最简单的方法是使用 huggingface-cli 工具中的 scan-cache 命令。此命令扫描缓存并打印报告，其中包含仓库 ID、仓库类型、磁盘使用情况、refs 和完整本地路径等信息。

下面的代码片段显示了一个文件夹中的扫描报告，其中缓存了 4 个模型和 2 个数据集。

➜ huggingface-cli scan-cache
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 有 1.4G 和 1.5G 两个修订版本，但总磁盘使用量仅为 1.9G。

➜ huggingface-cli scan-cache -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 "huggingface-cli scan-cache -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：有关仓库内缓存修订版本（例如 “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(...),
        ...
    ],
)

清理您的缓存

扫描您的缓存很有用，但接下来您真正想做的通常是删除某些部分以释放驱动器上的一些空间。这可以使用 delete-cache CLI 命令来实现。也可以通过编程方式使用扫描缓存时返回的 HFCacheInfo 对象中的 delete_revisions() 助手。

删除策略

要删除一些缓存，您需要传递要删除的修订版本的列表。该工具将根据此列表定义一个策略来释放空间。它返回一个 DeleteCacheStrategy 对象，该对象描述将删除哪些文件和文件夹。DeleteCacheStrategy 允许您了解预计将释放多少空间。一旦您同意删除，您必须执行它才能使删除生效。为了避免差异，您不能手动编辑策略对象。

删除修订版本的策略如下

包含修订版本符号链接的 snapshot 文件夹将被删除。
仅由要删除的修订版本指向的 blobs 文件也将被删除。
如果修订版本链接到一个或多个 refs，则引用将被删除。
如果删除了仓库中的所有修订版本，则整个缓存仓库将被删除。

修订版本哈希在所有仓库中都是唯一的。这意味着在删除修订版本时，您无需提供任何 repo_id 或 repo_type。

如果在缓存中找不到修订版本，它将被静默忽略。此外，如果在尝试删除文件或文件夹时找不到文件或文件夹，将记录警告，但不会抛出错误。删除操作将继续处理 DeleteCacheStrategy 对象中包含的其他路径。

从终端清理缓存

从 HF 缓存系统中删除某些修订版本的最简单方法是使用 huggingface-cli 工具中的 delete-cache 命令。该命令有两种模式。默认情况下，会向用户显示 TUI（终端用户界面），以选择要删除的修订版本。此 TUI 目前处于 beta 版，因为它尚未在所有平台上进行测试。如果 TUI 在您的机器上不起作用，您可以使用 --disable-tui 标志禁用它。

使用 TUI

这是默认模式。要使用它，您首先需要通过运行以下命令来安装额外的依赖项

pip install huggingface_hub["cli"]

然后运行命令

huggingface-cli delete-cache

您现在应该看到可以选中/取消选中的修订版本列表

说明

按键盘箭头键 <up> 和 <down> 移动光标。
按 <space> 切换（选中/取消选中）项目。
选中修订版本后，第一行会更新，向您显示将释放多少空间。
按 <enter> 确认您的选择。
如果您想取消操作并退出，可以选择第一个项目（“以下各项均不选”）。如果选中此项目，则将取消删除过程，无论选中其他哪些项目。否则，您也可以按 <ctrl+c> 退出 TUI。

一旦您选择了要删除的修订版本并按了 <enter>，将提示最后一条确认消息。再次按 <enter>，删除将生效。如果要取消，请输入 n。

✗ huggingface-cli delete-cache --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 模式目前处于 beta 版并且是可选的。在某些情况下，它可能在您的机器上不起作用，或者您觉得它不方便。

另一种方法是使用 --disable-tui 标志。该过程非常相似，因为系统会要求您手动查看要删除的修订版本列表。但是，此手动步骤不会直接在终端中进行，而是在运行时生成的临时文件中进行，您可以手动编辑该文件。

此文件在标头中包含您需要的所有说明。在您喜欢的文本编辑器中打开它。要选中/取消选中修订版本，只需使用 # 注释/取消注释即可。手动查看完成后并编辑完文件后，您可以保存它。返回到您的终端并按 <enter>。默认情况下，它将计算使用更新的修订版本列表将释放多少空间。您可以继续编辑文件或按 "y" 确认。

huggingface-cli delete-cache --disable-tui

命令文件示例

# INSTRUCTIONS
# ------------
# This is a temporary file created by running `huggingface-cli delete-cache` 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 库