Hugging Face Hub 怎样用缓存目录管理模型文件

我在把模型下载任务从个人目录迁到共享磁盘时，最先遇到的不是下载失败，而是“文件到底被缓存到哪里”。Hugging Face Hub 的正确做法是把 Hub 仓库缓存、下游库的 assets 缓存和 Xet 上传缓存分开管理；通常只需要优先设置 HF_HUB_CACHE，不要把所有目录都粗暴地指向同一个文件夹。

官方地址：https://huggingface.co/docs/huggingface_hub/guides/manage-cache

官方缓存指南把仓库缓存组织为 refs、blobs 和 snapshots。其中 blobs 保存实际文件，snapshots 按提交版本提供可读的文件视图。因此，本文的目标不是手工整理目录，而是建立一套可迁移、可检查、可回收的缓存边界。

先把四个缓存目录分清楚

HF_HOME 是 Hugging Face Hub 的总目录，默认是 ~/.cache/huggingface；HF_HUB_CACHE 只控制模型、数据集和 Space 等 Hub 仓库文件，默认是 $HF_HOME/hub。如果程序还会产生预处理文件、日志或外部下载资源，应使用 HF_ASSETS_CACHE；Xet 的 shard 和上传暂存数据则由 HF_XET_CACHE 管理。

对大多数“下载模型并在多项目间复用”的场景，我会把仓库缓存单独放在大容量磁盘，把 token 和其它配置留在用户目录。这样清理模型缓存时，不会把认证文件和项目自己的临时资产一起删掉。

在导入 huggingface_hub 前固定路径

环境变量是在 huggingface_hub 导入时读取的，所以应该在启动 Python 之前设置，或在脚本最顶部、导入库之前设置。只改变已经启动进程的环境变量，通常不会让已经初始化的缓存路径重新计算。

# 把 Hub 仓库文件放在专用磁盘，保留 HF_HOME 的 token 配置边界
export HF_HOME="/data/huggingface"
export HF_HUB_CACHE="/data/huggingface/hub"

# assets 和 Xet 数据分别归档，便于按用途统计空间
export HF_ASSETS_CACHE="/data/huggingface/assets"
export HF_XET_CACHE="/data/huggingface/xet"

# 启动同一个 shell 中的下载任务
python download_model.py

只想改变仓库缓存时，也可以只设置 HF_HUB_CACHE。若使用的是一次性的下载脚本，单个下载函数的 cache_dir 参数更明确；它表达的是“这一次调用放到哪里”，不必改变整个进程的默认目录。

repo 目录为什么不是普通的文件夹

一个模型仓库在缓存根目录下通常会变成类似 models--组织--仓库名 的目录。refs/main 记录分支当前指向的提交，blobs 以内容哈希保存实际文件，snapshots/ 则通过链接组织出某个版本的文件树。相同内容跨版本复用 blob，是缓存减少重复下载的关键。

因此，迁移缓存时应该整体移动仓库目录，或者让新环境继续指向完整的缓存根目录；不要只挑 snapshots 里的几个文件复制。缺少 refs 或 blobs 后，目录看起来仍然有文件，但 Hub 的版本解析和去重关系可能已经不完整。

/data/huggingface/hub/
└── models--org--demo-model/
    ├── refs/       # 分支或标签到提交的映射
    ├── blobs/      # 按内容标识保存的实际文件
    ├── snapshots/  # 按提交组织的可读文件视图
    └── trees/      # 提交对应的文件清单缓存

用下载函数把缓存策略落到代码

模型库通常应优先使用 snapshot_download 获取同一个提交的完整文件集合；只拿配置或词表等单个文件时，再使用 hf_hub_download。下面的例子把缓存路径显式写进函数参数，并用版本号让多次调用指向同一个快照。

from pathlib import Path

from huggingface_hub import hf_hub_download, snapshot_download

cache_dir = Path("/data/huggingface/hub")

# revision 可以固定到提交或标签，避免不同文件落在不同版本
snapshot_path = snapshot_download(
    repo_id="openai-community/gpt2",
    revision="main",
    cache_dir=cache_dir,
)

# 单文件下载复用同一个缓存根目录，返回的是本地文件路径
config_path = hf_hub_download(
    repo_id="openai-community/gpt2",
    filename="config.json",
    revision="main",
    cache_dir=cache_dir,
)

print("快照目录:", snapshot_path)
print("配置文件:", config_path)

如果下游库需要多个文件并且必须来自同一个提交，可以先解析并固定 revision，再把同一个 revision 传给多个下载调用。仅依赖可变的 main，可能让连续调用跨过仓库更新点；缓存目录能减少下载，但不会替你完成版本锁定。

检查本地是否已有文件，再决定是否联网

需要判断“某个文件是否已经在缓存里”时，可以使用 try_to_load_from_cache，它会区分已找到的路径、已知不存在和本地未知三种情况。这比直接猜目录名称更稳，也不会把缓存内部布局写死在业务代码里。

from huggingface_hub import _CACHED_NO_EXIST, try_to_load_from_cache

# 只检查本地缓存，不把“未知”误判成“文件不存在”
result = try_to_load_from_cache(
    repo_id="openai-community/gpt2",
    filename="config.json",
    revision="main",
    cache_dir="/data/huggingface/hub",
)

if isinstance(result, str):
    print("缓存文件:", result)
elif result is _CACHED_NO_EXIST:
    print("该版本已记录没有这个文件")
else:
    print("本地没有足够信息，需要按下载策略处理")

对离线任务，可以在启动前设置 HF_HUB_OFFLINE=1，让 Hub 只使用本地缓存；如果目标文件不在本地，应该把它当成可预期的缺失，而不是继续等待网络。

清理和共享时最容易踩的边界

• 不要在导入后才改环境变量。重启进程是最简单的处理方式，尤其是 notebook 或长驻服务。
• 不要把 HF_HUB_CACHE 当成备份目录。缓存里的文件可以重新下载，是否纳入备份应按业务需要决定。
• 留意符号链接。Hub 的缓存结构会使用链接来复用 blob；不支持链接的文件系统会退化为直接复制，磁盘占用可能明显增加。
• 共享磁盘要先确认权限和平台。多个系统共用缓存时，优先选择所有运行环境都能正确读取的目录，并给进程稳定的读写权限。
• 清理前先扫描。可以使用 scan_cache_dir(cache_dir=...) 获取仓库、版本和磁盘占用信息，再决定删除范围；不要靠字符串匹配随意删除。

我的落地结论

如果只是单机开发，保留默认目录也可以；如果是训练机、CI 或多个项目共享模型，建议至少固定 HF_HUB_CACHE，并把 HF_ASSETS_CACHE、HF_XET_CACHE 作为独立容量统计项。代码层面用 cache_dir 明确一次调用的边界，用固定 revision 管理版本，用 try_to_load_from_cache 和 scan_cache_dir 做程序化检查。

这套安排的重点不是把目录改得更复杂，而是让“模型文件在哪里、能否离线复用、哪些空间可以回收”都变成可解释的配置。官方环境变量说明见 https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables。

相关问题

HF_HOME 和 HF_HUB_CACHE 有什么区别？

HF_HOME 是 Hugging Face Hub 的总目录，HF_HUB_CACHE 只控制模型、数据集和 Space 等 Hub 仓库缓存。

改了 HF_HUB_CACHE 为什么程序还用旧目录？

常见原因是环境变量设置晚于 huggingface_hub 导入，或长驻进程没有重启。把设置放到启动命令前并重新启动进程。

能不能只复制 snapshots？

不建议。完整缓存还依赖 refs、blobs 和 trees；迁移时应保留完整 repo 缓存目录。