这阵子我手上有个任务挺典型：算法服务要从开发机挪到一台完全断网的内网服务器上，模型推理脚本本身倒不复杂，可第一次跑到一半，加载模型那一步卡了很久，最后直接给我抛了个“无法连接服务器”的异常。同事随口问一句“网上不是有离线模式吗”，我嘴上说“对”，心里清楚——离线模式没配好之前，它该联网还是会联网，该失败还是会失败。

HuggingFace 的离线模式看着只是几个环境变量的事，但真正落到断网环境里，牵扯到缓存结构、模型快照、代码参数、部署脚本，甚至容器的权限问题。这篇就按我这次的完整处理过程来讲，从原理到操作再到排错，争取让你拿着就能照做。

1. 先理解离线模型加载为什么比想象中复杂

1.1 模型加载请求的完整链路

我们在代码里写下from_pretrained("某个模型ID")的时候，底层并不只是“读一下本地文件”那么简单。transformers 库在加载前会发起一次网络请求，去 HuggingFace Hub 上确认这个模型是否存在、有没有更新，然后再决定是从缓存直接读取，还是把缺失的权重文件下载下来。

这个逻辑在联网环境里很顺畅，相当于手机连上家里的 Wi-Fi，打开视频 App 直接播放，不需要额外操作。可一旦服务器断网，就等于你把手机切成飞行模式但还指着视频 App 能自动播完——它做不到。因为客户端首先要去握手、校验版本、查文件清单，这一步失败，整个加载过程就会中止。

之前有同事问我：“模型不已经在本地缓存里了吗？为什么还要访问网络？”核心就在这：HuggingFace 的离线能力靠的不是“模型已经在本地”，而是“它能不能跳过远程校验这一步”。如果你没显式告诉它走离线模式，它默认就要先和远程通信。

1.2 缓存目录才是离线模式的主战场

HuggingFace 的默认缓存路径是这样一套结构：

• 根目录一般叫~/.cache/huggingface/hub
• 下面按模型 ID 分目录，比如models--账号名--模型名
• 目录里再拆成几个子目录：snapshots、blobs、refs

blobs保存的是真正的文件内容，snapshots里保存的是指向blobs的符号链接，用来模拟某个版本快照的文件目录。这种设计有点像 Git：blobs相当于对象库，snapshots相当于特定提交的工作区。

加载模型时，transformers 会先去refs/main里读取当前主分支对应的 commit 号，再进入snapshots/<commit号>去映射文件位置。如果 commit 校验通过且文件都在，它可以做到“零网络”加载。但要触发这个逻辑，你得让它明确知道：当前环境不需要联网，也不要尝试做远程检查。

理解了这套结构，后续所有配置都会变得顺理成章。你要做的事，就是把该下载的文件提前塞进这套结构，然后在断网机器上告诉库“别上网，就在这里找”。

1.3 明确离线模式的适用边界

这里要提前泼一盆冷水：离线模式不是万能的，它只解决“模型仓库文件已经完整存在于本地”的情况。如果你的模型仓库还依赖某些运行时动态拉取的扩展、自定义代码、或者某些大文件被阉割了，离线照样失败。所以建议在动手前先确认三件事：

• 模型 ID 和 revision（分支或 commit）要固定，不要留main这种会变动的引用
• 需要的附属文件齐不齐，比如 tokenizer 文件、配置文件、自定义 modeling 代码
• 目标机器上的 transformers、huggingface_hub 版本不能和打包机器差太多，否则缓存目录读取逻辑可能不兼容

离线模式本质上是“缩窄了加载范围”，不是“改变了加载逻辑”。理解这一点，后面遇到奇怪错误时就不会一头雾水。

2. 联网机器上如何一次把模型包准备齐

2.1 先查仓库 ID、修订版本与依赖文件清单

我第一次打包模型的时候，直接执行了下载命令，结果漏掉了 tokenizer 的附加文件，离线部署后加载到一半报错，非常尴尬。所以现在养成的习惯是：下载前先列出仓库里到底有哪些文件。

最新的 huggingface_hub 提供list_repo_files，可以快速看到模型仓库的全部文件清单，尤其是.bin、.safetensors、.txt、.json、.py这些后缀，能帮你确认依赖是否完整。命令形式大致是：

huggingface-cli repo info 某个账号/某个模型

如果安装的是较新版本，也可以用 Python 代码：

