w wyl123ly 的博客
MD

MOC-Transformer

25 KB 2026.10.22 原文件

MOC · Transformer 架构

本阶段地图

本阶段回答一个问题:nanochat 的 gpt.py 为什么长这样,而不是一个教科书 Transformer。前五篇拆开组件(自注意力、多头、RoPE、残差与归一化、前馈与激活),第六、七篇把它们组装成 GPTConfig 与一次完整前向,第八篇解释 nanochat 特有的 smear/值嵌入/残差标量/backout/softcap,第九、十篇处理执行后端(FlashAttention 与 FP8)。读完应能脱离注释复述 GPT.forward 的十个阶段,解释每个结构选择的代价,并能判断一次改动会影响参数量、FLOPs、显存还是数值稳定性。

flowchart TD
    A[自注意力机制] --> B[多头注意力]
    B --> C[位置编码与RoPE]
    B --> D[残差连接与LayerNorm]
    D --> E[前馈层与激活函数]
    C --> F[GPT模型类与config]
    E --> F
    F --> G[从第一性看nanochat的gpt.py]
    G --> H[nanochat架构特化技巧]
    B --> I[FlashAttention与高效注意力]
    G --> I
    E --> J[FP8混合精度训练]
    F --> J
    I --> K[09 推理 Engine 与 KV Cache]
    J --> L[05 预训练 speedrun]

图中的箭头表示「读后者前应先读前者」。注意力与多头是共同前提;配置把形状固定下来之后,完整前向才有确定的张量形状;特化、FA3、FP8 都建立在前向基线之上。最下方的两个目标不是本阶段的笔记,而是依赖本阶段的下游:KV Cache 依赖注意力与缓存分支,speedrun 依赖配置、前向与 FP8。

学习顺序与理由

本阶段按「组件 → 组装 → 特化 → 系统」四段推进。前三段是理解模型所需的最小闭环,第四段决定模型能否在真实硬件上跑出可用吞吐。下表给出标准顺序、前置与理由;前置跨阶段的条目已用双链标出。

序笔记直接前置为什么在这个位置
1[[自注意力机制]]02 的 [[softmax与softmax温度]]、[[矩阵与线性代数速查]]整个模型的计算核心;先建立 、缩放、掩码与加权求和的形状直觉
2[[多头注意力]]1把头拆分、并行、合并;解释 与 的关系
3[[位置编码与RoPE]]2注意力本身无位置信息;RoPE 是 nanochat 唯一的位置机制
4[[残差连接与LayerNorm]]1解释 pre-norm、残差流与 RMSNorm;没有它无法理解深层堆叠
5[[前馈层与激活函数]]4MLP 的 4 倍扩张与 ReLU²;c_fc/c_proj 的形状来源
6[[GPT模型类与config]]3、4、5;03 的 [[词表与特殊token]]把组件变成配置、参数量、优化器分组与检查点契约
7[[从第一性看nanochat的gpt.py]]6按真实执行顺序走一遍前向,串起前六篇的全部符号
8[[nanochat架构特化技巧]]7在基线上逐项加入 smear、值嵌入、、backout、softcap,并核算代价
9[[FlashAttention与高效注意力]]2、7注意力的执行后端;解释滑动窗口、FA3/SDPA 与 显存
10[[FP8混合精度训练]]5、7线性层的执行精度;解释缩放、三个 GEMM 与评测回退

第一段(1–5)不要跳读。第 1 篇给出注意力的数学定义,第 2 篇给出多头的形状与参数,第 4 篇给出残差与归一化的训练理由;这三篇是第 7 篇逐段拆解的前提。第 3 篇放在第 2 篇之后,是因为 RoPE 作用在已经拆好的 上;第 5 篇放在第 4 篇之后,是因为 MLP 的 pre-norm 与残差写法与注意力子层相同,先理解一个子层再复制到另一个更省力。

第二段(6–7)是全阶段的核心。第 6 篇先讲「形状与参数从哪来」,第 7 篇再讲「数据怎么流」。这个顺序不能反:如果先读前向,会在 n_head、n_kv_head、value_embeds 的维度上反复卡住;如果只读配置,又无法解释为什么 x0 在 smear 之后保存、为什么缓存只在最后一层推进。两篇合起来,才能把「配置派生形状」与「前向消费形状」闭合。

