如何更改 Hugging Face 缓存目录

如果要同时移动 Hugging Face 主目录及其默认缓存，请设置 HF_HOME。如果只想重定位已下载的 Hub 存储库，请设置 HF_HUB_CACHE。在下载停止时复制现有缓存，为使用缓存的进程持久设置变量，然后在删除任何内容之前验证一个保留的模型。

HF_HOME 与 HF_HUB_CACHE 不可互换

Hugging Face 提供多个缓存变量，因为本地数据并不完全相同。默认值由 HF_HOME 派生，通常为 ~/.cache/huggingface，除非 XDG_CACHE_HOME 对其进行更改。

• HF_HOME 会移动用于存储本地令牌状态和默认缓存子目录的 Hugging Face 主目录。
• HF_HUB_CACHE 会移动 Hub 存储库缓存——包括模型、数据集和 Spaces——其默认位置为 $HF_HOME/hub。
• HF_XET_CACHE 控制 Xet 分块缓存，默认为 $HF_HOME/xet。
• HF_ASSETS_CACHE 控制下游库资源，默认为 $HF_HOME/assets。

如果问题在于下载模型的存储，HF_HUB_CACHE 是范围最窄的覆盖项。如果希望在另一块磁盘上建立一个自包含的 Hugging Face 根目录，HF_HOME 更容易理解——但请记住，凭证和其他状态也可能随该根目录迁移。

选择目标位置前先检查当前路径

使用Hugging Face 缓存位置指南确认现有环境变量和特定库的覆盖项。笔记本、服务、容器和交互式 shell 可能不会继承相同环境。实际工作负载内打印的路径，比它从未使用的 shell 中的值更有用。

hf cache ls

# Python：查看此环境解析到的 Hub 缓存
python -c "from huggingface_hub.constants import HF_HUB_CACHE; print(HF_HUB_CACHE)"

复制前停止活动下载和训练作业。缓存包含快照和共享数据块；复制稳定的目录树，要比在另一个进程持续修改时追逐新链接更可靠。

在正确环境中持久保存新路径

一次性测试时，可在当前 shell 中设置变量。日常使用时，请将其放入启动工作负载的环境配置：shell 配置文件、服务单元、容器定义、笔记本内核或应用启动器。

# macOS 或 Linux：仅移动 Hub 存储库缓存
export HF_HUB_CACHE="/mnt/ai-cache/huggingface/hub"

# 或者移动整个 Hugging Face 主目录
export HF_HOME="/mnt/ai-cache/huggingface"

# PowerShell 用户环境变量
[Environment]::SetEnvironmentVariable(
  "HF_HUB_CACHE",
  "D:\AI-Cache\huggingface\hub",
  "User"
)

更改持久变量后重启应用。Python 库通常在导入时解析缓存常量；在进程中途更改环境，可能不会重定向已经开始的工作。

复制、指向、验证，然后清理

1. 在支持工作负载所需链接和权限的文件系统上创建目标位置。
2. 将旧缓存复制到其中，不要重新排列 refs、snapshots 或 blobs。
3. 设置所选环境变量并重启工作负载。
4. 运行 hf cache ls --revisions，确认预期的存储库和修订版本存在。
5. 离线加载一个已知模型，或对保留的存储库使用 hf cache verify <repo>。
6. 执行一次新的小型下载，确认发生变化的是目标位置，而不是来源。

至少在一次无错误重启后仍保留原缓存。如果验证失败，请恢复先前的变量，并调查复制过程或权限。不要试图通过手动合并两个不完整缓存来“修复”失败的迁移。

只有在此之后才决定是否清除旧缓存

目标位置经证明可用后，旧副本可能变为冗余。如果还想移除新缓存中的过时存储库或修订版本，请使用有文档依据的流程安全清除 Hugging Face 缓存。重定位和修剪是不同操作；混在一起会更难判断哪个操作导致模型缺失。

对于不可替代的模型系列，请在活动缓存之外维护有意保留的归档。Tensor Archive 可以保留相关本地工件、对其进行验证并精确还原。它不会修改 Hub 缓存，也不会选择代码应加载哪个修订版本。

相关存储解答

如果压力来自多个运行时而非一个缓存，请阅读如何整理一个基础模型及多个适配器。如需作出更广泛的保留或删除决策，请使用本地模型库保留清单。