---
tags: [nanochat, transformer, forward]
阶段: 04-Transformer架构
难度: ★★★
created: 2026-10-22
related: "[[GPT模型类与config]], [[nanochat架构特化技巧]], [[KV Cache原理]], [[残差连接与LayerNorm]]"
---

# 从第一性看nanochat的gpt.py

## 定义

`GPT.forward` 是 nanochat 的完整前向计算：输入形状为 $(B,T)$ 的 token id 与可选的目标 id，输出形状为 $(B,T,V)$ 的下一个 token logits 或标量交叉熵损失。它由十个连续阶段组成：截取 RoPE 片段、词嵌入与归一化、smear、保存 $x_0$、逐层残差混合、注意力子层、MLP 子层、backout 与最终归一化、反嵌入与 softcap、损失或返回。

符号约定：批大小 $B$、序列长度 $T$、层数 $L$、宽度 $C$、查询头数 $H$、KV 头数 $H_{kv}$、单头维度 $D=C/H$、词表大小 $V$、填充词表 $V'$。$\mathbf{x}\in\mathbb{R}^{B\times T\times C}$ 表示残差流；$\mathbf{x}_0$ 是 smear 之后保存的初始状态；$\lambda_i^{res}$ 与 $\lambda_i^{x0}$ 是第 $i$ 层的两个标量。**残差流**是贯穿所有 Block 的 $C$ 维向量序列，每个子层读取它的归一化版本，并把输出加回。

## 为什么重要

`gpt.py` 只有五百多行，但它是预训练、SFT、RL、评测与推理共同调用的唯一模型实现。训练脚本调用 `model(x,y)` 得到损失，评测脚本调用它得到 logits，Engine 调用它做 prefill 与 decode。任何一个阶段的顺序、形状或 dtype 错误都会传播到所有下游阶段：

- 训练：logits 宽度、目标对齐或 softcap 精度错误会直接改变损失与梯度。
- 推理：RoPE 片段偏移、KV Cache 推进或缓存布局错误会让生成结果与训练不一致。
- 优化：`Linear` 的权重 cast、嵌入 dtype 与参数分组决定显存与数值稳定性。
- 系统：是否使用滑动窗口、是否缓存 KV、是否复用注意力输出，决定吞吐与显存。

在「懂原理 / 能复现 / 懂工程」中，本篇同时覆盖三者：能脱离注释复述每一步是第一性的检验；能按形状调试是复现的检验；能解释每个技巧的代价是工程的检验。前置组件见 [[自注意力机制]]、[[前馈层与激活函数]]、[[位置编码与RoPE]] 与 [[残差连接与LayerNorm]]；本篇只讲它们如何在 nanochat 中组装。

## 原理与推导

`GPT.forward` 的调用签名是 `forward(self, idx, targets=None, kv_cache=None, loss_reduction='mean')`。`idx` 是 $(B,T)$ 的 `torch.long`；`targets` 与 `idx` 同形状，`-1` 表示忽略；`kv_cache` 为 `None` 时走训练/朴素推理路径，非空时走带缓存的推理路径。下面按真实执行顺序拆成十步。

### 1. 截取 RoPE 片段

进入模型前先检查三个条件：$T$ 不超过旋转缓存长度（`sequence_len * 10`）、`idx` 与 `cos` 同设备、`cos` 的 dtype 等于 `COMPUTE_DTYPE`。若存在 KV Cache，当前位置 $T_0$ 由 `kv_cache.get_pos()` 给出，旋转片段取 `cos[:, T0:T0+T]` 与 `sin[:, T0:T0+T]`。

形状：`cos_sin` 中两个张量均为 $(1,T,1,D/2)$，在注意力的头维上广播。去掉这一步，decode 的每个 token 都会从位置 0 开始旋转，查询与键的相对位置错误，生成质量会随上下文增长迅速下降；对训练路径，$T_0=0$，这一步退化为取前 $T$ 行，但断言仍然防止序列超过预计算缓存。

### 2. 词嵌入、dtype 对齐与 RMSNorm

