PEFT LoRA 微调后怎么合并权重并验证输出一致

LoRA 微调完成后，最稳妥的做法不是直接覆盖原模型目录，而是先用同一个基础模型加载 adapter，再调用 merge_and_unload() 生成独立模型，最后在完全相同的输入和解码参数下比较输出。若关闭采样后 token 序列一致、logits 只有很小的浮点误差，通常说明合并成功；如果差异明显，应优先检查基础模型、tokenizer、dtype 和量化配置。

先把合并前后的模型边界固定下来

PEFT adapter 保存的主要是增量参数，不能脱离对应的基础模型随意加载。先确认 adapter 目录中的 adapter_config.json 指向正确的基础模型，再确认 tokenizer 来自同一套词表。这里的“合并”本质上是把 LoRA 的低秩增量写回基础权重；合并之后得到的是普通 Transformers 模型，不再保留 PEFT 的切换、禁用或反合并能力。

用 merge_and_unload 合并并另存模型

下面的示例把原始 adapter 和合并结果放在不同目录。safe_merge=True 会在合并时检查潜在的 NaN；它不是效果评测，但能尽早发现坏权重。注意必须把返回值赋给 merged_model，再调用 save_pretrained。

from pathlib import Path
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

base_id = "your-org/base-model"
adapter_dir = Path("./lora-adapter")
merged_dir = Path("./merged-model")

# 基础模型与 tokenizer 必须来自同一套配置，避免输入或词表先发生变化。
tokenizer = AutoTokenizer.from_pretrained(base_id)
base_model = AutoModelForCausalLM.from_pretrained(
    base_id,
    torch_dtype=torch.float16,
    device_map="auto",
)

# 让 PEFT 把训练好的 LoRA adapter 挂到匹配的基础模型上。
peft_model = PeftModel.from_pretrained(base_model, adapter_dir)

# safe_merge 用于尽早发现潜在 NaN；返回值才是合并后的普通模型。
merged_model = peft_model.merge_and_unload(safe_merge=True)
merged_model.save_pretrained(merged_dir, safe_serialization=True)
tokenizer.save_pretrained(merged_dir)

如果使用了某些量化方式或当前 tuner 不支持合并，不能靠改目录名解决。先回到 adapter 的配置和 PEFT 版本说明；即使合并成功，量化模型也可能因为计算精度不同而无法做到逐元素相等。

让合并前后使用同一套推理条件

一致性检查最容易被“比较对象不一样”干扰。两条路径必须共享 tokenizer、原始文本、输入 token、attention_mask、最大新 token 数和解码策略。为了先排除随机性，使用贪心解码：do_sample=False、num_beams=1。不要一边使用采样，一边拿两次不同随机输出做结论。

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

prompt = "请用一句话解释 LoRA 合并的目的。"
inputs = tokenizer(prompt, return_tensors="pt").to(peft_model.device)

# 只读取生成结果，不更新权重，保证验证过程不会改变模型状态。
peft_model.eval()
merged_model.eval()
with torch.inference_mode():
    before = peft_model.generate(
        **inputs, max_new_tokens=32, do_sample=False, num_beams=1
    )
    after = merged_model.generate(
        **inputs, max_new_tokens=32, do_sample=False, num_beams=1
    )

# 先比较离散 token；相同 token 比直接比较字符串更容易定位 tokenizer 问题。
same_tokens = torch.equal(before.cpu(), after.cpu())
print({"same_tokens": same_tokens, "before": before[0].tolist(), "after": after[0].tolist()})

如果连输入 token 都不是同一组，就不要继续解释 logits。常见原因是合并目录没有保存 tokenizer、特殊 token 配置不同，或两次调用时 padding 和截断策略不一致。

比较 token 序列与 logits 差异

token 一致是最直观的发布前检查。若业务需要更细的证据，再让两条路径对同一前缀输出 logits，计算最大绝对误差。不要把一个固定阈值当成所有模型的通用标准：fp16、bf16、量化、GPU 内核和批大小都会改变误差范围。更实用的判断是先看 token 是否一致，再结合 dtype 和误差分布做灰度样本复核。

# logits_a 与 logits_b 来自同一批 input_ids 的前向结果。
logits_a = logits_a.float()
logits_b = logits_b.float()
max_abs_diff = (logits_a - logits_b).abs().max().item()
mean_abs_diff = (logits_a - logits_b).abs().mean().item()

# 误差只用于定位范围，阈值应按模型 dtype 与业务容忍度配置。
print({"max_abs_diff": max_abs_diff, "mean_abs_diff": mean_abs_diff})

排查顺序可以固定为：先重载同一个基础模型和 adapter，接着确认 tokenizer 与输入张量，再检查 safe_merge 和权重 dtype，最后才看量化实现或推理后端。若合并前输出正常、合并后全变成空答或重复文本，优先怀疑基础模型路径不匹配，而不是马上调温度。

常见问题

合并后还能切换多个 adapter 吗？

不能把合并后的普通模型当作原来的 PEFT 容器使用。需要保留多个 adapter、禁用 adapter 或反合并时，应保存未合并的 PEFT 目录，把合并模型当作单独的发布产物。

输出不完全一致是不是合并失败？

不一定。先确认两次输入 token 完全相同，并关闭采样；然后检查 dtype、量化和后端。如果 token 一致而 logits 只有小幅浮点误差，通常属于数值路径差异；如果 token 从第一处就分叉，再查模型、tokenizer 和生成配置。