企业官网建设流程全解析

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/swift

Megatron 以极致的训练速度和丰富的并行技术著称，但入门门槛较高；本文围绕 Swift（Megatron-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 一样简单易用。借助它，用户可以获得以下能力：

1. 直接加载 safetensors 格式权重即可用 Megatron 高效训练，训练产出也直接保存为 safetensors 格式，无需额外转换；
2. 支持兼容 LoRA 增量权重的双向转换（safetensors ↔ torch_dist）；
3. 支持Megatron->vLLM权重同步，服务于 GRPO/GKD 等在线强化学习算法；
4. 支持超大模型的跨机（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 无缝训练体验的核心：

从源码结构看，这一策略在 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 方向的全参数 SFT（2 卡，每卡约 76GiB），完整命令与 examples/megatron/mcore_bridge/full/dense.sh 一致：

# 2 * 76GiB PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \ NPROC_PER_NODE=2 \ IMAGE_MAX_TOKEN_NUM=1024 \ VIDEO_MAX_TOKEN_NUM=128 \ FPS_MAX_FRAMES=16 \ CUDA_VISIBLE_DEVICES=0,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 true：checkpoint 以 safetensors 格式落盘，可直接被 transformers/vLLM 消费；
• --tensor_model_parallel_size 2+--sequence_parallel true：2 卡 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-6：5% 预热、余弦衰减至 1e-6。

训练完成后，产出的 checkpoint 目录可直接作为普通 HF 模型加载，在验证集上做流式推理：

PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \ IMAGE_MAX_TOKEN_NUM=1024 \ VIDEO_MAX_TOKEN_NUM=128 \ FPS_MAX_FRAMES=16 \ CUDA_VISIBLE_DEVICES=0 \ 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_CONF='expandable_segments:True' \ NPROC_PER_NODE=2 \ CUDA_VISIBLE_DEVICES=0,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 产物的关键说明必须遵守：

1. 想导出合并后的全量权重而非 LoRA 增量权重：设置--merge_lora true。合并方式兼容性更好，支持所有模型系列。
2. transformers >= 5.0：Transformers 5.0 重构了 MoE 模型架构，新结构不支持 MoE LoRA 增量推理，可能导致推理异常——对 MoE 模型建议直接合并 LoRA（vLLM 不受此影响）。
3. 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_DEVICES=0 \ 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_DEVICES=0,1,2,3 \ NPROC_PER_NODE=4 \ 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_DEVICES=0 \ swift infer \ --model megatron_output/Qwen3-30B-A3B-Instruct-2507/vx-xxx/checkpoint-xxx-merged \ --stream true

megatron 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_DEVICES=0,1,2,3 \ NPROC_PER_NODE=4 \ 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_DEVICES=0,1,2,3 \ NPROC_PER_NODE=4 \ 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 true

LoRA 权重：双向转换

# torch_dist -> safetensors # 若需在 merge-lora 之后测试精度对齐，直接设置 `--merge_lora true` # 也可把 `--model safetensors路径` 换成 `--mcore_model torch-dist路径` # 两种写法等价，mcore-bridge 会自动处理 CUDA_VISIBLE_DEVICES=0,1,2,3 \ NPROC_PER_NODE=4 \ 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_DEVICES=0,1,2,3 \ NPROC_PER_NODE=4 \ 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_dist（convert_hf2mcore，convert.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 → safetensors（convert_mcore2hf，convert.py）：反向流程中，从 checkpoint 目录读取训练时保存的args.json（MegatronArguments.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默认False，test_convert_dtype默认float32（精度测试在 float32 下比对，规避低精度噪声）；
• 未指定--output_dir时，会依据--to_mcore/--to_hf自动在源 checkpoint 名后追加-mcore或-hf后缀；
• MoE 模型且tensor_model_parallel_size > 1时，自动强制sequence_parallel = True；
• MoE 模型自动开启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.sh：Dense 全参数（本文 Qwen3-VL 示例）；
• examples/megatron/mcore_bridge/full/moe.sh：MoE 全参数；
• examples/megatron/mcore_bridge/lora/moe.sh：MoE 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