第三段(8)是 nanochat 与通用 Transformer 的分叉点。它依赖第 7 篇的十步顺序,但不应在第 7 篇之前读:smear 的三条分支、值嵌入的门、resid/x0 的初始化、backout 的缓存位置,都是对前向的增量;没有基线,就分不清「必要结构」与「工程技巧」。

第四段(9–10)是系统层。第 9 篇依赖多头注意力与第 7 篇的注意力调用,解释为什么同样的数学在 FA3 与 SDPA 上速度差一个量级;第 10 篇依赖 MLP 形状与第 7 篇的 Linear,解释 FP8 只替换三个 GEMM 的操作数。把这两篇放在最后,是因为它们不改变模型定义,只改变执行方式;先懂定义,才能判断「换内核」与「改模型」的边界。

若时间有限,可按两条短路径读:

  • 架构最短路径:1 → 2 → 6 → 7 → 8。跳过 RoPE、残差、MLP 的独立篇,直接在第 7 篇遇到它们时回查;适合已有 Transformer 基础的读者。
  • 系统最短路径:2 → 7 → 9 → 10。先理解注意力与完整前向,再看 FA3 与 FP8 如何改变吞吐;适合要跑 speedrun 的读者。

三遍读法

第一遍只读 1、2、6、7,目标是建立「形状链路」:由 --depth 得到 ,由配置得到参数分组,由前向得到每步张量。第一遍不要纠结消融数值,遇到 RoPE、RMSNorm、ReLU² 先接受定义,记下回查位置。

第二遍读 3、4、5、8,目标是建立「设计理由」:RoPE 为什么只依赖相对位置、pre-norm 为什么让深层可训练、MLP 为什么扩张 4 倍、五项特化各自换来了什么。第二遍应开始把 dev/LOG.md 的消融与代码中的默认值对照,区分「结构必要」与「工程选择」。

第三遍读 9、10,并回到 7 做一次闭卷复述:不看代码写出十步前向、标出 FA3 调用与 FP8 替换的位置,再解释 disable_fp8 与 window_size 的语义。第三遍的产出不是笔记,而是一张能用于 05 与 09 的「形状—代价」表:每一步的张量、参数量、FLOPs、显存与失败模式。

建议节奏如下,按每天 2–3 小时计。

时段阅读内容产出
第 1 天1 → 2 → 6能由 depth 算出 与参数分组
第 2 天7 → 3 → 4 → 5闭卷写出十步前向与每步形状
第 3 天8 → 9五项特化的代价表、SSSL 窗口计数
第 4 天10 → 阶段项目FP8 的 per-tensor 示例、d24 形状核对

笔记索引

笔记核心问题难度在全库中的位置
[[自注意力机制]]缩放点积、因果掩码与 softmax 如何定义上下文聚合★★★04 的地基;05 的窗口与 09 的 KV Cache 都回指它
[[多头注意力]]为什么要拆头, 与 如何影响参数量与表达★★★连接 n_head 配置与 FA3 的 GQA 支持
[[位置编码与RoPE]]相对位置如何进入 ,负角度约定是什么★★★解释 cos/sin 缓存、decode 的位置偏移与长上下文
[[残差连接与LayerNorm]]pre-norm、残差流与 RMSNorm 为什么让深层可训练★★☆解释 Block.forward 的两条残差与无参数归一化
[[前馈层与激活函数]]4 倍扩张与 ReLU² 的形状、参数量与动机★★☆解释 c_fc/c_proj、MLP FLOPs 与 FP8 转换条件
[[GPT模型类与config]]depth 如何派生宽度、头数、参数量与优化器分组★★★04 的配置契约;05 的 speedrun 与缩放律从这里取数
[[从第一性看nanochat的gpt.py]]一次前向的十个阶段、每步形状与去掉的后果★★★全库核心篇;05/06/09 的代码对照都引用它
[[nanochat架构特化技巧]]smear、值嵌入、、backout、softcap 的动机与消融★★★解释 nanochat 与通用 Transformer 的差异
[[FlashAttention与高效注意力]]tiling、online softmax、FA3/SDPA 与滑动窗口★★★04 的执行后端;09 的 prefill/decode 与显存前提
[[FP8混合精度训练]]E4M3/E5M2、缩放粒度、三个 GEMM 与评测回退★★★04 的精度后端;05 的 --fp8 与成本估算

