Transformers 怎么离线加载 AI 模型？核对本地目录并完成一次推理

Transformers 离线加载的关键是：先准备完整本地模型目录和运行依赖，在新进程导入库之前设置 HF_HUB_OFFLINE=1，加载时再指定 local_files_only=True。验收需要真的运行一条输入并检查输出，不能只看目录存在。

本文在 Windows、Python 3.11.15、PyTorch 2.6.0 CPU、Transformers 4.57.1、huggingface_hub 0.36.2、Safetensors 0.8.0 环境运行。测试对象是公开 tiny-random-bert 小模型，输出只验证加载与前向计算，不代表真实语义理解质量；没有测试 GPU、大模型内存需求或读者的网络隔离环境。

离线前准备什么

Transformers 官方离线说明要求提前下载模型文件，并说明 HF_HUB_OFFLINE 与 local_files_only 的用法。依赖包、权重、配置和 tokenizer 都应提前准备；只设置环境变量，不能让缺失文件自动出现。

建立一个空练习目录并进入它。以下安装命令需要网络；离线目标机应提前完成相同依赖安装或准备兼容的安装包，而不是断网后再执行 pip 下载。

py -3.11 -m venv .venv-offline
.\.venv-offline\Scripts\python.exe -m pip install "torch==2.6.0" --index-url https://download.pytorch.org/whl/cpu
.\.venv-offline\Scripts\python.exe -m pip install "transformers==4.57.1" "huggingface_hub==0.36.2" "safetensors==0.8.0"

首次准备仍然联网。将以下代码保存为 prepare_model.py，用同一环境运行；它按官方 Hub 下载接口固定提交并保存到本地目录。

from huggingface_hub import snapshot_download
snapshot_download(
    repo_id="hf-internal-testing/tiny-random-bert",
    revision="f171d7baecaf37b5da5a3616d8833b9969753535",
    local_dir="models/tiny-random-bert",
    allow_patterns=["*.json", "*.safetensors", "vocab.txt"],
    token=False,
)

.\.venv-offline\Scripts\python.exe -X utf8 prepare_model.py

这个提交的模型资料标明其 model_type 为 bert，AutoModel 可读取其配置。它不是聊天模型，不应该用本文的 hidden state 输出判断问答能力。

在新进程中加载并执行一次前向计算

将下面代码保存为 offline_check.py，运行 .\.venv-offline\Scripts\python.exe -X utf8 offline_check.py。运行目录应与 prepare_model.py 一致。代码先确认本例所需六个文件存在，再加载本地分词器和模型。

这个演示还主动拦截普通 socket 连接，便于发现加载过程意外尝试联网。它只作用于当前 Python 进程，不能代替操作系统防火墙、整台机器断网或对其他进程的审计；真实隔离环境应按自己的网络策略另行验证。

import os
os.environ['HF_HUB_OFFLINE'] = '1'
import socket
def forbid_network(*args, **kwargs):
    raise RuntimeError('此演示禁止socket连接')
socket.socket.connect = forbid_network
socket.socket.connect_ex = forbid_network
socket.create_connection = forbid_network

from pathlib import Path
import torch
from transformers import AutoTokenizer, AutoModel

folder = Path('models/tiny-random-bert').resolve()
required = ['config.json', 'model.safetensors', 'tokenizer.json',
            'tokenizer_config.json', 'special_tokens_map.json', 'vocab.txt']
for name in required:
    p = folder / name
    if not p.is_file():
        raise RuntimeError(f'本地文件缺失: {name}')
tokenizer = AutoTokenizer.from_pretrained(folder, local_files_only=True)
model = AutoModel.from_pretrained(folder, local_files_only=True,
                                use_safetensors=True).cpu().eval()
inputs = tokenizer('Hello AI.', return_tensors='pt')
with torch.inference_mode():
    hidden = model(**inputs).last_hidden_state
expected_shape = (1, inputs['input_ids'].shape[1], model.config.hidden_size)
assert tuple(hidden.shape) == expected_shape
assert torch.isfinite(hidden).all().item()
print('input_shape:', tuple(inputs['input_ids'].shape))
print('hidden_shape:', tuple(hidden.shape))
print('finite:', torch.isfinite(hidden).all().item())
print('socket_connections: blocked')

怎样解释本次运行结果

input_shape: (1, 10)
hidden_shape: (1, 10, 32)
finite: True
socket_connections: blocked

输入是一条文本，分词后含 10 个 token；输出在这次测试中是 1×10×32 的隐藏状态。断言同时检查了输出形状与有限数值。得到这些结果，说明本例在禁止普通 socket 连接的进程中完成了本地加载和前向计算，不证明测试模型完成了可靠分类。

换模型后，token 数和 hidden_size 可以不同，不应强行要求输出仍是 1×10×32。应检查它是否符合该模型的配置和任务输出契约，例如分类 logits 的类别维度或生成结果的 token 序列。

加载失败时，从缺项而不是从开关入手

下一步可以把模型目录与原下载记录一起转移到目标机，在已经安装兼容依赖的新进程中重新运行同一固定输入，保存版本、输入和形状记录。

local_files_only 是否等于整个应用不会联网？

它限制这次加载使用本地文件；HF_HUB_OFFLINE 限制 Hub HTTP 调用。应用的其他网络请求、其他库和其他进程仍需单独核对。若你的实际目标是中文翻译，读取OPUS-MT 中文到英文离线翻译教程可继续处理译文校验；本篇主要解决通用本地加载是否跑通。