大模型原理与训练 / 系统课时
保存并离线重载模型
保存并离线重载模型
模型在联网机器上能运行,不代表复制几份权重后就能离线交付。一个可重复使用的本地包至少要让模型配置、权重和分词器彼此匹配,并在禁止访问 Hub 的新进程中成功重载。本篇会完成保存、完整性检查和离线验证闭环。
学习目标
- 使用
save_pretrained()保存模型与分词器所需文件 - 用
local_files_only=True和HF_HUB_OFFLINE=1验证不会偷偷回源下载 - 识别离线交付中常见的缺文件、版本漂移和缓存误判问题
明确离线目录里要有什么
模型对象与分词器对象需要分别保存。模型侧通常包含 config.json 与权重文件,生成模型还可能带有 generation_config.json;分词器侧则可能包含 tokenizer.json、词表、special tokens 配置等。具体文件名因模型家族而异,因此不要用“固定文件清单”替代真实重载测试。
| 组成 | 典型内容 | 缺失后的表现 |
|---|---|---|
| 模型配置 | config.json、可选生成配置 |
无法还原架构或生成参数 |
| 模型权重 | model.safetensors 或分片权重 |
模型无法实例化为已训练状态 |
| 分词器 | tokenizer 配置、词表或 tokenizer 文件 | 文本无法稳定转换为训练时的 token ID |
只调用 model.save_pretrained() 而忘记保存 tokenizer,是最常见的不完整交付之一。反过来,只复制 Hugging Face 缓存目录也不理想:缓存服务于下载复用,不是面向部署设计的自包含发布目录。
保存并在离线子进程中重载
下面使用一个很小的 T5 测试模型,先从固定提交下载,再把模型与分词器写入 offline-t5/。随后脚本启动一个全新的子进程,预先设置 HF_HUB_OFFLINE=1,并通过 local_files_only=True 只从本地目录加载,从而避免联网环境和已有缓存掩盖缺文件问题。
将代码保存为 offline_roundtrip.py 后运行。
import os
import subprocess
import sys
from pathlib import Path
MODEL_ID = "peft-internal-testing/tiny-T5ForConditionalGeneration"
REVISION = "3340286a49a0591bb4b8c2bcb57bda5ba00216be"
OUT_DIR = Path("offline-t5")
if os.environ.get("OFFLINE_CHILD") == "1":
from transformers import AutoModelForSeq2SeqLM, AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained(
OUT_DIR,
local_files_only=True,
)
model = AutoModelForSeq2SeqLM.from_pretrained(
OUT_DIR,
local_files_only=True,
)
print("offline reload ok")
print("model type:", model.config.model_type)
raise SystemExit(0)
from transformers import AutoModelForSeq2SeqLM, AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained(
MODEL_ID,
revision=REVISION,
)
model = AutoModelForSeq2SeqLM.from_pretrained(
MODEL_ID,
revision=REVISION,
)
tokenizer.save_pretrained(OUT_DIR)
model.save_pretrained(OUT_DIR)
checks = {
"config": (OUT_DIR / "config.json").exists(),
"weights": any(OUT_DIR.glob("*.safetensors"))
or any(OUT_DIR.glob("pytorch_model*.bin")),
"tokenizer": any(
(OUT_DIR / name).exists()
for name in ("tokenizer.json", "spiece.model", "vocab.json")
),
}
print("saved:", OUT_DIR, flush=True)
print("artifact check:", checks, flush=True)
child_env = os.environ.copy()
child_env["OFFLINE_CHILD"] = "1"
child_env["HF_HUB_OFFLINE"] = "1"
subprocess.run(
[sys.executable, __file__],
check=True,
env=child_env,
)预期输出(忽略首次下载进度信息):
saved: offline-t5
artifact check: {'config': True, 'weights': True, 'tokenizer': True}
offline reload ok
model type: t5这里的三项布尔检查只用于快速发现明显缺件,真正的验收信号是离线子进程能够从 offline-t5/ 完成实例化。HF_HUB_OFFLINE=1 让进程不访问 Hub,local_files_only=True 又把这两次 from_pretrained() 限定为本地文件,两层约束能更早暴露不完整交付物。
把离线验证做成发布门槛
准备部署包时,应复制整个 offline-t5/,而不是只挑出看起来重要的单个文件。然后在干净环境中安装与交付一致的 Python、Transformers、PyTorch 和 tokenizer 依赖,再执行同类离线重载测试。模型文件完整但运行库版本不兼容,同样会导致离线失败。
为了可复现,还应记录上游模型 ID、固定的 commit hash、依赖锁文件以及交付目录的校验和。save_pretrained() 解决的是“把当前对象序列化成可重载目录”,并不会替你保存完整的软件环境和来源审计信息。
处理几个容易漏掉的边界
如果原模型依赖 trust_remote_code=True,还要检查本地 config.json 中的 auto_map 以及保存目录中的自定义 Python 文件;仅有权重、配置和 tokenizer 仍可能不足。第三方代码必须先完成审查,再作为离线交付物一起验证。
量化模型、PEFT 适配器或分片超大模型也可能需要额外配置、索引文件或基座模型。遇到这些形态时不要猜文件清单,而应以“在目标依赖版本下、禁止网络访问、从交付目录完成真实重载”为最终判据。这样得到的离线包才是可交付、可验证,而不是只在开发机缓存命中时看似可用。