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

在大模型落地的实战中，一个常见的痛点是：明明只微调了少量参数，部署时却还得背负整个基础模型 + LoRA 插件的双重重担。启动慢、依赖多、运维复杂——这些问题让原本轻量高效的 PEFT 方法显得有些“名不副实”。

而真正的生产级解决方案，应该是把训练成果固化下来：将 LoRA 的增量更新永久融合进原始模型，生成一个独立、自包含、开箱即用的新模型。这不仅是工程上的简化，更是从实验走向服务的关键一步。

LLaMA-Factory 提供了一条极为简洁的路径来实现这一目标——通过一条 export 命令和一个 YAML 配置文件，就能完成跨架构、跨模态、安全可靠的 LoRA 合并。本文将带你深入这个过程的每一个细节，避开常见陷阱，并分享一些提升效率的实用技巧。

---

核心命令：一键导出合并模型

整个流程的核心就是这条命令：

llamafactory-cli export examples/merge_lora/qwen2_5vl_lora_sft.yaml

别小看这一行，它背后完成了一系列精密操作：

1. 加载原始浮点精度的基础模型（如 Qwen2.5-VL-7B-Instruct）
2. 读取指定路径下的 LoRA 权重（adapter_model.bin）及其配置
3. 将低秩矩阵 $ \Delta W = A \cdot B $ 按照预设规则叠加到对应层的原始权重 $ W $ 上，得到 $ W’ = W + \Delta W $
4. 卸载所有 LoRA 相关结构，恢复为标准 Transformer 架构
5. 分片保存为完整的模型包，包含 tokenizer、generation config、对话模板等全套组件

这套机制支持包括 Qwen、LLaMA、ChatGLM、Baichuan、Phi、Mistral 在内的上百种主流架构，甚至涵盖多模态模型如 Qwen-VL 和 LLaVA。你只需要换一下配置文件里的路径和模板名称，其余工作全部自动化处理。

---

配置详解：YAML 文件怎么写？

下面是一个典型的合并配置示例：

### 注意：合并 LoRA 时禁止使用量化模型或设置 quantization_bit！

### 模型配置
model_name_or_path: Qwen/Qwen2.5-VL-7B-Instruct
adapter_name_or_path: saves/qwen2_5vl-7b/lora/sft
template: qwen2_vl
trust_remote_code: true

### 导出配置
export_dir: output/qwen2_5vl_lora_sft
export_size: 5
export_device: cpu
export_legacy_format: false

我们来逐个拆解这些参数的实际意义与选择逻辑。

model 模块关键参数

参数	说明
model_name_or_path	必须指向未量化的原始模型。可以是 Hugging Face Hub 的 ID，也可以是本地路径。重点强调：不能是 GPTQ/AWQ/INT4 等任何量化版本。这类模型的权重已经被近似压缩，无法与 LoRA 的增量矩阵精确相加，强行合并会导致输出混乱甚至崩溃。
adapter_name_or_path	LoRA 训练完成后保存的目录，必须包含 adapter_model.bin 和 adapter_config.json。建议使用绝对路径或相对于项目根目录的相对路径，避免加载失败。
template	对话模板名称，直接影响 prompt 的拼接方式。例如 Qwen 多模态模型需用 qwen2_vl，LLaMA 系列常用 llama3 或 alpaca。一旦设错，模型可能无法识别 system/user/assistant 角色标记，导致交互异常。
trust_remote_code	对于 Qwen、ChatGLM 这类非标准架构模型，必须设为 true，否则会因找不到自定义模型类或 tokenizer 而报错。

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

export 模块控制输出行为

参数	说明
export_dir	输出目录，最终生成的模型将完整存放于此。该目录可直接用于 from_pretrained()、Ollama 部署或上传至 Hugging Face Hub。
export_size	控制分片数量。设为 5 表示最多生成 5 个权重文件（如 pytorch_model-00001-of-00005.safetensors），适用于 7B~13B 模型，避免单文件过大影响加载性能。对于更大模型可适当增加。
export_device	推荐根据硬件条件灵活选择： • 显存充足 → auto（利用 GPU 加速，速度快） • 显存紧张或无 GPU → cpu（稳定但较慢） 注意：即使选 cpu，PyTorch 仍会使用 CUDA 进行数据搬运，因此基本 CUDA 环境仍是必需的。
export_legacy_format	强烈建议保持 false，使用 safetensors 格式。相比传统的 .bin 文件，它具备内存映射优势且能防止恶意代码注入，已被 vLLM、TGI 等现代推理引擎广泛支持。

---

合并流程发生了什么？

当你执行 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 资源。以下是推荐策略：

场景	推荐设置
单卡 24GB+（如 3090/4090）	export_device: auto
显存 < 16GB 或无 GPU	export_device: cpu
多卡服务器	export_device: auto，框架自动调度

💡 小提示：即使使用 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 合并看似只是一个工程步骤，实则是连接“研究”与“生产”的桥梁。它的价值不仅在于简化部署，更在于实现了模型资产的标准化封装。

关键点	实践建议
核心价值	固化微调成果，便于共享、部署、版本管理
最大风险	使用量化模型合并 → 输出失真
推荐配置	export_device: auto, export_legacy_format: false, export_size: 5
适用范围	支持 100+ 主流架构，含多模态
最终产物	完整、可移植、无需依赖 PEFT 的标准模型

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