跳到主要内容

Megatron Bridge 入门

版本与验证范围

本文对应 TrainingSuite v2.2.0 的 Megatron Bridge 多模态训练示例。验证环境使用镜像依赖的 Megatron Bridge 0.4.2、Megatron Core 0.19、Python 3.12 和 8 × MTT S5000;示例依赖 training-musa-adaptor 中的 MUSA 适配。

新增的 Qwen3-30B-A3B tulu3 文本 SFT 示例要求单独安装官方开源 v0.6.2,两套流程需要分别遵循对应文档。

1. Megatron Bridge 是什么​

Megatron Bridge 是 Hugging Face 与 Megatron Core 之间的模型和训练配置桥接层。它读取 Hugging Face 配置与权重,构造对应的 Megatron 模型,并提供训练、并行和 checkpoint 转换能力。

在本文的 MUSA 训练链路中:

  • Megatron Core 负责模型并行和训练执行;
  • Megatron Bridge 负责模型映射、权重加载和训练配置组织;
  • training-musa-adaptor 提供 MUSA 算子与上游接口适配;
  • TrainingSuite 镜像提供 PyTorch、torch_musa、MCCL、MATE 和 Transformer Engine 等基础能力。

Megatron Bridge 不替代 Megatron Core,也不等同于 MT-Megatron。需要加载 Hugging Face 模型或复用 Bridge recipe 时使用 Megatron Bridge;已有原生 Megatron Core 模型和 checkpoint 时,可以直接使用 Megatron Core。

2. 支持范围​

v2.2.0 示例覆盖以下四个模型:

模型加载 HF 权重继续训练 / SFT随机初始化从头预训练验证说明
Qwen3-VL-32B-Instruct支持支持历史完成 5 步 SFT 和 100 步随机初始化训练
Qwen3.5-4B支持支持历史完成 100 步随机初始化训练
Qwen3.5-35B-A3B支持支持历史完成 100 步随机初始化训练
Qwen3.8-27B支持支持使用历史 20 步记录,本轮未复测

本文中的两种模式含义如下:

  • 加载 HF 权重继续训练 / SFT:默认读取 MODEL_PATH 中的 Hugging Face 权重,使用 LLaVA conversation 数据,训练 loss 只计算 assistant token。Bridge 0.4.2 使用 DirectHFSFTDatasetConfig 组织数据。
  • 随机初始化从头预训练:追加 --load-hf-weights false,只读取 Hugging Face 模型配置来构造结构,不加载权重。必须使用新的输出目录,并显式设置学习率和 warmup。

Bridge 的训练入口名为 pretrain(),但当前示例传入的是 SFT/VLM conversation 数据和 assistant-only loss。不能用入口函数名判断数据是否属于原始 token 预训练。

此外,v2.2.0 还提供基于 tulu3 数据的 Qwen3-30B-A3B 纯文本 SFT 示例。该示例使用 examples/megatron_bridge/qwen3_sft,要求单独安装开源 Megatron Bridge v0.6.2,步骤见使用 Megatron Bridge 执行 Qwen3-30B-A3B SFT。

3. 训练架构​

Hugging Face 配置与权重
↓
Megatron Bridge:模型映射、权重加载、训练配置
↓
Megatron Core:TP / PP / EP / DP 与训练执行
↓
training-musa-adaptor:MUSA 接口与算子适配
↓
torch_musa / MATE / Transformer Engine / MCCL
↓
MTT S5000

Qwen3.5 系列包含线性注意力路径时,Gated Delta Net 默认使用 Flash Linear Attention 的 Triton 实现。提供 torch_musa_op_extension TileLang 实现时,可通过 TORCH_MUSA_OP_EXTENSION_PATH 切换;切换前必须确认日志出现实际分发信息。

4. 环境基线​

下表是本文多模态示例实测使用的 Bridge 0.4.2 环境。

组件验证版本或配置
GPU8 × MTT S5000,每卡 80 GB
Python3.12
PyTorch / torch_musa2.9.0.post1 / 2.9.0.post1
Megatron Bridge0.4.2
Megatron Corecore_v0.19.0;源码自报版本 0.19.1
Transformer Engine / MATE2.13.0 / 0.2.8.post2
FlashAttention2.8.3.post4
Triton / TileLang MUSA3.2.0+musa4.3.10 / 0.1.12+musa.4
NumPy1.26.1
Transformers / Megatron Energon5.16.1 / 6.0.1
training-musa-adaptor2.2.0
Flash Linear Attention / fla-core0.5.2 / 0.5.2
训练精度 / attention backendBF16 / flash

Transformers 5.16.1 超过 Bridge 0.4.2 wheel 声明的部分版本范围,是当前 MUSA 适配组合的实测版本。不要为了消除声明冲突而无约束升级 PyTorch、Triton、Transformer Engine 或安装全部 Bridge extras。

5. 能力边界​

  • 已验证 backbone、视觉塔、投影层和一层 MTP 的 8 卡训练;没有覆盖全部模型结构和任意并行组合。
  • 已验证 attention_backend=flash;没有覆盖 local、unfused attention 和 veRL 左填充路径。
  • 没有验证 torch.compile、FP8 收敛、HF 数值逐值等价和其他尺寸模型。
  • Bridge 启动脚本强制 checkpoint.save=null。20 步或 100 步训练正常结束,不代表 checkpoint、optimizer 和 RNG 恢复能力已经验证。
  • Qwen3.8-27B 的权重包含 output_gate_type=swish,当前 Bridge/Core 未处理该语义。即使训练可以运行,也不能据此认定模型语义或 Hugging Face 数值已经对齐。
  • 本文耗时和 loss 来自特定节点、镜像、数据、权重、seed 和并行配置,只用于该次运行的可追溯验收,不是跨版本性能基准。

6. 文档导航​