Chapter 13

5000 行通读路线

📌 commit 2411b02读完它你能号称"读过一个完整的预训练框架"

本书的最大目标是让你真正读完一个完整的预训练框架。nanotron 5000 行刚好做到这件事。本章给一份"按章节倒序的通读清单"。

13.1三天通读计划

Day	文件	累计行数
Day 1 （架构）	`config/config.py` `parallel/context.py` `parallel/parameters.py` `helpers.py`	~1200 行
Day 2 （分布式核心）	`parallel/tensor_parallel/nn.py` `parallel/tensor_parallel/functional.py` `parallel/pipeline_parallel/engine.py` `parallel/pipeline_parallel/state.py` `optim/zero.py` `optim/clip_grads.py`	~1800 行
Day 3 （模型 + 训练）	`models/llama.py` `trainer.py` `data/dataloader.py` `serialize/main.py`	~2000 行

13.2每天怎么读

当天开始先读对应本书章节（4-5 / 5-6 / 9-10）；
带着问题打开源码：找本书引用的那些函数；
对每个非平凡函数，自己 用伪代码改写一遍，验证理解；
跑一次 tiny config + 加 print，验证执行顺序符合理解。

13.3读完后你应该能回答

3 维 process group 怎么排？rank 怎么算？
TP ColumnLinear / RowLinear 内部各几次通信？什么类型？
1F1B pipeline 的 warmup / cool-down 步数公式？
ZeRO-1 optimizer step 完后怎么 sync 到其他 rank？
梯度累积时 DP all-reduce 在哪一步？
QKV / gate+up 为什么 fuse？省了什么？
nanotron checkpoint 跨 mesh resume 为什么不行？

能流畅回答这 7 个问题，你已经理解 90% 的现代预训练框架架构，去读 Megatron / TorchTitan 都轻松很多。

13.4项目时间线

时间	变更
2023-12	HF 开源 nanotron v0.1
2024-02	Llama / GPT 模型
2024-05	FineWeb 训练实战（HF 自家 1.5T token 数据集）
2024-09	SmolLM2 训练用 nanotron
2024-12	FP8 训练实验
2025-Q1	MoE 支持（DeepSeek 风）

13.5对照其他

	nanotron	TorchTitan	Megatron-LM
代码量	~5K	~5K	~50K
分布式抽象	自家	DTensor	自家
性能	★★★	★★★★	★★★★★
易读	★★★★★	★★★★★	★★
跟 HF 生态	★★★★★	★★★	★★★

13.6HF 的训练栈整体观

HF 自家训练栈是三层：

nanotron：预训练；
TRL：对齐（SFT/DPO/GRPO/PPO）；
PEFT：参数高效微调；
+ accelerate：底层分布式启动；
+ datasets / tokenizers / transformers 全套。

三者解耦但能配合，HF 路线图非常清晰。

13.7社区入口

GitHub: https://github.com/huggingface/nanotron（2.7k+ ⭐）
HF Discord / forum
FineWeb / SmolLM 项目代码（用 nanotron 训）
HF 博客的 nanotron 相关 post

13.8真实源码树（v2026）

nanotron/
├── run_train.py:1                ★ CLI 入口：torchrun + --config-file
│
└── src/nanotron/
    ├── trainer.py                 DistributedTrainer
    ├── helpers.py                 ckpt 恢复 / step 计算工具
    ├── distributed.py:1-50        torch.distributed 薄封装
    ├── constants.py / sanity_checks.py
    │
    ├── parallel/                  ★ 3D+ 并行
    │   ├── context.py:12-58       ParallelContext (tp/pp/dp/cp/ep)
    │   ├── parameters.py          NanotronParameter
    │   ├── pipeline_parallel/     PipelineEngine + TensorPointer
    │   ├── tensor_parallel/       TensorParallelLinearColumn / Row
    │   ├── data_parallel/
    │   ├── tied_parameters.py
    │   └── sharded_parameters.py
    │
    ├── models/                    ★ 模型实现（每个一文件）
    │   ├── base.py:1-50            NanotronModel ABC
    │   ├── llama.py (54KB)         LlamaForTraining / LlamaBlock / Attention
    │   ├── qwen.py (48KB)          Qwen2ForTraining（含 MoE）
    │   └── starcoder2.py (72KB)
    │
    ├── optim/
    │   ├── base.py:28              BaseOptimizer ABC
    │   ├── gradient_accumulator.py:18  FP32 主梯度 + allreduce
    │   ├── optimizer_from_gradient_accumulator.py  胶水
    │   ├── zero.py                  ZeRO 实现
    │   ├── clip_grads.py / named_optimizer.py / inherit_from_other_optimizer.py
    │
    ├── config/
    │   ├── config.py:1-100         主 Config（YAML + dacite）
    │   ├── models_config.py        每模型 args
    │   └── parallelism_config.py
    │
    ├── fp8/                       ★ FP8 训练（nanotron 的招牌）
    │   ├── linear.py:24            FP8Linear（继承 nn.Linear）
    │   ├── tensor.py               动态 amax / scaling
    │   ├── parameter.py            FP8Parameter
    │   ├── meta.py                 FP8Meta TypedDict
    │   ├── kernel.py               fp8_matmul_kernel
    │   ├── dtypes.py / constants.py
    │
    ├── nn/                        ★ 自家算子
    │   ├── moe.py:26               Router + grouped GEMM
    │   ├── ring_attention.py       长上下文 ring attn
    │   ├── flex_attention.py       PyTorch 2.4+ FlexAttn
    │   ├── llama3_ring_attention.py
    │   ├── attention.py / layer_norm.py
    │
    ├── data/                      dataloader / clm_process / samplers
    ├── generation/                 推理 / 采样
    └── scaling/parametrization.py SpectralMup

13.9FP8 训练源码地图

文件	关键内容
`fp8/linear.py:24`	`FP8Linear`: 继承 `nn.Linear`，把 weight / grad 包成 FP8Parameter
`fp8/tensor.py`	`update_scaling_factor()`: 按 amax 动态调 scale
`fp8/meta.py`	`FP8LinearMeta`: `{input_grad: FP8E4M3, weight_grad: FP8E4M3, output_grad: FP8E5M2}`
`fp8/kernel.py`	定制 CUDA kernel（用 TransformerEngine 底层）

这是当前所有开源训练框架里 FP8 训练最易读的实现，只有几百行核心代码。

13.10HF 转换脚本对照

脚本	方向
`examples/llama/convert_hf_to_nanotron.py:1-40`	HF → nanotron（含 head interleave / QKV fuse）
`examples/llama/convert_nanotron_to_hf.py`	nanotron → HF（safetensors）
`examples/llama/convert_weights.py`	weight name mapping 表
`examples/mamba/convert_hf_to_nanotron.py`	Mamba 专用
`examples/inference/qwen_moe/convert.py`	Qwen2-MoE 专用

13.11结语

nanotron 是 HuggingFace 给社区的"分布式训练教科书"—— 代码精炼到能在一周内读完，覆盖了 3D 并行 + ZeRO-1 + checkpoint 的所有核心机制。跟着本书走完三天的通读计划，你就完成了大多数人没机会做的事——真正理解了一个工业级预训练框架是怎么搭起来的。

剩下的进阶之路：

读 TorchTitan：看 PyTorch 新抽象（DTensor / FSDP2）；
读 Megatron-Core：看最高性能实现；
读 ColossalAI：看更高层 plugin 设计；
读 NeMo：看多模态 + 端到端栈；
自己改 nanotron，加新模型、新 schedule、新 optimizer。