尧图网站建设 
swift LoRA模型合并完整指南3步把适配器权重融合为可部署的完整模型【免费下载链接】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的模型合并功能3步把LoRA权重融合进基础模型得到一个标准、独立、可直接上线的完整模型全程只需一条swift export命令。核心概念合并到底在做什么为什么LoRA权重要先合并一次⚡ LoRA训练时基础模型参数是冻结的你实际训出来的只是一组低秩增量矩阵A、B。这意味着适配器不能单独工作它必须挂载在原始基础模型上才能推理部署时要多带一步加载每次部署都得基础模型 适配器成对提供多一个依赖就多一个出错点推理时有额外开销每个目标层都要额外做一次低秩矩阵乘法。模型合并Model Merging就是把这组增量一次性算进基础模型的原始权重里输出一个不再需要适配器的完整模型。swift合并的内部原理mermaid在swift里整个过程由swift export驱动核心就三步源码见 swift/pipelines/export/merge_lora.py准备模型与模板prepare_model_template加载基础模型并套上适配器执行融合Swift.merge_and_unload(model)把LoRA增量写入各层权重然后卸载适配器落盘保存save_checkpoint按标准格式保存权重默认safetensors默认单分片5GB。合并带来的三个直接收益收益说明部署简化一个目录就是一个完整模型vLLM、Ollama、swift infer都能直接加载无需再传--adapters推理提速目标层少一次低秩矩阵乘法逐token生成的延迟会稳定下降分发方便单个模型目录即可交付、打包、做版本管理快速上手一条命令完成合并环境准备先装好swift并确认可用# 推荐pip安装 pip install ms-swift -U # 或源码安装需要最新功能时 git clone https://gitcode.com/GitHub_Trending/swift1/swift cd swift pip install -e .# 验证安装 swift --help | head最小可运行命令假设你已经用swift跑过一次LoRA训练比如 examples/train/lora_sft.sh 里的写法得到了output/vx-xxx/checkpoint-xxx目录。合并只需要swift export \ --adapters output/vx-xxx/checkpoint-xxx \ --merge_lora true就这么短。✅ 你不需要写--model因为swift会自动从checkpoint里的args.json读出训练时的基础模型、精度、模板等全部配置。跑完后合并结果默认保存在checkpoint目录/checkpoint-xxx-merged/。关键参数速查参数说明完整列表见 docs/source/Instruction/Command-line-parameters.md 的合并参数一节--adapters必填。LoRA训练输出的checkpoint目录目录内须有swift训练时自动生成的args.json--merge_lora设为true才触发合并支持lora、llamapro、longlora三种tuner--output_dir可选。不指定时自动在checkpoint旁生成xxx-merged目录--safe_serialization默认true保存为safetensors--max_shard_size默认5GB控制权重分片大小深度解析合并流程与核心数学完整执行流程注意最后一步合并完成后swift会把args.model指向合并结果、清空adapters所以量化、导出Ollama、推送这些后续操作天然作用在合并后的模型上一条命令串起来即可。核心融合数学每个被LoRA覆盖的线性层融合只做一次矩阵加法。用伪代码表示# 每个被LoRA覆盖的线性层源码: Swift.merge_and_unload delta lora_B lora_A # 低秩增量 delta delta * scaling # scaling lora_alpha / lora_rank weight.data delta融合是纯本地张量运算不需要GPU加速框架7B量级的模型通常在几分钟内完成视磁盘IO而定。args.json替你省掉的活swift export启动时会调用load_args_from_ckpt见 swift/arguments/base_args/base_args.py只要你没手动指定model、model_type、torch_dtype、task_type等训练配置都从checkpoint的args.json中恢复。这带来一个实用好处合并命令对多模态模型同样简单——Qwen2.5-VL这类模型处理器的版本、模板配置也一并被还原不会出现合并成功但多模态推理跑偏的问题。真实场景4个进阶用法场景一合并量化一步到位合并后直接AWQ/GPTQ量化省一次完整模型的读写。⚠️ 量化必须提供校准数据集否则直接报错swift export \ --adapters output/checkpoint-1000 \ --merge_lora true \ --quant_method awq \ --quant_bits 4 \ --dataset AI-ModelScope/alpaca-gpt4-data-zh#128 \ --output_dir merged_model-awq支持的量化方法awq、gptq、bnb、fp8、gptq_v2量化细节见 docs/source/Instruction/Export-and-push.md。场景二合并并推送模型库合并完直接推送到Model Hub用于团队共享swift export \ --adapters output/checkpoint-1000 \ --merge_lora true \ --push_to_hub true \ --hub_model_id your_name/your-model-merged场景三合并后导出Ollama格式本地部署到Ollama生成所需的Modelfileswift export \ --adapters output/checkpoint-1000 \ --merge_lora true \ --to_ollama true场景四指定分片与输出路径大模型按5GB分片保存可能产生太多文件可以调大分片swift export \ --adapters output/checkpoint-1000 \ --merge_lora true \ --output_dir merged_model \ --max_shard_size 10GB验证与避坑确认合并真的成功了确认合并成功 两层验证缺一不可1. 检查输出目录结构以Qwen2.5-7B为例checkpoint-1000-merged/ ├── config.json ├── generation_config.json ├── model-00001-of-0000X.safetensors ├── model.safetensors.index.json └── tokenizer 相关文件2. 推理对比合并前带适配器与合并后纯模型输出应基本一致# 合并前 swift infer --model Qwen/Qwen2.5-7B-Instruct \ --adapters output/checkpoint-1000 \ --stream true # 合并后 swift infer --model output/checkpoint-1000-merged \ --stream true高频报错对照表报错/现象原因解决AssertionError: args_path: ...checkpoint目录里没有args.jsoncheckpoint必须是swift训练产出手动训练的模型请显式传--model等参数FileExistsError: ... already exists--output_dir指定的目录已存在换路径或加--exist_ok true覆盖日志提示already exists, skipping默认的xxx-merged目录已存在本次跳过了保存加--exist_ok true或删除旧目录后重跑ValueError: Please input the quant datasetAWQ/GPTQ量化缺校准集补充--dataset参数警告--to_mcore/to_hfdoes not support--merge_lora两类参数不兼容merge_lora被自动关闭拆成两步先合并再做格式转换加载基础模型时OOM合并需完整载入一次基座权重加--device_map cpu_offload把权重卸载到CPU牺牲速度换显存排错三板斧# 1. 看args.json确认基础模型和LoRA配置是否为预期 cat output/checkpoint-1000/args.json | head -30 # 2. 看合并日志关键行 # 正常应依次出现: Merge LoRA... - Saving merged weights... # - Successfully merged LoRA and saved in ... # 3. 用swift infer做合并前后输出对比见上文验证命令总结回顾一下这条最短路径训练swift sft --tuner_type lora ...产出带args.json的checkpoint合并swift export --adapters ckpt --merge_lora true配置自动还原默认存到xxx-merged部署对合并后的目录直接用swift infer/swift deploy/vLLM加载无需再带--adapters进阶时记住两个组合拳--merge_lora--quant_method合并即量化和**--merge_lora--push_to_hub/--to_ollama**合并即分发。源码入口在 swift/pipelines/export/示例脚本在 examples/export/。如果你正在做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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 swift LoRA模型合并完整指南：3步把适配器权重融合为可部署的完整模型
swift LoRA模型合并完整指南3步把适配器权重融合为可部署的完整模型【免费下载链接】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的模型合并功能3步把LoRA权重融合进基础模型得到一个标准、独立、可直接上线的完整模型全程只需一条swift export命令。核心概念合并到底在做什么为什么LoRA权重要先合并一次⚡ LoRA训练时基础模型参数是冻结的你实际训出来的只是一组低秩增量矩阵A、B。这意味着适配器不能单独工作它必须挂载在原始基础模型上才能推理部署时要多带一步加载每次部署都得基础模型 适配器成对提供多一个依赖就多一个出错点推理时有额外开销每个目标层都要额外做一次低秩矩阵乘法。模型合并Model Merging就是把这组增量一次性算进基础模型的原始权重里输出一个不再需要适配器的完整模型。swift合并的内部原理mermaid在swift里整个过程由swift export驱动核心就三步源码见 swift/pipelines/export/merge_lora.py准备模型与模板prepare_model_template加载基础模型并套上适配器执行融合Swift.merge_and_unload(model)把LoRA增量写入各层权重然后卸载适配器落盘保存save_checkpoint按标准格式保存权重默认safetensors默认单分片5GB。合并带来的三个直接收益收益说明部署简化一个目录就是一个完整模型vLLM、Ollama、swift infer都能直接加载无需再传--adapters推理提速目标层少一次低秩矩阵乘法逐token生成的延迟会稳定下降分发方便单个模型目录即可交付、打包、做版本管理快速上手一条命令完成合并环境准备先装好swift并确认可用# 推荐pip安装 pip install ms-swift -U # 或源码安装需要最新功能时 git clone https://gitcode.com/GitHub_Trending/swift1/swift cd swift pip install -e .# 验证安装 swift --help | head最小可运行命令假设你已经用swift跑过一次LoRA训练比如 examples/train/lora_sft.sh 里的写法得到了output/vx-xxx/checkpoint-xxx目录。合并只需要swift export \ --adapters output/vx-xxx/checkpoint-xxx \ --merge_lora true就这么短。✅ 你不需要写--model因为swift会自动从checkpoint里的args.json读出训练时的基础模型、精度、模板等全部配置。跑完后合并结果默认保存在checkpoint目录/checkpoint-xxx-merged/。关键参数速查参数说明完整列表见 docs/source/Instruction/Command-line-parameters.md 的合并参数一节--adapters必填。LoRA训练输出的checkpoint目录目录内须有swift训练时自动生成的args.json--merge_lora设为true才触发合并支持lora、llamapro、longlora三种tuner--output_dir可选。不指定时自动在checkpoint旁生成xxx-merged目录--safe_serialization默认true保存为safetensors--max_shard_size默认5GB控制权重分片大小深度解析合并流程与核心数学完整执行流程注意最后一步合并完成后swift会把args.model指向合并结果、清空adapters所以量化、导出Ollama、推送这些后续操作天然作用在合并后的模型上一条命令串起来即可。核心融合数学每个被LoRA覆盖的线性层融合只做一次矩阵加法。用伪代码表示# 每个被LoRA覆盖的线性层源码: Swift.merge_and_unload delta lora_B lora_A # 低秩增量 delta delta * scaling # scaling lora_alpha / lora_rank weight.data delta融合是纯本地张量运算不需要GPU加速框架7B量级的模型通常在几分钟内完成视磁盘IO而定。args.json替你省掉的活swift export启动时会调用load_args_from_ckpt见 swift/arguments/base_args/base_args.py只要你没手动指定model、model_type、torch_dtype、task_type等训练配置都从checkpoint的args.json中恢复。这带来一个实用好处合并命令对多模态模型同样简单——Qwen2.5-VL这类模型处理器的版本、模板配置也一并被还原不会出现合并成功但多模态推理跑偏的问题。真实场景4个进阶用法场景一合并量化一步到位合并后直接AWQ/GPTQ量化省一次完整模型的读写。⚠️ 量化必须提供校准数据集否则直接报错swift export \ --adapters output/checkpoint-1000 \ --merge_lora true \ --quant_method awq \ --quant_bits 4 \ --dataset AI-ModelScope/alpaca-gpt4-data-zh#128 \ --output_dir merged_model-awq支持的量化方法awq、gptq、bnb、fp8、gptq_v2量化细节见 docs/source/Instruction/Export-and-push.md。场景二合并并推送模型库合并完直接推送到Model Hub用于团队共享swift export \ --adapters output/checkpoint-1000 \ --merge_lora true \ --push_to_hub true \ --hub_model_id your_name/your-model-merged场景三合并后导出Ollama格式本地部署到Ollama生成所需的Modelfileswift export \ --adapters output/checkpoint-1000 \ --merge_lora true \ --to_ollama true场景四指定分片与输出路径大模型按5GB分片保存可能产生太多文件可以调大分片swift export \ --adapters output/checkpoint-1000 \ --merge_lora true \ --output_dir merged_model \ --max_shard_size 10GB验证与避坑确认合并真的成功了确认合并成功 两层验证缺一不可1. 检查输出目录结构以Qwen2.5-7B为例checkpoint-1000-merged/ ├── config.json ├── generation_config.json ├── model-00001-of-0000X.safetensors ├── model.safetensors.index.json └── tokenizer 相关文件2. 推理对比合并前带适配器与合并后纯模型输出应基本一致# 合并前 swift infer --model Qwen/Qwen2.5-7B-Instruct \ --adapters output/checkpoint-1000 \ --stream true # 合并后 swift infer --model output/checkpoint-1000-merged \ --stream true高频报错对照表报错/现象原因解决AssertionError: args_path: ...checkpoint目录里没有args.jsoncheckpoint必须是swift训练产出手动训练的模型请显式传--model等参数FileExistsError: ... already exists--output_dir指定的目录已存在换路径或加--exist_ok true覆盖日志提示already exists, skipping默认的xxx-merged目录已存在本次跳过了保存加--exist_ok true或删除旧目录后重跑ValueError: Please input the quant datasetAWQ/GPTQ量化缺校准集补充--dataset参数警告--to_mcore/to_hfdoes not support--merge_lora两类参数不兼容merge_lora被自动关闭拆成两步先合并再做格式转换加载基础模型时OOM合并需完整载入一次基座权重加--device_map cpu_offload把权重卸载到CPU牺牲速度换显存排错三板斧# 1. 看args.json确认基础模型和LoRA配置是否为预期 cat output/checkpoint-1000/args.json | head -30 # 2. 看合并日志关键行 # 正常应依次出现: Merge LoRA... - Saving merged weights... # - Successfully merged LoRA and saved in ... # 3. 用swift infer做合并前后输出对比见上文验证命令总结回顾一下这条最短路径训练swift sft --tuner_type lora ...产出带args.json的checkpoint合并swift export --adapters ckpt --merge_lora true配置自动还原默认存到xxx-merged部署对合并后的目录直接用swift infer/swift deploy/vLLM加载无需再带--adapters进阶时记住两个组合拳--merge_lora--quant_method合并即量化和**--merge_lora--push_to_hub/--to_ollama**合并即分发。源码入口在 swift/pipelines/export/示例脚本在 examples/export/。如果你正在做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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考