from huggingface_hub import list_repo_files files = list_repo_files("某个账号/某个模型") print(files)

这一步的意义不是走流程，而是提前建立一张“模型包裹清单”。我通常会把输出保存成文本，和后续实际下载的目录做核对，确保打包分发时不会漏文件。

2.2 下载整个快照的命令与参数拆解

下载模型推荐用huggingface-cli download而不是手动去逐个wget。命令可以带几个关键参数：

huggingface-cli download 某个账号/某个模型 \ --revision main \ --cache-dir /data/offline_models/cache \ --local-dir /data/offline_models/bundle

这里我用到了两个目录参数，很多人容易混：--cache-dir是给 huggingface_hub 自己管理缓存用的，下载的文件会按我们前面说的snapshots、blobs结构存放；--local-dir则是把仓库文件平铺到一个目录里，更像传统下载。实际测试下来，如果你的最终目标是“离线后在另一台机器上通过 transformers 加载”，保留--cache-dir的完整缓存结构是最稳妥的。--local-dir适合你想直接拿到扁平文件、自己管理加载路径的场景，但那样就需要在代码里额外指定路径。

为了让离线环境更可控，我通常会把--revision从main换成固定 commit。这样做的好处是，缓存里的refs指向不会因为后续远程仓库更新而变化。你可以先在联网机器上查一下 commit 号：

huggingface-cli scan-cache

或者直接在网页端复制 commit 哈希，然后下载时带上去。

2.3 提前把 tokenizer、模型、配置一次拉齐

对大多数自然语言处理项目来说，光有模型权重文件还不够。一个典型模型的必需文件通常包括：

• config.json：模型结构参数
• tokenizer.json/tokenizer_config.json：分词器配置
• vocab.txt/merges.txt：词表和 BPE 合并规则
• model.safetensors或pytorch_model.bin：模型权重
• 可能的generation_config.json、special_tokens_map.json等

如果你通过huggingface-cli download下载整个仓库，这些文件一般都会拉齐。但要注意的是，如果你的代码后续还使用了 “自动分词器” 或者 “自动处理器”，比如调用了AutoTokenizer.from_pretrained，它同样会尝试联网检查。所以不只是模型权重，所有配套文件都要进入同一套缓存。

我在打包时还会额外验证一个动作：联网状态下先在打包机器上真实运行一次模型推理。这个验证动作会确保所有文件不仅被下载到磁盘，而且能被缓存机制正确索引。很多文件缺失、目录错误的问题，都能在这一步提前暴露。

2.4 制作分发包档案：目录切割、校验和检查

模型文件打包到内网环境时，最常用的方式是把整个缓存目录打成压缩包。

cd /data/offline_models tar czf offline-models-bundle.tar.gz cache

这里有几个注意点：

• 如果缓存目录里文件特别多，建议不要直接在磁盘上压缩后再拷贝，而是先tar到目标存储里，避免产生大量零散文件传输
• 某些环境对符号链接支持不好，如果迁移过程中软链接断掉，缓存目录会瞬间“看起来完整、实际不可用”
• 打包完成后，务必记录整个缓存目录的大小，核对文件数量

一个实用的校验方法：

tar -tvzf offline-models-bundle.tar.gz | wc -l

在源机器上记录数量，目标机解压后再统计，两者一致才心中有底。

3. 断网环境部署：环境变量与代码改造双保险

3.1 两套环境变量怎么理解：HF_HUB_OFFLINE 与 TRANSFORMERS_OFFLINE

离线模式最核心的两个环境变量是：

• HF_HUB_OFFLINE：让 huggingface_hub 这个底层库直接跳过所有网络请求
• TRANSFORMERS_OFFLINE：让 transformers 上层逻辑在创建 pipeline、加载模型时也默认走离线路径

实际使用中，我两个都会设，因为 transformers 本身和 huggingface_hub 在不同版本里对离线支持的程度有细微差别。设成1就行：

export HF_HUB_OFFLINE=1 export TRANSFORMERS_OFFLINE=1

如果你还用到 datasets，建议顺手加一个HF_DATASETS_OFFLINE=1。早期版本曾用HF_DATASETS_OFFLINE这个命名，现在 datasets 也在逐步拥抱 huggingface_hub，但加上这个变量不影响正常使用，反而更保险。

关于三者的分工，可以简单理解成：