逐篇导读

  • 自注意力机制:先看缩放点积的形状,再看因果掩码为什么是上三角为 。读完后应能写出 、、 的形状,并解释除以 的必要性。若这一篇没过,后面的多头与 KV Cache 都会变成背公式。
  • 多头注意力:重点不是「多个头更好」这句话,而是头拆分后每个头的维度、拼接顺序与 的形状。读完后应能由 推出 ,并解释 GQA 下 的维度为什么可以更小。
  • 位置编码与RoPE:把旋转矩阵写成 分块,核对 nanochat 的负角度约定。读完后应能解释为什么 RoPE 只依赖相对位置、为什么 decode 要从 kv_cache.get_pos() 截取 cos/sin,以及 base=100000 与旧文档 10000 的差异。
  • 残差连接与LayerNorm:把 pre-norm 的顺序写清楚:归一化在子层之前,残差相加在子层之后。读完后应能解释零初始化 c_proj 为什么让 Block 初始为恒等映射,以及 RMSNorm 无可学习参数意味着什么。
  • 前馈层与激活函数:核对 c_fc 的 、ReLU² 的逐元素平方、c_proj 的 。读完后应能算出 d24 单个 Block 的 MLP 参数量,并解释为什么 FP8 过滤条件会跳过小层。
  • GPT模型类与config:把 GPTConfig 的七个字段、build_model_meta 的取整公式、num_scaling_params 的五组统计与 setup_optimizer 的六个 AdamW 组放在一张表里。读完后应能解释为什么 d24 的总参数是 13.84 亿而 scaling params 只有 7.30 亿。
  • 从第一性看nanochat的gpt.py:这是全阶段的核心。按十步顺序读,每一步都问三个问题:输入输出形状是什么、参数在哪里、去掉会怎样。读完后应能不看代码画出前向数据流表,并指出 x0 在 smear 之后保存、缓存只在最后一层推进。
  • nanochat架构特化技巧:把五项技巧的动机、公式、参数量、FLOPs 与消融证据列成表。读完后应能判断哪一项证据最强(值嵌入)、哪一项最弱(backout),并解释为什么这些不是通用 Transformer 的必备项。
  • FlashAttention与高效注意力:先理解标准注意力的 显存,再读 tiling 与 online softmax,最后看 FA3/SDPA 的分派。读完后应能解释 window_size=(left,0) 包含当前 token 的语义、SDPA 回退为什么在滑动窗口下仍然慢,以及注释 768 与代码 512 的差异。
  • FP8混合精度训练:把 FP8 限定在 Linear 的三个 GEMM 上,不要把「混合精度」理解成整个模型 8 位。读完后应能写出 per-tensor 的 scale/clamp/反量化、解释前向 E4M3 与反向 E5M2 的分工,并说明 disable_fp8 为什么必须包住每个评测入口。

阶段定位与上下游

本阶段位于「03 分词器」与「05 预训练」之间,但不是一条单行道。上游提供三个输入:02 的 softmax、矩阵乘法与复杂度工具;03 的词表大小 与特殊 token;01 的项目目标(用 --depth 一个旋钮训练 GPT-2 级模型)。下游消费三类输出:05 的训练脚本需要 GPTConfig、参数量、FLOPs 与优化器分组;09 的推理需要前向顺序、KV Cache 分支与 FA3 的 flash_attn_with_kvcache;06/07 的 SFT 与 RL 需要 targets 的 -1 掩码与 logits 形状。

方向笔记本阶段提供给它的东西
上游[[词表与特殊token]]vocab_size、填充到 64 的倍数、lm_head 切片
上游[[softmax与softmax温度]]、[[矩阵与线性代数速查]]注意力与 MLP 的公式、形状与复杂度
下游[[训练脚本与speedrun]]build_model_meta、setup_optimizer、estimate_flops
下游[[KV Cache原理]]KVCache 的形状、prev_embedding、FA3 缓存接口
下游[[缩放定律与模型深度]]num_scaling_params 的口径与 d12/d24 的数字

因此,本阶段不是「读完就可以丢掉」的架构综述:05 的每个超参数都能追溯到这里的某个形状或分组,09 的每个显存数字都能追溯到这里的 n_layer、n_kv_head 与窗口。

