swift LoRA 模型合并实战：一条 export 命令如何把适配器变成可部署的完整模型

swift LoRA 模型合并实战：一条 export 命令如何把适配器变成可部署的完整模型

【免费下载链接】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 适配器训练完成后，checkpoint 目录并不能直接上线。这篇文章围绕 swift 的模型合并能力展开：先用一条swift export命令完成 LoRA 权重合并到基础模型，再解释低秩权重并入原模型的原理，并给出显存预算、多适配器融合与量化合并等进阶用法，最后附上可照做的验证清单和排查表，帮你对接 vLLM 部署前把每一步都跑对。

先跑通：一条命令完成 LoRA 权重合并

前提是你有一个由 swift 训练产出的 checkpoint（目录内含args.json）。

用 swift export 合并 LoRA 权重到基础模型

✅ 合并只需三个关键参数：

# 指向训练产出的 checkpoint，打开合并开关，指定落盘目录 swift export \ --adapters output/vx-xxx/checkpoint-xxx \ --merge_lora true \ --output_dir merged_model

参数按"参数 → 作用 → 默认行为"理解：

• --adapters→ 指向包含 LoRA 权重与args.json的 checkpoint 目录 → 必填；基础模型信息由此自动补齐
• --merge_lora→ 开启权重合并开关 → 默认 false，不设 true 则不会执行合并
• --output_dir→ 合并后完整模型的落盘位置 → 缺省时保存为<适配器目录名>-merged

合并产物长什么样

执行成功后，目标路径下出现一个标准模型目录，不再附带任何适配器文件：

merged_model/ ├── config.json # 模型配置 ├── generation_config.json # 生成参数 ├── pytorch_model-00001-of-00002.bin ├── pytorch_model-00002-of-00002.bin ├── pytorch_model.bin.index.json └── special_tokens_map.json

这类产物可直接被 vLLM、SGLang 等主流推理框架加载，无需再做适配层处理。

原理与流程：低秩矩阵如何并入基础模型

LoRA 适配器不改动基座权重，只训练一对低秩小矩阵 A、B；所谓合并，就是把这对矩阵带来的增量一次性写回基座各目标层的权重里。每个目标层的更新公式为：

W = W + (B @ A) × scaling # scaling = alpha / rank

写入完成后，模型不再需要外挂适配器，推理路径上省掉一次矩阵乘法，这也是合并后延迟普遍更低的来源。整条链路按顺序执行五步：

1. swift 从 checkpoint 的args.json读取基础模型 ID 与训练配置，因此不必再手动传--model
2. 加载基础模型，并挂载 LoRA 的 A、B 两路权重
3. 逐目标层做低秩乘积，按公式增量写回基座权重
4. 以标准格式（config.json、分片权重、索引文件等）保存到output_dir
5. 产物即完整模型，可直接进入推理与部署环节

环境依赖与显存预算

安装并验证 swift

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

swift --version # 预期输出类似：ms-swift 3.0.0

pip list | grep -E "torch|transformers|peft|modelscope" # 版本基线：torch >= 2.0, transformers >= 4.33, peft >= 0.11, modelscope >= 1.23

不同规模模型合并所需显存

进阶场景：多适配器融合与量化合并

按 0.7 : 0.3 权重融合两个任务适配器

当两个 checkpoint 分别来自不同任务的微调时，按顺序列出路径，并用--adapter_weights控制各自贡献比例：

# 第一个适配器权重占比 0.7，第二个占 0.3 swift export \ --adapters output/task1/checkpoint-500 output/task2/checkpoint-800 \ --merge_lora true \ --adapter_weights 0.7 0.3

量化合并与 swift 合并模型接 vLLM 部署

• --quant_bits→ 指定量化位宽（4 或 8）→ 缺省不量化
• --quant_method→ 选择量化算法（awq / gptq / bnb）→ 需搭配校准数据集
• --dataset→ 提供量化校准语料 → 不传则无法执行量化
• --use_hf→ 在 Hugging Face 与魔搭两种产物格式间切换 → 默认 true，即 HF 格式

# 合并同时做 4-bit AWQ 量化 swift export \ --adapters output/checkpoint-1000 \ --merge_lora true \ --quant_bits 4 \ --quant_method awq \ --dataset AI-ModelScope/alpaca-gpt4-data-zh#100

产物可直接交给 vLLM 起服务，完成从合并到部署的衔接：

python -m vllm.entrypoints.api_server \ --model merged_model \ --tensor-parallel-size 1 \ --port 8000

验证与排错：确认合并没有跑偏

三步验证清单

1. 完整性：核对落盘目录是否齐全，应包含config.json、分片权重、pytorch_model.bin.index.json与special_tokens_map.json
2. 一致性：同一提示词分别走"基座 + 适配器"和"合并模型"两条路径，输出应基本一致

# 合并前：基础模型挂载适配器 swift infer \ --model Qwen/Qwen2.5-7B-Instruct \ --adapters output/checkpoint-1000 \ --text "你是谁？" # 合并后：只加载合并产物 swift infer \ --model merged_model \ --text "你是谁？"

3. 性能：以 7B 规模模型实测，合并后单次推理延迟普遍降低 15%–30%，吞吐约提升 15%–25%；若合并后反而更慢，先回到训练配置排查

出错时按表定位

⚠️ 常见故障按"先查什么、再做什么"组织：

两个补充手段：

# 打开详细日志，定位卡住的具体环节 swift export --adapters output/checkpoint-1000 --merge_lora true --debug true # 自动读取失败时，强制指定基础模型 swift export --adapters output/checkpoint-1000 --merge_lora true --model Qwen/Qwen2.5-7B-Instruct

收尾：合并产物上线前的落地建议

从合并权重到生产发布的检查项

1. 合并放在最后做：所有任务微调全部收敛后再执行一次合并，避免同一批权重反复走合并流程
2. 给产物打版本标记：例如model-v1.0-merged，线上排查与回滚时一目了然
3. 保留原始适配器与基座：合并参数（rank、adapter_weights）需要调整时，无需重训即可再次合并
4. 把合并纳入 CI：在发布流水线中加一步swift export --adapters output/checkpoint-final --merge_lora true，自动归档产物
5. 回归测试常态化：每次上线前复跑合并前后推理对比，延迟或输出异常即阻断发布

【免费下载链接】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