Chapter 13

源码导读：Megatron-Core / NeMo 边界

📌 commit 2ea3e0fNeMo 50 万行从何下手

NeMo 仓库巨大（约 50 万行），但只有少量"主干"代码是核心。本章给一份阅读路线，并把 NeMo / Megatron-Core / TransformerEngine 的边界标出来。

13.1仓库结构

NeMo/                               https://github.com/NVIDIA-NeMo/NeMo
├── nemo/
│   ├── collections/
│   │   ├── llm/                    ★ 2.x LLM 训练核心
│   │   │   ├── gpt/model.py
│   │   │   ├── recipes/             几十个 recipe
│   │   │   ├── peft/
│   │   │   └── ...
│   │   ├── nlp/                    1.x 兼容层（仍在维护）
│   │   │   ├── models/
│   │   │   ├── modules/
│   │   │   └── data/
│   │   ├── vlm/                    Vision-Language
│   │   ├── speechlm/               Speech LLM
│   │   ├── asr/ / tts/             ASR / TTS
│   │   ├── multimodal/             扩散
│   │   └── common/                  共享层（tokenizer / metrics）
│   ├── lightning/                  ★ PT-Lightning 适配
│   │   ├── pytorch/
│   │   ├── megatron_parallel.py
│   │   └── strategies/
│   ├── core/                       老 1.x 核心（Trainer 等）
│   ├── utils/
│   └── deploy/                     部署相关
├── examples/                       ★ 几百个示例
├── scripts/
│   ├── checkpoint_converters/       NeMo ↔ HF 转换
│   └── ...
├── tutorials/                       Jupyter notebook
└── tests/

13.2建议阅读顺序

#	文件	读什么
1	`nemo/collections/llm/recipes/llama3_8b.py`	典型 recipe 的写法
2	`nemo/collections/llm/gpt/model/base.py`	GPTModel 怎么基于 MCore 构建
3	`nemo/lightning/megatron_parallel.py`	Lightning 怎么挂上 Megatron-Core
4	`nemo/lightning/strategies/megatron_strategy.py`	分布式策略
5	`nemo/collections/llm/peft/`	LoRA / DoRA / IA3 实现
6	`nemo/collections/llm/api.py`	train / finetune / pretrain 高层 API
7	`scripts/checkpoint_converters/convert_llama_nemo_to_hf.py`	QKV 转换怎么写
8	`nemo/collections/nlp/data/language_modeling/megatron/preprocess_data_for_megatron.py`	indexed dataset 生成

13.3NeMo / MCore 边界

谁负责	什么
NeMo	recipe / Lightning 集成 / aligner / 多模态 / 检查点格式 / 部署
Megatron-Core	ColumnParallelLinear / RowParallelLinear / DistributedDataParallel / PP schedule / DistributedOptimizer / TransformerLayer / GPTModel
TransformerEngine	FP8 GEMM / FlashAttention / RMSNorm / DotProductAttention
Apex	fused optimizer / fused layer norm（部分被 TE 取代）

13.4关键 commit 时间线

时间	变更
2019	NeMo 项目首次开源（v0.x，主打 ASR/TTS）
2022	v1.0：NeMo Megatron Collection 加入
2023-09	NeMo Aligner 独立子项目
2024-03	NeVA / SpeechLLM 多模态
2024-08	v2.0 alpha：Lightning 2.0 + Python recipe
2024-11	FP8 训练正式 GA
2025-01	v2.2：Megatron-Core 0.11 + NeVA 多张图
2025-04	v2.4（本书）：Qwen3 / DeepSeek 支持

13.5对照其他框架

	NeMo	Megatron-LM 原版	ColossalAI	TorchTitan
顶层 API	Lightning + recipe	命令行	Booster + Plugin	原生 PyTorch
多模态	★★★★★	—	★（OpenSora）	—
分布式底座	Megatron-Core	原生	自家	DTensor
RLHF	NeMo Aligner	—	ColossalChat	—
部署集成	TRT-LLM / Triton / NIM	—	—	—
性能	★★★★★	★★★★★	★★★★	★★★★

13.6社区入口