符号约定与关键事实

全阶段统一使用以下符号;各篇首次出现时会再定义一次。

符号含义
批大小
序列长度(上下文)
Transformer 层数,对应 n_layer 与 --depth
残差流宽度,对应 n_embd
查询头数,对应 n_head
KV 头数,对应 n_kv_head
单头维度,
词表大小与填充到 64 倍数后的词表大小
滑动窗口左边界;S 层的 为 向上取整到 128
第 层的残差增益与 混合系数
smear 与 backout 的标量系数

d12 与 d24 的关键数字如下。它们在本阶段各篇中反复出现,建议记住 d24 一行。

项目d12d24
n_embd / 7681536
n_head / 612
n_kv_head / 612
单头维度 128128
值嵌入层数612
总参数286,261,7301,384,122,122
transformer_matrices + lm_head110,100,912729,810,624
滑动窗口(SSSL)9 层 512、3 层 204818 层 512、6 层 2048

结构事实清单:

  • 归一化:F.rms_norm,无可学习参数;每个子层前做一次 pre-norm。
  • 位置:RoPE,当前代码基频 base=100000,按 约定旋转;cos/sin 缓存长度为 sequence_len * 10。
  • 注意力:QK norm 后 各乘 1.2;默认 n_kv_head=n_head,代码支持 GQA。
  • MLP:c_fc 扩张 4 倍,ReLU²,c_proj 回到 ;全部 Linear 无 bias。
  • 词表:填充到 64 的倍数,lm_head 输出切片回 ;wte 与 lm_head 不共享。
  • 特化:smear 读前 24 个通道;值嵌入隔层且最后一层必有,门为 ;resid 初始化 1.15→1.05,x0 0.20→0.05;backout 在 缓存、减 0.2 倍;softcap 15。
  • 窗口:SSSL 按层平铺,最后一层强制全上下文;当前代码对 算出短窗口 512。

版本与注释差异

1. RoPE 基频:当前 gpt.py 的 _precompute_rotary_embeddings 默认 base=100000;若在旧笔记或提示中看到 10000,以当前快照为准。

2. 短窗口:_compute_window_sizes 的表达式对 求值为 512,行内注释却写「2048 -> 768」;以可执行表达式为准,必要时用本篇的脚本复核。

3. softcap:当前 forward 硬编码 15;dev/LOG.md 的 2026-03-02 条目记录 d24 上 20 最优(val loss 0.716→0.715)并称设为默认,但快照代码仍是 15。两者不一致,实验记录应分别标注「LOG 结论」与「当前代码」。

4. 历史数字:LOG 中 d8–d20 的 bpb、d26 的 FP8 吞吐、旧版 FineWeb 数据都对应不同快照,不能与当前 ClimbMix/d24 的绝对值直接比较;本阶段只在解释机制时引用其相对结论。

术语表

术语本阶段中的含义
meta device只保存形状与 dtype、不分配存储的 PyTorch 设备;GPT.__init__ 在其中运行
残差流贯穿所有 Block 的 维向量序列,子层读取其归一化版本并加回输出
pre-norm先归一化再进子层,残差相加在子层输出之后;nanochat 的 Block 采用此结构
RMSNorm按均方根归一化、无仿射参数;norm(x) = F.rms_norm(x, (C,))
RoPE旋转位置编码;nanochat 按 约定旋转 ,基频 100000
GQA分组查询注意力; 时多个查询头共享一组 KV 头;默认配置不缩减
sliding window每个查询只向前看 个 token;SSSL 中 S 为 上取整到 128
logit softcap用 压缩 logits;当前 ,在 fp32 中执行
值嵌入按 token id 查出的额外值向量,门控后加到 ;隔层且最后一层必有
FP88 位浮点;E4M3 用于前向输入/权重,E5M2 用于反向梯度
per-tensor 量化整个张量共用一个缩放因子;nanochat 的 _to_fp8 采用此粒度

阶段项目:核对 d24 的形状

在进入 05 之前,用一段不依赖仓库的脚本核对本阶段反复使用的三个数字:宽度、头数、值嵌入层数。它不训练模型,只验证「depth → 配置」的推导。

import math

