当前位置：首页 > 文章列表 > 科技周边 > 人工智能 > Hugging Face 模型缓存怎么换目录并离线加载

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

来源：17golang原创 2026-09-06 02:38:55 0浏览收藏

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

要点速览

HF_HUB_CACHE 是直接指定 Hub 缓存目录的优先选项，HF_HOME 是更大的 Hugging Face 数据根目录。
用 snapshot_download 提前准备仓库；缓存根目录和某个 revision 的本地 snapshot 不是同一个路径概念。
离线加载要在 import 前设置环境变量，并确认配置文件、 tokenizer 和权重都已经进入缓存。

先选缓存变量：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、缓存和模型文件的边界会混在一起。

Hugging Face HF_HUB_CACHE、HF_HOME 与 XDG_CACHE_HOME 到 Hub 缓存根目录和模型仓库缓存的静态关系图 — 图1：用静态关系图区分 HF_HUB_CACHE、HF_HOME 与 XDG_CACHE_HOME 对 Hub 缓存目录的影响。

准备模型时用 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_download、Hub 缓存、本地 snapshot、HF_HUB_OFFLINE 与 from_pretrained 的静态依赖关系图 — 图2：静态呈现模型仓库、缓存快照和离线加载参数的边界，便于定位缺文件与误联网问题。

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

现象	优先检查	处理方向
仍写入用户目录	变量设置时机和优先级	在 import 前设置，确认没有被更高优先级的 HF_HUB_CACHE 覆盖
离线启动卡住	HF_HUB_OFFLINE 是否生效	启动前设置，并给 from_pretrained 增加 local_files_only=True
找得到仓库但缺文件	快照内容和 revision	重新准备同一 revision，确认 config、tokenizer 和权重齐全

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