• HF_HUB_OFFLINE控制“下载管道的开关”
• TRANSFORMERS_OFFLINE控制“transformers 加载逻辑的开关”
• HF_DATASETS_OFFLINE控制“数据集加载的开关”

三者配合，才算把整条加载链路都按住。

3.2 代码里显式声明 local_files_only 的正确姿势

环境变量设了，代码里最好再加一道保险。from_pretrained系列方法大多支持local_files_only参数，只要设为True，不管环境变量有没有生效，都不会发起网络请求。

基础用法：

from transformers import AutoModelForSequenceClassification, AutoTokenizer model_name = "某个账号/某个模型" model = AutoModelForSequenceClassification.from_pretrained( model_name, local_files_only=True, ) tokenizer = AutoTokenizer.from_pretrained( model_name, local_files_only=True, )

如果你用的是pipeline接口，参数传递方式略有不同。早期一些坑是直接传local_files_only=True会爆参数错误，正确姿势是塞进model_kwargs：

from transformers import pipeline classifier = pipeline( "text-classification", model="某个账号/某个模型", model_kwargs={"local_files_only": True}, )

local_files_only是个很纯粹的逻辑：它不在本地缓存命中就直接抛错，绝不尝试联网。这对离线部署是理想行为，因为你宁可看到一个清晰的报错，也不想看到服务器悄悄卡在超时重试。

3.3 如何让缓存目录被持久化容器和非 root 用户正常访问

部署模型经常会遇到两个问题：一是代码跑在 Docker 容器里，二是服务进程用非 root 用户启动。这两个场景都会影响缓存目录读取。

如果是 Docker，关键在于启动容器时把缓存目录以只读方式挂载进去：

docker run -d \ -v /data/offline_models/cache:/root/.cache/huggingface \ -e HF_HUB_OFFLINE=1 \ -e TRANSFORMERS_OFFLINE=1 \ your-service-image:latest

这里要注意，容器内代码如果以 root 跑，默认缓存路径是/root/.cache/huggingface。如果你在镜像里特意设置了HOME环境变量为/app，路径就得跟着变，别被默认值误导。

如果是非 root 用户，最容易踩的坑是权限。模型文件如果是 root 打包的，解压后普通用户可能没有读权限，离线加载时会看到一堆 “Permission denied”。处理办法是递归调整权限，或者解压后用chown归属到运行服务的用户：

sudo chown -R service_user:service_group /data/offline_models/cache

这个操作很基础，但特别容易漏。我见过不止一次因为权限问题导致服务起不来，还让排查方向跑偏到网络上的案例。

3.4 用启动脚本统一注入环境变量

环境变量的设置方式如果散落在各个配置文件里，维护起来很痛苦。我更推荐写一个启动脚本，专门负责“离线环境变量 + 缓存路径 + 服务启动”全套工作。

下面是一个可以直接参考的模板：

#!/bin/bash export HF_HOME=/data/offline_models/hf_home export HF_HUB_OFFLINE=1 export TRANSFORMERS_OFFLINE=1 export HF_DATASETS_OFFLINE=1 cd /app/my_service exec python app.py

设置HF_HOME的好处是把缓存目录从默认的~/.cache/huggingface迁移到一个稳定、可控的路径，避免用户切换时找不到缓存。我把HF_HOME和HF_HUB_CACHE的关系也理一下：HF_HUB_CACHE可以单独指定缓存子目录，但大多数场景只需要设置HF_HOME就够了。

4. 高频报错排查与部署防坑清单

4.1 报错一：明明设置了离线模式还提示无法连接服务器

这个报错第一反应不是看网络，而是确认环境变量到底有没有被服务进程继承。常见原因有三个：

• 环境变量只写进了某个 shell 会话，但服务由 systemd 或其他管理器启动，没读到
• 代码里人为覆盖了环境变量或者local_files_only被改成False
• 使用了不同的用户身份启动服务，而环境变量设置是在另一个用户的配置里

排查时，先在服务启动用户下执行:

echo $HF_HUB_OFFLINE echo $TRANSFORMERS_OFFLINE

如果输出是空的，说明根本没继承上。另一种简单粗暴验法是在启动命令前临时加env HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 python app.py，如果这样就能过，问题基本定位在环境变量注入环节。

4.2 报错二：文件反复查找但目录index.json不匹配

这个报错有点隐晦。看起来缓存目录里有文件，也加载到了多个文件，但最后总在某个文件上提示找不到，或者版本对不上。

