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/swiftLoRA低秩适配训练完的那一刻往往是最轻松的显存省了、速度也够看。可一旦进入部署环节麻烦就来了——推理框架加载模型时还得额外挂载适配器目录多一层依赖、多一次反序列化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 .装完确认环境里的关键依赖没有版本冲突torch2.0、transformers4.33、peft0.11即可pip list | grep -E torch|transformers|peft|modelscope⚠️ 易错点如果 pip 报 torch 依赖冲突先单独pip install --no-deps处理冲突包再重装 swift避免连带降级 torch。一条命令完成合并最小可用步骤只要你的 checkpoint 是用 swift 训练出来的目录里就有训练时自动写下的args.json它会记录基础模型 ID、模板、系统提示词等全部信息。因此合并时不需要再写--modelswift 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参数说明易错点--adapters指向含args.json的 checkpoint 目录基础模型信息自动从中读取手动训练的 adapter 目录若没有args.json必须补--model显式指定基座--merge_lora设为 true 触发合并支持 lora、llamapro、longlora 三种适配器只传--adapters不传它会走推送/原样导出逻辑不会融合--output_dir合并结果保存路径缺省为checkpoint名-merged目标目录已存在时直接报FileExistsError需先清理或指定新路径--safe_serialization是否输出 safetensors默认 true极少数旧推理框架读不了 safetensors 时才设为 false--max_shard_size单分片上限默认 5GB超大模型加载慢时可加大到 10GB减少分片数 小经验输出目录名会自动带上后缀merged、awq-int4、ollama 等合并、量化各产出一份互不覆盖做版本管理很方便。合并的完整数据流整条流水线的输入输出关系如下排障时按顺序定位即可其中 G 步的scaling lora_alpha / r也就是训练时设的秩和缩放系数——如果合并后效果异常优先回头检查训练参数是否被误改合并本身不会引入误差。合并后量化显存还能再砍一半部署侧如果显存紧张可以在同一条命令里顺带量化。swift 支持 AWQ、GPTQ、FP8、BNB 四种方法脚本示例在 examples/export/quantize/选型建议方法校准数据耗时适用场景AWQ / GPTQ需要约 256~500 条长7B 约 20~40 分钟精度优先配合 vLLM/SGLang 推理加速FP8 / BNB不需要短分钟级快速出卡先跑通链路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 压测合并前后延迟与吞吐正常结果应是延迟下降、吞吐上升方向反了就要查硬件或框架配置而不是怀疑合并。常见报错与对应解法现象高概率原因处理FileExistsError: output_dir already exists重跑时输出目录未清理换新路径或确认后删掉旧目录加载阶段报基座权重缺失/结构不符自动读取的 model ID 与实际 checkpoint 不一致显式追加--model 原始基座强制指定OOM / CPU 内存不足大基座在合并时全量载入72B 级建议--device_map cpu分步处理或加大主机内存合并后精度下降与合并无关多为训练端 rank/目标模块设置过激回查args.json中lora_rank、target_modules重新训练推送失败token 权限不足或 model_id 无编辑权限核对--hub_token账号对该组织有编辑权排障时打开args.json看一眼永远是第一动作它同时是合并时 swift 用了什么和当初训练用了什么的单一事实来源。落地建议把合并放进交付流水线时机等全部微调任务结束再合并避免多次重复执行合并本身 7B 级通常 5~15 分钟。备份原始 adapter 目录体积小7B LoRA 约 50~200MB务必保留任何策略问题都能低成本重合并。命名给输出目录打上版本与量化标记例如qwen25-7b-codestyle-v1-merged、...-awq-int4与发布记录一一对应。接入合并产物直接作为 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
