MOC · 数学与工程基础
本阶段地图
02 是全书唯一不产生模型产物的阶段,产出是两样东西:一套可以在纸上复核的公式,一份可以按美元结算的成本估算。六篇笔记按「表示 → 概率 → 损失 → 更新规则 → 成本」推进:矩阵给出形状与谱,softmax 把 logits 变成分布,交叉熵把分布变成损失,AdamW 与 Muon 把损失变成参数更新,FLOPs 把更新次数变成小时与美元。读完之后应当能独立回答三个问题:d24 的每个矩阵是什么形状、Muon 的更新为什么被正交化、8×H100 跑一次 speedrun 为什么是约 2 小时而不是 20 小时。
flowchart LR
A["矩阵与线性代数速查"] --> B["softmax与softmax温度"]
A --> D["梯度下降与AdamW"]
B --> C["交叉熵与困惑度"]
C --> D
D --> E["Muon优化器"]
A --> E
C --> F["FLOPs与训练成本估算"]
D --> F
E --> F
E -.-> P["05 预训练"]
F -.-> P
依赖关系的说明:矩阵与线性代数速查是全部五篇的前置,因为形状规则与 SVD 在每一篇里都会再次出现;softmax 与交叉熵是紧邻的一对,后者是前者的对数形式;AdamW 同时依赖交叉熵(梯度的来源)与矩阵(参数分组);Muon 依赖 AdamW(共享参数分组、调度器与融合核约定)与矩阵(极分解);FLOPs 依赖全部五篇,是本阶段唯一的汇总型笔记。
学习顺序与理由
- 矩阵与线性代数速查。先建立形状与谱的语言。理由:d24 的每一个张量形状、Muon 的每一次正交化、FLOPs 的每一个 都建立在这一篇上;跳过它会在后面反复卡在维度上。检验标准是能默写 与「最近正交矩阵是 」。
- softmax与softmax温度。把 logits 转成分布,并建立数值稳定的习惯。理由:温度与 top- 是 07 阶段 RL rollout 与 09 阶段推理的直接输入;而「减最大值」是后面交叉熵实现的同一技巧。检验标准是能推出熵对 的导数并解释单调性。
- 交叉熵与困惑度。把分布转成标量损失,并学会把 nat 换成 bpb。理由:训练日志、SFT 掩码、评测指标全部围绕这一篇;bpb 与 CORE 的分工也在这里第一次出现。检验标准是能手算一个 batch 的损失并说明
ignore_index的分母。 - 梯度下降与AdamW。把损失转成更新。理由:nanochat 的参数被切成两类,AdamW 是其中一类;三条自动缩放公式(批大小、宽度、权重衰减)是「换
--depth就能训」的实现基础。检验标准是从 恒定推出 的缩放式。 - Muon优化器。另一半更新规则,也是本阶段最难的一篇。理由:49% 的参数走 Muon,且它与 AdamW 在同一个融合优化器里共享调度;不读这一篇,05 阶段的分布式优化器分片无法理解。检验标准是能逐段解释
muon_step_fused并算出一个形状组的学习率倍数。 - FLOPs与训练成本估算。把更新次数换算成时间与钱。理由:它是前五篇的汇总练习,先用矩阵形状算 ,再用交叉熵与优化器确定 token 预算,最后用 MFU 换算成本。检验标准是给出 d24 的 FLOPs/token 并解释 48 美元档对应的 MFU。
顺序上的两个可选项:若已熟悉 Adam,可与第 4 篇并行读第 5 篇,但必须先读完第 1 篇第 5 节(极分解);若目标只是跑通 speedrun,可先读第 6 篇的第 6、7 节,再回头补第 5 篇,但这样无法解释 Muon 的学习率倍数。
每篇的读法
- 矩阵与线性代数速查:先看第 1、2 节,合上笔记把 d24 的九个张量形状写一遍;再看第 5 节,把「最近正交矩阵」的证明补全;最后对照第 7 节的形状表,确认哪些形状落进 Muon 的四个分组。不要在这一篇上花时间做数值线性代数的练习,SVD 的算法细节属于跨库内容。
- softmax与softmax温度:动手跑例 1 的溢出演示,把
shift=False打开观察nan;再跑例 2 的熵表,确认单调性。然后打开nanochat/engine.py的sample_next_token与nanochat/gpt.py的generate,把两处的 top- 与温度顺序写在纸上对比。这一篇的重点是「顺序」与「定义域」,不是推导技巧。 - 交叉熵与困惑度:先用 np 手算一个三分类的 CE,再手算一个含
-1的 batch;然后把evaluate_bpb的八条注释逐条对应到代码行。最后用验证集的实际数字做一次 nat→bpb 的换算,确认分母是字节而不是 token。 - 梯度下降与AdamW:把
adamw_step_fused的十三行代码与更新式一一对应,标出哪一行是衰减、哪一行是偏差修正。然后用base_train.py的打印值核对三条缩放公式(d12 应全为 1)。这一篇最容易「看懂但写错」,务必手写一遍更新式。 - Muon优化器:先读第 1 节的两个范数预算对比,理解「谱预算」与「Frobenius 预算」的差别;再读第 3 节的迭代式,对照系数表跑例 1;最后按第 7 节的分组表核对哪些参数进 Muon。分布式部分可以在读完 05 阶段后再回看。
- FLOPs与训练成本估算:先手算 ,再加注意力项,再用计算器核对;然后把 MFU 从 35% 调到 50%,观察小时数如何从 2.80 变到 1.96。最后用 README 的 48 美元反推 MFU,理解「同一个数字可以由不同假设得到」。
笔记索引
| 笔记 | 核心问题 | 必须记住的公式或事实 | 难度 | 前置 |
|---|---|---|---|---|
| [[矩阵与线性代数速查]] | 形状、范数与谱如何决定参数量与计算量 | ;;d24 的四个 Muon 形状组 | ★★☆ | [[线性代数]](跨库) |
| [[softmax与softmax温度]] | 温度如何改变分布与熵,数值上如何不溢出 | ;;减最大值 | ★★☆ | 矩阵与线性代数速查 |
| [[交叉熵与困惑度]] | 损失、困惑度与 bpb 之间如何换算 | ;; | ★★☆ | softmax与softmax温度 |
| [[梯度下降与AdamW]] | 更新式怎么写,三条自动缩放从哪来 | ; | ★★★ | 交叉熵与困惑度 |
| [[Muon优化器]] | 为什么正交化,五个组件各自修什么 | ;Polar Express 五组系数;保范数缩放 | ★★★ | 梯度下降与AdamW |
| [[FLOPs与训练成本估算]] | 一次训练花多少 FLOPs、多少小时、多少美元 | ; | ★★★ | 全部五篇 |
符号约定与关键事实
符号表
全阶段统一的符号,跨篇不改变含义:
| 符号 | 含义 | 出现位置 |
|---|---|---|
PyTorch Linear 的权重,前向为 | 矩阵、Muon、FLOPs | |
| 一个 batch 的激活 | 矩阵、FLOPs | |
| 梯度矩阵或更新矩阵 | Muon | |
| logits 向量, | softmax、交叉熵 | |
| softmax 输出的概率 | softmax、交叉熵 | |
| 、 | 单 token 损失、平均损失(nat) | 交叉熵 |
| 、 | 学习率、权重衰减系数 | AdamW、Muon |
| 、、 | 矩衰减率、数值稳定项 | AdamW、Muon(NorMuon) |
| 动量系数(Muon) | Muon | |
| 矩阵参数量(不是总参数量) | FLOPs | |
| 、、、 | 头数、头维、层数、序列长度 | 矩阵、FLOPs |
| 、 | 全局批大小(token)、训练总 token 数 | AdamW、FLOPs |
| 、 | 词表大小、rank(矩阵的秩或 param:data 比例,按上下文区分) | 交叉熵、FLOPs |
d24 关键事实
| 项目 | 数值 | 来源 |
|---|---|---|
n_embd / n_head / head_dim | 1536 / 12 / 128 | GPTConfig,由 --depth=24 自动推导 |
| 词表大小 | 32768 | GPTConfig.vocab_size |
| 矩阵参数量 | 729,810,648 | num_matmul_params |
| 缩放参数量 | 729,810,624 | num_scaling_params 的 transformer_matrices + lm_head |
| 总参数量 | 1,384,122,122 | num_scaling_params 的 total |
| FLOPs/token(训练) | 4,775,225,616 | estimate_flops |
| 训练 token 数(ratio 8) | 5,838,471,168 | ratio × 缩放参数量,批大小取 2 的幂后取整 |
| 总 FLOPs | FLOPs/token × token 数 | |
| Muon 形状组 | 、、、 | setup_optimizer 按形状分组 |
| AdamW 生效学习率(d24) | 0.008 / 0.300 / 0.150 / 0.00707 / 0.7071 / 0.200 | base_train.py 默认值 × 批大小与宽度因子 |
三条自动缩放公式
base_train.py 在 --depth 变化时自动推出后两式,宽度因子在 setup_optimizer 内:
、(d12)是调参基准; 是 d12 在相同 param:data 比例下的 token 数。d24 时 、,两者相乘为 1,于是嵌入与解嵌出的学习率回到 d12 的数值。
两个单位换算
第一条用于把训练损失换成压缩率,第二条用于把压缩率换成与词表无关的指标。两者都不含模型假设,是纯单位换算。
一条纪律
只指矩阵参数量。本库中凡出现「参数量」而未加限定,指 num_scaling_params 的分组值;凡提到 , 一律是矩阵参数量。混用会让 FLOPs 估算偏大约 90%。
与相邻阶段的接口
| 方向 | 内容 | 承接笔记 |
|---|---|---|
| 从 01 继承 | 「nanochat 与 nanoGPT 的边界」决定本阶段只讲训练侧数学,不讲推理调度 | [[MOC-背景与定位]](后续阶段) |
| 向 03 输出 | 词表大小决定 ,进而决定 softmax 与交叉熵的成本;token_bytes 是 bpb 的分母 | 分词器阶段 |
| 向 04 输出 | 形状规则用于阅读 gpt.py;SVD 与谱用于理解 attention 的低秩结构与 Muon 的适用面 | Transformer 阶段 |
| 向 05 输出 | 参数分组、三条缩放公式、 与 MFU、Muon 的分布式分片 | 预训练阶段 |
| 向 06 输出 | ignore_index=-1、SFT 掩码、损失平均的分母 | 中段训练与 SFT 阶段 |
| 向 07 输出 | 温度、top-、熵与采样分布 | 强化学习阶段 |
| 向 09 输出 | 的前向口径、KV Cache 的字节数、roofline 的分子分母 | 推理 Engine 阶段 |
向 05 输出的最后落点是 runs/speedrun.sh 里的一条命令。本篇的成本估算可以直接与它对账:
torchrun --standalone --nproc_per_node=8 -m scripts.base_train -- \
--depth=24 --target-param-data-ratio=8 --device-batch-size=16 --fp8
--depth=24 决定 与 token 数,--device-batch-size=16 与 8 卡共同决定每步 token 数,--fp8 决定实际墙钟时间。改任何一项,FLOPs 与美元都要按 FLOPs与训练成本估算 的公式重算。
常见卡点与处理
| 现象 | 可能原因 | 处理 |
|---|---|---|
| 算出的 FLOPs 比日志大约 90% | 把 wte、value_embeds 当成矩阵参数 | 用 num_matmul_params 的口径重算, |
| 自己实现的 CE 比 PyTorch 小 | 平均值把 ignore_index 的 0 计入了分母 | 用 losses.sum()/valid_count,或直接用 reduction='mean' |
| bpb 与别人差 1.44 倍 | 把 nat 当 bit,漏了除以 | 检查分母是否有 |
| 低温采样仍然很平 | 忘了 softcap 把 logits 压到 | 区分「原始 logits 的温度」与「softcap 后 logits 的温度」 |
手写 softmax 得到 nan | 未减最大值,fp32/fp16 溢出 | 先减行最大值,或直接用 F.softmax |
| Muon 的更新范数不等于 | 漏了 Muon+,或对宽矩阵误用了 检验 | 用 与 核对 |
| Muon 学习率比预期大一倍 | 漏算 max(1, m/n) 倍数,或对宽矩阵也乘了它 | 只有高矩阵()的倍数大于 1 |
| 训练 2 小时但算出 20 小时 | 忘了乘卡数,或把 MFU 当成 5% | 小时数 |
| MFU 与论文差两倍 | 峰值口径不同(稀疏 vs 稠密) | 核对 get_peak_flops 的取值口径 |
换 --depth 后 bpb 不可比 | 分词器或验证集被同时改动 | 先确认 token_bytes 与验证集一致,再比较 bpb |
| 手算的 Muon 更新范数偏大 | 忘了 Muon+ 的 重整,或漏了 安全因子 | 用 逐步打印,与例 1 的 1.414214 对齐 |
本阶段的推导清单
下表是可以独立复核的推导,按笔记顺序排列。每条都应当能在不看笔记的情况下重做一遍,并在遇到符号不确定时回到对应小节。
| 序 | 推导 | 关键一步 | 所在笔记 |
|---|---|---|---|
| 1 | 矩阵乘法的两种视角 | 按列拆开写成线性组合 | [[矩阵与线性代数速查]] |
| 2 | 转置恒等式与高/宽分支等价 | [[矩阵与线性代数速查]] | |
| 3 | 最近正交矩阵引理 | von Neumann 迹不等式与 | [[矩阵与线性代数速查]] |
| 4 | softmax 的平移不变性与雅可比 | [[softmax与softmax温度]] | |
| 5 | 熵对 的导数 | 化为 | [[softmax与softmax温度]] |
| 6 | CE 与最大似然的等价 | 分解为数据熵加 KL | [[交叉熵与困惑度]] |
| 7 | CE 对 logits 的梯度 | [[交叉熵与困惑度]] | |
| 8 | nat 到 bpb 的换算 | [[交叉熵与困惑度]] | |
| 9 | 偏差修正的无偏性 | [[梯度下降与AdamW]] | |
| 10 | 谱预算下的最优更新 | [[Muon优化器]] | |
| 11 | NorMuon 的保范数性质 | 缩放后 | [[Muon优化器]] |
| 12 | 规则 | 前向 、反向 | [[FLOPs与训练成本估算]] |
| 13 | 注意力项 | 前向 、反向 | [[FLOPs与训练成本估算]] |
| 14 | 权重衰减的 T_epoch 缩放 | 令 恒定 | [[FLOPs与训练成本估算]] |
术语中英对照
| 中文 | 英文 | 一句话定义 |
|---|---|---|
| 矩阵乘法 | matrix multiplication | 内维相等时的行内积运算 |
| 转置 | transpose | 行列互换,满足 |
| 奇异值分解 | singular value decomposition | |
| 极分解 | polar decomposition | , 正交、 半正定 |
| 条件数 | condition number | 最大与最小奇异值之比 |
| 秩 | rank | 线性映射实际使用的维数 |
| 范数 | norm | 衡量矩阵或向量大小的函数 |
| 概率单纯形 | probability simplex | 非负且和为 1 的向量集合 |
| 温度 | temperature | softmax 前对 logits 的除法系数 |
| 熵 | entropy | ,分布的分散程度 |
| 交叉熵 | cross-entropy | 用模型分布编码真实标签的平均代价 |
| 困惑度 | perplexity | 平均损失的指数,等效候选数 |
| 每字节比特数 | bits per byte, bpb | 总 nat 除以 与总字节数 |
| 学习率 | learning rate | 每步位移的比例或绝对值 |
| 动量 | momentum | 梯度的指数滑动平均 |
| 偏差修正 | bias correction | 用 校正零初始化带来的偏差 |
| 权重衰减 | weight decay | 每步按比例收缩参数的正则项 |
| 解耦衰减 | decoupled weight decay | 不进入梯度、直接施加在参数上的衰减 |
| 正交化 | orthogonalization | 把更新换成最近的半正交矩阵 |
| 动量法 | momentum method | 用历史梯度平滑当前更新 |
| 融合核 | fused kernel | 把多步元素级运算编进一个计算图 |
| 模型浮点利用率 | model FLOPs utilization | 实测算力与峰值算力之比 |
| 专家混合 | mixture of experts | 每 token 只激活部分前馈子网络 |
自检流程
读完本阶段后,建议按三轮自检:
- 复述轮:合上笔记,按「形状 → 分布 → 损失 → 更新 → 成本」的顺序在白纸上写一遍五组公式。写不出的符号回到符号表查,不要凭印象补。
- 算例轮:把六篇的「例子与代码」全部重跑一遍,逐个核对预期输出。数值对不上时先怀疑自己的环境(numpy 版本、浮点格式),再怀疑笔记;所有引用的输出都是在本机 numpy 2.5.4 上实跑得到的。
- 核对轮:打开源码快照,把本篇引用的函数名、默认值、形状逐个核对。凡是与
dev/LOG.md冲突的地方,以nanochat/gpt.py、nanochat/optim.py与scripts/base_train.py为准,冲突点在各篇的「版本说明」中有记录。
三轮都通过之后,再进入 03 阶段。若某一轮卡住超过半小时,先记录到实验日志,然后跳到下一篇,回头再补——本阶段的六篇不是严格的线性依赖,只有第 1 篇是全部前置。
阶段产出物
本阶段不产出模型,产出的是一张可以带走的纸。建议按下列六项落地,每项都能独立核对;全部写完之后,这一阶段才算真正完成。
| 产出物 | 内容 | 核对方式 | 来源笔记 |
|---|---|---|---|
| 形状表 | d24 的九个张量形状、参数量、每 token 前向 FLOPs | 与 num_scaling_params 的分组值对照 | [[矩阵与线性代数速查]] |
| 熵表 | 五个温度下的 、(nat/bit) | 重跑例 2,检查单调性与 上界 | [[softmax与softmax温度]] |
| 损失手算 | 一个含 -1 的 batch 的平均损失与 bpb | 与 PyTorch 的 ignore_index 行为对照 | [[交叉熵与困惑度]] |
| 超参数表 | d12/d20/d24 的批大小、两个缩放因子、三条生效学习率 | 与 base_train.py 的打印值对照 | [[梯度下降与AdamW]] |
| Muon 手算 | 一个 更新的五轮 、Muon+ 范数、掩码 | 重跑例 1、例 2,逐行核对 | [[Muon优化器]] |
| 成本表 | 三档预算下的小时数与美元 | 重跑计算器,与日志的 MFU 对照 | [[FLOPs与训练成本估算]] |
六项产出物的共同要求是可复核:每个数字都要能追到一行代码、一次计算或一条公式。数字对不上时,优先检查三种情况:口径(矩阵参数与总参数、nat 与 bit、bf16 与 FP8 峰值)、单位(token 与字节、秒与小时)、以及版本(dev/LOG.md 与当前代码的差异)。
达标清单
- [ ] 能画出 d24 的
c_q、c_fc、mlp.c_proj、lm_head的形状,并说出哪些进 Muon、哪些进 AdamW。 - [ ] 能证明「列正交矩阵中离 最近的是 」,并说明它在 Muon 里对应哪一步。
- [ ] 能写出 softmax 的数值稳定实现,并解释 fp32、fp16、bf16 三种格式的溢出阈值差异。
- [ ] 能推出熵对 的导数,并据此判断温度升高时熵的变化方向。
- [ ] 能手算一个含
ignore_index=-1的 batch 的平均损失,并说明分母是什么。 - [ ] 能把一段验证集的总 nat 与总字节换成 bpb,并说明为什么不能按 token 数归一。
- [ ] 能写出 AdamW 的更新式,说明偏差修正与解耦衰减各自解决什么问题。
- [ ] 能从 与 推出 的缩放式。
- [ ] 能逐段复述
muon_step_fused的七个阶段,并解释 MuonEq 与 Muon+ 各修正什么。 - [ ] 能说明 cautious weight decay 的掩码为什么依赖参数符号而不只是梯度符号。
- [ ] 能算出一个形状组的 Muon 有效学习率,并解释 倍数的方向。
- [ ] 能由 算出 d24 的 FLOPs/token,再算出 8×H100 在给定 MFU 下的小时数与美元。
- [ ] 能解释 48 美元、100 美元、1000 美元三个档位分别对应什么 token 预算与模型规模。
- [ ] 能指出
get_peak_flops的 989 TFLOPs 是 bf16 稠密峰值(稀疏为 1979 TFLOPs),并说明峰值口径对 MFU 解释的影响。
参考来源
- Karpathy, nanochat(commit 92d63d4):
nanochat/gpt.py、nanochat/optim.py、nanochat/loss_eval.py、nanochat/common.py、scripts/base_train.py、dev/LOG.md、dev/LEADERBOARD.md、README —— 本阶段全部事实基准。 - Kingma & Ba, Adam(1412.6980);Loshchilov & Hutter, Decoupled Weight Decay Regularization(1711.05101)—— 对应 AdamW 篇。
- Jordan et al., Muon(2502.16982);Amsel et al., The Polar Express(2505.16932);arXiv 2510.05491(NorMuon);arXiv 2411.16085(Cautious Weight Decay)—— 对应 Muon 篇。
- Chowdhery et al., PaLM(2204.02311);Hoffmann et al., Chinchilla(2203.15556);Kaplan et al., Scaling Laws(2001.08361);Hägele et al., Power Lines(2505.13738)—— 对应 FLOPs 与成本篇。
- Goodfellow, Bengio, Courville, Deep Learning(2016);d2l.ai;PyTorch 文档 —— 线性代数、数值稳定性与交叉熵的基础定义。
- 《AI学习总纲》对应笔记:线性代数、矩阵分解-SVD与特征分解、概率与统计、微积分与梯度、损失函数、优化算法-梯度下降与Adam、优化器与学习率、自回归生成与采样、模型推理优化、分布式训练与部署 —— 本阶段不重复其推导,只写 nanochat 的落地。