大模型原理与训练 / 系统课时

保存并离线重载模型

保存并离线重载模型

模型在联网机器上能运行,不代表复制几份权重后就能离线交付。一个可重复使用的本地包至少要让模型配置、权重和分词器彼此匹配,并在禁止访问 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 后运行。

python
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,
)

预期输出(忽略首次下载进度信息):

text
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 适配器或分片超大模型也可能需要额外配置、索引文件或基座模型。遇到这些形态时不要猜文件清单,而应以“在目标依赖版本下、禁止网络访问、从交付目录完成真实重载”为最终判据。这样得到的离线包才是可交付、可验证,而不是只在开发机缓存命中时看似可用。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

保存并离线重载模型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通