w wyl123ly 的博客
MD

MOC-数学与工程基础

22 KB 2026.10.22 原文件

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 依赖全部五篇,是本阶段唯一的汇总型笔记。

学习顺序与理由

  1. 矩阵与线性代数速查。先建立形状与谱的语言。理由:d24 的每一个张量形状、Muon 的每一次正交化、FLOPs 的每一个 都建立在这一篇上;跳过它会在后面反复卡在维度上。检验标准是能默写 与「最近正交矩阵是 」。
  2. softmax与softmax温度。把 logits 转成分布,并建立数值稳定的习惯。理由:温度与 top- 是 07 阶段 RL rollout 与 09 阶段推理的直接输入;而「减最大值」是后面交叉熵实现的同一技巧。检验标准是能推出熵对 的导数并解释单调性。
  3. 交叉熵与困惑度。把分布转成标量损失,并学会把 nat 换成 bpb。理由:训练日志、SFT 掩码、评测指标全部围绕这一篇;bpb 与 CORE 的分工也在这里第一次出现。检验标准是能手算一个 batch 的损失并说明 ignore_index 的分母。
  4. 梯度下降与AdamW。把损失转成更新。理由:nanochat 的参数被切成两类,AdamW 是其中一类;三条自动缩放公式(批大小、宽度、权重衰减)是「换 --depth 就能训」的实现基础。检验标准是从 恒定推出 的缩放式。
  5. Muon优化器。另一半更新规则,也是本阶段最难的一篇。理由:49% 的参数走 Muon,且它与 AdamW 在同一个融合优化器里共享调度;不读这一篇,05 阶段的分布式优化器分片无法理解。检验标准是能逐段解释 muon_step_fused 并算出一个形状组的学习率倍数。
  6. 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_dim1536 / 12 / 128GPTConfig,由 --depth=24 自动推导
词表大小32768GPTConfig.vocab_size
矩阵参数量 729,810,648num_matmul_params
缩放参数量729,810,624num_scaling_params 的 transformer_matrices + lm_head
总参数量1,384,122,122num_scaling_params 的 total
FLOPs/token(训练)4,775,225,616estimate_flops
训练 token 数(ratio 8)5,838,471,168ratio × 缩放参数量,批大小取 2 的幂后取整
总 FLOPsFLOPs/token × token 数
Muon 形状组、、、setup_optimizer 按形状分组
AdamW 生效学习率(d24)0.008 / 0.300 / 0.150 / 0.00707 / 0.7071 / 0.200base_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 迹不等式与 [[矩阵与线性代数速查]]
4softmax 的平移不变性与雅可比[[softmax与softmax温度]]
5熵对 的导数化为 [[softmax与softmax温度]]
6CE 与最大似然的等价分解为数据熵加 KL[[交叉熵与困惑度]]
7CE 对 logits 的梯度[[交叉熵与困惑度]]
8nat 到 bpb 的换算[[交叉熵与困惑度]]
9偏差修正的无偏性[[梯度下降与AdamW]]
10谱预算下的最优更新[[Muon优化器]]
11NorMuon 的保范数性质缩放后 [[Muon优化器]]
12 规则前向 、反向 [[FLOPs与训练成本估算]]
13注意力项 前向 、反向 [[FLOPs与训练成本估算]]
14权重衰减的 T_epoch 缩放令 恒定[[FLOPs与训练成本估算]]

术语中英对照

中文英文一句话定义
矩阵乘法matrix multiplication内维相等时的行内积运算
转置transpose行列互换,满足
奇异值分解singular value decomposition
极分解polar decomposition, 正交、 半正定
条件数condition number最大与最小奇异值之比
秩rank线性映射实际使用的维数
范数norm衡量矩阵或向量大小的函数
概率单纯形probability simplex非负且和为 1 的向量集合
温度temperaturesoftmax 前对 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 只激活部分前馈子网络

自检流程

读完本阶段后,建议按三轮自检:

  1. 复述轮:合上笔记,按「形状 → 分布 → 损失 → 更新 → 成本」的顺序在白纸上写一遍五组公式。写不出的符号回到符号表查,不要凭印象补。
  2. 算例轮:把六篇的「例子与代码」全部重跑一遍,逐个核对预期输出。数值对不上时先怀疑自己的环境(numpy 版本、浮点格式),再怀疑笔记;所有引用的输出都是在本机 numpy 2.5.4 上实跑得到的。
  3. 核对轮:打开源码快照,把本篇引用的函数名、默认值、形状逐个核对。凡是与 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 的落地。