引言：PEFT LoRA适配器与基础模型合并的必要性
在使用参数高效微调（peft）技术，特别是lora（low-rank adaptation）对大型语言模型进行微调后，我们通常会得到一个轻量级的适配器模型。这个适配器模型只包含微调过程中修改的少量权重，它需要与原始的基础模型结合才能进行推理。在部署或分享模型时，将适配器与基础模型合并成一个完整的、独立的模型是一个常见的需求，这样可以简化模型的加载和使用，无需同时管理两个模型组件。
然而，许多初学者在尝试合并时可能会遇到困难，例如尝试直接使用transformers库的AutoModel.from_pretrained加载PEFT适配器，或者尝试手动对模型权重进行加权平均。这些方法通常会导致错误，因为PEFT适配器有其特定的结构和加载机制。
错误的合并尝试及原因分析
一个常见的错误尝试是使用transformers.AutoModel.from_pretrained来加载PEFT适配器，并试图通过手动加权的方式合并权重，如下所示：
from transformers import AutoModel
# 错误示范：尝试直接加载PEFT适配器
# pretrained_model = AutoModel.from_pretrained("TinyLlama/TinyLlama-1.1B-Chat-v0.6")
# lora_adapter = AutoModel.from_pretrained("ArcturusAI/Crystalline-1.1B-v23.12-tagger") # 此处会报错
# ... 后续的权重合并逻辑也是不正确的 ...当执行 lora_adapter = AutoModel.from_pretrained("ArcturusAI/Crystalline-1.1B-v23.12-tagger") 时，通常会遇到 OSError，提示模型路径下缺少 pytorch_model.bin、tf_model.h5 等标准模型权重文件。这是因为PEFT适配器通常只包含适配器层的权重，而非完整的模型权重文件，transformers.AutoModel无法识别这种格式。此外，PEFT模型的工作原理并非简单地将基础模型和适配器模型的权重进行加权平均，而是通过将适配器层注入到基础模型的特定层中来修改其行为。因此，手动合并权重的方法在逻辑上也是不正确的。
正确的合并策略：使用PEFT库的merge_and_unload方法
PEFT库本身提供了将适配器与基础模型合并的官方且高效的方法：merge_and_unload()。这个方法能够正确地将适配器权重融合到基础模型的对应层中，并返回一个标准的transformers模型实例。
1. 加载PEFT适配器模型
首先，我们需要使用peft库中专门用于加载PEFT模型的类，例如AutoPeftModelForCausalLM，来加载已训练的PEFT适配器。这个类会自动识别并加载PEFT适配器以及其关联的基础模型配置。
from peft import AutoPeftModelForCausalLM
import torch
# 定义PEFT适配器模型的本地路径或Hugging Face模型ID
# 假设您已将适配器模型下载到本地，或者可以直接从Hugging Face Hub加载
model_id = "./ArcturusAI/Crystalline-1.1B-v23.12-tagger" # 示例路径
# 加载PEFT适配器模型
# 注意：这里会同时加载基础模型和适配器权重
peft_model = AutoPeftModelForCausalLM.from_pretrained(
model_id,
torch_dtype=torch.bfloat16 # 根据您的硬件和模型大小选择合适的dtype
)
print(f"加载后的模型类型: {type(peft_model)}")
# 预期输出: 2. 执行模型合并
加载完成后，peft_model是一个PeftModelForCausalLM实例。通过调用其merge_and_unload()方法，PEFT库会自动将适配器权重合并到基础模型中，并返回一个标准的transformers模型实例。
# 执行合并操作
merged_model = peft_model.merge_and_unload()
print(f"合并后的模型类型: {type(merged_model)}")
# 预期输出: (或对应基础模型的类型) 此时，merged_model已经是一个包含所有必要权重的完整模型，可以像任何其他transformers模型一样进行使用和保存。
3. 保存合并后的模型
合并后的模型可以直接使用transformers库的save_pretrained方法保存到本地，以便后续加载和部署。
# 定义保存路径
save_directory = "./ArcturusAI/Crystalline-1.1B-v23.12-tagger-fullmodel"
# 保存合并后的模型
merged_model.save_pretrained(save_directory)
print(f"合并后的模型已保存至: {save_directory}")处理分词器（Tokenizer）
需要注意的是，merge_and_unload()方法只处理模型的权重，而不会处理分词器。分词器（Tokenizer）是独立于模型权重的组件，它负责将文本转换为模型可以理解的数字序列。因此，您需要单独加载基础模型的分词器，并将其保存到与合并模型相同的目录中，以确保模型的完整性。
from transformers import AutoTokenizer
# 加载基础模型的分词器
base_model_name = "TinyLlama/TinyLlama-1.1B-Chat-v0.6"
tokenizer = AutoTokenizer.from_pretrained(base_model_name)
# 将分词器保存到与合并模型相同的目录
tokenizer.save_pretrained(save_directory)
print(f"分词器已保存至: {save_directory}")完成上述步骤后，./ArcturusAI/Crystalline-1.1B-v23.12-tagger-fullmodel 目录下将包含一个完整的、可直接加载和使用的模型（包括权重和分词器）。
注意事项：PEFT版本兼容性
在处理PEFT模型时，可能会遇到不同版本peft库训练的模型之间兼容性问题。例如，较新版本的peft可能在adapter_config.json文件中引入了新的配置键（如loftq_config, megatron_config, megatron_core），而旧版本的peft在加载时可能无法识别这些键，导致加载失败。
如果遇到此类问题，一种解决方案是手动编辑adapter_config.json文件，移除那些不兼容的配置键。这通常在您尝试使用一个较旧的peft版本加载由较新版本训练的适配器时发生。
示例（假设您已将模型下载到本地并需要修改）：
- 下载模型： 确保PEFT适配器模型已下载到本地路径。
- 定位 adapter_config.json： 在模型路径下找到 adapter_config.json 文件。
- 编辑文件： 使用文本编辑器打开 adapter_config.json。
- 移除不兼容的键： 查找并删除如 "loftq_config": null、"megatron_config": {}、"megatron_core": {} 等键值对。
- 保存文件： 保存修改后的 adapter_config.json。
重要提示： 这种手动修改配置文件的做法应作为临时解决方案，并仅在您明确知道哪些键是问题根源时才使用。最佳实践是尽量保持peft库版本的一致性，或者在训练时就考虑到部署环境的peft版本。
总结
将PEFT LoRA适配器与基础模型合并是一个相对直接的过程，关键在于使用peft库提供的正确工具。通过AutoPeftModelForCausalLM加载适配器，然后调用merge_and_unload()方法，即可高效地完成模型合并。同时，不要忘记单独处理分词器，并将其与合并后的模型一同保存，以确保模型部署的完整性和便捷性。在处理不同版本peft训练的模型时，注意潜在的兼容性问题，并采取适当的措施进行解决。
