LLaMA-Factory 合并 LoRA 适配器完整指南

🛑 血泪教训提醒：曾有团队误将训练时使用的 quantization_bit: 4 配置带入合并阶段，结果模型输出完全失真。务必确保合并配置中不出现任何量化相关字段。

export 模块控制输出行为

合并流程发生了什么？

当你执行 export 命令后，系统实际上经历了以下几个阶段：

1. 环境初始化与设备探测

[INFO] Setting ds_accelerator to cuda (auto detect) INFO Automatically detected platform cuda. 

框架自动识别当前可用硬件平台（CUDA/ROCm/MPS），并设置相应的加速后端。这是保证后续操作高效运行的前提。

2. 加载基础模型与 Tokenizer

[INFO] loading file vocab.json [INFO] loading file tokenizer.json [INFO] Instantiating Qwen2_5_VLForConditionalGeneration model under default dtype torch.bfloat16. 

这一阶段会加载：
- tokenizer 及其配置
- 图像预处理器（针对多模态模型）
- generation config（解码参数）
- 模型结构本身，保持原始精度类型（如 bfloat16）

特别要注意的是，模型不会被移动到 GPU，除非你明确指定了 export_device: auto。对于 CPU 合并场景，整个过程都在内存中进行。

3. LoRA 融合与卸载

[INFO] Merged 1 adapter(s). [INFO] Loaded adapter(s): saves/qwen2_5vl-7b/lora/sft 

核心动作在这里发生：
- 解析 adapter_config.json 获取 rank、alpha、target_modules 等信息
- 调用 PEFT 的 model.merge_and_unload() 方法
- 遍历所有带有 LoRA 的模块，执行 $ W' = W + \Delta W $
- 删除 LoRA 层中的旁路结构（A/B 矩阵），恢复为普通线性层

完成后，模型已不再是'带插件'的状态，而是真正意义上的'新模型'。

4. 模型保存与分片输出

[INFO] The model is bigger than the maximum size per checkpoint (5GB) and is going to be split in 4 checkpoint shards. 

最后一步是持久化存储：
- 按照 export_size 进行分片
- 写入以下必要文件：
- config.json
- generation_config.json
- tokenizer_config.json
- special_tokens_map.json
- preprocessor_config.json（多模态专用）
- chat_template.jinja
- model.safetensors.index.json（分片索引）

✅ 最终产物可以直接用于：
- Transformers 加载推理
- Ollama 构建镜像
- Hugging Face Hub 发布

常见问题与避坑指南

❗ 错误一：用了量化模型做合并

这是最普遍也最致命的问题。量化模型（如 -GPTQ、-AWQ、bitsandbytes 加载）本质上是对权重做了有损压缩。当你试图把 LoRA 的增量加回去时，数学上已经不再成立。

正确做法：始终使用原始 FP16/BF16 模型进行合并。如果你只有量化版，先用 transformers 正常加载原版模型再合并。

❗ 错误二：adapter 路径无效或损坏

确保你的 LoRA 目录下至少包含：

saves/qwen2_5vl-7b/lora/sft/
├── adapter_config.json
├── adapter_model.bin
└── README.md # 可选 

可以用这段代码快速验证：

from peft import PeftModel
model = PeftModel.from_pretrained(base_model, "saves/qwen2_5vl-7b/lora/sft")
print(model.active_adapters()) # 应输出 ['default'] 

如果报错找不到模块或键缺失，说明适配器不完整。

❗ 错误三：忽略多模态组件

对于 Qwen-VL、LLaVA 这类模型，很多人只关注文本部分，却忘了图像输入依赖 image_processor 和 preprocessor_config.json。LLaMA-Factory 默认会自动复制这些文件，但如果你手动处理合并流程，请务必保留它们，否则图片无法解析。

❗ 错误四：export_device 设置不当

虽然 cpu 最安全，但在高性能机器上浪费了 GPU 资源。以下是推荐策略：

💡 小提示：即使使用 CPU 合并，也建议保留 CUDA 环境，因为某些 tensor 操作仍会借助 GPU 缓冲传输数据。

