1. 理解PEFT适配器与基础模型的合并需求
在使用parameter-efficient fine-tuning (peft) 技术，特别是lora（low-rank adaptation）对大型语言模型进行微调后，我们通常会得到一个轻量级的适配器模型，它只包含相对于基础模型的小部分增量权重。为了部署或分享这个微调后的模型，我们常常需要将其与原始的基础模型合并，生成一个完全独立、可直接加载和使用的完整模型，而无需再依赖原始的基础模型。
2. 常见误区与问题分析
许多用户在尝试合并PEFT适配器时，可能会遇到以下两种常见误区：
2.1 尝试使用transformers.AutoModel直接加载PEFT适配器
一种常见的错误尝试是直接使用transformers库中的AutoModel.from_pretrained()方法来加载PEFT适配器。例如：
from transformers import AutoModel
# ...
lora_adapter = AutoModel.from_pretrained("ArcturusAI/Crystalline-1.1B-v23.12-tagger")这种方法会导致OSError，错误信息通常是“does not appear to have a file named pytorch_model.bin...”。这是因为PEFT适配器（如LoRA模型）本身并不包含一个完整的模型权重文件（如pytorch_model.bin），它只存储了微调过程中修改的少量参数，这些参数需要与原始基础模型的权重结合才能构成一个完整的模型。AutoModel期望加载的是一个完整的预训练模型，而不是一个适配器。
2.2 手动合并模型权重
另一种不推荐的方法是尝试手动加载基础模型和适配器的state_dict，然后通过某种比例（例如，加权平均）来合并它们的权重。
# 错误示范：不推荐手动合并权重
from transformers import AutoModel
# ...
pretrained_model = AutoModel.from_pretrained("TinyLlama/TinyLlama-1.1B-Chat-v0.6")
# ... 假设可以加载适配器权重
# combined_weights = {}
# for key in pretrained_weights:
# combined_weights[key] = 0.8 * pretrained_weights[key] + 0.2 * lora_adapter_weights[key]
# pretrained_model.load_state_dict(combined_weights)这种方法不仅复杂，而且通常是错误的。PEFT适配器中的权重并非简单地与基础模型权重进行线性组合。peft库在底层以特定的方式管理这些增量权重，手动合并无法正确地将它们集成到基础模型中。
3. 正确的合并方法：使用peft.merge_and_unload()
peft库提供了专门的工具来处理适配器的加载和合并。其核心功能是merge_and_unload()，它能够将PEFT适配器中的增量权重正确地合并到其所基于的基础模型中，并返回一个标准的transformers模型实例。
3.1 加载PEFT适配器模型
首先，我们需要使用peft库提供的类来加载PEFT适配器。对于因果语言模型（如Llama），可以使用AutoPeftModelForCausalLM。
from peft import AutoPeftModelForCausalLM
# 假设适配器模型已下载到本地路径，或直接使用Hugging Face模型ID
# 如果模型在Hugging Face Hub上，可以直接使用 "ArcturusAI/Crystalline-1.1B-v23.12-tagger"
# 如果是本地路径，确保路径正确指向包含adapter_config.json和adapter_model.bin的目录
model_id = "./ArcturusAI/Crystalline-1.1B-v23.12-tagger" # 示例本地路径
# 或者 model_id = "ArcturusAI/Crystalline-1.1B-v23.12-tagger" # Hugging Face Hub ID
peft_model = AutoPeftModelForCausalLM.from_pretrained(model_id)
print(f"加载后的模型类型：{type(peft_model)}")执行上述代码，你将看到peft_model的类型是peft.peft_model.PeftModelForCausalLM，这表明它是一个带有PEFT适配器的模型实例。
3.2 执行合并操作
加载适配器模型后，可以直接调用merge_and_unload()方法。这个方法会将适配器中的权重应用到基础模型上，并返回一个标准的transformers模型对象。
merged_model = peft_model.merge_and_unload()
print(f"合并后的模型类型：{type(merged_model)}")输出将显示merged_model的类型变为transformers.models.llama.modeling_llama.LlamaForCausalLM（或对应基础模型的类型），这表明它现在是一个完全合并且独立的transformers模型，不再需要PEFT库来管理适配器。
4. 保存合并后的模型
合并完成后，merged_model现在是一个标准的transformers模型。你可以使用transformers库的save_pretrained()方法将其保存到本地，以便后续加载和使用。
# 定义保存路径
save_path = "ArcturusAI/Crystalline-1.1B-v23.12-tagger-fullmodel"
merged_model.save_pretrained(save_path)
print(f"合并后的模型已保存到：{save_path}")5. 处理分词器（Tokenizer）
需要注意的是，merge_and_unload()操作只处理模型权重。分词器（Tokenizer）是独立于模型权重的组件，它负责文本的预处理和后处理。因此，你仍然需要从原始的基础模型库中加载分词器，并将其与合并后的模型一起保存，以确保新模型能够正确地处理输入文本。
from transformers import AutoTokenizer
# 从原始基础模型加载分词器
tokenizer = AutoTokenizer.from_pretrained("TinyLlama/TinyLlama-1.1B-Chat-v0.6")
# 将分词器保存到与合并模型相同的路径
tokenizer.save_pretrained(save_path)
print(f"分词器已保存到：{save_path}")现在，save_path目录下将包含合并后的模型权重文件和对应的分词器文件，形成一个完整的、可独立部署的模型包。
6. 重要注意事项：PEFT版本兼容性
在实际操作中，你可能会遇到peft库版本不兼容的问题。例如，如果你的适配器模型是在较旧的peft版本下训练的，而你尝试使用较新的peft版本加载，可能会因为adapter_config.json中存在新版本不支持的字段而报错。
解决此问题的一种方法是手动编辑adapter_config.json文件，删除那些导致兼容性问题的字段。例如，如果在使用peft==0.6.2加载旧版本训练的模型时遇到问题，可能需要从adapter_config.json中移除以下键：
- loftq_config
- megatron_config
- megatron_core
在进行此类修改之前，建议先备份原始文件。这确保了即使出现问题，你也可以恢复到原始配置。
总结
通过利用peft库提供的merge_and_unload()功能，我们可以高效且正确地将PEFT LoRA适配器与基础模型合并，生成一个完全独立的预训练模型。这个过程避免了手动权重合并的复杂性和错误，并确保了模型能够以标准的transformers格式进行加载和使用。同时，不要忘记单独处理并保存分词器，并留意peft版本兼容性问题，以确保整个流程的顺利进行。
