---
tags: [nanochat, MOC, transformer]
阶段: 04-Transformer架构
难度: ★★★
created: 2026-10-22
related: "[[00-MOC]], [[自注意力机制]], [[从第一性看nanochat的gpt.py]]"
---

# MOC · Transformer 架构

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

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

第一段（1–5）不要跳读。第 1 篇给出注意力的数学定义，第 2 篇给出多头的形状与参数，第 4 篇给出残差与归一化的训练理由；这三篇是第 7 篇逐段拆解的前提。第 3 篇放在第 2 篇之后，是因为 RoPE 作用在已经拆好的 $\mathbf{q},\mathbf{k}$ 上；第 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` 得到 $C,H,H_{kv}$，由配置得到参数分组，由前向得到每步张量。第一遍不要纠结消融数值，遇到 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 算出 $C,H,H_{kv}$ 与参数分组 |
| 第 2 天 | 7 → 3 → 4 → 5 | 闭卷写出十步前向与每步形状 |
| 第 3 天 | 8 → 9 | 五项特化的代价表、`SSSL` 窗口计数 |
| 第 4 天 | 10 → 阶段项目 | FP8 的 per-tensor 示例、d24 形状核对 |

## 笔记索引

| 笔记 | 核心问题 | 难度 | 在全库中的位置 |
|---|---|---|---|
| [[自注意力机制]] | 缩放点积、因果掩码与 softmax 如何定义上下文聚合 | ★★★ | 04 的地基；05 的窗口与 09 的 KV Cache 都回指它 |
| [[多头注意力]] | 为什么要拆头，$H$ 与 $D$ 如何影响参数量与表达 | ★★★ | 连接 `n_head` 配置与 FA3 的 GQA 支持 |
| [[位置编码与RoPE]] | 相对位置如何进入 $\mathbf{q},\mathbf{k}$，负角度约定是什么 | ★★★ | 解释 `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、值嵌入、$x_0$、backout、softcap 的动机与消融 | ★★★ | 解释 nanochat 与通用 Transformer 的差异 |
| [[FlashAttention与高效注意力]] | tiling、online softmax、FA3/SDPA 与滑动窗口 | ★★★ | 04 的执行后端；09 的 prefill/decode 与显存前提 |
| [[FP8混合精度训练]] | E4M3/E5M2、缩放粒度、三个 GEMM 与评测回退 | ★★★ | 04 的精度后端；05 的 `--fp8` 与成本估算 |

## 逐篇导读

