Hugging Face 模型缓存怎么换目录并离线加载

如果模型文件不适合放在系统盘，最直接的做法是在启动 Python 进程前设置 HF_HUB_CACHE；如果还想把 token、Hub 缓存等 Hugging Face 数据统一迁移，再考虑 HF_HOME。离线环境不能只改目录：模型必须先下载到目标缓存，运行时再配合 HF_HUB_OFFLINE=1 或 local_files_only=True，否则仍可能等待网络。

先选缓存变量：HF_HUB_CACHE 还是 HF_HOME

Hugging Face Hub 默认把缓存放在 ~/.cache/huggingface/hub。只想把模型、数据集和 Space 的仓库缓存换到数据盘时，优先设置 HF_HUB_CACHE；它表达的是“Hub 仓库缓存放在哪里”。如果还要迁移 token 和其他 Hugging Face 本地数据，则使用 HF_HOME，Hub 缓存通常位于它下面的 hub 目录。

# 直接把 Hub 仓库缓存放到数据盘
export HF_HUB_CACHE=/data/huggingface/hub

# 需要统一迁移 Hugging Face 本地数据时使用更大的根目录
# export HF_HOME=/data/huggingface

python load_model.py  # 环境变量要在 Python 导入库之前生效

两者同时设置时，按文档优先级理解：HF_HUB_CACHE 直接决定 Hub 缓存路径，HF_HOME 负责默认根目录。XDG_CACHE_HOME 只在没有设置 HF_HOME 时参与回退。不要把 HF_HOME 误写成某个仓库的 snapshot 目录，否则 token、缓存和模型文件的边界会混在一起。

准备模型时用 snapshot_download 固定仓库内容

仅改变环境变量不会自动把旧机器上的文件搬过来。联网准备阶段可以用 snapshot_download 下载一个仓库的快照；如果需要可复现，额外固定 revision。cache_dir 适合单次调用指定目录，环境变量则适合整台机器或容器统一约束。

from huggingface_hub import snapshot_download

# 把指定仓库准备到统一缓存目录，并固定 revision 便于复现
snapshot_path = snapshot_download(
    repo_id="distilbert/distilbert-base-uncased",
    revision="main",
    cache_dir="/data/huggingface/hub",
)
print(snapshot_path)  # 这里是本次快照路径，不等于缓存根目录

示例中的模型名只是公开仓库示意，生产环境应替换成已确认可用的仓库。迁移时不要只复制某个 blobs 文件；Hub 缓存还依赖 refs、snapshots 等目录关系。若团队更希望把模型当作普通目录交付，也可以在准备阶段记录返回的本地 snapshot 路径，再让加载代码直接指向它。

离线加载要同时固定缓存和模型路径

Transformers 官方建议在无网或受限网络环境提前准备文件，然后设置 HF_HUB_OFFLINE=1，让 Hub 不再发起 HTTP 请求。对单次加载，也可以在 from_pretrained 中传入 local_files_only=True。前者是运行环境约束，后者是调用级约束，部署脚本里可以同时使用。

# 必须在导入 transformers / huggingface_hub 前设置
export HF_HUB_CACHE=/data/huggingface/hub
export HF_HUB_OFFLINE=1

from transformers import AutoTokenizer, AutoModel

# 只读取已经缓存的配置、词表和权重，缺文件时直接报错
tokenizer = AutoTokenizer.from_pretrained(
    "distilbert/distilbert-base-uncased",
    local_files_only=True,
)
model = AutoModel.from_pretrained(
    "distilbert/distilbert-base-uncased",
    local_files_only=True,
)

离线开关并不会替你补齐文件；缺少 tokenizer 配置或权重时，正确结果应是快速失败，而不是把问题隐藏在网络超时里。若已经拿到了明确的本地 snapshot，也可以把路径直接传给 from_pretrained，这样排查时更容易区分“缓存索引没找到”和“目录内容不完整”。

缓存目录改了仍找不到模型，按这张表排查

最后记住三个边界：缓存根目录不是本地 snapshot 路径；换目录不是迁移文件；离线开关也不是下载器。把这三件事分开，模型部署到数据盘、容器卷或内网机器时会稳定很多。

Hugging Face 模型缓存常见问题

HF_HOME 和 HF_HUB_CACHE 能同时设置吗？

可以，但应明确优先级。需要精确控制 Hub 仓库缓存时直接设置 HF_HUB_CACHE；HF_HOME 更适合统一管理 Hugging Face 本地数据。

设置 HF_HUB_OFFLINE=1 后还能下载模型吗？

不能把它当下载开关使用。它的作用是阻止 Hub 发起网络请求，模型必须先在联网阶段准备好。

local_files_only=True 和 HF_HUB_OFFLINE=1 有什么区别？

前者限制一次 from_pretrained 调用，后者限制 Hub 运行环境。部署脚本中同时设置更容易暴露缺失文件。

为什么改了缓存目录却没有释放旧磁盘空间？

新目录只影响后续读取或下载，不会自动搬迁、删除旧缓存。确认新目录可用后，再按仓库和 revision 逐项清理旧目录。