PEFT LoRA适配器与基础模型合并实践
在使用peft (parameter-efficient fine-tuning) 技术对大型语言模型进行微调后，一个常见的需求是将训练好的lora适配器权重与原始的基础模型权重合并，从而得到一个独立的、可以直接部署的完整模型。这个过程不同于简单的模型权重叠加，需要利用peft库提供的专门功能。本教程将指导您如何正确地执行这一合并操作，并避免常见的陷阱。
理解合并的必要性与常见误区
许多开发者在尝试合并PEFT LoRA适配器时，可能会遇到以下误区：
- 直接使用 transformers.AutoModel.from_pretrained 加载适配器： PEFT适配器模型（例如LoRA）通常只包含微调过程中修改的少量参数。transformers.AutoModel.from_pretrained 期望加载一个完整的模型检查点，而不是一个仅包含适配器权重的目录。因此，直接尝试加载适配器会因找不到完整的模型权重文件（如pytorch_model.bin）而报错。
- 手动合并权重： 尝试通过手动方式（例如，将基础模型和适配器的权重按比例相加）来合并权重是不可行的。LoRA等PEFT方法并非简单地修改所有权重，而是通过注入低秩矩阵来间接调整模型行为。手动合并无法正确地将这些低秩修改整合到原始模型结构中。
正确的做法是利用peft库提供的工具，它能够理解适配器的结构并将其有效地“烘焙”到基础模型中。
使用 peft 库进行模型合并
peft 库为我们提供了 merge_and_unload() 方法，能够优雅地完成LoRA适配器与基础模型的合并。
步骤一：加载PEFT适配器模型
首先，我们需要使用peft库中的AutoPeftModelForCausalLM来加载我们的PEFT适配器。这个类会智能地识别适配器配置，并将其与底层的基础模型关联起来。
from peft import AutoPeftModelForCausalLM
import torch # 导入torch以设置设备
# 假设您的PEFT适配器模型保存在本地路径或Hugging Face模型ID
# 例如，如果适配器模型是 ArcturusAI/Crystalline-1.1B-v23.12-tagger
# 并且您希望将其与 TinyLlama/TinyLlama-1.1B-Chat-v0.6 合并
# 为了确保兼容性，建议先将Hugging Face上的适配器模型下载到本地
# 或直接使用其Hugging Face ID。这里以本地路径为例，因为它在某些peft版本兼容性问题上更灵活。
model_id = "ArcturusAI/Crystalline-1.1B-v23.12-tagger" # 替换为您的适配器路径或ID
# 如果是本地路径，确保路径是正确的
# 如果是Hugging Face ID，peft会自动下载基础模型并加载适配器
peft_model = AutoPeftModelForCausalLM.from_pretrained(
model_id,
torch_dtype=torch.bfloat16, # 根据您的模型和硬件选择合适的dtype
device_map="auto" # 自动分配设备，例如GPU
)
print(f"加载的适配器模型类型: {type(peft_model)}")说明：
- AutoPeftModelForCausalLM.from_pretrained() 会自动检测适配器配置，并从适配器配置文件中指定的base_model_name_or_path加载基础模型，然后将适配器权重加载到基础模型之上。
- torch_dtype 和 device_map 参数可以帮助您优化模型加载的性能和内存使用。
步骤二：执行合并操作
加载适配器模型后，peft_model 实际上是一个 PeftModel 类的实例，它将基础模型和适配器视为一体。现在，我们可以调用 merge_and_unload() 方法来将适配器权重合并到基础模型中。
# 执行合并操作
merged_model = peft_model.merge_and_unload()
# 合并后，模型将变回一个标准的transformers模型实例
print(f"合并后模型的类型: {type(merged_model)}")输出示例：
加载的适配器模型类型: <class 'peft.peft_model.PeftModelForCausalLM'> 合并后模型的类型: <class 'transformers.models.llama.modeling_llama.LlamaForCausalLM'>
从输出可以看出，peft_model 最初是 peft.peft_model.PeftModelForCausalLM 类型，经过 merge_and_unload() 后，merged_model 变回了基础模型对应的 transformers 类（例如 LlamaForCausalLM），这意味着适配器权重已成功并入基础模型。
步骤三：保存合并后的模型
合并后的模型现在是一个标准的transformers模型，您可以像保存任何其他transformers模型一样保存它。
# 定义保存路径
output_dir = "./ArcturusAI/Crystalline-1.1B-v23.12-tagger-fullmodel"
# 保存合并后的模型
merged_model.save_pretrained(output_dir)
print(f"合并后的模型已保存至: {output_dir}")处理分词器（Tokenizer）
需要注意的是，merge_and_unload() 操作只处理模型权重，而不涉及分词器。分词器是模型的重要组成部分，它定义了文本如何被编码和解码。为了确保新模型能够正确使用，您需要从原始的基础模型库中加载分词器，并将其保存到与合并模型相同的目录中。
from transformers import AutoTokenizer
# 从原始基础模型加载分词器
base_model_tokenizer_id = "TinyLlama/TinyLlama-1.1B-Chat-v0.6"
tokenizer = AutoTokenizer.from_pretrained(base_model_tokenizer_id)
# 将分词器保存到与合并模型相同的目录
tokenizer.save_pretrained(output_dir)
print(f"分词器已从 {base_model_tokenizer_id} 加载并保存至: {output_dir}")完成上述步骤后，output_dir 目录下将包含一个完整的、可独立加载和使用的模型（包括权重和分词器）。
注意事项与故障排除
PEFT版本兼容性
peft库的不同版本之间可能存在不兼容性，尤其是在adapter_config.json文件中新增或修改了配置项时。如果您在加载PEFT适配器时遇到错误，例如与loftq_config、megatron_config、megatron_core等相关的错误，这很可能是版本不匹配导致的。
解决方案：
升级或降级peft库： 尝试使用与训练适配器时相同的peft版本，或升级到最新版本以获取更好的兼容性。
-
手动修改 adapter_config.json： 如果您确定某些配置项在当前peft版本中不被支持或引起冲突，可以尝试手动编辑适配器目录下的 adapter_config.json 文件，删除那些导致问题的键值对。例如，如果您的peft版本不支持loftq_config，您可以将其从JSON文件中移除。
{ "peft_type": "LORA", "task_type": "CAUSAL_LM", "base_model_name_or_path": "TinyLlama/TinyLlama-1.1B-Chat-v0.6", // ... 其他配置 ... // "loftq_config": {}, // 如果导致问题，可以考虑删除 // "megatron_config": {}, // 如果导致问题，可以考虑删除 // "megatron_core": "megatron.core", // 如果导致问题，可以考虑删除 }请谨慎操作此步骤，并确保您了解删除这些配置可能带来的影响。 通常，这仅在旧版本适配器与新版本peft库不兼容时作为临时解决方案。
总结
通过遵循本教程，您可以利用peft库提供的AutoPeftModelForCausalLM和merge_and_unload()方法，轻松地将PEFT LoRA适配器与基础模型合并。记住，处理分词器是合并过程不可或缺的一部分，并且要留意peft库的版本兼容性问题。正确合并模型后，您将获得一个独立的、高性能的微调模型，可以直接用于推理或进一步部署。
