理解 MT-Megatron 0.19.0 代码架构与 ModuleSpec
本文介绍 MT-Megatron 的主要代码模块和 ModuleSpec 模型定义方式,帮助你在阅读源码、接入新模型或修改 MoE 结构时定位入口。本文侧重解释设计原理,不提供完整训练命令。
1. 代码模块概览
MT-Megatron 的代码主要分为模型定义、数据处理、训练配置和训练执行四类模块。下图展示主要目录和依赖关系:

阅读源码时,可以按以下顺序定位:
- 从训练启动脚本确认入口、工作目录和模型配置 。
- 从训练配置查找模型规模和并行参数。
- 从模型注册入口定位目标模型实现。
- 从数据模块确认 tokenizer、数据格式和样本组织方式。
2. 使用 ModuleSpec 注册模型
Megatron 使用 ModuleSpec 封装层、模块和配置,将模型结构与参数初始化解耦。模型提供函数负责创建模型并返回 Megatron 可识别的模型对象。
典型注册关系如下:



![]()
接入新模型时,应同时核对模块构造参数、层注册顺序和训练配置。仅修改模型类而没有更新 ModuleSpec 或配置入口时,训练进程可能仍加载旧模型。
3. ModuleSpec 的职责
ModuleSpec 负责描述模块类型、构造参数、子模块和初始化方式。它将“使用哪个实现”和“如何使用该实现”分开,便于代码复用和替换。


model_provider 负责根据配置构建模型,并将 ModuleSpec 注册到具体层或子模块。阅读代码时,应优先确认以下信息:
- 当前配置选择了哪个
model_provider。 - 每类层使用哪个
ModuleSpec。 - 构造参数来自命令行、配置文件还是代码默认值。
- 初始化和 checkpoint 加载是否使用同一套模块定义。
![]()
![]()


4. 使用 ModuleSpec 定义 MoE Layer
MoE 模型在普通 Transformer Block 中增加专家网络和路由器。阅读或修改 MoE 实现时,应分别检查 Layer、Router、ModuleSpec 和 forward 四个部分。
4.1 定义专家层

专家层负责保存专家参数并执行专家前馈计算。专家数量、单专家隐藏维度和并行方式由训练配置控制。
4.2 定义 Router

Router 负责计算每个 token 选择哪些专家。排查路由问题时,同时检查路由分数函数、top-k、分组策略、负载均衡损失和容量因子。
4.3 注册 MoE ModuleSpec

ModuleSpec 将专家层、Router 和辅助损失组合成可构建的 MoE 模块。
4.4 理解 forward 流程

典型 forward 流程先由 Router 为 token 选择专家,再执行 token permute、专家计算、结果合并和辅助损失计算。启用通信重叠、DeepEP 或激活卸载后,执行顺序和缓冲区生命周期会发生变化。
5. 延伸阅读
- 返回 MT-Megatron 产品介绍,查看产品定位和版本基线。
- 阅读 MT-Megatron 训练参数参考,核对模型、MoE 和并行参数。
- 阅读 MT-Megatron 关键特性与参数说明,了解 FP8、DeepEP、通信重叠和性能分析。
- 查看 MT-Megatron 官方仓库中的模型和示例源码。

