你们有没有遇到过这种情况：模型文件明明已经全部缓存在本机，拔掉网线之后再跑推理脚本，结果加载阶段照样卡在超时上，控制台刷了一屏Connection error。我在离线环境里踩过好几次类似的坑，最后是靠一套固定的 HuggingFace 离线模式配置把问题压下去的。这篇文章就把我的做法、背后的原理以及踩坑记录完整写出来，希望能帮你在断网环境下也能顺畅加载模型。
这篇内容适合三类人：做模型部署、需要把推理服务搬进无外网环境的人；团队多人共用一台 GPU 机器、经常被网络波动搞到上游加载失败的人；还有刚接触 HuggingFace、搞不清HF_HUB_OFFLINE、local_files_only、缓存目录到底是什么关系的初学者。本文不绕弯子，直接从现象、原理、实操和排错四个层面来讲，每步都给可以照抄的命令和写法。
1. 问题现象与根因：from_pretrained到底卡在哪一步
1.1 一个典型的断网加载失败现场
先描述一个我反复撞见的过程。你写了一个很正常的推理脚本：
from transformers import AutoModel, AutoTokenizer model_name = "some-org/some-model" model = AutoModel.from_pretrained(model_name) tokenizer = AutoTokenizer.from_pretrained(model_name)在有网的时候跑得很快，下载完之后第二次运行也不会重新下载全部文件，因为 HuggingFace 有本地缓存。问题出在断网之后：你确认过/root/.cache/huggingface/hub下确实有models--some-org--some-model这个目录，可脚本依然报错，报错信息大致是：
Connection error: We couldn't connect to 'https://huggingface.co' to load this model, it's possible that the model you're trying to load is not available locally.这个报错最让人困惑的地方在于：缓存明明存在，但程序还是先尝试访问远端，访问失败后又没自动落到本地，最后直接终止。你可能会怀疑是缓存坏了，删掉重新下载，等下次断网又一样。
后来我逐步理解到，HuggingFace 的加载器并不完全是把“本地缓存”当作首选，它在定位文件时，会先检查远端仓库的信息，只有当离线开关生效时，才会彻底跳过远端探测。这个问题不是个例，换到datasets、diffusers等库也一样。
1.2from_pretrained内部的“远端优先”逻辑
要理解离线模式为什么需要显式配置，得先弄清楚from_pretrained是怎么找你模型的。
transformers里的from_pretrained最终会调用huggingface_hub这套底层库。底层库接收一个repo_id（类似some-org/some-model），然后按这套流程处理：
- 先看传入的是不是一个本地路径，如果是本地路径，就直接读取本机文件，不走 Hub。
- 如果不是本地路径，就视为 Hub 仓库 ID，开始定位本地缓存是否已有这个仓库的快照。
- 如果本地快照存在，而你没有开启
local_files_only，某些情况下仍会去访问远端，确认当前 revision 是否还是最新，或者补全缺失文件。 - 如果本地没有任何缓存，自然就会发起下载请求。
所以问题不在于“缓存是否能用”，而在于“加载器要不要进行联网探测”。默认情况下，远端仓库才是它眼里的“完整事实来源”，本地缓存只是它用来加速的副本。一旦网络不是完全不通，而是超时、DNS 解析慢、被防火墙掐住连接，那加载器会卡在网络等待上，而不是立刻切回本地缓存。
这也是为什么单纯把模型文件放在默认缓存目录里还不够。只要没告诉它“只许用本地”，它就会试着往外连，而离线模式的本质，就是把这个“往外连”的动作直接掐断。
1.3 三个关键环境变量到底控制什么
HuggingFace 的离线配置有几个入口，最常用的是下面几个环境变量。
| 环境变量 | 作用范围 | 典型值 | 说明 |
|---|---|---|---|
HF_HUB_OFFLINE | huggingface_hub基础层 | 1/0 | 当前最推荐的开关，设为1后统一禁止 Hub 联网请求 |
TRANSFORMERS_OFFLINE | transformers库 | 1/0 | 兼容老项目的开关，transformers内部也会读取，建议和HF_HUB_OFFLINE一起设置 |
HF_DATASETS_OFFLINE | datasets库 | 1/0 | 专门控制数据集加载是否走离线模式 |
HF_HOME | 缓存根目录 | /data/hf_home | 默认是~/.cache/huggingface，设置后模型、数据集、模块缓存都会集中到这里 |
HF_HUB_CACHE | 模型与数据集仓库缓存 | /data/hf_hub_cache | 优先级高于HF_HOME下面的hub子目录 |
这里有个容易混淆的点：HF_HUB_OFFLINE是基础层开关，它会影响所有基于huggingface_hub的库，包括transformers、diffusers、sentence-transformers等。TRANSFORMERS_OFFLINE是偏老牌的做法，在很早期的transformers项目中就存在，为了兼容旧代码，我一般会把两个都配上。
另外，HF_HOME和HF_HUB_CACHE决定的是缓存目录，和离线开关是两个维度。正确姿势是：先把缓存目录指到你要用的位置，再把离线开关打开。否则缓存文件散落在多个位置，即使开了离线模式，也可能因为找不到对应路径而报“模型不存在”。
2. 离线模式配置的核心思路与方案取舍
2.1 几种可行的离线加载方案对比
离线模式不是只有一种写法，按使用场景可以分成四类，我列个表直接对比。
| 方案 | 适合场景 | 优点 | 需要注意的地方 |
|---|---|---|---|
设置HF_HUB_OFFLINE=1环境变量 | 容器、服务、定时任务 | 全局生效，改一次即可 | 会跳过所有 Hub 联网操作 |
代码里传local_files_only=True | 单独脚本、逻辑分支 | 精细控制，不影响其他联网功能 | 需要逐个加载点修改 |
| 先在线下载，再迁移完整缓存目录 | 完全无网的机器 | 不依赖目标机器网络 | 要维护缓存包的版本 |
| 共享缓存目录 | 多机、多容器 | 避免重复下载 | 需要处理并发和权限问题 |
我自己偏向“环境变量优先，代码参数兜底”的组合：通常环境变量管全局，一旦有某个库不认环境变量，就在代码里加local_files_only=True。这种组合可以在不改动业务代码逻辑的前提下，把绝大多数加载问题按住。
2.2 系统环境变量的配置方法与注意点
在 Linux 或 macOS 上，直接写进启动脚本即可：
export HF_HUB_OFFLINE=1 export TRANSFORMERS_OFFLINE=1 export HF_HUB_CACHE=/data/hf_model_cache如果你用的是 systemd 管理推理服务，可以把环境变量写进 service 文件：
[Service] Environment="HF_HUB_OFFLINE=1" Environment="TRANSFORMERS_OFFLINE=1" Environment="HF_HUB_CACHE=/data/hf_model_cache"Windows 上在 PowerShell 里这样设置：
$env:HF_HUB_OFFLINE = "1" $env:TRANSFORMERS_OFFLINE = "1" $env:HF_HUB_CACHE = "D:\hf_cache"设置完记得用python -c "import os; print(os.environ.get('HF_HUB_OFFLINE'))"验证一下。我在实际项目里遇到过环境变量写进.env文件但服务没加载.env的情况，排查了半小时才发现变量根本没到子进程里。
还要注意：环境变量是对当前进程及它的子进程生效。如果你把命令放到nohup、cron或容器里，要确保变量在那些环境下同样可见。写进Dockerfile是最不容易漏的方式：
ENV HF_HUB_OFFLINE=1 ENV TRANSFORMERS_OFFLINE=1 ENV HF_HUB_CACHE=/data/hf_model_cache2.3 代码级配置：local_files_only的正确打开方式
如果你的情况比较特殊，比如同一个程序里既要加载本地缓存，又要偶尔做在线拉新，那就不适合全局设置环境变量，而是应该在单个调用里指定离线加载。
以transformers为例：
from transformers import AutoModel, AutoTokenizer model_id = "some-org/some-model" model = AutoModel.from_pretrained(model_id, local_files_only=True) tokenizer = AutoTokenizer.from_pretrained(model_id, local_files_only=True)一旦加了local_files_only=True，加载器就不会尝试访问 Hub，只会在本地缓存或给定路径里找。如果本地没有目标模型，会直接抛出OSError而不是卡在连接超时上。这个异常反而更“干脆”，方便你在代码里做降级处理。
我处理离线降级时的写法是这样：
from transformers import AutoModel, AutoTokenizer model_id = "some-org/some-model" try: model = AutoModel.from_pretrained(model_id, local_files_only=True) tokenizer = AutoTokenizer.from_pretrained(model_id, local_files_only=True) except OSError: raise RuntimeError( f"模型 {model_id} 不在本地缓存中，无法离线加载，请先在有网环境完成下载" )这里有几个细节值得注意：
local_files_only在transformers里已经支持很久了，但不是所有底层加载器都叫这个名字，有些接口叫use_auth_token或不接受该参数，要按具体库的文档确认。- 如果你显式传了
force_download=True，那即使HF_HUB_OFFLINE=1也可能不生效，因为force_download会强制绕过缓存。很多“开了离线还是联网”的诡异问题，都是这里打架造成的。 - 两个组件要分别传
local_files_only=True，不要只给AutoModel传而忘了给AutoTokenizer传。否则加载器同样会去联网找 tokenizer 文件。
代码级配置更灵活，适合做“在线/离线双模式”的程序，但缺点是要侵入业务逻辑。如果是部署类项目，我仍然推荐先配环境变量。
3. 从在线预下载到离线可用的完整实操链路
3.1 在线阶段把模型整包拉下来
离线加载的前提是先有缓存。最稳妥的做法是找一台能联网的机器，先把目标模型完整下载到默认缓存，再整体迁移过去。
用huggingface-cli下载：
pip install -U "huggingface_hub[cli]" huggingface-cli download some-org/some-model如果你想指定 revision，比如固定到某个 commit：
huggingface-cli download some-org/some-model --revision 9a7b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b这里的关键点是：默认不带参数时，HuggingFace CLI 会把模型写入~/.cache/huggingface/hub/models--some-org--some-model目录，这个目录结构是transformers默认能识别的。如果你下载到随意一个自定义目录，之后加载时反而要额外传cache_dir。
下载完成后，用缓存检查命令确认状态：
huggingface-cli scan-cache输出里能看到所有缓存仓库的 ID、revision 和占用空间。如果只想下载某个模型的一部分，可以通过--include/--exclude过滤：
huggingface-cli download some-org/some-model \ --include "config.json" "*.safetensors" \ --exclude "*.msgpack" "*.h5"这个功能很实用。比如你只做 CPU 推理，不想要 FP16 权重，那就可以只拉config.json和pytorch_model.bin。过滤得当，缓存体积能小不少。
如果项目是 Python 脚本控制一切，也可以直接在代码里用snapshot_download：
from huggingface_hub import snapshot_download snapshot_download( repo_id="some-org/some-model", revision="main", allow_patterns=["*.json", "*.safetensors"], )snapshot_download和 CLI 下载结果一致，都会落在同一个默认缓存目录下，后面用from_pretrained("some-org/some-model")就能直接命中。
3.2 缓存目录结构解析与跨机迁移
HuggingFace 现代版本的缓存目录并不是简单地把文件平铺放下，它的内部结构长这样：
~/.cache/huggingface/hub/ └── models--some-org--some-model/ ├── refs/ │ └── main ├── blobs/ │ ├── 9a7b1c... (文件内容) │ └── 8d2e3f... (文件内容) └── snapshots/ └── 9a7b1c... (commit hash 对应的目录) ├── config.json -> ../../blobs/9a7b1c... └── model.safetensors -> ../../blobs/8d2e3f...这种设计是为了实现去重：如果多个 commit 版本共享同一份文件，blobs里只会保留一份实体文件，而不同版本的snapshots目录通过软链接指过去。
跨机迁移时，最简单的方式是打包整个hub目录：
tar -czf hf_cache.tar.gz -C ~/.cache/huggingface hub再到目标机器解压：
mkdir -p /data/hf_home tar -xzf hf_cache.tar.gz -C /data/hf_home解压后确认路径：如果HF_HOME=/data/hf_home，那缓存目录就是/data/hf_home/hub。
这里要提醒：迁移时不要只复制snapshots而丢掉blobs，因为snapshots下的文件很多是软链接，真正的文件实体在blobs。只复制链接过去就是一堆断链。反过来只复制blobs也行，但要重新生成snapshots目录的链接，手工操作很容易出错，不如整体复制省事。
3.3 不同框架的离线加载示例
离线模式在不同框架里的入口略有差异，但核心目标一致：不要为了加载模型或数据集去访问远端。
transformers加载模型和分词器：
from transformers import AutoModel, AutoTokenizer model_id = "some-org/some-model" model = AutoModel.from_pretrained(model_id, local_files_only=True) tokenizer = AutoTokenizer.from_pretrained(model_id, local_files_only=True)datasets加载数据集时，如果数据已经缓存过：
from datasets import load_dataset dataset = load_dataset( "some-org/some-dataset", split="train", local_files_only=True, cache_dir="/data/hf_home/datasets", )不同版本的datasets对local_files_only的支持程度不太一样。稳妥做法是先用huggingface-cli download把数据集整体拉到本地，再用load_from_disk加载：
from datasets import load_from_disk dataset = load_from_disk("/data/hf_datasets/some-dataset")diffusers加载扩散模型时同样可以加local_files_only：
from diffusers import DiffusionPipeline pipe = DiffusionPipeline.from_pretrained( "some-org/diffusion-model", local_files_only=True, torch_dtype=torch.float16, )如果你是直接用本地目录路径加载，比如from_pretrained("/data/models/some-model")，那加载器会把它当作本地路径处理，基本不涉及 Hub 离线问题。这也是一个绕过离线问题的土办法：把模型包放在固定目录，代码里不要写 repo ID，而是写绝对路径。
3.4 共享缓存与多机复用方案
当你有多台 GPU 机器同时做推理，逐台下载模型太浪费带宽，更合理的做法是共享同一个缓存目录。
最简单的共享手段是使用共享文件系统，把同一块磁盘挂载到多台机器，再统一设置：
export HF_HUB_CACHE=/shared/hf_cache多机共用缓存时要注意并发问题。同一个仓库同时被多个进程写，huggingface_hub内部有一定文件锁机制，但大型模型下载时仍然可能出现互相等待或临时文件残留。我的经验是：
- 先找一台机器预处理模型，确认缓存完整后再开放给其他机器读。
- GPU 机器统一用只读方式挂载缓存，避免推理进程意外写入。
- 如果缓存目录在远程文件系统上，加载大型分片模型时随机读取速度可能比本地 SSD 慢，需要做性能测试。
共享缓存跑通后，模型文件只要下载一次，之后所有机器在断网状态下都能直接from_pretrained。
4. 常见问题与排查技巧实录
4.1 缓存明明存在，却还是报连接错误
这个问题是我被问到最多的。常见原因按出现频率排序：
第一，环境变量没有真正传到推理进程。比如你用docker run启动容器，但写环境变量时漏了-e HF_HUB_OFFLINE=1；或者用了systemd，但变量没写进 service 配置。排查方式很简单，在推理脚本最前面打印一下：
import os print("HF_HUB_OFFLINE =", os.environ.get("HF_HUB_OFFLINE")) print("TRANSFORMERS_OFFLINE =", os.environ.get("TRANSFORMERS_OFFLINE")) print("HF_HUB_CACHE =", os.environ.get("HF_HUB_CACHE"))第二，代码里显式传了cache_dir，而且这个目录和你的实际缓存目录不一致。from_pretrained默认读~/.cache/huggingface/hub，但如果你写了cache_dir="/tmp/cache"，它就会去/tmp/cache找，找不到就会联网。要用统一的路径并保持代码和配置一致。
第三，revision 不匹配。你本地缓存的是某个 commit，代码里写的是revision="main"，如果在有网环境下，加载器会去远端确认main是否就是本地缓存的 commit；断网时这个过程就可能失败。建议用明确的 commit hash 作为 revision，不要用main这种浮动分支。
第四，代码里带了force_download=True。这个参数会让加载器无视已有缓存，强制重新下载。离线环境下只要出现这个参数，基本必卡网络。
4.2 离线模式下依然报“模型不存在”
出现OSError: Can't load model ... no such file or directory时，说明加载器已经进入了 local-only 模式，但本地真的没有对应文件。这时候排查重点不是网络，而是缓存本身。
先用命令看一下缓存里有没有这个仓库：
huggingface-cli scan-cache或者找目录：
find /data/hf_home -maxdepth 3 -type d -name "models--*"如果仓库路径不存在，那就是之前下载没落在这里。常见原因是下载机器和推理机器的HF_HOME不一致，或者下载时用了--local-dir把文件拉到了别的目录。
还有一种情况是仓库存在，但文件不完整。比如中断下载后，blobs里只保留了一部分文件，加载器检查不到必需权重就会抛异常。解决方案很简单：在有网环境重新执行huggingface-cli download some-org/some-model，它会补齐缺失文件，然后清理这个仓库的临时残留。
4.3 Windows 与共享目录下的软链接坑
HuggingFace 缓存会在snapshots目录下创建大量符号链接。Linux 和 macOS 下没有感觉，Windows 上却经常出问题。
典型的报错是：
OSError: Cannot create symbolic link : File name too long或者因为 Windows 默认不允许普通用户创建 symlink，导致缓存构建失败。遇到这种情况，我给出的建议是：
- 在 Windows 开发模式下运行，这个模式会放宽符号链接权限。
- 不要开启“以管理员身份运行”后乱改权限，反而容易把缓存目录的属主搞乱。
- 把
HF_HOME指到一个路径短、没有空格的目录，比如D:\hf_cache，能规避不少 Windows 长路径问题。 - 如果是在公司共享磁盘上跑，要注意文件系统是否支持符号链接，很多 NAS 挂载卷是不支持的。
如果只想忽略符号链接警告，可以设置：
HF_HUB_DISABLE_SYMLINKS_WARNING=1但这只是掩盖问题，该缺的链接还是会缺。最理想的方案还是尽量在 Linux 环境运行模型服务。
4.4 典型报错速查表
我整理了一份离线相关报错的速查表，方便你对照定位。
| 报错关键字 | 可能原因 | 处理思路 |
|---|---|---|
Connection error: We couldn't connect to huggingface.co | 未启用离线模式，且网络不可达 | 设置HF_HUB_OFFLINE=1或加local_files_only=True |
OSError: Can't load model ... no such file or directory | 本地缓存不存在或路径不对 | 检查HF_HUB_CACHE、cache_dir，确认仓库是否已下载 |
Repository Not Found for url ... | repo ID 拼写错误，或模型在缓存里用了不同名称 | 用huggingface-cli scan-cache核对仓库 ID |
Cannot create symbolic link | Windows 权限或共享文件系统不支持软链接 | 调整开发模式、更换本地磁盘 |
TLS/SSL error | 系统时间不同步或证书文件异常 | 检查时间同步，更新证书链 |
A file ... doesn't exist | 缓存文件不完整 | 重新运行snapshot_download补齐文件 |
排查时不要一上来就删缓存。先打印环境变量，再scan-cache，再检查代码里的cache_dir和 revision，大多数问题都能在五分钟内定位。
5. 工程化落地与我的实操心得
5.1 在线更新与离线启动的双模式设计
如果你的服务既要支持在线更新模型，又要在网络断开时自动落到本地缓存，最直接的做法是在启动脚本里做一次网络判断。比如这样：
if curl -s --max-time 3 -o /dev/null https://huggingface.co; then export HF_HUB_OFFLINE=0 else export HF_HUB_OFFLINE=1 fi python run_inference.py这个写法看起来简单，实际效果非常稳定。网络正常时继续沿用远端优先逻辑，网络断开时快速切换到纯本地。
更好的做法是在 Python 代码里控制，这样可以把日志打清楚：
import os import socket def is_network_available(host="huggingface.co", timeout=3): try: socket.getaddrinfo(host, None, timeout=timeout) return True except OSError: return False os.environ["HF_HUB_OFFLINE"] = "0" if is_network_available() else "1"启动日志里把离线标志打印出来，后面排查线上问题会省很多事。
5.2 模型版本固化与缓存完整性校验
离线模式最怕的不是没网络，而是缓存被误更新或误删。我在团队里推行的做法是把模型 revision 写进依赖清单，和代码一起提交：
# model_requirements.txt some-org/some-model@9a7b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b some-org/embedding-model@main每次发布前，用脚本扫描缓存并记录每个模型的 commit hash。如果有更新需求，先在开发机下载新版本，跑完评测再更新线上缓存。这样流程清晰，也不会出现线上机器突然联网拉到一个和验证版本不一致的权重。
还要定期检查缓存完整性。最简单的办法是对整个hub目录做一次 checksum 记录，发布时再次比对：
find /data/hf_home/hub -type f -exec sha256sum {} \; > cache_checksums.txt模型文件通常很大，全量校验比较耗时，但发布前的灰度机器抽查还是值得做的。
5.3 最后的几条个人经验
在我实际维护离线环境的经历中，有几点体会特别深。
第一，不要把 repo ID 和本地路径混着用。如果代码里写的是 repo ID，模型文件就必须在标准缓存目录下；如果写本地路径，就把模型包放到固定目录并使用HF_HUB_CACHE统一管理。两种方式各有用处，但混用会让排查变得困难。
第二，环境变量宁多勿缺。我通常是HF_HUB_OFFLINE=1和TRANSFORMERS_OFFLINE=1一起设，并额外把HF_HUB_CACHE指到独立磁盘。多一个变量不会损失什么，少一个却可能让你在断网时多踩一次坑。
第三，离线加载要提前演练。不要等到真断网了再去试。我一般在有网环境下载完模型后，直接断开网络或通过配置把网络路径改成不可达，跑一遍完整推理链路，确认没报错再上线。一次演练能省掉后续大量紧急排查时间。
如果你正在计划把模型服务部署到无外网的机房，或者只是希望摆脱 HuggingFace 网络波动对训练和推理的影响，先把缓存建好，再把离线模式跑通，这套组合确实能让人踏实不少。
