介绍如何使用 LLaMA-Factory 将微调后的 LoRA 适配器合并到基础模型中，生成独立可部署模型。核心命令为 llamafactory-cli export，配合 YAML 配置文件完成权重融合。文章详细解析了配置参数、合并流程及常见问题。同时提供了 Transformers、Ollama 及 Hugging Face Hub 三种使用方式，并给出低显存优化、批量合并及一致性校验等最佳实践。
在大模型落地的实战中，一个常见的痛点是：明明只微调了少量参数，部署时却还得背负整个基础模型 + LoRA 插件的双重重担。启动慢、依赖多、运维复杂——这些问题让原本轻量高效的 PEFT 方法显得有些'名不副实'。
而真正的生产级解决方案，应该是把训练成果固化下来：将 LoRA 的增量更新永久融合进原始模型，生成一个独立、自包含、开箱即用的新模型。这不仅是工程上的简化，更是从实验走向服务的关键一步。
LLaMA-Factory 提供了一条极为简洁的路径来实现这一目标——通过一条 export 命令和一个 YAML 配置文件，就能完成跨架构、跨模态、安全可靠的 LoRA 合并。本文将带你深入这个过程的每一个细节，避开常见陷阱，并分享一些提升效率的实用技巧。
整个流程的核心就是这条命令：
llamafactory-cli export examples/merge_lora/qwen2_5vl_lora_sft.yaml
别小看这一行，它背后完成了一系列精密操作：
adapter_model.bin）及其配置这套机制支持包括 Qwen、LLaMA、ChatGLM、Baichuan、Phi、Mistral 在内的上百种主流架构，甚至涵盖多模态模型如 Qwen-VL 和 LLaVA。你只需要换一下配置文件里的路径和模板名称，其余工作全部自动化处理。
下面是一个典型的合并配置示例：
### 注意：合并 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_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_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 命令后，系统实际上经历了以下几个阶段：
[INFO] Setting ds_accelerator to cuda (auto detect) INFO Automatically detected platform cuda.
框架自动识别当前可用硬件平台（CUDA/ROCm/MPS），并设置相应的加速后端。这是保证后续操作高效运行的前提。
[INFO] loading file vocab.json [INFO] loading file tokenizer.json [INFO] Instantiating Qwen2_5_VLForConditionalGeneration model under default dtype torch.bfloat16.
这一阶段会加载：
特别要注意的是，模型不会被移动到 GPU，除非你明确指定了 export_device: auto。对于 CPU 合并场景，整个过程都在内存中进行。
[INFO] Merged 1 adapter(s). [INFO] Loaded adapter(s): saves/qwen2_5vl-7b/lora/sft
核心动作在这里发生：
adapter_config.json 获取 rank、alpha、target_modules 等信息model.merge_and_unload() 方法完成后，模型已不再是'带插件'的状态，而是真正意义上的'新模型'。
[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.jsongeneration_config.jsontokenizer_config.jsonspecial_tokens_map.jsonpreprocessor_config.json（多模态专用）chat_template.jinjamodel.safetensors.index.json（分片索引）✅ 最终产物可以直接用于：
这是最普遍也最致命的问题。量化模型（如 -GPTQ、-AWQ、bitsandbytes 加载）本质上是对权重做了有损压缩。当你试图把 LoRA 的增量加回去时，数学上已经不再成立。
正确做法：始终使用原始 FP16/BF16 模型进行合并。如果你只有量化版，先用 transformers 正常加载原版模型再合并。
确保你的 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 默认会自动复制这些文件，但如果你手动处理合并流程，请务必保留它们，否则图片无法解析。
虽然 cpu 最安全，但在高性能机器上浪费了 GPU 资源。以下是推荐策略：
| 场景 | 推荐设置 |
|---|---|
| 单卡 24GB+（如 3090/4090） | export_device: auto |
| 显存 < 16GB 或无 GPU | export_device: cpu |
| 多卡服务器 | export_device: auto，框架自动调度 |
💡 小提示：即使使用 CPU 合并，也建议保留 CUDA 环境，因为某些 tensor 操作仍会借助 GPU 缓冲传输数据。
成功合并后，你就拥有了一个标准的 Hugging Face 模型包，使用方式完全透明。
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 库。
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 直接调用。
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 模型，全程零错误。
假设你训练了 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 时代，这种能力尤为珍贵。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online