# 只验证 depth → 宽度/头数/值嵌入层数,不训练模型
def facts(depth):
    C = math.ceil(depth * 64 / 128) * 128
    H = C // 128
    ve = sum(1 for i in range(depth) if i % 2 == (depth - 1) % 2)
    return C, H, ve

for d in (12, 24):
    C, H, ve = facts(d)
    print(f"d{d}: n_embd={C}, n_head={H}, n_kv_head={H}, ve_layers={ve}")

预期输出:

d12: n_embd=768, n_head=6, n_kv_head=6, ve_layers=6
d24: n_embd=1536, n_head=12, n_kv_head=12, ve_layers=12

若输出不是这两行,先检查 aspect_ratio 与 head_dim 是否仍为默认的 64 与 128;若把 head_dim 改成 64, 会翻倍,n_embd 不变,单头维度变小,注意力的参数量与 KV Cache 都会改变。这个脚本只覆盖形状;参数量、num_scaling_params 与优化器分组的完整核对在 GPT模型类与config 的可运行脚本中给出。

常见停滞点

  • 把头数当成固定值。n_head 由 推出;改变 --depth 会同时改变宽度与头数,不能只改一个。
  • 把 RoPE 当成绝对位置编码。RoPE 只进入 的内积,不改变 embedding;decode 时要用缓存的绝对位置截取 cos/sin。
  • 把 window_pattern 的行内注释当成事实。当前代码对 算出 512;注释写 768 是过期信息。
  • 把总参数量当成 scaling params。值嵌入让 d24 的总参数达到 13.84 亿,但缩放律只用 7.30 亿的矩阵 + lm_head。
  • 把 FP8 当成推理量化。FP8 只替换训练时 Linear 的三个 GEMM;评测必须用 disable_fp8 回 bf16。
  • 用 GPT.generate 评估吞吐。它没有 KV Cache,生成 个 token 的复杂度约为 ;生产路径是 Engine.generate_batch。

与《AI学习总纲》的分工

同 vault 的《AI学习总纲》05-Transformer与LLM原理 负责通用原理与教学推导;本阶段只负责把这些原理落到 nanochat 的具体实现、默认值与工程取舍。两边的边界如下。

主题总纲负责本阶段负责
注意力数学[[注意力机制与QKV]] 的 推导、缩放点积与 softmaxCausalSelfAttention.forward 的投影形状、QK norm、1.2 缩放、FA3 调用
多头与 GQA[[因果注意力与多头注意力]]、[[分组查询注意力GQA]] 的头拆分与广播n_head/n_kv_head 配置、ve_gate 的 KV 头维度、默认不缩减 KV
位置编码[[位置编码-正弦与RoPE]] 的正弦编码、RoPE 旋转与相对性base=100000、负角度约定、cos/sin 缓存与 decode 偏移
完整架构[[Transformer架构详解]]、[[GPT系列架构]] 的编码器/解码器与 GPT 演化GPTConfig 字段、build_model_meta、参数分组、gpt.py 十步前向
训练与推理[[从零实现小型GPT指南]] 的从零实现、[[KV缓存]] 的通用缓存推导nanochat 的 meta device 初始化、FA3/SDPA、smear 的缓存分支、FP8
系统优化[[模型推理优化]] 的通用量化/融合/批处理Float8Linear 的动态 per-tensor 缩放、--fp8 过滤条件与 disable_fp8

阅读建议:先读总纲的 Transformer架构详解 建立组件定义,再读本阶段的 从第一性看nanochat的gpt.py 看这些组件在仓库中的实际顺序;遇到 GQA、RoPE、KV Cache 的通用推导时回总纲,遇到默认值、初始化、窗口模式与优化器分组时查本库。不要把总纲的教科书结构与 nanochat 的特化混为一谈:前者解释「为什么这样设计」,后者解释「这个仓库为什么这样实现」。

两边冲突时的处理顺序是:当前 repo 的可执行代码优先于行内注释,行内注释优先于旧版文档;dev/LOG.md 的相对结论(谁更好、差多少)可引用,绝对 bpb/吞吐必须标注数据版本与模型深度。总纲若与本库的实现细节不同,以本库快照为准,并在对应笔记中写明差异,而不是静默覆盖。

阶段产出