这通常发生在你把打包机器的缓存目录拷贝到目标机时，符号链接结构被破坏了。前面说过，snapshots里的文件是指向blobs的符号链接，很多拷贝方式默认不保留符号链接，比如直接用普通的cp -r或者某些网盘同步工具就会丢。

解决办法有两个方向：

• 用tar/rsync -a保留符号链接
• 如果文件已经拷乱了，可以删除对应的模型缓存目录，重新解压原始 tar 包，别试图手工修复一半

我自己的习惯是：任何一次跨机器迁移 huggingface 缓存，都当成一个完整的压缩归档处理，不在中间做增量同步。

4.3 报错三：HF_HUB_OFFLINE 对 pipeline 模式的自动加载失效

场景是这样：环境变量全设好了，用AutoModel加载没问题，但一旦用pipeline，又会出现联网请求。

问题不在环境变量，而是pipeline初始化时不一定把所有传入参数都透传给底层from_pretrained。如果你只是pipeline("text-generation", model="某个账号/某个模型")，它默认还是会按 transform 的标准流程尝试加载，尽管有TRANSFORMERS_OFFLINE兜底，但某些版本存在差异。

更稳的写法是把local_files_only明确写进model_kwargs：

from transformers import pipeline pipe = pipeline( "text-generation", model="某个账号/某个模型", model_kwargs={"local_files_only": True}, )

如果是自定义模型类，也可以把model_kwargs换成config文件中已有的参数，但最直接的就是上面这种。

4.4 报错四：磁盘挂载导致缓存碎片化

还有一种比较少见的坑：你把缓存目录放在了通过网络挂载的共享盘上，访问速度很不稳定，读取时偶尔出现文件句柄超时，导致加载失败。这和离线模式本身关系不大，但会影响最终体验。

遇到这种场景，建议把缓存目录放在本地 SSD/HDD 上，或者至少保证一个副本在本地。如果必须用共享存储，优先考虑下流行的内容寻址方案，把大文件分块存储，避免一次读取整个大权重文件时耗尽连接。

5. 我在离线部署中养成的三个习惯

5.1 下载时固定每次的 commit 版本号

模型仓库在持续更新，哪怕只是 config 里的一个小字段改动，都可能让缓存目录中refs/main指向的 commit 改变。离线环境无法及时跟进远程更新，如果你的代码还写死了某个特定行为，就必须固定 commit。

我现在的做法是，在项目目录里保存一个model_pin.txt，里面记录模型 ID、commit 号、下载日期。这样无论是三个月后重新打包，还是同事接手，都能一眼看出当前用的到底是什么版本。

model_id: my-team/classifier-x revision: 9f8c2a1 download_date: 2025-02-10

5.2 用实测脚本验证“真正断了网”

部署完成后，我会跑一个“断网自检”，不是看ping通不通，而是直接看加载模型时会不会卡在网络请求上。

简单做法是在目标机上临时把缓存目录复制一份到内存盘，然后把原缓存目录改个名字，强制它从新路径加载。还有一种更直接的方式：在目标机上把HF_HUB_OFFLINE=1配上local_files_only=True，再跑一次推理，观察日志里有没有出现“fetch”“connect”等关键词。

我习惯把验证脚本做成固定入口：

python verify_offline.py

脚本里加载模型、加载 tokenizer、跑一个最短推理、打印结果。每次部署完先跑它，绿灯了再启动正式服务，能省下很多莫名其妙的排障时间。

5.3 事后对缓存目录做一致性校验

离线部署不是交付完就结束了。缓存目录可能因为人为误删、覆盖安装、磁盘空间清理等方式被弄坏。我建议把“缓存一致性校验”纳入定期巡检或灾备演练。

可以利用huggingface-cli scan-cache看一下现有缓存状态，确认哪些模型是完整快照，哪些是孤儿缓存。这个工具能输出比较清晰的表格，列出模型、版本、大小、占用情况，适合作为巡检基准。

如果团队有监控平台，还可以给模型加载成功/失败加个指标。当某一次模型加载异常时，先看缓存状态，再定位代码变更，处理效率会高很多。

离线模式真正落地之后，这类部署就不再是“玄学”了。它就是一个有固定步骤、固定校验方法的工程活儿。你在断网环境里遇到的每个错误，几乎都能回溯到“环境变量没设、文件没下全、缓存结构被破坏、代码没显式离线”这四个原因之一。把这几条堵住，剩下的事情就顺了。