Swift Megatron-SWIFT 的 Mcore-Bridge 实践safetensors 与 Megatron 权重的双向无缝转换【免费下载链接】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/swiftMegatron 以极致的训练速度和丰富的并行技术著称但入门门槛较高本文围绕 SwiftMegatron-SWIFT集成的 mcore-bridge 组件完整讲解如何直接用 safetensors 格式模型在 Megatron 上完成全参数/LoRA 训练、如何导出与校验转换精度以及如何支撑 GRPO/GKD 等 RLHF 场景下的权重同步读完即可复制文中的命令完成从训练到推理验证的闭环。为什么需要 Mcore-Bridge原生 Megatron-Core 训练栈与 Hugging Face 生态之间存在结构性鸿沟Megatron 模型采用 TP/PP/EP/ETP 切分后的torch_dist权重格式而社区模型普遍以 safetensors 分发两者互转繁琐且容易出错。mcore-bridge 正是为抹平这道鸿沟而生目标是把 Megatron 训练做到与 transformers 一样简单易用。借助它用户可以获得以下能力直接加载 safetensors 格式权重即可用 Megatron 高效训练训练产出也直接保存为 safetensors 格式无需额外转换支持兼容 LoRA 增量权重的双向转换safetensors ↔ torch_dist支持Megatron-vLLM权重同步服务于 GRPO/GKD 等在线强化学习算法支持超大模型的跨机multi-machine转换。Mcore-Bridge 兼容 Dense/MoE/多模态等多种模型架构训练完成后的转换产物可以直接用 transformers、vLLM、SGLang 等主流推理框架部署。在 Swift 源码中mcore-bridge 是一个独立安装的第三方包pip install mcore-bridge核心入口类为GPTBridge在 Megatron 环境初始化文件 中通过_patch_mcore_bridge()对GPTBridge.save_weights做了增强包装使保存 safetensors 时能自动处理 PEFT 配置、多模态 target_modules 正则、config 与 processor 落盘等细节见 init.py。权重读取与保存策略四个关键参数Megatron-SWIFT 中从哪读权重、往哪写权重由四个参数共同决定这也是 Mcore-Bridge 无缝训练体验的核心参数行为--model / --adapters / --ref_model / --ref_adapters通过 mcore-bridge 加载 safetensors 格式权重--mcore_model / --mcore_adapter / --mcore_ref_model / --mcore_ref_adapter使用 Megatron 原生方式加载 torch_dist 格式 checkpoint--save_safetensors决定训练权重保存为 safetensors 还是 mcore 格式默认True见 megatron_args.py--no_save_optim当设置为false时会额外保存 mcore 权重以便断点续训从源码结构看这一策略在 sft_args.py 中做了强制校验--mcore_model会被转为绝对路径并要求目录存在且--model与--mcore_model至少传一个否则直接报错。另外值得注意的是在 LoRA 场景下megatron_args.py 中self.merge_lora self.save_safetensors即保存为 safetensors 格式时默认会合并 LoRA——这解释了下文示例中显式设置--merge_lora false的原因。还有一个实用提示GKD/GRPO 训练时若更新 vLLM 权重出现 GPU OOM可以设置--offload_bridge true把参与同步的张量先卸载到 CPU 以降低显存占用。这一点在源码中有直接对应——rollout_mixin.py 中target_device cpu if self.args.offload_bridge else None该逻辑在权重同步的两处路径L581 与 L615均生效offload_bridge定义于 megatron_args.py默认为False。当前 Mcore-Bridge 支持 TP/PP/EP/ETP/VPP 等并行技术支持的模型清单可查阅 Supported-models-and-datasets。全参数无缝训练Qwen3-VL 多模态示例以下示例在多模态模型 Qwen3-VL-8B-Instruct 上做 OCR 方向的全参数 SFT2 卡每卡约 76GiB完整命令与 examples/megatron/mcore_bridge/full/dense.sh 一致# 2 * 76GiB PYTORCH_CUDA_ALLOC_CONFexpandable_segments:True \ NPROC_PER_NODE2 \ IMAGE_MAX_TOKEN_NUM1024 \ VIDEO_MAX_TOKEN_NUM128 \ FPS_MAX_FRAMES16 \ CUDA_VISIBLE_DEVICES0,1 \ megatron sft \ --model Qwen/Qwen3-VL-8B-Instruct \ --save_safetensors true \ --dataset AI-ModelScope/LaTeX_OCR:human_handwrite#5000 \ --load_from_cache_file true \ --tensor_model_parallel_size 2 \ --sequence_parallel true \ --packing true \ --freeze_llm false \ --freeze_vit true \ --freeze_aligner true \ --split_dataset_ratio 0.01 \ --micro_batch_size 1 \ --global_batch_size 4 \ --recompute_granularity full \ --recompute_method uniform \ --recompute_num_layers 1 \ --finetune true \ --cross_entropy_loss_fusion true \ --lr 1e-5 \ --lr_warmup_fraction 0.05 \ --min_lr 1e-6 \ --num_train_epochs 1 \ --output_dir megatron_output/Qwen3-VL-8B-Instruct \ --save_steps 200 \ --max_length 2048 \ --dataloader_num_workers 4 \ --no_save_optim true \ --no_save_rng true \ --dataset_num_proc 8参数解读--model Qwen/Qwen3-VL-8B-Instruct走 mcore-bridge 路径直接读取 safetensors 权重无需先转换--save_safetensors truecheckpoint 以 safetensors 格式落盘可直接被 transformers/vLLM 消费--tensor_model_parallel_size 2--sequence_parallel true2 卡 TP 切分并启用序列并行--freeze_vit true --freeze_aligner true --freeze_llm false只微调 LLM 主干冻结视觉塔与 aligner配合--recompute_granularity full控制显存--no_save_optim true --no_save_rng true微调场景不保存优化器状态与 RNG 状态。由前文策略可知一旦no_save_optim设为false就会额外保存一份 mcore 权重用于续训--lr_warmup_fraction 0.05 --min_lr 1e-65% 预热、余弦衰减至 1e-6。训练完成后产出的 checkpoint 目录可直接作为普通 HF 模型加载在验证集上做流式推理PYTORCH_CUDA_ALLOC_CONFexpandable_segments:True \ IMAGE_MAX_TOKEN_NUM1024 \ VIDEO_MAX_TOKEN_NUM128 \ FPS_MAX_FRAMES16 \ CUDA_VISIBLE_DEVICES0 \ swift infer \ --model megatron_output/Qwen3-VL-8B-Instruct/vx-xxx/checkpoint-xxx \ --load_data_args true \ --stream true--load_data_args true会复用训练时保存的数据参数如max_length、模板配置保证推理预处理与训练一致。LoRA 训练Qwen3-MoE 自认知微调除全参数外Mcore-Bridge 同样支持 LoRA 训练。以下示例对纯文本 MoE 模型 Qwen3-30B-A3B 做自认知self-cognition训练2 卡、约 50GiB与 examples/megatron/mcore_bridge/lora/moe.sh 对应# 50GiB PYTORCH_CUDA_ALLOC_CONFexpandable_segments:True \ NPROC_PER_NODE2 \ CUDA_VISIBLE_DEVICES0,1 \ megatron sft \ --model Qwen/Qwen3-30B-A3B-Instruct-2507 \ --save_safetensors true \ --merge_lora false \ --dataset swift/Chinese-Qwen3-235B-2507-Distill-data-110k-SFT#2000 \ swift/self-cognition#1000 \ --load_from_cache_file true \ --tuner_type lora \ --lora_rank 8 \ --lora_alpha 32 \ --target_modules all-linear \ --split_dataset_ratio 0.01 \ --moe_permute_fusion true \ --expert_model_parallel_size 2 \ --moe_grouped_gemm true \ --moe_shared_expert_overlap true \ --moe_aux_loss_coeff 1e-3 \ --micro_batch_size 8 \ --global_batch_size 16 \ --recompute_granularity full \ --recompute_method uniform \ --recompute_num_layers 1 \ --num_train_epochs 1 \ --finetune true \ --cross_entropy_loss_fusion true \ --lr 1e-4 \ --lr_warmup_fraction 0.05 \ --min_lr 1e-5 \ --output_dir megatron_output/Qwen3-30B-A3B-Instruct-2507 \ --eval_steps 200 \ --save_steps 200 \ --max_length 2048 \ --dataloader_num_workers 8 \ --dataset_num_proc 8 \ --no_save_optim true \ --no_save_rng true \ --sequence_parallel true \ --moe_expert_capacity_factor 2 \ --attention_backend flash \ --model_author swift \ --model_name swift-robot其中 MoE 相关的开关值得注意--expert_model_parallel_size 2将专家按 EP 切到 2 卡--moe_grouped_gemm true用 Grouped GEMM 批量计算专家前向--moe_shared_expert_overlap true让共享专家计算与通信重叠--moe_aux_loss_coeff 1e-3加入负载均衡辅助损失。两条关于 LoRA 产物的关键说明必须遵守想导出合并后的全量权重而非 LoRA 增量权重设置--merge_lora true。合并方式兼容性更好支持所有模型系列。transformers 5.0Transformers 5.0 重构了 MoE 模型架构新结构不支持 MoE LoRA 增量推理可能导致推理异常——对 MoE 模型建议直接合并 LoRAvLLM 不受此影响。transformers 5.0由于 transformers 与 Megatron 的专家实现结构差异例如 transformers 中 Qwen3-VL-MoE 的专家组件以 Parameter 而非 Linear 层实现部分模型无法转换 LoRA 增量权重但 Qwen3-VL-MoE 在 LoRA 仅作用于linear_proj与linear_qkv时可以转换。多数模型Qwen3-MoE、Qwen3-Omni-MoE、GLM4.5-V 等均可正常转换。训练完成后用 vLLM 引擎加载基座模型 导出的 LoRA 增量权重推理# 具体模型在 vLLM 中的 LoRA 支持情况请参照 vLLM 文档 CUDA_VISIBLE_DEVICES0 \ swift infer \ --model Qwen/Qwen3-30B-A3B-Instruct-2507 \ --adapters megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx \ --infer_backend vllm \ --vllm_max_model_len 8192 \ --stream true如果需要手动Merge-LoRA请使用megatron export命令而不是swift export——原因是 Megatron 与 transformers 中 MoE 模型的结构并不必然一致跨结构合并必须由 Megatron 侧完成# 若 adapter 为 mcore 格式请改用 --mcore_adapter # 若最终格式要求 mcore使用 --to_mcore true CUDA_VISIBLE_DEVICES0,1,2,3 \ NPROC_PER_NODE4 \ megatron export \ --model Qwen/Qwen3-30B-A3B-Instruct-2507 \ --adapters megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx \ --output_dir megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-merged \ --merge_lora true \ --to_hf true \ --tensor_model_parallel_size 2 \ --expert_model_parallel_size 2 \ --pipeline_model_parallel_size 2随后用 transformers 引擎对合并后的完整权重推理CUDA_VISIBLE_DEVICES0 \ swift infer \ --model megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-merged \ --stream truemegatron export独立转换与精度校验除了训练过程中的转换与保存Mcore-Bridge 还支持megatron export做独立的权重导出。该命令在转换过程中支持转换精度测试对新模型接入时验证正确性非常有用对于 Megatron-SWIFT 已集成的模型通常不会出现精度偏差可以放心使用默认--test_convert_precision false。一个多模态模型的注意项请重点观察mean_diff (with loss)字段。mean_diff可能显示较大差异因为它包含了图像 token而 loss 并不在该部分上计算——只看mean_diff (with loss)才能真实反映可训练部分的转换质量。全参数权重safetensors → torch_dist# safetensors - torch_dist CUDA_VISIBLE_DEVICES0,1,2,3 \ NPROC_PER_NODE4 \ megatron export \ --model Qwen/Qwen3-30B-A3B-Instruct-2507 \ --output_dir Qwen3-30B-A3B-Instruct-2507-mcore \ --to_mcore true \ --tensor_model_parallel_size 2 \ --expert_model_parallel_size 2 \ --pipeline_model_parallel_size 2 \ --test_convert_precision true全参数权重torch_dist → safetensors# torch_dist - safetensors CUDA_VISIBLE_DEVICES0,1,2,3 \ NPROC_PER_NODE4 \ megatron export \ --mcore_model Qwen3-30B-A3B-Instruct-2507-mcore \ --output_dir Qwen3-30B-A3B-Instruct-2507-hf \ --to_hf true \ --tensor_model_parallel_size 2 \ --expert_model_parallel_size 2 \ --pipeline_model_parallel_size 2 \ --test_convert_precision trueLoRA 权重双向转换# torch_dist - safetensors # 若需在 merge-lora 之后测试精度对齐直接设置 --merge_lora true # 也可把 --model safetensors路径 换成 --mcore_model torch-dist路径 # 两种写法等价mcore-bridge 会自动处理 CUDA_VISIBLE_DEVICES0,1,2,3 \ NPROC_PER_NODE4 \ megatron export \ --model Qwen/Qwen3-30B-A3B-Instruct-2507 \ --mcore_adapter megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx \ --output_dir megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-lora \ --merge_lora false \ --to_hf true \ --tensor_model_parallel_size 2 \ --expert_model_parallel_size 2 \ --pipeline_model_parallel_size 2 \ --test_convert_precision true# safetensors - torch_dist CUDA_VISIBLE_DEVICES0,1,2,3 \ NPROC_PER_NODE4 \ megatron export \ --model Qwen/Qwen3-30B-A3B-Instruct-2507 \ --adapters megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-lora \ --output_dir megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-mcore \ --merge_lora false \ --to_mcore true \ --tensor_model_parallel_size 2 \ --expert_model_parallel_size 2 \ --pipeline_model_parallel_size 2 \ --test_convert_precision true转换链路源码解析理解megatron export的底层流程有助于排查转换问题。两个方向的实现分别位于 convert.py 中的convert_hf2mcore()与convert_mcore2hf()safetensors → torch_distconvert_hf2mcoreconvert.py先用prepare_model_template准备 HF 模型按检查点大小自动推算thread_count每 10GB 约一个线程并对torch_dist分片打补丁随后构造MegatronArguments、调用get_mcore_model建立 Megatron 模型骨架核心一步是bridge.load_weights([mg_model], args.model_info.model_dir)——即由GPTBridge完成 safetensors 权重到切分后 Megatron 模型的搬运最后save_mcore_checkpoint落盘 torch_dist 格式。若开启--test_convert_precision精度校验被刻意放在保存之后执行避免测试过程污染落盘权重。torch_dist → safetensorsconvert_mcore2hfconvert.py反向流程中从 checkpoint 目录读取训练时保存的args.jsonMegatronArguments.load_args_config恢复并行拓扑等配置若带mcore_adapter则先加载基座再挂 PEFT 模型并执行peft_model.merge_and_unload()完成 LoRA 合并--to_hf分支调用bridge.save_weights([mg_model], args.output_dir, args..., processor...)输出 safetensors同时拷贝args.json--to_mcore分支则重新分片保存 torch_dist 检查点。参数默认值与自动化行为可以在 export_args.py 中确认test_convert_precision默认Falsetest_convert_dtype默认float32精度测试在 float32 下比对规避低精度噪声未指定--output_dir时会依据--to_mcore/--to_hf自动在源 checkpoint 名后追加-mcore或-hf后缀MoE 模型且tensor_model_parallel_size 1时自动强制sequence_parallel TrueMoE 模型自动开启moe_grouped_gemm转换过程统一强制no_save_optim/no_save_rng/no_load_optim/no_load_rng/finetune保证纯权重搬运。此外convert_kwargs中还固定了use_cpu_initialization: True与attention_backend: unfused意味着转换时模型在 CPU 上初始化、使用非融合注意力——这正是多机转换超大模型能力的基础GPU 显存几乎不参与权重搬运。仓库中的可用示例Mcore-Bridge 相关脚本集中在 examples/megatron/mcore_bridge 目录下可按需参考examples/megatron/mcore_bridge/full/dense.shDense 全参数本文 Qwen3-VL 示例examples/megatron/mcore_bridge/full/moe.shMoE 全参数examples/megatron/mcore_bridge/lora/moe.shMoE LoRA本文 Qwen3-30B-A3B 示例examples/megatron/mcore_bridge/lora/new_special_tokens.sh新增特殊 token 的 LoRA 训练examples/megatron/mcore_bridge/lora/seq_cls.sh序列分类任务的 LoRA 训练。小结Mcore-Bridge 把加载 safetensors → Megatron 并行训练 → 保存 safetensors做成了默认路径--model读、--save_safetensors写--mcore_*系列参数保留原生 torch_dist 通道megatron export提供带精度校验的独立双向转换--offload_bridge则为 GRPO/GKD 的 vLLM 权重同步提供显存兜底。对已接入 Megatron-SWIFT 的模型这套链路可以直接复用对新模型接入--test_convert_precision true的mean_diff (with loss)指标则是验证转换正确性的最直接手段。【免费下载链接】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 Megatron-SWIFT 的 Mcore-Bridge 实践：safetensors 与 Megatron 权重的双向无缝转换
Swift Megatron-SWIFT 的 Mcore-Bridge 实践safetensors 与 Megatron 权重的双向无缝转换【免费下载链接】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/swiftMegatron 以极致的训练速度和丰富的并行技术著称但入门门槛较高本文围绕 SwiftMegatron-SWIFT集成的 mcore-bridge 组件完整讲解如何直接用 safetensors 格式模型在 Megatron 上完成全参数/LoRA 训练、如何导出与校验转换精度以及如何支撑 GRPO/GKD 等 RLHF 场景下的权重同步读完即可复制文中的命令完成从训练到推理验证的闭环。为什么需要 Mcore-Bridge原生 Megatron-Core 训练栈与 Hugging Face 生态之间存在结构性鸿沟Megatron 模型采用 TP/PP/EP/ETP 切分后的torch_dist权重格式而社区模型普遍以 safetensors 分发两者互转繁琐且容易出错。mcore-bridge 正是为抹平这道鸿沟而生目标是把 Megatron 训练做到与 transformers 一样简单易用。借助它用户可以获得以下能力直接加载 safetensors 格式权重即可用 Megatron 高效训练训练产出也直接保存为 safetensors 格式无需额外转换支持兼容 LoRA 增量权重的双向转换safetensors ↔ torch_dist支持Megatron-vLLM权重同步服务于 GRPO/GKD 等在线强化学习算法支持超大模型的跨机multi-machine转换。Mcore-Bridge 兼容 Dense/MoE/多模态等多种模型架构训练完成后的转换产物可以直接用 transformers、vLLM、SGLang 等主流推理框架部署。在 Swift 源码中mcore-bridge 是一个独立安装的第三方包pip install mcore-bridge核心入口类为GPTBridge在 Megatron 环境初始化文件 中通过_patch_mcore_bridge()对GPTBridge.save_weights做了增强包装使保存 safetensors 时能自动处理 PEFT 配置、多模态 target_modules 正则、config 与 processor 落盘等细节见 init.py。权重读取与保存策略四个关键参数Megatron-SWIFT 中从哪读权重、往哪写权重由四个参数共同决定这也是 Mcore-Bridge 无缝训练体验的核心参数行为--model / --adapters / --ref_model / --ref_adapters通过 mcore-bridge 加载 safetensors 格式权重--mcore_model / --mcore_adapter / --mcore_ref_model / --mcore_ref_adapter使用 Megatron 原生方式加载 torch_dist 格式 checkpoint--save_safetensors决定训练权重保存为 safetensors 还是 mcore 格式默认True见 megatron_args.py--no_save_optim当设置为false时会额外保存 mcore 权重以便断点续训从源码结构看这一策略在 sft_args.py 中做了强制校验--mcore_model会被转为绝对路径并要求目录存在且--model与--mcore_model至少传一个否则直接报错。另外值得注意的是在 LoRA 场景下megatron_args.py 中self.merge_lora self.save_safetensors即保存为 safetensors 格式时默认会合并 LoRA——这解释了下文示例中显式设置--merge_lora false的原因。还有一个实用提示GKD/GRPO 训练时若更新 vLLM 权重出现 GPU OOM可以设置--offload_bridge true把参与同步的张量先卸载到 CPU 以降低显存占用。这一点在源码中有直接对应——rollout_mixin.py 中target_device cpu if self.args.offload_bridge else None该逻辑在权重同步的两处路径L581 与 L615均生效offload_bridge定义于 megatron_args.py默认为False。当前 Mcore-Bridge 支持 TP/PP/EP/ETP/VPP 等并行技术支持的模型清单可查阅 Supported-models-and-datasets。全参数无缝训练Qwen3-VL 多模态示例以下示例在多模态模型 Qwen3-VL-8B-Instruct 上做 OCR 方向的全参数 SFT2 卡每卡约 76GiB完整命令与 examples/megatron/mcore_bridge/full/dense.sh 一致# 2 * 76GiB PYTORCH_CUDA_ALLOC_CONFexpandable_segments:True \ NPROC_PER_NODE2 \ IMAGE_MAX_TOKEN_NUM1024 \ VIDEO_MAX_TOKEN_NUM128 \ FPS_MAX_FRAMES16 \ CUDA_VISIBLE_DEVICES0,1 \ megatron sft \ --model Qwen/Qwen3-VL-8B-Instruct \ --save_safetensors true \ --dataset AI-ModelScope/LaTeX_OCR:human_handwrite#5000 \ --load_from_cache_file true \ --tensor_model_parallel_size 2 \ --sequence_parallel true \ --packing true \ --freeze_llm false \ --freeze_vit true \ --freeze_aligner true \ --split_dataset_ratio 0.01 \ --micro_batch_size 1 \ --global_batch_size 4 \ --recompute_granularity full \ --recompute_method uniform \ --recompute_num_layers 1 \ --finetune true \ --cross_entropy_loss_fusion true \ --lr 1e-5 \ --lr_warmup_fraction 0.05 \ --min_lr 1e-6 \ --num_train_epochs 1 \ --output_dir megatron_output/Qwen3-VL-8B-Instruct \ --save_steps 200 \ --max_length 2048 \ --dataloader_num_workers 4 \ --no_save_optim true \ --no_save_rng true \ --dataset_num_proc 8参数解读--model Qwen/Qwen3-VL-8B-Instruct走 mcore-bridge 路径直接读取 safetensors 权重无需先转换--save_safetensors truecheckpoint 以 safetensors 格式落盘可直接被 transformers/vLLM 消费--tensor_model_parallel_size 2--sequence_parallel true2 卡 TP 切分并启用序列并行--freeze_vit true --freeze_aligner true --freeze_llm false只微调 LLM 主干冻结视觉塔与 aligner配合--recompute_granularity full控制显存--no_save_optim true --no_save_rng true微调场景不保存优化器状态与 RNG 状态。由前文策略可知一旦no_save_optim设为false就会额外保存一份 mcore 权重用于续训--lr_warmup_fraction 0.05 --min_lr 1e-65% 预热、余弦衰减至 1e-6。训练完成后产出的 checkpoint 目录可直接作为普通 HF 模型加载在验证集上做流式推理PYTORCH_CUDA_ALLOC_CONFexpandable_segments:True \ IMAGE_MAX_TOKEN_NUM1024 \ VIDEO_MAX_TOKEN_NUM128 \ FPS_MAX_FRAMES16 \ CUDA_VISIBLE_DEVICES0 \ swift infer \ --model megatron_output/Qwen3-VL-8B-Instruct/vx-xxx/checkpoint-xxx \ --load_data_args true \ --stream true--load_data_args true会复用训练时保存的数据参数如max_length、模板配置保证推理预处理与训练一致。LoRA 训练Qwen3-MoE 自认知微调除全参数外Mcore-Bridge 同样支持 LoRA 训练。以下示例对纯文本 MoE 模型 Qwen3-30B-A3B 做自认知self-cognition训练2 卡、约 50GiB与 examples/megatron/mcore_bridge/lora/moe.sh 对应# 50GiB PYTORCH_CUDA_ALLOC_CONFexpandable_segments:True \ NPROC_PER_NODE2 \ CUDA_VISIBLE_DEVICES0,1 \ megatron sft \ --model Qwen/Qwen3-30B-A3B-Instruct-2507 \ --save_safetensors true \ --merge_lora false \ --dataset swift/Chinese-Qwen3-235B-2507-Distill-data-110k-SFT#2000 \ swift/self-cognition#1000 \ --load_from_cache_file true \ --tuner_type lora \ --lora_rank 8 \ --lora_alpha 32 \ --target_modules all-linear \ --split_dataset_ratio 0.01 \ --moe_permute_fusion true \ --expert_model_parallel_size 2 \ --moe_grouped_gemm true \ --moe_shared_expert_overlap true \ --moe_aux_loss_coeff 1e-3 \ --micro_batch_size 8 \ --global_batch_size 16 \ --recompute_granularity full \ --recompute_method uniform \ --recompute_num_layers 1 \ --num_train_epochs 1 \ --finetune true \ --cross_entropy_loss_fusion true \ --lr 1e-4 \ --lr_warmup_fraction 0.05 \ --min_lr 1e-5 \ --output_dir megatron_output/Qwen3-30B-A3B-Instruct-2507 \ --eval_steps 200 \ --save_steps 200 \ --max_length 2048 \ --dataloader_num_workers 8 \ --dataset_num_proc 8 \ --no_save_optim true \ --no_save_rng true \ --sequence_parallel true \ --moe_expert_capacity_factor 2 \ --attention_backend flash \ --model_author swift \ --model_name swift-robot其中 MoE 相关的开关值得注意--expert_model_parallel_size 2将专家按 EP 切到 2 卡--moe_grouped_gemm true用 Grouped GEMM 批量计算专家前向--moe_shared_expert_overlap true让共享专家计算与通信重叠--moe_aux_loss_coeff 1e-3加入负载均衡辅助损失。两条关于 LoRA 产物的关键说明必须遵守想导出合并后的全量权重而非 LoRA 增量权重设置--merge_lora true。合并方式兼容性更好支持所有模型系列。transformers 5.0Transformers 5.0 重构了 MoE 模型架构新结构不支持 MoE LoRA 增量推理可能导致推理异常——对 MoE 模型建议直接合并 LoRAvLLM 不受此影响。transformers 5.0由于 transformers 与 Megatron 的专家实现结构差异例如 transformers 中 Qwen3-VL-MoE 的专家组件以 Parameter 而非 Linear 层实现部分模型无法转换 LoRA 增量权重但 Qwen3-VL-MoE 在 LoRA 仅作用于linear_proj与linear_qkv时可以转换。多数模型Qwen3-MoE、Qwen3-Omni-MoE、GLM4.5-V 等均可正常转换。训练完成后用 vLLM 引擎加载基座模型 导出的 LoRA 增量权重推理# 具体模型在 vLLM 中的 LoRA 支持情况请参照 vLLM 文档 CUDA_VISIBLE_DEVICES0 \ swift infer \ --model Qwen/Qwen3-30B-A3B-Instruct-2507 \ --adapters megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx \ --infer_backend vllm \ --vllm_max_model_len 8192 \ --stream true如果需要手动Merge-LoRA请使用megatron export命令而不是swift export——原因是 Megatron 与 transformers 中 MoE 模型的结构并不必然一致跨结构合并必须由 Megatron 侧完成# 若 adapter 为 mcore 格式请改用 --mcore_adapter # 若最终格式要求 mcore使用 --to_mcore true CUDA_VISIBLE_DEVICES0,1,2,3 \ NPROC_PER_NODE4 \ megatron export \ --model Qwen/Qwen3-30B-A3B-Instruct-2507 \ --adapters megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx \ --output_dir megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-merged \ --merge_lora true \ --to_hf true \ --tensor_model_parallel_size 2 \ --expert_model_parallel_size 2 \ --pipeline_model_parallel_size 2随后用 transformers 引擎对合并后的完整权重推理CUDA_VISIBLE_DEVICES0 \ swift infer \ --model megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-merged \ --stream truemegatron export独立转换与精度校验除了训练过程中的转换与保存Mcore-Bridge 还支持megatron export做独立的权重导出。该命令在转换过程中支持转换精度测试对新模型接入时验证正确性非常有用对于 Megatron-SWIFT 已集成的模型通常不会出现精度偏差可以放心使用默认--test_convert_precision false。一个多模态模型的注意项请重点观察mean_diff (with loss)字段。mean_diff可能显示较大差异因为它包含了图像 token而 loss 并不在该部分上计算——只看mean_diff (with loss)才能真实反映可训练部分的转换质量。全参数权重safetensors → torch_dist# safetensors - torch_dist CUDA_VISIBLE_DEVICES0,1,2,3 \ NPROC_PER_NODE4 \ megatron export \ --model Qwen/Qwen3-30B-A3B-Instruct-2507 \ --output_dir Qwen3-30B-A3B-Instruct-2507-mcore \ --to_mcore true \ --tensor_model_parallel_size 2 \ --expert_model_parallel_size 2 \ --pipeline_model_parallel_size 2 \ --test_convert_precision true全参数权重torch_dist → safetensors# torch_dist - safetensors CUDA_VISIBLE_DEVICES0,1,2,3 \ NPROC_PER_NODE4 \ megatron export \ --mcore_model Qwen3-30B-A3B-Instruct-2507-mcore \ --output_dir Qwen3-30B-A3B-Instruct-2507-hf \ --to_hf true \ --tensor_model_parallel_size 2 \ --expert_model_parallel_size 2 \ --pipeline_model_parallel_size 2 \ --test_convert_precision trueLoRA 权重双向转换# torch_dist - safetensors # 若需在 merge-lora 之后测试精度对齐直接设置 --merge_lora true # 也可把 --model safetensors路径 换成 --mcore_model torch-dist路径 # 两种写法等价mcore-bridge 会自动处理 CUDA_VISIBLE_DEVICES0,1,2,3 \ NPROC_PER_NODE4 \ megatron export \ --model Qwen/Qwen3-30B-A3B-Instruct-2507 \ --mcore_adapter megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx \ --output_dir megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-lora \ --merge_lora false \ --to_hf true \ --tensor_model_parallel_size 2 \ --expert_model_parallel_size 2 \ --pipeline_model_parallel_size 2 \ --test_convert_precision true# safetensors - torch_dist CUDA_VISIBLE_DEVICES0,1,2,3 \ NPROC_PER_NODE4 \ megatron export \ --model Qwen/Qwen3-30B-A3B-Instruct-2507 \ --adapters megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-lora \ --output_dir megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-mcore \ --merge_lora false \ --to_mcore true \ --tensor_model_parallel_size 2 \ --expert_model_parallel_size 2 \ --pipeline_model_parallel_size 2 \ --test_convert_precision true转换链路源码解析理解megatron export的底层流程有助于排查转换问题。两个方向的实现分别位于 convert.py 中的convert_hf2mcore()与convert_mcore2hf()safetensors → torch_distconvert_hf2mcoreconvert.py先用prepare_model_template准备 HF 模型按检查点大小自动推算thread_count每 10GB 约一个线程并对torch_dist分片打补丁随后构造MegatronArguments、调用get_mcore_model建立 Megatron 模型骨架核心一步是bridge.load_weights([mg_model], args.model_info.model_dir)——即由GPTBridge完成 safetensors 权重到切分后 Megatron 模型的搬运最后save_mcore_checkpoint落盘 torch_dist 格式。若开启--test_convert_precision精度校验被刻意放在保存之后执行避免测试过程污染落盘权重。torch_dist → safetensorsconvert_mcore2hfconvert.py反向流程中从 checkpoint 目录读取训练时保存的args.jsonMegatronArguments.load_args_config恢复并行拓扑等配置若带mcore_adapter则先加载基座再挂 PEFT 模型并执行peft_model.merge_and_unload()完成 LoRA 合并--to_hf分支调用bridge.save_weights([mg_model], args.output_dir, args..., processor...)输出 safetensors同时拷贝args.json--to_mcore分支则重新分片保存 torch_dist 检查点。参数默认值与自动化行为可以在 export_args.py 中确认test_convert_precision默认Falsetest_convert_dtype默认float32精度测试在 float32 下比对规避低精度噪声未指定--output_dir时会依据--to_mcore/--to_hf自动在源 checkpoint 名后追加-mcore或-hf后缀MoE 模型且tensor_model_parallel_size 1时自动强制sequence_parallel TrueMoE 模型自动开启moe_grouped_gemm转换过程统一强制no_save_optim/no_save_rng/no_load_optim/no_load_rng/finetune保证纯权重搬运。此外convert_kwargs中还固定了use_cpu_initialization: True与attention_backend: unfused意味着转换时模型在 CPU 上初始化、使用非融合注意力——这正是多机转换超大模型能力的基础GPU 显存几乎不参与权重搬运。仓库中的可用示例Mcore-Bridge 相关脚本集中在 examples/megatron/mcore_bridge 目录下可按需参考examples/megatron/mcore_bridge/full/dense.shDense 全参数本文 Qwen3-VL 示例examples/megatron/mcore_bridge/full/moe.shMoE 全参数examples/megatron/mcore_bridge/lora/moe.shMoE LoRA本文 Qwen3-30B-A3B 示例examples/megatron/mcore_bridge/lora/new_special_tokens.sh新增特殊 token 的 LoRA 训练examples/megatron/mcore_bridge/lora/seq_cls.sh序列分类任务的 LoRA 训练。小结Mcore-Bridge 把加载 safetensors → Megatron 并行训练 → 保存 safetensors做成了默认路径--model读、--save_safetensors写--mcore_*系列参数保留原生 torch_dist 通道megatron export提供带精度校验的独立双向转换--offload_bridge则为 GRPO/GKD 的 vLLM 权重同步提供显存兜底。对已接入 Megatron-SWIFT 的模型这套链路可以直接复用对新模型接入--test_convert_precision true的mean_diff (with loss)指标则是验证转换正确性的最直接手段。【免费下载链接】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），仅供参考