PEFT适配器检查点为什么不包含完整基础模型

训练完 LoRA 或其他 PEFT 适配器，打开检查点目录却只看到 adapter_model.safetensors 和 adapter_config.json，这通常不是保存失败。PEFT 的目标就是只保存可训练的适配器参数，把体积较大的冻结基础模型留在外部；恢复时再把两者装配起来。

官方地址：https://huggingface.co/docs/peft/main/developer_guides/checkpoint

检查点不包含完整基础模型，是 PEFT 的参数高效设计。只要适配器配置仍能指向匹配的基础模型，就可以恢复推理或继续训练；只有需要独立部署时，才考虑额外保存或合并完整模型。

先看目录：缺少基础模型不等于保存失败

这次问题往往出现在两个时刻：训练任务结束后检查输出目录，或者把检查点上传到模型仓库后发现文件明显比基础模型小。先不要把“文件少”当成损坏证据，我们要先按职责拆开目录。

官方 checkpoint 文档明确说明，save_pretrained() 保存的是适配器文件与配置，state_dict 只包含适配器模块参数。也就是说，保存动作本身没有把基础模型“删掉”，而是没有重复拷贝它。

故障根因：训练更新范围和保存范围是同一件事

PEFT 训练时，基础模型大部分参数被冻结，优化器真正更新的是 LoRA 矩阵、Prefix 等适配器参数。为了让检查点足够小、便于在多个基础模型副本之间复用，保存器默认沿用这个边界：把会变化的部分保存下来，把不会变化的部分留给加载方提供。

因此需要区分三个容易混淆的对象：

• 训练检查点：用于保存适配器进度，通常还会由 Trainer 维护训练状态，以便从某个 checkpoint 继续训练。
• 适配器发布包：权重加配置，适合在已知基础模型的前提下共享、切换和挂载。
• 独立部署模型：不希望部署环境再寻找基础模型时，才需要把基础模型一起交付，或将适配器合并进基础权重后另存。

换句话说，检查点小并不代表训练结果丢失；它代表结果被表达成“基础模型 + 增量适配器”的组合。

恢复检查点：先加载基础模型，再挂载适配器

恢复的关键顺序是先根据配置加载与训练时一致的基础模型，再将适配器目录交给 PEFT。下面的示例只展示恢复关系，模型名称应替换成训练时实际使用的值。

from transformers import AutoModelForCausalLM
from peft import PeftConfig, PeftModel

adapter_dir = "./my-adapter"

# 先读取适配器配置，取得训练时绑定的基础模型标识。
peft_config = PeftConfig.from_pretrained(adapter_dir)

# 基础模型必须与训练时的架构、词表和关键配置保持匹配。
base_model = AutoModelForCausalLM.from_pretrained(
    peft_config.base_model_name_or_path
)

# 将适配器参数挂到基础模型上，得到可用于推理或继续训练的组合模型。
model = PeftModel.from_pretrained(base_model, adapter_dir)
model.eval()  # 推理场景关闭训练态行为

如果配置里的基础模型标识不可访问、被移动，或本地使用了不同修订版本，加载失败并不说明适配器文件损坏，而是组合中的另一半没有按原约束准备好。生产环境应记录基础模型的仓库、修订版本、分词器和 PEFT 配置。

继续训练还是独立部署：按结果选择保存策略

确定“为什么没有基础模型”之后，下一步是根据交付目标做选择，而不是盲目把大文件复制进每个检查点。

继续训练

保留适配器检查点和训练状态，使用同一基础模型恢复。这样能继续沿用轻量检查点的优势；如果换了基础模型、词表或关键架构配置，原适配器不一定仍然适用。

保留可切换适配器

把基础模型作为共享依赖，把多个适配器放在不同目录。推理服务可以按任务加载或切换适配器，适合一个基础模型对应多个领域能力的场景。发布清单中至少要同时写明基础模型标识、适配器版本和兼容的 PEFT/Transformers 范围。

导出独立模型

当部署侧不想再管理适配器依赖，可以使用适配器模型提供的合并能力，将增量权重写入基础模型后保存新的模型目录。合并前先保留原始适配器包；合并后的目录适合直接交付，但会失去轻量切换和单独更新适配器的便利。

# 仅在确认目标是独立部署时才执行合并导出。
merged_model = model.merge_and_unload()

# 保存合并后的完整模型；分词器仍要与模型一起交付。
merged_model.save_pretrained("./merged-model", safe_serialization=True)

复查清单：把“文件缺失”改成“依赖完整”

1. 确认目录中有适配器权重和配置，而不是只检查是否存在基础模型大文件。
2. 从 adapter_config.json 记录基础模型标识、PEFT 类型和目标模块。
3. 用与训练时一致的基础模型和分词器加载，再恢复适配器。
4. 继续训练保留适配器检查点；独立部署再考虑合并或额外交付基础模型。
5. 在模型仓库说明组合关系，避免接收方把适配器目录误当成完整模型直接加载。

最后可以把这个问题记成一句话：PEFT 保存的是“变化量”，不是“完整世界”。只要基础模型和适配器的契约没有断，检查点体积小反而说明参数高效微调正在按设计工作。

相关问题

为什么 adapter_config.json 很重要？

它记录了适配器类型以及加载所需的关键配置，通常还会提供基础模型标识。没有配置时，加载方可能无法自动判断如何把权重注入正确的模块。

可以只把 adapter_model.safetensors 发给别人吗？

不建议。权重文件需要与配置和匹配的基础模型一起解释；至少应同时交付配置，并明确基础模型来源和版本。

合并后还能像原来一样切换多个适配器吗？

合并后的目录更接近独立完整模型，通常不再保留原来的适配器切换边界。需要灵活切换时，应保留未合并的适配器包。