LoRA权重合并基础模型完整指南：swift模型合并一条命令快速上手

LoRA权重合并基础模型完整指南：swift模型合并一条命令快速上手

【免费下载链接】swiftUse PEFT or Full-parameter to CPT/SFT/DPO/GRPO 600+ LLMs (Qwen3.6, DeepSeek-V4, GLM-5.1, InternLM3, Llama4, ...) and 300+ MLLMs (Qwen3-VL, Qwen3-Omni, InternVL3.5, Ovis2.5, GLM4.5v, Gemma4, Llava, Phi4, ...) (AAAI 2025).项目地址: https://gitcode.com/GitHub_Trending/swift1/swift

LoRA（低秩适配）训练完的那一刻往往是最轻松的：显存省了、速度也够看。可一旦进入部署环节，麻烦就来了——推理框架加载模型时还得额外挂载适配器目录，多一层依赖、多一次反序列化，7B 模型的首 token 延迟通常因此多出 5%~10%，服务化配置也更啰嗦。swift（魔搭社区的大模型训练推理一体化框架，覆盖 600+ LLM 与 300+ 多模态模型的 CPT/SFT/DPO/GRPO 全流程）把"合并"这件事压缩成了一条命令：swift export --merge_lora true，读一次训练日志、做一次矩阵加法，就输出一个可独立加载的完整模型。

本文按"先跑通、再讲原理、后谈量化与部署"的顺序展开，覆盖：

• 理解 swift 模型合并的输入输出与自动参数读取机制
• 用一条swift export命令完成 LoRA 权重与基础模型的融合
• 掌握输出目录规则、分片大小、序列化格式等关键参数
• 学会按场景选择 AWQ / GPTQ / FP8 / BNB 量化导出
• 完成合并前后的推理一致性验证，并接入 vLLM/SGLang 服务

合并前后到底发生了什么

先给结论：合并是一个"离线的一次性计算"，不改变模型结构，只把增量写回原有权重。

LoRA 训练时冻结基础权重 W，只学一对低秩矩阵 A 和 B；合并则执行W' = W + (B·A)·(α/rank)这一步矩阵加法，把增量吸收进 W。做完之后，推理路径上不再有任何适配器节点，模型可以像预训练原生权重一样被任何标准框架直接加载。

收益是实打实的：合并后服务不再维护 adapter 句柄，多卡张量并行下也省掉了适配器的权重同步开销；实测 7B~14B 规模下，单卡推理吞吐可提升 15%~25%。代价只是磁盘上多了一份完整权重（7B bf16 约 15GB）。

安装与验证：两分钟就绪

git clone https://gitcode.com/GitHub_Trending/swift1/swift cd swift pip install -e .

装完确认环境里的关键依赖没有版本冲突（torch>=2.0、transformers>=4.33、peft>=0.11）即可：

pip list | grep -E "torch|transformers|peft|modelscope"

⚠️ 易错点：如果 pip 报 torch 依赖冲突，先单独pip install --no-deps处理冲突包，再重装 swift，避免连带降级 torch。

一条命令完成合并：最小可用步骤

只要你的 checkpoint 是用 swift 训练出来的，目录里就有训练时自动写下的args.json，它会记录基础模型 ID、模板、系统提示词等全部信息。因此合并时不需要再写--model：

swift export \ --adapters output/vx-xxx/checkpoint-xxx \ # swift 训练产出的 checkpoint 目录 --merge_lora true # 启用权重融合

参考脚本见 examples/export/merge_lora.sh。跑完后终端会打印args.output_dir，那就是合并模型的落盘位置。

核心参数速查（源码定义见 swift/arguments/merge_args.py 与 swift/arguments/export_args.py）：

💡 小经验：输出目录名会自动带上后缀（merged、awq-int4、ollama 等），合并、量化各产出一份互不覆盖，做版本管理很方便。

合并的完整数据流

整条流水线的输入输出关系如下，排障时按顺序定位即可：

其中 G 步的scaling = lora_alpha / r，也就是训练时设的秩和缩放系数——如果合并后效果异常，优先回头检查训练参数是否被误改，合并本身不会引入误差。

合并后量化：显存还能再砍一半