读完本阶段,书面上应留下四张表,而不是只有划线:

  • 配置表:--depth → 、总参数、scaling params、值嵌入层数。
  • 数据流表:十个阶段的输入/输出形状、参数位置、去掉后的后果。
  • 特化代价表:smear、值嵌入、resid/x0、backout、softcap 的参数量、FLOPs、消融证据与风险。
  • 执行表:FA3/SDPA 的适用条件、窗口计数、FP8 的转换层数与回退路径。

这四张表是 05 训练脚本、06 SFT、07 RL 与 09 推理的共同索引。后续阶段遇到「为什么 d24 的 batch 是 16」「为什么 SFT 的 logits 要切片」「为什么 KV Cache 是 147,456 字节/token」时,都应能回到这里的某一行。

四张表不必一次写对。每读完一篇补一行,第四天用阶段复盘检查缺口;若某一行只能抄课文、不能用自己的话解释,就说明该篇还没有真正读完。

表的作用是暴露缺口,而不是收集正确句子;发现缺口时沿双链回到对应笔记的「原理与推导」。

阶段复盘:五个必须能回答的问题

  1. 形状:--depth=24 如何得到 1536 宽度、12 个查询头、12 个 KV 头?d24 的总参数与 scaling params 分别是多少,差额来自哪里?
  2. 数据流:GPT.forward 的十个阶段分别做什么?为什么 在 smear 之后保存,为什么缓存只在最后一层推进,为什么 logits 要先切片再转 fp32?
  3. 结构:RMSNorm 为什么没有可学习参数?RoPE 的负角度约定为什么不影响结果?QK norm 与 1.2 缩放各解决什么问题?ReLU²、无 bias、不共享权重各自换来了什么?
  4. 系统:FA3 的 window_size=(left,0) 与 SDPA 的显式掩码如何对应?FP8 的三个 GEMM 分别量化哪些操作数?为什么评测必须 disable_fp8?
  5. 证据:五项架构特化中哪一项的消融证据最强,哪一项最弱?当前快照与 LOG/注释的三处差异是什么,分别以什么为准?

能回答这五个问题,再进入 05。若第 1、2 题有卡顿,回到 GPT模型类与config 与 从第一性看nanochat的gpt.py;若第 4 题有卡顿,回到 FlashAttention与高效注意力 与 FP8混合精度训练。第 5 题没有标准答案,但必须能区分「代码事实」「LOG 结论」与「注释说法」。

达标清单

  • [ ] 能画出本阶段的依赖图,并说明为什么第 6 篇在第 7 篇之前、第 8 篇在第 7 篇之后。
  • [ ] 能由 --depth=24 推出 1536 宽度、12 个查询头、12 个 KV 头,并计算总参数与 scaling params。
  • [ ] 能不看笔记复述 GPT.forward 的十个阶段,标出每步形状与至少三个「去掉会怎样」。
  • [ ] 能解释 RMSNorm、RoPE、QK norm、ReLU²、无 bias、不共享权重各自解决什么问题。
  • [ ] 能写出 SSSL 在 d24 上的窗口计数,并说明 FA3 的 (left,0) 与 SDPA 显式掩码的对应关系。
  • [ ] 能解释 FP8 的 E4M3/E5M2 取舍、per-tensor 缩放、三个 GEMM 的量化位置与 disable_fp8 的必要性。
  • [ ] 能列出五项架构特化的参数/FLOPs 代价,并指出哪一项的消融证据最弱。
  • [ ] 能指出当前快照与 LOG/注释的三处差异(基频、短窗口、softcap),并说明以什么为准。

参考来源

  • Karpathy, nanochat(commit 92d63d4),README.md、nanochat/gpt.py、nanochat/flash_attention.py、nanochat/fp8.py —— 对应本阶段全部事实与默认值。
  • Karpathy, nanochat,dev/LOG.md —— 对应滑动窗口、per-layer scalars、值嵌入、softcap 与 FP8 的实验记录。
  • Vaswani et al., Attention Is All You Need, arXiv:1706.03762 —— 本阶段前五篇的共同数学基础。
  • Dao et al., FlashAttention: Fast and Memory-Efficient Exact Attention with IO-Awareness, arXiv:2205.14135;Shah et al., FlashAttention-3, arXiv:2407.08608 —— 对应第 9 篇。
  • Micikevicius et al., FP8 Formats for Deep Learning, arXiv:2209.05433 —— 对应第 10 篇。