离线部署 Hugging Face 模型，核心不是在目标机器上下载，而是提前在有网环境把模型文件落成完整缓存目录，再整体搬运到内网。这样在线机器产生流量，离线机器只做本地目录读取。

可以用 huggingface-cli download 在有网机器把模型仓库完整下载到指定缓存目录，再复制到离线机并通过 HF_HUB_CACHE 指向该目录；加载时配合 TRANSFORMERS_OFFLINE=1 强制禁止网络请求。实际能否成功，取决于模型文件是否完整、缓存路径是否被 transformers 正确识别，以及 transformers 和 huggingface_hub 版本是否兼容。

下面按准备、下载、迁移、验证四步给出可执行命令，并根据环境提供两种缓存方式。

准备有网环境

huggingface-cli 来自 huggingface_hub 包，需要先安装。可以在准备机（能访问互联网的普通笔记本或服务器）上执行：

pip install -U huggingface_hub

确认命令可用：

huggingface-cli version

如果出现 command not found，检查 Python 环境是否激活。

下载模型仓库到本地

用 huggingface-cli download 下载指定模型，建议先把下载目录单独规划出来，例如：

mkdir -p /data/hf_download
huggingface-cli download gpt2 `--cache-dir` /data/hf_download

其中 gpt2 替换为目标模型名，例如 bert-base-uncased、sentence-transformers/paraphrase-MiniLM-L6-v2。私有模型需要登录，可先执行 huggingface-cli login 或带 `--token`。

如果当前 huggingface_hub 版本支持 `--local-dir`，可以直接生成扁平目录，离线加载时更直观，也避免缓存目录里的符号链接在复制后断掉：

huggingface-cli download gpt2 `--local-dir` /data/hf_model_gpt2

需要结合当前环境确认 CLI 是否支持 `--local-dir`；如果不支持，退回 `--cache-dir` 方式。

cache-dir 保留标准缓存结构，transformers 通过哈希匹配；local-dir 直接将模型文件放到一个目录，加载时传路径即可。选用哪种取决于你后面习惯哪种加载方式。

离线机指定本地路径

把上面生成的目录整体传送到离线机，例如放到 /opt/hf_cache。然后设置环境变量：

export HF_HOME=/opt/hf_cache
export HF_HUB_CACHE=$HF_HOME/hub
export TRANSFORMERS_OFFLINE=1

如果模型是用 `--local-dir` 下载的，则不需要设置 HF_HUB_CACHE，加载时直接写模型路径，也可以一并设置 TRANSFORMERS_OFFLINE 来阻止任何网络请求。

如果使用 cache-dir 结构，/opt/hf_cache 下应该能看到由模型名 hash 生成的子目录，而不是直接看到 gpt2 文件夹。建议用 huggingface-cli scan-cache 检查目录摘要：

huggingface-cli scan-cache

它会在当前配置的缓存目录里列出已缓存的模型、版本和占用空间。

验证离线加载

在离线机跑以下 Python 脚本，确认 transformers 能通过本地缓存还原模型：

from transformers import AutoTokenizer, AutoModel
model_name = 'gpt2'
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModel.from_pretrained(model_name)
print(tokenizer.encode('hello'), model.config.hidden_size)

如果环境变量设置正确，并且模型文件完整，这段代码会正常输出 token id 和 hidden_size。TRANSFORMERS_OFFLINE=1 已经能强制本地加载，不需要额外禁用网络。

还有一个容易出问题的点：不要只复制权重文件（比如 .safetensors 或 .bin）。transformers 加载模型时还要求 config.json、tokenizer.json 等元文件在同一份快照内。huggingface-cli download 默认会取整个仓库，所以尽量不要用 `--include` 做部分下载，除非你明确知道所用加载方式只需要那些文件。