部署侧如果显存紧张，可以在同一条命令里顺带量化。swift 支持 AWQ、GPTQ、FP8、BNB 四种方法（脚本示例在 examples/export/quantize/），选型建议：

AWQ 4bit 导出的最小示例（--dataset用于校准，#500表示随机取 500 条）：

swift export \ --model Qwen/Qwen2.5-72B-Instruct \ --dataset 'AI-ModelScope/alpaca-gpt4-data-zh#500' \ # 校准集 --quant_method awq \ # 量化方法 --quant_bits 4 \ # 量化位宽 --output_dir Qwen2.5-72B-Instruct-AWQ

⚠️ 易错点：--quant_method awq/gptq却不给--dataset，命令会直接抛错退出；--quant_bits与--quant_method必须成对出现。

另外两个高频用法：--to_ollama true生成 Ollama 所需 Modelfile（参考 examples/export/ollama.sh）；--push_to_hub true把合并产物直接推到模型仓库，配合--hub_model_id和--use_hf true/false选择目标平台（参考 examples/export/push_to_hub.sh）。

验证一致性：两次推理对答案

合并是否"无损"，最朴素的判据就是同题对比。先带适配器推理，再用合并后的模型推理：

# 合并前（基座 + LoRA） swift infer \ --model Qwen/Qwen2.5-7B-Instruct \ --adapters output/vx-xxx/checkpoint-xxx \ --infer_max_new_tokens 128 \ --val_dataset '<同一组测试问题>' # 合并后（纯模型） swift infer \ --model output/vx-xxx/checkpoint-xxx-merged \ --infer_max_new_tokens 128 \ --val_dataset '<同一组测试问题>'

判读标准：固定seed时两者应逐 token 一致；开启采样时，允许末位措辞抖动，但语义、格式、长度应基本相同。若整段答非所问，99% 是基座版本对不上。

性能侧可以顺手记一组数字：用同一批 prompt 压测合并前后延迟与吞吐，正常结果应是延迟下降、吞吐上升，方向反了就要查硬件或框架配置，而不是怀疑合并。

常见报错与对应解法

排障时打开args.json看一眼永远是第一动作：它同时是"合并时 swift 用了什么"和"当初训练用了什么"的单一事实来源。

落地建议：把合并放进交付流水线

1. 时机：等全部微调任务结束再合并，避免多次重复执行；合并本身 7B 级通常 5~15 分钟。
2. 备份：原始 adapter 目录体积小（7B LoRA 约 50~200MB），务必保留，任何策略问题都能低成本重合并。
3. 命名：给输出目录打上版本与量化标记，例如qwen25-7b-codestyle-v1-merged、...-awq-int4，与发布记录一一对应。
4. 接入：合并产物直接作为 vLLM/SGLang 的--model参数起服务，无需任何 adapter 相关配置，部署链路回到"一个目录"的简单形态。

小结

• 合并的本质是W' = W + B·A·scaling的一次离线矩阵加法，结构不变、推理更轻
• 一条swift export --adapters <ckpt> --merge_lora true即可完成，基座信息从args.json自动读取
• 输出目录默认<ckpt>-merged，已存在即报错；--max_shard_size控制分片
• 显存紧张时同命令追加--quant_method+--quant_bits走 AWQ/GPTQ/FP8/BNB
• 验收口径：同题两次推理一致 + 延迟吞吐不劣于带 adapter 版本

下一步，挑一个刚训完的 checkpoint 把上面的命令跑一遍，把合并前后的延迟数字贴出来——如果哪一步报错，欢迎直接到项目仓库提 issue，附上args.json内容会大幅加快定位速度。觉得有用不妨点赞、收藏、关注后续更新。

【免费下载链接】swiftUse PEFT or Full-parameter to CPT/SFT/DPO/GRPO 600+ LLMs (Qwen3.6, DeepSeek-V4, GLM-5.1, InternLM3, Llama4, ...) and 300+ MLLMs (Qwen3-VL, Qwen3-Omni, InternVL3.5, Ovis2.5, GLM4.5v, Gemma4, Llava, Phi4, ...) (AAAI 2025).项目地址: https://gitcode.com/GitHub_Trending/swift1/swift