- [[自注意力机制]]：先看缩放点积的形状，再看因果掩码为什么是上三角为 $-\infty$。读完后应能写出 $\mathbf{S}$、$\mathbf{P}$、$\mathbf{O}$ 的形状，并解释除以 $\sqrt{D}$ 的必要性。若这一篇没过，后面的多头与 KV Cache 都会变成背公式。
- [[多头注意力]]：重点不是「多个头更好」这句话，而是头拆分后每个头的维度、拼接顺序与 $\mathbf{W}_O$ 的形状。读完后应能由 $C=1536,H=12$ 推出 $D=128$，并解释 GQA 下 $\mathbf{k},\mathbf{v}$ 的维度为什么可以更小。
- [[位置编码与RoPE]]：把旋转矩阵写成 $2\times2$ 分块，核对 nanochat 的负角度约定。读完后应能解释为什么 RoPE 只依赖相对位置、为什么 decode 要从 `kv_cache.get_pos()` 截取 `cos/sin`，以及 `base=100000` 与旧文档 `10000` 的差异。
- [[残差连接与LayerNorm]]：把 pre-norm 的顺序写清楚：归一化在子层之前，残差相加在子层之后。读完后应能解释零初始化 `c_proj` 为什么让 Block 初始为恒等映射，以及 RMSNorm 无可学习参数意味着什么。
- [[前馈层与激活函数]]：核对 `c_fc` 的 $C\to4C$、ReLU² 的逐元素平方、`c_proj` 的 $4C\to C$。读完后应能算出 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与高效注意力]]：先理解标准注意力的 $O(T^2)$ 显存，再读 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 的词表大小 $V$ 与特殊 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` 与窗口。

## 符号约定与关键事实

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

| 符号 | 含义 |
|---|---|
| $B$ | 批大小 |
| $T$ | 序列长度（上下文） |
| $L$ | Transformer 层数，对应 `n_layer` 与 `--depth` |
| $C$ | 残差流宽度，对应 `n_embd` |
| $H$ | 查询头数，对应 `n_head` |
| $H_{kv}$ | KV 头数，对应 `n_kv_head` |
| $D$ | 单头维度，$D=C/H$ |
| $V,V'$ | 词表大小与填充到 64 倍数后的词表大小 |
| $W$ | 滑动窗口左边界；`S` 层的 $W$ 为 $T/4$ 向上取整到 128 |
| $\lambda_i^{res},\lambda_i^{x0}$ | 第 $i$ 层的残差增益与 $x_0$ 混合系数 |
| $\lambda_s,\lambda_b$ | smear 与 backout 的标量系数 |

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

| 项目 | d12 | d24 |
|---|---:|---:|
| `n_embd` / $C$ | 768 | 1536 |
| `n_head` / $H$ | 6 | 12 |
| `n_kv_head` / $H_{kv}$ | 6 | 12 |
| 单头维度 $D$ | 128 | 128 |
| 值嵌入层数 | 6 | 12 |
| 总参数 | 286,261,730 | 1,384,122,122 |
| `transformer_matrices + lm_head` | 110,100,912 | 729,810,624 |
| 滑动窗口（`SSSL`） | 9 层 512、3 层 2048 | 18 层 512、6 层 2048 |

结构事实清单：

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

> [!info] 版本与注释差异
> 1. RoPE 基频：当前 `gpt.py` 的 `_precompute_rotary_embeddings` 默认 `base=100000`；若在旧笔记或提示中看到 `10000`，以当前快照为准。
> 2. 短窗口：`_compute_window_sizes` 的表达式对 $T=2048$ 求值为 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 的 $C$ 维向量序列，子层读取其归一化版本并加回输出 |
| pre-norm | 先归一化再进子层，残差相加在子层输出之后；nanochat 的 Block 采用此结构 |
| RMSNorm | 按均方根归一化、无仿射参数；`norm(x) = F.rms_norm(x, (C,))` |
| RoPE | 旋转位置编码；nanochat 按 $-\theta$ 约定旋转 $\mathbf{q},\mathbf{k}$，基频 100000 |
| GQA | 分组查询注意力；$H_{kv}<H$ 时多个查询头共享一组 KV 头；默认配置不缩减 |
| sliding window | 每个查询只向前看 $W$ 个 token；`SSSL` 中 `S` 为 $T/4$ 上取整到 128 |
| logit softcap | 用 $c\tanh(\ell/c)$ 压缩 logits；当前 $c=15$，在 fp32 中执行 |
| 值嵌入 | 按 token id 查出的额外值向量，门控后加到 $\mathbf{v}$；隔层且最后一层必有 |
| FP8 | 8 位浮点；E4M3 用于前向输入/权重，E5M2 用于反向梯度 |
| per-tensor 量化 | 整个张量共用一个缩放因子；nanochat 的 `_to_fp8` 采用此粒度 |

## 阶段项目：核对 d24 的形状

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

```python
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}")
```

预期输出：

```text
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，$H$ 会翻倍，`n_embd` 不变，单头维度变小，注意力的参数量与 KV Cache 都会改变。这个脚本只覆盖形状；参数量、`num_scaling_params` 与优化器分组的完整核对在 [[GPT模型类与config]] 的可运行脚本中给出。

## 常见停滞点

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

## 与《AI学习总纲》的分工

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

| 主题 | 总纲负责 | 本阶段负责 |
|---|---|---|
| 注意力数学 | [[注意力机制与QKV]] 的 $\mathbf{Q},\mathbf{K},\mathbf{V}$ 推导、缩放点积与 softmax | `CausalSelfAttention.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` → $C,H,H_{kv},L$、总参数、`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` 的十个阶段分别做什么？为什么 $x_0$ 在 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 篇。