```python
x = self.transformer.wte(idx)   # (B, T, C)
x = x.to(COMPUTE_DTYPE)         # fp16 路径下是有效转换，bf16 下通常是空操作
x = norm(x)                     # RMSNorm over C
```

`wte` 是 $(V',C)$ 的查表矩阵，输出 $(B,T,C)$。`norm` 是 `F.rms_norm(x, (C,))`，没有可学习参数；它把每个位置的 $C$ 维向量按其均方根归一化。去掉归一化，嵌入的初始标准差 0.8 会直接进入残差流，注意力 logits 与 MLP 激活的尺度随初始化漂移，深层训练需要重新调参；保留它则不增加任何参数与矩阵乘。

### 3. smear：把前一个 token 的嵌入混入当前 token

训练/预填充阶段（`kv_cache is None` 或 `T > 1`）的公式为

$$
\tilde{\mathbf{x}}_t=\mathbf{x}_t+\lambda_s\,\sigma\!\left(\mathbf{w}_s^\top \mathbf{x}_{t,1:24}\right)\mathbf{x}_{t-1},
\qquad t\ge 1,
$$

其中 $\tilde{\mathbf{x}}_0=\mathbf{x}_0$，$\sigma$ 是 sigmoid，$\mathbf{w}_s\in\mathbb{R}^{24}$ 是 `smear_gate` 的权重，$\lambda_s$ 是 `smear_lambda`。门只读取当前 token 的前 24 个通道，输出一个标量，再在 $C$ 维上广播。形状：门为 $(B,T-1,1)$，前一 token 嵌入为 $(B,T-1,C)$，相加后仍为 $(B,T,C)$。

解码阶段（`T=1` 且缓存已有内容）改为读取 `kv_cache.prev_embedding`：在修改当前嵌入之前，先把它存为下一步的 `prev_embedding`；然后用当前 token 的前 24 个通道算门，加上缓存的上一 token 嵌入。这样训练、预填充、解码三条分支在数学上一致。

去掉 smear，模型仍可通过注意力学习相邻 token 的关系，但需要额外的层与头去实现一个一阶 bigram 查表；保留它的代价是 25 个参数、一次 sigmoid 与 $O(BT)$ 的逐元素运算。`dev/LOG.md` 记录过早期全宽度门控版本「收益可忽略」，当前版本把门输入压到 24 个通道，成本已降到可忽略量级，但它不是模型能力的必要条件。

### 4. 保存 $x_0$ 与 backout 槽位

```python
x0 = x
backout_layer = n_layer // 2
x_backout = None
```

$x_0$ 是 **smear 之后**的归一化嵌入，不是 `wte(idx)` 的原始输出；这一点决定了 $x_0$ 已经包含一阶邻接信息。`backout_layer` 是 $L//2$，d24 时为 12，即在第 12 号 Block（第 13 层）之后缓存残差。去掉 $x_0$，后续每层的 $x_0$ 混合项就没有输入，`x0_lambdas` 失效；去掉 backout 槽位，最后的减项没有缓存可用。

### 5. 逐层残差混合

每个 Block 之前先做一次逐元素混合：

$$
\mathbf{x}\leftarrow \lambda_i^{res}\mathbf{x}+\lambda_i^{x0}\mathbf{x}_0.
$$

形状不变，仍为 $(B,T,C)$。初始化规则是

$$
\lambda_i^{res}=1.15-\frac{0.10\,i}{L-1},\qquad
\lambda_i^{x0}=0.20-\frac{0.15\,i}{L-1},
$$

浅层的残差增益大于 1，深层略低于 1.05；$x_0$ 的混入从 0.20 递减到 0.05。去掉这一行，模型退化为标准残差（系数 1）且没有 $x_0$ 捷径；实验记录显示这两个标量在各深度上带来稳定的 bpb 改善，详见 [[nanochat架构特化技巧]]。

### 6. 注意力子层

Block 采用 pre-norm：先归一化，再进注意力，最后把输出加回残差流。`CausalSelfAttention.forward` 的顺序如下。

**6.1 投影。** 输入 $\mathbf{x}\in\mathbb{R}^{B\times T\times C}$，三个输入投影给出

$$
\mathbf{q}=\mathbf{x}\mathbf{W}_Q,\quad
\mathbf{k}=\mathbf{x}\mathbf{W}_K,\quad
\mathbf{v}=\mathbf{x}\mathbf{W}_V,
$$

注意力输出再过输出投影：

$$
\mathbf{y}=\operatorname{Attn}(\mathbf{q},\mathbf{k},\mathbf{v})\,\mathbf{W}_O,
$$

其中 $\operatorname{Attn}$ 表示带因果与窗口掩码的缩放点积注意力，定义见 [[自注意力机制]]；$\mathbf{W}_Q\in\mathbb{R}^{C\times C}$，$\mathbf{W}_K,\mathbf{W}_V\in\mathbb{R}^{C\times H_{kv}D}$，$\mathbf{W}_O\in\mathbb{R}^{C\times C}$。reshape 后 $\mathbf{q}$ 为 $(B,T,H,D)$，$\mathbf{k},\mathbf{v}$ 为 $(B,T,H_{kv},D)$。去掉任一输入投影，注意力就没有对应的查询、键或值；去掉输出投影，多头结果无法混合回 $C$ 维。

**6.2 值嵌入。** 若该层有值嵌入（`has_ve(i,L)` 为真），先查表得到 $\mathbf{e}^{ve}\in\mathbb{R}^{B\times T\times H_{kv}D}$，reshape 为 $(B,T,H_{kv},D)$；门为

$$
\mathbf{g}=3\,\sigma\!\left(\mathbf{W}_{ve}\mathbf{x}_{:,:,1:12}\right)\in(0,3)^{B\times T\times H_{kv}},
$$

然后 $\mathbf{v}\leftarrow\mathbf{v}+\mathbf{g}\odot\mathbf{e}^{ve}$（在 $D$ 维上广播）。门输入只取前 12 个通道，输出维度是 $H_{kv}$；去掉值嵌入，模型少了一条几乎不耗 FLOPs 的容量通路，参数量减少约 6 个（d12）或 12 个（d24）词表大小的矩阵。

**6.3 RoPE 与 QK norm。** 对 $\mathbf{q},\mathbf{k}$ 的最后一维按前后两半做旋转：

$$
\begin{pmatrix}y_1\\y_2\end{pmatrix}
=
\begin{pmatrix}\cos\theta & \sin\theta\\-\sin\theta & \cos\theta\end{pmatrix}
\begin{pmatrix}x_1\\x_2\end{pmatrix}.
$$

代码旋转 $-\theta$，与教科书约定互为转置；由于只有 $\mathbf{q}$ 与 $\mathbf{k}$ 的相对旋转进入内积，两者功能等价，保留负号是为了检查点兼容。旋转后对每个头做 RMSNorm，再乘 1.2：

$$
\mathbf{q}\leftarrow 1.2\cdot\operatorname{RMSNorm}(\mathbf{q}),\qquad
\mathbf{k}\leftarrow 1.2\cdot\operatorname{RMSNorm}(\mathbf{k}).
$$

去掉 RoPE，模型失去位置信息；去掉 QK norm，注意力 logits 的尺度随头维度与初始化漂移；去掉 1.2，注意力分布更平缓。1.2 是把缩放分摊到 $\mathbf{q}$ 与 $\mathbf{k}$ 上的经验选择，代码注释承认尚未从第一性推出最优值。

**6.4 Flash Attention。** 训练路径调用

```python
y = flash_attn.flash_attn_func(q, k, v, causal=True, window_size=window_size)
```

输入 $\mathbf{q}$ 为 $(B,T,H,D)$，$\mathbf{k},\mathbf{v}$ 为 $(B,T,H_{kv},D)$，输出 $\mathbf{y}$ 为 $(B,T,H,D)$。`window_size` 是 `(left, 0)`：`left` 表示每个位置只向前看 `left` 个 token（含自身共 `left+1` 个键），`(-1, 0)` 表示全上下文。去掉 Flash Attention，标准实现要物化 $(B,H,T,T)$ 的分数矩阵；去掉 causal，当前位置会看到未来 token；去掉窗口，短窗口层的注意力计算与显存回到全上下文。

**6.5 缓存路径与输出。** 推理时调用 `flash_attn_with_kvcache`，把当前步的 $\mathbf{k},\mathbf{v}$ 原地写入该层的 `k_cache/v_cache`，用 `cache_seqlens` 定位，输出仍为 $(B,T,H,D)$。缓存位置只由最后一层推进一次（`if self.layer_idx == kv_cache.n_layers - 1: kv_cache.advance(T)`），否则每层都会把位置推进 $T$，下一步读到错误的槽位。最后把 $(B,T,H,D)$ reshape 为 $(B,T,C)$，过 $\mathbf{W}_O$，加回残差流。

### 7. MLP 子层

Block 的第二个子层同样是 pre-norm：

$$
\mathbf{h}=\operatorname{ReLU}(\mathbf{x}\mathbf{W}_{fc})^2,\qquad
\mathbf{x}\leftarrow\mathbf{x}+\mathbf{h}\mathbf{W}_{proj},
$$

其中 $\mathbf{W}_{fc}\in\mathbb{R}^{C\times 4C}$，$\mathbf{W}_{proj}\in\mathbb{R}^{4C\times C}$。形状：`c_fc` 输出 $(B,T,4C)$，ReLU² 不改变形状，`c_proj` 回到 $(B,T,C)$。去掉 ReLU²，两个线性层退化为一个线性映射；去掉 4 倍扩张，MLP 容量不足；去掉残差，深层梯度无法直接回传。ReLU² 是 [[前馈层与激活函数]] 的主题，本篇只确认它在 `MLP.forward` 中的位置。

### 8. backout 与最终归一化

循环结束后，如果缓存了中层残差：

$$
\mathbf{x}\leftarrow\mathbf{x}-\lambda_b\,\mathbf{x}_{mid},
$$

其中 $\lambda_b$ 是 `backout_lambda`，初值 0.2；$\mathbf{x}_{mid}$ 是第 $L//2$ 个 Block 之后的残差。随后做一次 `norm(x)`。去掉减项，最终表示仍携带浅层特征；去掉最终归一化，`lm_head` 的输入尺度不受控，logits 会随训练发散。注意 backout 在最终归一化之前、所有 Block 之后执行，不是在每个 Block 内。

### 9. 反嵌入、切片与 logit softcap

```python
logits = self.lm_head(x)                 # (B, T, V')
logits = logits[..., :self.config.vocab_size]  # (B, T, V)
logits = logits.float()                  # fp32
logits = 15 * torch.tanh(logits / 15)    # (-15, 15)
```

`lm_head` 是 $(C,V')$ 的无 bias 线性层，权重 master 精度为 fp32，前向时由 `Linear` cast 到激活 dtype。切片去掉词表填充；`float()` 把 logits 转到 fp32；softcap 用 $\tanh$ 平滑压缩到 $(-15,15)$，其导数为 $1-\tanh^2(z/15)$，在 $|z|\gg 15$ 时趋近 0，防止极端 logits 让交叉熵梯度爆炸。

去掉切片，损失的目标索引只在 $[0,V)$ 内，填充列永远不参与正确类，等价于给每行加一个固定偏置，浪费计算；去掉 `float()`，softcap 与交叉熵在 bf16 下做，$\tanh$ 饱和区的微小差异会被舍入；去掉 softcap，logits 无界，训练后期可能出现极端值。nanochat 当前代码把 `softcap` 硬编码为 15；`dev/LOG.md` 在 d24 上扫过 5 到 30，记录 20 最优（val loss 0.716 → 0.715），但当前快照仍是 15，两者不一致，阅读时以代码为准。

### 10. 损失或返回 logits

若 `targets` 非空：

```python
loss = F.cross_entropy(logits.view(-1, logits.size(-1)),
                       targets.view(-1), ignore_index=-1,
                       reduction=loss_reduction)
return loss
```

`targets` 与 `idx` 同形状，`-1` 的位置被忽略，用于 SFT/RL 的掩码。若 `targets` 为空，直接返回 $(B,T,V)$ 的 logits，供生成或评测使用。去掉 `ignore_index=-1`，padding 位置会被当作合法类别参与损失；去掉 `reduction` 参数，RL 无法按样本求和。

### 11. 组件选择：RMSNorm、Linear、无 bias、不共享权重

**RMSNorm。** `norm` 直接调用 `F.rms_norm(x, (C,))`，没有 $\gamma$ 或 $\beta$。公式为

$$
\operatorname{RMSNorm}(\mathbf{x})=\frac{\mathbf{x}}{\sqrt{\frac{1}{C}\sum_{j=1}^{C}x_j^2+\epsilon}}.
$$

PyTorch 在未显式传入 `eps` 时按 dtype 取默认值；bf16 下的 $\epsilon$ 比 fp32 大，这是 bf16 归一化仍能稳定工作的原因之一。没有可学习缩放，参数为零；代价是失去逐通道的再缩放能力，收益是少一组需要初始化的参数，且不会与残差标量重复。

**Linear 的 dtype cast。** `Linear` 继承 `nn.Linear`，只重写 `forward`：

```python
class Linear(nn.Linear):
    def forward(self, x):
        return F.linear(x, self.weight.to(dtype=x.dtype))
```

master 权重保持 fp32 供优化器更新；每次前向把权重临时 cast 到激活 dtype（通常是 bf16），矩阵乘在 bf16 中进行。nanochat 删除了 `torch.amp.autocast`，因为 autocast 只实际 cast 了 Linear 权重，而 RMSNorm、交叉熵与 Flash Attention 都自行处理 dtype；显式 cast 让精度路径可读、可调。去掉这个 cast，fp32 权重与 bf16 激活会在 `F.linear` 处 dtype 不匹配；改用 autocast 则重新引入不可控的算子白名单。

**无 bias。** 所有 `Linear` 都是 `bias=False`；RMSNorm 也没有平移参数。每个线性层少一个输出维度大小的向量，d24 的 `lm_head` 少 32768 个参数，注意力与 MLP 少 $C$ 或 $4C$ 个。无 bias 会失去每层独立的常数偏移，但后续线性层与残差路径可以吸收这些偏移；RMSNorm 只归一化尺度，不做中心化，因此「后续归一化会重新中心化」不能作为无 bias 的理由。无 bias 主要是减少参数、简化内核并避免偏置与归一化的冗余，属于架构选择而非纯优化。

**不共享权重。** `wte` 与 `lm_head` 是两个独立的 $(V',C)$ 矩阵，d24 各 50,331,648 个参数，合计约 1.0 亿。共享可以省一半嵌入参数，但会把「输入查表」与「输出分类」的梯度绑在一起：两者的学习率在 `setup_optimizer` 中分别是 0.212 与 0.0057（d24），量级相差近 37 倍，共享后无法同时满足。nanochat 选择不共享，并用独立的初始化尺度（`wte` 0.8，`lm_head` 0.001）控制初始 logits。

### 前向数据流表

| 步 | 操作 | 输入形状 | 输出形状 | 去掉会怎样 |
|---:|---|---|---|---|
| 1 | 取 RoPE 片段 | `cos` $(1,10T_{\max},1,D/2)$ | $(1,T,1,D/2)$ | 缓存解码位置错误 |
| 2 | `wte` + cast + RMSNorm | $(B,T)$ | $(B,T,C)$ | 嵌入尺度失控 |
| 3 | smear | $(B,T,C)$ | $(B,T,C)$ | 少一条一阶邻接通路 |
| 4 | 保存 $x_0$ / backout 槽 | $(B,T,C)$ | 引用 | 后续标量失效 |
| 5 | resid/x0 混合 | $(B,T,C)$ | $(B,T,C)$ | 退化为标准残差 |
| 6 | 注意力子层 | $(B,T,C)$ | $(B,T,C)$ | 无上下文聚合 |
| 7 | MLP 子层 | $(B,T,C)$ | $(B,T,C)$ | 无逐位置非线性 |
| 8 | backout + 最终 norm | $(B,T,C)$ | $(B,T,C)$ | 浅层特征残留/尺度漂移 |
| 9 | `lm_head` + slice + float + softcap | $(B,T,C)$ | $(B,T,V)$ | 无词表分布/数值不稳 |
| 10 | 交叉熵或返回 | $(B,T,V)$ | 标量或 $(B,T,V)$ | 无训练信号 |

表中 $T_{\max}$ 指 `sequence_len`；旋转缓存长度是它的 10 倍（默认 20480），实际前向只截取前 $T$ 行。`cos/sin` 的形状是 $(1,10T_{\max},1,D/2)$，不是 $(1,T,1,D/2)$；如果把它按当前序列长度预分配，decode 超过该长度时会触发断言。

### generate 的朴素实现与 Engine 的差异

`GPT.generate` 是给调试用的最小自回归循环：断言输入是 Python `list`、批大小为 1，把 token 列表转成 $(1,T)$，每一步把完整序列送入 `forward`，取最后一个位置的 logits，做 top-k、温度缩放、`multinomial` 或 `argmax`，拼回序列并 `yield` 一个整数。它没有 KV Cache，因此第 $t$ 步的注意力要重算前 $t$ 个位置；生成 $T$ 个 token 的总计算是 $O(T^3)$（每步 $O(t^2)$），显存也随序列增长。

`Engine.generate_batch` 使用 `KVCache`：先对提示做一次 prefill，得到最后位置的 logits 与缓存；再分配 `num_samples` 行的解码缓存，把提示的 K/V 复制到每一行，之后每步只送一个 token，调用 `flash_attn_with_kvcache` 追加缓存。它支持批内多行采样、停止 token、工具调用状态机与温度/top-k 参数，是评测、CLI 与 RL rollout 的实际路径。两者的数学定义相同，工程路径不同；不要用 `generate` 的耗时评估模型吞吐。

### 在 nanochat 中的落地

| 文件/函数 | 关键语句 | 作用 |
|---|---|---|
| `nanochat/gpt.py: GPT.forward` | `x = norm(self.transformer.wte(idx))` | 嵌入与归一化 |
| `nanochat/gpt.py: GPT.forward` | `x = torch.cat([x[:, :1], x[:, 1:] + gate * x[:, :-1]], dim=1)` | 训练/预填充 smear |
| `nanochat/gpt.py: GPT.forward` | `x = self.resid_lambdas[i] * x + self.x0_lambdas[i] * x0` | 逐层混合 |
| `nanochat/gpt.py: CausalSelfAttention.forward` | `q, k = norm(q), norm(k)`；`q = q * 1.2` | QK norm 与缩放 |
| `nanochat/gpt.py: CausalSelfAttention.forward` | `flash_attn.flash_attn_with_kvcache` | 缓存推理 |
| `nanochat/gpt.py: GPT.forward` | `logits = softcap * torch.tanh(logits / softcap)` | logit softcap |
| `nanochat/gpt.py: GPT.generate` | `logits = self.forward(ids)[:, -1, :]` | 朴素生成 |
| `nanochat/engine.py: Engine.generate_batch` | `KVCache` + `sample_next_token` | 生产级生成 |

## 关键直觉

> [!tip] 前向是「一条残差流 + 四类注入」
> 把 $\mathbf{x}$ 看成一条从嵌入流向 logits 的主干。主干上只有四类写操作：词嵌入提供 token 身份，smear 提供前一 token 的短期记忆，$x_0$ 提供回到初始状态的捷径，值嵌入提供按 token 查表的额外容量；注意力的输出与 MLP 的输出则是每次读取归一化主干后的加性更新。归一化发生在每次读取之前，标量 $\lambda^{res},\lambda^{x0}$ 控制主干自身的增益。这个视角与定义中的十步一一对应：每一步要么是注入，要么是读取，要么是压缩。

## 例子与代码

`GPT.forward` 的核心段落如下（省略了断言与 KV Cache 分支）：

```python
def forward(self, idx, targets=None, kv_cache=None, loss_reduction='mean'):
    B, T = idx.size()
    T0 = 0 if kv_cache is None else kv_cache.get_pos()
    cos_sin = self.cos[:, T0:T0+T], self.sin[:, T0:T0+T]

    x = self.transformer.wte(idx)
    x = x.to(COMPUTE_DTYPE)
    x = norm(x)
    gate = self.smear_lambda.to(x.dtype) * torch.sigmoid(self.smear_gate(x[:, 1:, :24]))
    x = torch.cat([x[:, :1], x[:, 1:] + gate * x[:, :-1]], dim=1)  # smear
    x0 = x

    x_backout = None
    for i, block in enumerate(self.transformer.h):
        x = self.resid_lambdas[i] * x + self.x0_lambdas[i] * x0
        ve = self.value_embeds[str(i)](idx).to(x.dtype) if str(i) in self.value_embeds else None
        x = block(x, ve, cos_sin, self.window_sizes[i], kv_cache)
        if i == self.config.n_layer // 2:
            x_backout = x

    x = x - self.backout_lambda.to(x.dtype) * x_backout
    x = norm(x)
    logits = self.lm_head(x)[..., :self.config.vocab_size].float()
    logits = 15 * torch.tanh(logits / 15)
    if targets is not None:
        return F.cross_entropy(logits.view(-1, logits.size(-1)),
                               targets.view(-1), ignore_index=-1,
                               reduction=loss_reduction)
    return logits
```

这段代码为了展示顺序做了压缩，`gate` 的定义与缓存分支在上文第 6 步给出；真实实现还包含 KV Cache 的空值判断与形状断言，`generate` 外层则用 `torch.inference_mode` 包裹。下面是一段可独立运行的形状复现，使用 d24 的维度，逐步打印每步张量形状；它不计算真实注意力，只验证形状链路：

```python
import torch
import torch.nn.functional as F

B, T, C, H, Hkv, D, V = 2, 8, 1536, 12, 12, 128, 32768
x = torch.zeros(B, T, C)
print("embedding", tuple(x.shape))

x = F.rms_norm(x, (C,))
gate = torch.zeros(B, T - 1, 1)
x = torch.cat([x[:, :1], x[:, 1:] + gate * x[:, :-1]], dim=1)
print("after smear", tuple(x.shape))

x0 = x
for i in range(2):  # 只演示两层的形状
    x = 1.1 * x + 0.1 * x0
    q = torch.zeros(B, T, H, D)
    k = torch.zeros(B, T, Hkv, D)
    v = torch.zeros(B, T, Hkv, D)
    ve = torch.zeros(B, T, Hkv, D)
    v = v + torch.zeros(B, T, Hkv, 1) * ve
    y = torch.zeros(B, T, H, D).reshape(B, T, C)
    x = x + y
    h = F.relu(torch.zeros(B, T, 4 * C)).square()
    x = x + torch.zeros(B, T, C)

x = x - torch.zeros(1) * x
x = F.rms_norm(x, (C,))
logits = 15 * torch.tanh(torch.zeros(B, T, V) / 15)
print("q/k/v", tuple(q.shape), tuple(k.shape), tuple(v.shape))
print("mlp hidden", tuple(h.shape))
print("logits", tuple(logits.shape))
```

预期输出：

```text
embedding (2, 8, 1536)
after smear (2, 8, 1536)
q/k/v (2, 8, 12, 128) (2, 8, 12, 128) (2, 8, 12, 128)
mlp hidden (2, 8, 6144)
logits (2, 8, 32768)
```

形状脚本里 `q` 的最后一维是 `D=128`，`k/v` 的第三维是 `Hkv=12`；若把 `n_kv_head` 改成 6，`k/v` 形状会变为 `(2,8,6,128)`，而 `q` 仍是 `(2,8,12,128)`，这就是 GQA 的广播前提。`c_fc` 的 4 倍扩张在 d24 下是 `1536 → 6144`。

## 易错点

> [!warning] 六个可检验的错误
> 1. 认为 $x_0$ 是 `wte(idx)` 的原始输出。它在 `norm` 与 smear 之后保存，已经包含相邻 token 信息；把 $x_0$ 改到更早的位置会改变所有层的混合语义。
> 2. 在带缓存的 decode 中让每个 Block 都推进 `kv_cache.advance(T)`。真实实现只在最后一层推进一次，否则位置会一次跳 $L\cdot T$。
> 3. 把 `cos_sin` 的偏移写成 0。decode 时必须用 `kv_cache.get_pos()` 截取当前绝对位置的旋转片段，否则位置编码与缓存内容错位。
> 4. 在 softcap 之前把 logits 切回 bf16，或先做交叉熵再做 softcap。正确顺序是 `lm_head → slice → float → softcap → cross_entropy`。
> 5. 忘记 `targets` 的 `-1` 掩码。SFT 与 RL 用 `-1` 标记不参与损失的位置；去掉 `ignore_index` 会让这些位置被当作类别 0 以外的非法索引而报错，或污染损失。
> 6. 用 `GPT.generate` 的耗时判断推理性能。它没有 KV Cache，生成长度 $T$ 的总计算约为 $O(T^3)$；生产路径是 `Engine.generate_batch`。

## 关联笔记

- 前置：[[自注意力机制]]、[[前馈层与激活函数]]、[[位置编码与RoPE]]。分别对应本篇第 6、7 步与 RoPE 片段。
- 前置：[[残差连接与LayerNorm]]。pre-norm、RMSNorm 与残差流的通用原理见该篇。
- 后续：[[nanochat架构特化技巧]]。smear、值嵌入、$x_0$、backout、softcap 的动机、消融与代价在该篇展开。
- 后续：[[KV Cache原理]]。本篇只讲缓存分支的位置，缓存布局、显存与 prefill/decode 的完整推导见该篇。
- 跨库：[[Transformer架构详解]]。通用 Transformer 的编码器/解码器结构与多头注意力推导见该篇，本篇只讲 nanochat 的组装顺序。

## 达标检测

- [ ] 不看代码，按顺序写出 `GPT.forward` 的十个阶段，并标出每个阶段的输出形状。
- [ ] 解释 $x_0$ 为什么在 smear 之后保存，以及去掉 $x_0$ 会影响哪些参数。
- [ ] 手算 d24 的 `q`、`k/v`、`c_fc`、`logits` 形状，说明 GQA 下 `k/v` 的第三维为什么可以小于 `q`。
- [ ] 说明 `Linear` 为什么要显式把权重 cast 到输入 dtype，以及它与 autocast 的区别。
- [ ] 解释 logit softcap 的公式、导数与必须在 fp32 中执行的原因。
- [ ] 指出 `GPT.generate` 与 `Engine.generate_batch` 的三处工程差异，并估算前者生成 $T$ 个 token 的复杂度。
- [ ] 运行形状脚本，核对输出与文中表格一致；再把 `Hkv` 改为 6 观察 `k/v` 形状变化。
- [ ] 找出「decode 位置偏移」与「softcap 精度」两类 bug 的最小复现条件。

## 参考来源

- Karpathy, *nanochat*（commit `92d63d4`），`nanochat/gpt.py` 的 `GPT.forward`、`CausalSelfAttention.forward`、`MLP.forward`、`GPT.generate` —— 对应本篇全部执行顺序与形状。
- Karpathy, *nanochat*，`dev/LOG.md` 中 2026-01-11 的 per-layer scalars、2026-01-16 的架构消融、2026-03-02 的 softcap 调参 —— 对应标量、backout 与 softcap 的实验记录。
- Vaswani et al., *Attention Is All You Need*, arXiv:1706.03762 —— 缩放点积注意力与残差/归一化的原始结构。
- Zhang & Sennrich, *Root Mean Square Layer Normalization*, arXiv:1910.07467 —— 无参数 RMSNorm 的定义与数值性质。
- So et al., *Primer: Searching for Efficient Transformers for Language Modeling*, arXiv:2109.08668 —— ReLU² 激活的来源。
- Su et al., *RoFormer: Enhanced Transformer with Rotary Position Embedding*, arXiv:2104.09864 —— RoPE 的相对位置性质；nanochat 的负角度约定与基频以其代码为准。
