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/swiftLoRA 适配器训练完成后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写入完成后模型不再需要外挂适配器推理路径上省掉一次矩阵乘法这也是合并后延迟普遍更低的来源。整条链路按顺序执行五步swift 从 checkpoint 的args.json读取基础模型 ID 与训练配置因此不必再手动传--model加载基础模型并挂载 LoRA 的 A、B 两路权重逐目标层做低秩乘积按公式增量写回基座权重以标准格式config.json、分片权重、索引文件等保存到output_dir产物即完整模型可直接进入推理与部署环节环境依赖与显存预算安装并验证 swiftgit clone https://gitcode.com/GitHub_Trending/swift1/swift cd swift pip install -e .swift --version # 预期输出类似ms-swift 3.0.0pip list | grep -E torch|transformers|peft|modelscope # 版本基线torch 2.0, transformers 4.33, peft 0.11, modelscope 1.23不同规模模型合并所需显存基础模型规模合并所需最低显存推荐显卡7B16GBRTX 3090 / A1013B24GBRTX 4090 / A10070B80GBA100 / H100进阶场景多适配器融合与量化合并按 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验证与排错确认合并没有跑偏三步验证清单完整性核对落盘目录是否齐全应包含config.json、分片权重、pytorch_model.bin.index.json与special_tokens_map.json一致性同一提示词分别走基座 适配器和合并模型两条路径输出应基本一致# 合并前基础模型挂载适配器 swift infer \ --model Qwen/Qwen2.5-7B-Instruct \ --adapters output/checkpoint-1000 \ --text 你是谁 # 合并后只加载合并产物 swift infer \ --model merged_model \ --text 你是谁性能以 7B 规模模型实测合并后单次推理延迟普遍降低 15%–30%吞吐约提升 15%–25%若合并后反而更慢先回到训练配置排查出错时按表定位⚠️ 常见故障按先查什么、再做什么组织故障表现先检查处理路径合并时 OOM显存余量与模型规模是否匹配改用--quant_bits 4量化合并压低占用或启用--low_cpu_mem_usage基础模型加载失败args.json记录的模型 ID 与当前环境是否一致按args.json原始字段重新拉取基座或用--model参数强制指定合并后能力下降训练时 LoRA 的 rank 是否偏高降低 rank 重训或用--adapter_weights重新分配贡献基础模型信息读不出来checkpoint 内是否存在args.json确认训练端 swift 3.0.0 后重新产出 checkpoint两个补充手段# 打开详细日志定位卡住的具体环节 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收尾合并产物上线前的落地建议从合并权重到生产发布的检查项合并放在最后做所有任务微调全部收敛后再执行一次合并避免同一批权重反复走合并流程给产物打版本标记例如model-v1.0-merged线上排查与回滚时一目了然保留原始适配器与基座合并参数rank、adapter_weights需要调整时无需重训即可再次合并把合并纳入 CI在发布流水线中加一步swift export --adapters output/checkpoint-final --merge_lora true自动归档产物回归测试常态化每次上线前复跑合并前后推理对比延迟或输出异常即阻断发布【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考