合并后的模型如何使用？

成功合并后，你就拥有了一个标准的 Hugging Face 模型包，使用方式完全透明。

方式一：Transformers 原生加载

from transformers import AutoModelForCausalLM, AutoTokenizer
model = AutoModelForCausalLM.from_pretrained("output/qwen2_5vl_lora_sft")
tokenizer = AutoTokenizer.from_pretrained("output/qwen2_5vl_lora_sft")
inputs = tokenizer("你好，请介绍一下你自己。", return_tensors="pt").to("cuda")
outputs = model.generate(**inputs, max_new_tokens=100)
print(tokenizer.decode(outputs[0], skip_special_tokens=True)) 

无需任何额外依赖，也不需要 peft 库。

方式二：Ollama 快速部署

LLaMA-Factory 自动生成 Modelfile，可直接构建镜像：

cd output/qwen2_5vl_lora_sft
ollama create my-qwen-lora -f Modelfile
ollama run my-qwen-lora 

Modelfile 示例内容：

FROM ./pytorch_model-00001-of-00005.safetensors
PARAMETER temperature 0.1
PARAMETER top_p 0.001
TEMPLATE """{{ if .System }}<|im_start|>system {{ .System }}<|im_end|> {{ end }}<|im_start|>user {{ .Prompt }}<|im_end|> <|im_start|>assistant {{ .Response }}""" 

从此可以通过 API 或 Web UI 直接调用。

方式三：发布到 Hugging Face Hub

huggingface-cli login
git lfs install
git clone https://huggingface.co/spaces/yourname/qwen2_5vl_finetuned
cp -r output/qwen2_5vl_lora_sft/* yourname-qwen2_5vl_finetuned/
cd yourname-qwen2_5vl_finetuned && git add . && git commit -m "upload merged model"
git push 

别人就可以直接 from_pretrained("yourname/qwen2_5vl_finetuned") 使用你的定制模型。

高阶技巧与最佳实践

✅ 技巧一：低显存机器也能合并

若你在 16GB 以下显存的设备上操作，强烈建议：

export_device: cpu 

虽然耗时会长一些（7B 模型约 5~10 分钟），但稳定性极高。我曾在一台老旧的 T4 服务器上成功合并 13B 模型，全程零错误。

✅ 技巧二：批量合并多个任务的 LoRA

假设你训练了 SFT、DPO、RLHF 多个版本的适配器，可以用脚本自动化合并：

for task in sft dpo rl; do sed "s|lora/sft|lora/$task|" examples/merge_lora/template.yaml > temp.yaml llamafactory-cli export temp.yaml done 

配合 CI/CD 流程，实现'训练完自动打包'，极大提升迭代效率。

✅ 技巧三：校验合并前后的一致性

为了确保合并没有引入偏差，建议随机抽取几个测试样本，对比两种模式的输出：

# 合并前（基础模型 + LoRA）
model_with_lora = PeftModel.from_pretrained(base, "lora/sft")
input_ids = tokenizer("请写一首关于春天的诗", return_tensors="pt").input_ids.to("cuda")
with torch.no_grad():
    logits_before = model_with_lora(input_ids).logits
# 合并后（独立模型）
merged_model = AutoModelForCausalLM.from_pretrained("merged_model")
with torch.no_grad():
    logits_after = merged_model(input_ids).logits
# 比较输出差异
assert torch.allclose(logits_before, logits_after, atol=1e-4), "合并前后 logits 差异过大！" 

数值误差应控制在 1e-4 以内，否则说明合并过程存在问题。

总结与思考

LoRA 合并看似只是一个工程步骤，实则是连接'研究'与'生产'的桥梁。它的价值不仅在于简化部署，更在于实现了模型资产的标准化封装。

LLaMA-Factory 凭借统一接口和强大生态，真正做到了'一次训练，随处部署'。掌握这项技能，意味着你能更快地将实验想法转化为实际服务能力。在今天这个节奏越来越快的 AI 时代，这种能力尤为珍贵。