Transformers 如何在离线或防火墙环境中离线运行？

如果你的 GPU 实例处于云内网或被防火墙隔离，脚本在下载模型权重或数据集时会挂起，随后抛出连接错误。官方文档描述的现象是下载挂起后超时，并报错：

ValueError: Connection error, and we cannot find the requested files in the cached path.
Please try again or make sure your Internet connection is on.

出现这个错误时，Transformers 的解决思路是：把需要的模型文件提前下载到本地缓存，然后在离线机器上关闭对 Hub 的 HTTP 访问，直接从缓存加载。这条离线工作流记录在 安装文档的 Offline mode 一节中，排错文档的 Firewalled environments 一节也指向同一处。

前提条件

• 已按 安装文档完成 Transformers 安装，其测试环境为 Python 3.10+ 与 PyTorch 2.5+（例如 uv pip install "transformers[torch]"）。
• 离线环境的核心要求（原文表述）：使用 Transformers 于离线或防火墙环境，必须提前下载并缓存所需的文件。
• 模型文件的默认缓存目录由 shell 环境变量 HF_HUB_CACHE 决定，默认是 ~/.cache/huggingface/hub（Windows 为 C:\Users\username\.cache\huggingface\hub）。缓存目录可用以下环境变量按优先级覆盖：HF_HUB_CACHE、HF_HOME、XDG_CACHE_HOME + /huggingface（仅当 HF_HOME 未设置时生效）。

第一步：在有网络的机器上预下载模型

snapshot_download 会把你指定的 Hub 仓库文件下载进本地缓存，是官方给出的预下载方式：

from huggingface_hub import snapshot_download

snapshot_download(repo_id="meta-llama/Llama-2-7b-hf", repo_type="model")

其中 repo_id 换成你实际需要使用的模型仓库。文档同时提到，huggingface_hub 的下载指南中还提供了按 revision 下载、从 CLI 下载、按文件过滤等更多下载选项，可按需要查阅。

下载完成后，让离线机器上对应缓存路径（默认 ~/.cache/huggingface/hub）中存在这些文件。

第二步：在离线机器上启用离线模式加载

设置环境变量 HF_HUB_OFFLINE=1，作用是加载模型时阻止对 Hub 的 HTTP 调用。文档给出的示例是用它运行语言模型训练脚本 examples/pytorch/language-modeling/run_clm.py（... 为文档省略的其余参数，完整参数以该脚本为准）：

HF_HUB_OFFLINE=1 \
python examples/pytorch/language-modeling/run_clm.py --model_name_or_path meta-llama/Llama-2-7b-hf --dataset_name wikitext ...

判断方式：脚本应直接从缓存加载模型继续运行，而不是再出现上文那个 Connection error 报错。

可选分支：用 local_files_only 只加载本地文件

如果模型文件放在某个本地目录（而不是依赖 HF 缓存结构），也可以在 PreTrainedModel.from_pretrained 中设置 local_files_only=True，只从本地加载文件。文档示例：

from transformers import LlamaForCausalLM

model = LlamaForCausalLM.from_pretrained("./path/to/local/directory", local_files_only=True)

其中 ./path/to/local/directory 是文档中的占位路径，替换为你存放模型文件的实际本地目录即可。

限制与参考

• 离线模式不能代替预下载：没有提前缓存文件时，离线加载依然会失败，HF_HUB_OFFLINE=1 只负责阻止对 Hub 的 HTTP 调用。
• HF_HUB_OFFLINE 等 HF_* 变量由 huggingface_hub 管理，环境变量参考文档将离线工作流的入口指向 installation.md 的 Offline mode 一节。
• 如果错误发生在其他环节（导入报错、显存不足等），可回到 排错文档 对照其他章节处理。