PEFT 怎样只保存 adapter 权重

做 LoRA 或其他 PEFT 微调时，最容易误解的一点是：训练对象看起来仍然是一个完整的 Transformer，但真正需要分发的往往只是 adapter 增量。只要保存的是已经挂好 PEFT 层的模型对象，save_pretrained() 默认就会写出 adapter 配置和 adapter 权重，而不会把冻结的基础模型一并复制进目录。

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

这篇只讨论“保存以后目录里有什么”。示例以 LoRA 为主，不讨论把 adapter 合并进基础模型、量化转换或具体训练数据。

先把完整模型和 adapter 产物分开

一次 PEFT 训练实际上有两个层次：基础模型负责原有能力，adapter 负责这次任务学习到的增量。基础模型通常体积最大，而且同一个基础模型可以挂载多个任务 adapter；如果每次都把完整模型复制到输出目录，存储和传输都会重复。

PEFT 官方的保存语义就是围绕这个边界设计的。调用 PeftModel.save_pretrained() 时，保存的 state dict 只包含 adapter 模块参数；默认安全序列化后，常见的核心文件是 adapter_model.safetensors 和 adapter_config.json。因此，adapter 目录本身不是一个可以脱离基础模型独立推理的完整模型。

可以把目录关系理解成下面这样：

直接保存 PeftModel 的 adapter

训练完成后，直接对 PEFT 模型调用 save_pretrained() 即可。下面的代码保留了中文注释，关键点是保存 peft_model，而不是再次调用基础 Transformer 的保存方法。

from pathlib import Path

from peft import LoraConfig, get_peft_model
from transformers import AutoModelForCausalLM

base_id = "your-base-model"
output_dir = Path("artifacts/my-adapter")

# 先加载基础模型，再只在目标模块上附加 LoRA 参数。
base_model = AutoModelForCausalLM.from_pretrained(base_id)
lora_config = LoraConfig(
    r=8,
    lora_alpha=16,
    target_modules=["q_proj", "v_proj"],
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
)
peft_model = get_peft_model(base_model, lora_config)

# 保存的是 adapter 配置和增量权重，不把冻结的基础权重复制到该目录。
peft_model.save_pretrained(output_dir, safe_serialization=True)

默认情况下，目录至少应围绕两个文件组织：

• adapter_config.json：记录 PEFT 方法、目标模块和基础模型等配置。
• adapter_model.safetensors：保存 adapter 的参数；如果关闭安全序列化，文件名可能是 adapter_model.bin。

保存后的目录还可能带有 README、训练状态或模型卡文件，这些属于发布辅助信息，并不等于基础模型权重被保存进来了。

多 adapter 和 embedding 层按需收口

一个 PeftModel 可以同时挂载多个命名 adapter。此时 selected_adapters 用来限制本次保存的 adapter 名称；不传它时，默认会保存全部 adapter。不要把“当前启用的 adapter”与“目录中要保存的 adapter”混为一谈：激活状态影响推理，保存选择影响发布文件。

# 只保存名为 support 的 adapter，避免把实验中的其他 adapter 一起发布。
peft_model.save_pretrained(
    "artifacts/support-adapter",
    selected_adapters=["support"],
    safe_serialization=True,
)

# 某些任务确实训练了 embedding 层时，显式决定是否把它们一起保存。
peft_model.save_pretrained(
    "artifacts/support-with-embeddings",
    selected_adapters=["support"],
    save_embedding_layers=True,
    safe_serialization=True,
)

save_embedding_layers 默认是 "auto"。如果 adapter 的目标模块涉及常见 embedding 层，PEFT 会根据配置判断；如果团队希望发布目录的边界完全明确，可以在确认训练方案后显式传入 True 或 False。显式设置并不代表一定要保存 embedding，而是把这个取舍写进保存调用。

从目录重新挂回基础模型

adapter 目录只有增量部分，所以交付时必须同时约定基础模型的来源、版本或不可变标识。读取时先加载基础模型，再将 adapter 目录交给 PEFT；不要直接把 adapter 目录传给只认识完整 Transformer 权重的加载入口。

from peft import PeftModel
from transformers import AutoModelForCausalLM

# 基础模型必须与 adapter_config.json 记录的模型体系兼容。
base_model = AutoModelForCausalLM.from_pretrained("your-base-model")

# 从目录读取 adapter_config.json 和 adapter_model.safetensors。
model = PeftModel.from_pretrained(
    base_model,
    "artifacts/my-adapter",
    is_trainable=False,  # 发布推理时不再把 adapter 标为可训练。
)

# 需要多个 adapter 时，给每个目录分配不同名称，再按名称切换。
model.load_adapter("artifacts/support-adapter", adapter_name="support")
model.set_adapter("support")

如果你使用的是 Transformers 对 PEFT 的直接集成，也可以在挂载 adapter 的模型对象上调用相应的保存方法；关键仍是确认保存对象确实持有 adapter，且发布目录要保留可恢复所需的配置文件。

训练器和发布前的取舍

Transformers 的 Trainer 在 PEFT 场景下会识别 adapter checkpoint，通常只保存 adapter 权重与配置，因此 checkpoint 目录会比完整模型小很多。最终发布前仍要区分三种需求：

1. 继续训练：保留训练器需要的状态，并确认 checkpoint 中的 adapter 与优化器状态是否匹配。
2. 共享任务能力：保留基础模型标识、adapter_config.json 和 adapter 权重，发布最小可复用目录。
3. 交付单体模型：另行设计合并或导出流程，不要把 adapter-only 目录误称为完整模型。

最后可以用下面的速查表做保存决策：

常见追问

为什么保存目录里没有基础模型文件？

这是 PEFT 的预期行为。冻结的基础模型不属于 adapter state dict，加载 adapter 时需要再次提供兼容的基础模型。

可以只保存当前激活的 adapter 吗？

不要只根据激活状态推断保存结果。多 adapter 场景应使用 selected_adapters 明确给出要保存的名称。

adapter_model.bin 和 safetensors 怎么选？

默认的 safe_serialization=True 会生成 safetensors。除非兼容旧流程，否则优先保留默认的安全序列化格式。