GitHub: https://github.com/NVIDIA-NeMo/NeMo（17k+ ⭐）
官方文档: https://docs.nvidia.com/nemo-framework/
Discord: NVIDIA Developer
Aligner 仓库: NVIDIA/NeMo-Aligner
Curator 仓库: NVIDIA/NeMo-Curator

13.7当前仓库（v2.8 语音版）真实源码树

本仓库现在以语音 / 语音 LLM 为主。ls nemo/：

nemo/
├── collections/                ★ 五大 collection
│   ├── asr/                     Canary / Parakeet / Citrinet / Conformer-CTC
│   ├── tts/                     FastPitch / HiFi-GAN / VITS
│   ├── audio/                   audio-to-audio（去噪 / 增强 / 分离）
│   ├── speechlm2/               ★ SALM 多模态 LLM + Duplex
│   │   ├── models/               salm.py / salm_automodel.py:45 / duplex_*.py
│   │   ├── data/                 salm_dataset.py / datamodule.py
│   │   └── parts/                automodel_lora.py:27 / parallel.py /
│   │                              optim_setup.py / pretrained.py / encoder_chunking.py
│   └── common/                   tokenizer / 工具
│
├── core/                       ★ 神经类型系统 + 配置 + 优化器
│   ├── classes/                  modelPT.py（save_to/restore_from）
│   ├── config/                    hydra_runner.py
│   ├── connectors/                save_restore_connector.py
│   ├── neural_types/
│   └── optim/
│
├── lightning/                  ★ PyTorch Lightning 基础
│   ├── base.py                   Base LightningModule
│   ├── base_callback.py
│   ├── callback_group.py
│   └── one_logger_callback.py
│
├── utils/                      exp_manager.py / export_utils.py / megatron_utils.py
├── agents/voice_agent/         ★ 2026 新 Voice Agent
├── deploy/                      推理部署
└── export/                      ONNX / TRT 导出

13.8四份外部仓库分工速查

仓库	负责
NVIDIA/NeMo（本仓库）	语音 / ASR / TTS / Speech LLM / Voice Agent
NVIDIA/NeMo-Framework	纯 LLM 预训练 / SFT / DPO / multimodal-VLM
NVIDIA/NeMo-RL	大规模 RL（GRPO / PPO / DPO）
NVIDIA/NeMo-Curator	数据去重 / quality filter / GPU-accelerated dataset 处理
NVIDIA/Megatron-Bridge	Megatron ↔ HF / NeMo ↔ HF 互转
NVIDIA/Megatron-LM	★ 上述大部分 LLM 训练的底层算子

13.9Hydra 入口模式（所有训练脚本都长这样）

nemo/core/config/hydra_runner.py 提供的 @hydra_runner 装饰器是所有 NeMo 训练脚本的统一入口。看 examples/speechlm2/salm_train.py:28–56：

from nemo.core.config import hydra_runner

@hydra_runner(config_path="conf", config_name="salm")
def train(cfg):
    trainer = Trainer(**resolve_trainer_cfg(cfg.trainer))
    model = SALM(cfg.model)         # 或 SALMAutomodel(cfg.model)
    datamodule = build_datamodule(cfg.data)
    trainer.fit(model, datamodule)

if __name__ == "__main__":
    train()

对应配置在 examples/speechlm2/conf/salm.yaml。CLI 覆盖：python salm_train.py trainer.devices=8 model.optim.lr=1e-4。

13.10从代码风格看 CLAUDE.md（NeMo 风格指南）

nemo/CLAUDE.md 列了贡献规范，关键几条：

line-length 119（不是 88，不是 100）；
black 用 skip_string_normalization；
isort + ruff 配套；
所有训练脚本走 @hydra_runner；
常用工具脚本：scripts/estimate_duration_bins.py、scripts/oomptimizer.py、scripts/estimate_data_weights.py、scripts/convert_to_tarred_audio_dataset.py。

13.11这章你需要带走的

NeMo 50 万行但核心在 nemo/collections/llm/ 和 nemo/lightning/；
读源码先看 recipe，然后 GPTModel，最后 MegatronStrategy；
分布式细节 90% 在 Megatron-Core，NeMo 主要做集成；
NeMo 真正的护城河是多模态 + 部署链路；
2025 实战中 NeMo 是 NVIDIA 全栈用户的首选，其他可考虑 Megatron / ColossalAI / TorchTitan。