【Hugging Face】管理 huggingface_hub 缓存系统

摘要

这篇文档介绍了Hugging Face Hub的缓存系统。该系统旨在提供一个中央缓存，以便不同版本的文件可以被下载和缓存。缓存系统将文件组织成模型、数据集和空间等不同的目录，每个目录包含特定类型的文件。系统确保如果文件已经下载并更新，除非明确要求，否则不会再次下载。

这篇文档还提到了一些关于缓存系统的具体信息，例如缓存目录的结构、文件夹中包含的文件类型以及如何检查和删除缓存。此外，文档还介绍了如何使用Hugging Face CLI工具来扫描和删除部分缓存。

从这篇文档中，你可以得到以下要点：

• Hugging Face Hub的缓存系统旨在提供一个中央缓存，以便不同版本的文件可以被下载和缓存。
• 缓存系统将文件组织成模型、数据集和空间等不同的目录，每个目录包含特定类型的文件。
• 缓存系统使用符号链接来共享相同的文件，以节省磁盘空间。
• 可以使用Hugging Face CLI工具来扫描和删除部分缓存，以释放磁盘空间。
• 可以自定义缓存目录，并可以通过环境变量或参数来指定。
• 缓存系统还支持检查和删除缓存中的文件。
• 除了Hugging Face Hub的缓存系统之外，下游库还可以使用cached_assets_path()方法来缓存与HF相关的其他文件。
• Hugging Face Hub的缓存系统使用符号链接来提高效率，但并非所有计算机都支持符号链接。
• 可以使用huggingface-cli工具的scan-cache命令来扫描缓存并获取报告。
• 可以使用huggingface-cli工具的delete-cache命令来删除部分缓存。

🚚🚒🚑🚎🚐🚌🛻🚙🛺🚕🚓🚗🚚🚒🚑🚎🚐🚌🛻🚙

了解缓存

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

缓存系统设计如下：

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

< CACHE_DIR > 通常是您用户的主目录。但是，您可以通过所有方法的 cache_dir 参数或指定 HF_HOME 或 HUGGINGFACE_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 文件夹包含指示给定引用的最新修订的文件。例如，如果我们之前从存储库的主分支中获取了一个文件，则 refs 文件夹将包含一个名为 main 的文件，它本身将包含当前 head 的提交标识符。

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

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

Blobs

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

Snapshots

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

在上面的解释中，我们最初从 aaaaaa 修订中获取了一个文件，然后再从 bbbbbb 修订中获取了一个文件。在这种情况下，我们现在在快照文件夹中有两个文件夹：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 上不存在的文件。它的结构与快照文件夹相同，每个已知修订一个子文件夹：

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

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

那么现在您可能会想知道，为什么这些信息甚至相关呢？在某些情况下，框架尝试加载模型的可选文件。保存可选文件的不存在使加载模型更快，因为它每个可选文件节省了 1 个 HTTP 调用。例如，在 transformers 中，每个 tokenizer 都可以支持其他文件。您第一次在计算机上加载 tokenizer 时，它将缓存哪些可选文件存在（哪些不存在），以使下一次初始化的加载时间更快。

要测试是否本地缓存了文件（而不进行任何 HTTP 请求），可以使用 try_to_load_from_cache() 助手。它将返回文件路径（如果存在并已缓存）、_CACHED_NO_EXIST 对象（如果已缓存不存在）或 None（如果我们不知道）。