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 环境。
| 组件 | 验证版本或 配置 |
|---|---|
| GPU | 8 × MTT S5000,每卡 80 GB |
| Python | 3.12 |
PyTorch / torch_musa | 2.9.0.post1 / 2.9.0.post1 |
| Megatron Bridge | 0.4.2 |
| Megatron Core | core_v0.19.0;源码自报版本 0.19.1 |
| Transformer Engine / MATE | 2.13.0 / 0.2.8.post2 |
| FlashAttention | 2.8.3.post4 |
| Triton / TileLang MUSA | 3.2.0+musa4.3.10 / 0.1.12+musa.4 |
| NumPy | 1.26.1 |
| Transformers / Megatron Energon | 5.16.1 / 6.0.1 |
| training-musa-adaptor | 2.2.0 |
| Flash Linear Attention / fla-core | 0.5.2 / 0.5.2 |
| 训练精度 / attention backend | BF16 / 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. 文档导航
- Megatron Bridge 预训练与 SFT SOP:准备模型和数据、安装检查、四个模型的拉起命令、验收与常见问题。
- 使用 Megatron Bridge 执行 Qwen3-30B-A3B SFT:使用 tulu3 数据完成文本 SFT,并明确区分镜像依赖 0.4.2 与开源 v0.6.2。
- 训练框架适配说明:查看 v2.2.0 其他训练框架和版本边界。
- Megatron Bridge 官方文档:查看上游模型、recipe 和 checkpoint 转换能力。
- Megatron-LM 官方仓库:查看 Megatron Core 源码和版本说明。

