---
tags: [nanochat, transformer, attention]
阶段: 04-Transformer架构
难度: ★★★
created: 2026-10-22
related: "[[多头注意力]], [[FlashAttention与高效注意力]], [[KV Cache原理]], [[注意力机制与QKV]]"
---

# 自注意力机制

## 定义

**自注意力**（self-attention）是一种把序列中每个位置的表示重写为同序列其他位置值向量的加权和的运算，权重由该位置与各位置的查询—键内积经 softmax 归一化得到。给定输入 $\mathbf{X}\in\mathbb{R}^{B\times T\times C}$，先做三组线性投影

$$
\mathbf{Q}=\mathbf{X}\mathbf{W}_Q,\qquad
\mathbf{K}=\mathbf{X}\mathbf{W}_K,\qquad
\mathbf{V}=\mathbf{X}\mathbf{W}_V,
$$

再按头拆分、在每头内计算

$$
\mathbf{S}=\frac{\mathbf{Q}\mathbf{K}^{\top}}{\sqrt{d_k}},\qquad
\mathbf{A}=\operatorname{softmax}_{\text{row}}(\mathbf{S}+\mathbf{M}),\qquad
\mathbf{O}=\mathbf{A}\mathbf{V},\qquad
\mathbf{Y}=\mathbf{O}\mathbf{W}_O .
$$

其中 $\mathbf{O}$ 先由各头输出沿通道维拼接为 $(B,T,C)$，再乘输出投影。符号与术语逐项定义如下。

| 符号 | 含义 |
|---|---|
| $B$ | 批量大小，一次前向并行处理的序列条数 |
| $T$ | 序列长度，即一次前向的 token 数 |
| $C$ | 模型维度，代码中为 `n_embd`，d12 取 $768$、d24 取 $1536$ |
| $H$ | 注意力头数，代码中为 `n_head`，满足 $C=H d_k$ |
| $d_k$ | 每头维度，代码中为 `head_dim`；当 $\mathbf{W}_Q$ 输出维为 $C$ 时 $d_k=C/H$ |
| $\mathbf{x}_t$ | 位置 $t$ 的输入向量，$\mathbf{x}_t\in\mathbb{R}^{C}$ |
| $\mathbf{Q},\mathbf{K},\mathbf{V}$ | 分头后的查询、键、值，形状 $(B,H,T,d_k)$ |
| $\mathbf{S}$ | 打分矩阵，形状 $(B,H,T,T)$；$S_{tj}$ 是位置 $t$ 对位置 $j$ 的匹配分数 |
| $\mathbf{M}$ | 加性掩码，允许为 $0$、禁止为 $-\infty$，形状可广播到 $(B,H,T,T)$ |
| $\mathbf{A}$ | 注意力权重，每行是一个概率分布 |
| $\mathbf{W}_Q,\mathbf{W}_K,\mathbf{W}_V,\mathbf{W}_O$ | 查询、键、值、输出投影矩阵，nanochat 中均为 $C\times C$ 且无偏置 |
| $\mathcal{A}_t$ | 位置 $t$ 的允许配对集合；因果掩码下 $\mathcal{A}_t=\{j:j\le t\}$ |

**查询**（query）是当前位置发出的匹配请求；**键**（key）是各位置提供的可匹配特征；**值**（value）是被加权汇聚的内容。**缩放点积注意力**（scaled dot-product attention）指打分经 $1/\sqrt{d_k}$ 缩放的点积注意力。**因果掩码**（causal mask）把位置 $t$ 的允许集合限制为 $\{1,\dots,t\}$，使输出只依赖前缀。**注意力头**（attention head）是通道维的一个 $d_k$ 维子空间及其独立的投影与 softmax。**滑动窗口注意力**（sliding-window attention）在因果掩码之上再加下界 $j\ge t-W$，把每行非零元限制在宽度 $W+1$ 的带内。

## 为什么重要

自注意力的功能是**跨 token 混合**。一个 Transformer 块中，前馈层、归一化、残差都逐位置作用，不改变 token 之间的信息流动；只有注意力把不同位置的表示相加。若去掉注意力，每个位置的输出只由该位置的嵌入与逐位置变换决定，模型退化为对当前 token 的 $n$-gram 分类器，无法利用上下文区分同形异义的 token，也无法完成复制、指代、算术等需要跨位置读取的任务。

它同时决定训练与推理的计算结构。训练时一次前向对全部 $T$ 个位置并行计算，每个位置读取自己的前缀，代价 $O(T^2d)$；推理时新 token 逐步产生，需要复用已算出的键与值，这直接导致 [[KV Cache原理]] 中的缓存设计。序列越长，注意力打分矩阵越大，长上下文的主要成本来自这一项；nanochat 用 sliding window 把部分层的有效长度从 $T$ 降到 $T/4$，是在质量与算力之间的显式取舍。

它还是若干工程约束的来源。因果性要求实现中掩码方向不能错；混合精度要求缩放与 softmax 的 dtype 与内核一致；[[FlashAttention与高效注意力]] 的布局是 $(B,T,H,d_k)$，决定了 nanochat 的 `CausalSelfAttention.forward` 不做转置；QK norm 与 $1.2$ 缩放则是对注意力 logits 尺度的直接干预。这些选择都不是抽象数学，而是写进 `nanochat/gpt.py` 的具体语句。

在全书中的位置：本篇是 04 阶段的第一篇，承接 02 阶段的 softmax 与矩阵乘法，给出注意力本身的完整推导；[[多头注意力]] 在本篇基础上展开头的拆分与合并，[[位置编码与RoPE]] 解决注意力对位置不敏感的问题，[[残差连接与LayerNorm]] 与前馈层负责把注意力嵌入可训练的整体。对应三条主线：懂原理要求能独立完成第 2 节的方差推导与第 5 节的复杂度核算；能复现要求写出可运行的注意力并验证因果性；懂工程要求能解释 FA3 布局与 KV 缓存分支。

## 原理与推导

### 1 从固定加权平均到内容寻址

先看一个不含参数的版本。设每个位置有一个值向量 $\mathbf{x}_j\in\mathbb{R}^{C}$，位置 $t$ 的输出取

$$
\mathbf{o}_t=\sum_{j=1}^{T}a_{tj}\mathbf{x}_j,\qquad a_{tj}\ge 0,\qquad \sum_{j=1}^{T}a_{tj}=1 .
$$

这是一次加权平均。若权重 $a_{tj}$ 是预先固定的（例如所有位置等权，或按距离衰减），模型只能表达与内容无关的汇总，无法在“读取哪个位置”上做条件判断。

自注意力的改动是把权重变成输入自身的函数。对每个位置计算查询 $\mathbf{q}_t=\mathbf{W}_Q^{\top}\mathbf{x}_t$ 与键 $\mathbf{k}_j=\mathbf{W}_K^{\top}\mathbf{x}_j$，用内积衡量匹配程度：

$$
s_{tj}=\mathbf{q}_t^{\top}\mathbf{k}_j,\qquad
a_{tj}=\frac{\exp(s_{tj})}{\sum_{l\in\mathcal{A}_t}\exp(s_{tl})},\qquad
\mathbf{o}_t=\sum_{j\in\mathcal{A}_t}a_{tj}\mathbf{v}_j,\qquad
\mathbf{v}_j=\mathbf{W}_V^{\top}\mathbf{x}_j .
$$

查询与键使用不同投影，是因为两者角色不对称：查询描述“当前位置需要什么”，键描述“某位置能提供什么”，若共享同一投影，内积就退化为输入与自身的相似度，表达能力受限。值投影与键投影也分开：键负责匹配，值负责被搬运的内容，两者无需一致。

写成矩阵形式并拆分到 $H$ 个头，即得到定义中的四式。参数量方面，$\mathbf{W}_Q,\mathbf{W}_K,\mathbf{W}_V$ 各 $C\times C$（nanochat 的 `c_q`、`c_k`、`c_v`），输出投影 $\mathbf{W}_O$ 再 $C\times C$，一层注意力共 $4C^2$ 个权重。d12 的 $C=768$ 对应 $4\times768^2=2\,359\,296$，d24 的 $C=1536$ 对应 $4\times1536^2=9\,437\,184$。

这里有一个容易忽略的点：$\mathbf{W}_Q$ 的输出维是 $H d_k=C$，所以 `c_q` 的权重形状是 $(C,C)$；只有当启用 GQA（`n_kv_head < n_head`）时，`c_k`、`c_v` 的输出维才缩小为 $H_{kv}d_k$，详见 [[多头注意力]]。

### 2 为什么要除以 $\sqrt{d_k}$

设 $\mathbf{q},\mathbf{k}\in\mathbb{R}^{d_k}$ 的每个分量独立、均值为 $0$、方差为 $1$。内积

$$
s=\mathbf{q}^{\top}\mathbf{k}=\sum_{i=1}^{d_k}q_i k_i
$$

是 $d_k$ 个独立同分布项之和，每项 $q_i k_i$ 的均值为 $0$、方差为 $\mathbb{E}[q_i^2]\mathbb{E}[k_i^2]=1$，因此

$$
\mathbb{E}[s]=0,\qquad \operatorname{Var}(s)=d_k,\qquad \operatorname{sd}(s)=\sqrt{d_k}.
$$

维度越大，打分的典型绝对值越大。softmax 对整体平移不变，但对尺度敏感：把打分同乘 $c>0$，分布会变尖锐（$c>1$）或变平坦（$c<1$）。当 $d_k=128$ 时，未缩放的打分标准差约 $11.3$，一行 $512$ 个键中的最大打分比均值高约 $3$ 个标准差，softmax 接近 one-hot，权重集中在少数位置。

饱和的代价出现在梯度上。对一行打分 $\mathbf{s}$，softmax 的雅可比为

$$
\frac{\partial a_i}{\partial s_j}=a_i(\delta_{ij}-a_j),
$$

当分布接近 one-hot 时，$a_i(1-a_i)\to0$，权重对 logits 的导数趋零，注意力子层几乎收不到有效梯度。除以 $\sqrt{d_k}$ 把打分的方差归一为 $1$：

$$
\operatorname{Var}\!\left(\frac{s}{\sqrt{d_k}}\right)=\frac{d_k}{d_k}=1 .
$$

这一步不改变 softmax 的形式，只把 logits 放到 softmax 的线性响应区间。缩放因子的位置等价：可以先除在打分上，也可以把 $\mathbf{q}$ 预先除以 $\sqrt{d_k}$；两者只差一个与位置无关的常数，但只能做一次，做两次等价于除以 $d_k$。

nanochat 在此之上又加了两处尺度干预，见「在 nanochat 中的落地」一节：QK norm 把每个头的 $\mathbf{q},\mathbf{k}$ 行归一为 RMS $1$，随后各自乘 $1.2$。若只看缩放因子，FlashAttention 内部仍按 $1/\sqrt{d_k}$ 缩放，于是打分的标准差约为 $1.44$（因为 $1.2\times1.2=1.44$）。这一取值使分布比标准缩放更尖锐，是作者在仓库注释中明确写出的取舍。

用随机数据可以量化上述效应。取 $B=2$、$T=512$、$d_k=128$ 的高斯查询与键，比较三种 logits 下 softmax 的平均最大权重、平均熵与雅可比因子：

```python
import math
import torch

torch.manual_seed(0)
B, T, H, D = 2, 512, 1, 128
q = torch.randn(B, T, H, D)
k = torch.randn(B, T, H, D)
raw = torch.einsum("bthd,bshd->bhts", q, k)      # (B,H,T,T)，注意不是 q @ k.transpose(-2,-1)
scaled = raw / math.sqrt(D)

for name, logits in [("未缩放", raw), ("1/sqrt(d)", scaled), ("nanochat 1.2^2", 1.44 * scaled)]:
    a = torch.softmax(logits, -1)
    entropy = -(a * (a + 1e-12).log()).sum(-1).mean().item()
    print("%s：最大权重 %.4f，熵 %.3f nats，雅可比因子 %.4f"
          % (name, a.max(-1).values.mean().item(), entropy, (a * (1 - a)).mean().item()))
```

```text
未缩放：最大权重 0.8138，熵 0.527 nats，雅可比因子 0.0005
1/sqrt(d)：最大权重 0.0276，熵 5.737 nats，雅可比因子 0.0019
nanochat 1.2^2：最大权重 0.0660，熵 5.209 nats，雅可比因子 0.0019
```

$T=512$ 时均匀分布的熵为 $\ln 512\approx6.24$ nats、最大权重为 $1/512\approx0.002$。未缩放时最大权重 $0.81$、熵 $0.53$，分布已接近 one-hot；缩放后最大权重降为 $0.028$，熵回到 $5.74$，仍然高于均匀分布但不再饱和。$1.44$ 倍缩放把最大权重抬到 $0.066$、熵压到 $5.21$，方向与“更尖锐”的注释一致。

### 3 softmax 行归一化的含义

对固定的 $t$，$\mathbf{A}_{t,:}$ 是单纯形上的一个点：非负且和为 $1$。由此得到三条可直接使用的性质。

第一，输出是值向量的凸组合。$\mathbf{o}_t=\sum_j a_{tj}\mathbf{v}_j$ 落在 $\{\mathbf{v}_j\}$ 的凸包内，其范数不会超过最大值的范数；注意力只能“选择与混合”，不能放大单个值向量。放大由输出投影 $\mathbf{W}_O$ 与后续层完成。

第二，行归一化使输出尺度与 $T$ 无关。若省略归一化而直接对 $\exp(s_{tj})$ 加权求和，行和被 $\sum_j\exp(s_{tj})$ 放大，$T$ 越大输出越大，深层数值范围失控。归一化后每行质量恒为 $1$，无论 $T=32$ 还是 $T=2048$。

第三，掩码必须在归一化之前生效。因果掩码把 $j>t$ 的指数置零，分母自动只统计允许位置，权重和为 $1$；若先对全行归一化再把未来位置置零，行和小于 $1$，输出被整体缩小，且缩小比例随 $t$ 变化，后续层无法用一个常数补偿。完整论证见 [[因果注意力与多头注意力]] 第 3 节，这里只记录结论。

实现上的数值稳定性要求先减去行最大值再取指数，即计算 $\exp(s_{tj}-m_t)$，其中 $m_t=\max_j s_{tj}$。该变换不改变 softmax 的结果，但避免 $\exp$ 上溢。nanochat 不手写这段代码，训练时由 FlashAttention 的融合内核完成，回退路径由 `F.scaled_dot_product_attention` 完成；两者都在内部做同样的稳定化。

### 4 因果掩码

语言模型的训练目标是逐位置预测下一个 token。位置 $t$ 的表示若读取了 $x_{t+1}$，输出层就可以直接复制答案，损失趋零而模型不具备生成能力。因果掩码把允许集合限制为 $\mathcal{A}_t=\{j:j\le t\}$：

$$
M_{tj}=\begin{cases}0,&j\le t,\\-\infty,&j>t,\end{cases}
\qquad
A_{tj}=\frac{\exp(s_{tj}+M_{tj})}{\sum_{j'}\exp(s_{tj'}+M_{tj'})}.
$$

$T=4$ 时 $\mathbf{M}$ 为

$$
\mathbf{M}=
\begin{pmatrix}
0&-\infty&-\infty&-\infty\\
0&0&-\infty&-\infty\\
0&0&0&-\infty\\
0&0&0&0
\end{pmatrix}.
$$

被禁止位置的指数为 $0$，对分母无贡献；权重精确为 $0$，反向时也不接收梯度。训练时一次前向可以并行算完 $T$ 个位置，因为每个位置的输入都是真实 token（教师强制），掩码只限制读取范围，不限制并行度。

nanochat 不在 Python 层构造这个矩阵。`CausalSelfAttention.forward` 把因果性交给内核：训练分支调用 `flash_attn_func(q, k, v, causal=True, window_size=window_size)`，FA3 在分块计算时跳过对角块以上的块，等价于上述掩码，但省去了 $T\times T$ 矩阵的显式存储与加法。训练与推理的这条分工决定了实现形状：正因为掩码在内核里，`q`、`k`、`v` 才可以直接保持 $(B,T,H,d_k)$ 布局，不需要为了掩码相加而转置。

在因果之上，nanochat 默认再叠加滑动窗口。`GPTConfig.window_pattern` 的取值为 `"SSSL"`：`S` 表示短窗，`L` 表示全长，模式按层平铺，最后一层强制为 `L`。`_compute_window_sizes` 把 `S` 映射为

```python
short_window = -(-long_window // 4 // 128) * 128   # 向上取整到 128 的倍数
```

即 $T/4$ 向上取整到 $128$ 的倍数；$T=2048$ 时为 $512$，允许集合是 $[t-512,t]$（含自身，最多 $513$ 个键）。`window_size` 的第二个分量固定为 $0$，表示不看未来。第 $i$ 层实际使用的窗口是 `window_sizes[i]`，传入 `flash_attn_func` 或 `flash_attn_with_kvcache` 的 `window_size` 参数。

> [!info] 版本与注释差异
> 当前快照的运行时短窗为 $512$（$2048/4$）。`gpt.py` 中该行的行内注释写“2048 -> 768”，`scripts/base_train.py` 的 `--window-pattern` 帮助写“S=half context”，`dev/LOG.md` 2026-01-11 条目也写 `sequence_len // 2`；这三处描述与代码表达式不一致，以表达式与运行结果为准。

### 5 复杂度与 FLOPs

设 $d=C$。单个头一次前向的两次矩阵乘为 $T\times d_k$ 与 $d_k\times T$ 的乘积、$T\times T$ 与 $T\times d_k$ 的乘积，各 $2T^2d_k$ FLOPs；$H$ 个头合计

$$
H\cdot 4T^{2}d_k=4T^{2}C .
$$

投影部分为 $8TC^2$：$\mathbf{Q},\mathbf{K},\mathbf{V}$ 各 $2TC^2$，输出投影 $2TC^2$。softmax 自身的 $O(T^2H)$ 逐元素运算相对矩阵乘可忽略。因此单层前向约为

$$
\underbrace{8TC^{2}}_{\text{投影}}+\underbrace{4T^{2}C}_{\text{打分与加权}},
$$

对 $T$ 的依赖是二次的，对 $C$ 的依赖在线性项与二次项中各出现一次。记 $d=C$，注意力项为 $O(T^2d)$、投影项为 $O(Td^2)$，单层合计 $O(T^2d+Td^2)$；当 $T\gg d$ 时由第一项主导，当 $d\gg T$ 时由第二项主导。全模型 $L$ 层再乘 $L$。以 d24（$C=1536$、$T=2048$、$L=24$）为例，单层投影 $8\times2048\times1536^2\approx3.87\times10^{10}$，打分与加权 $4\times2048^2\times1536\approx2.58\times10^{10}$，单层合计约 $6.45\times10^{10}$ FLOPs；d12 对应约 $2.25\times10^{10}$。注意这是前向、且窗口为全长时的数；滑动窗口把 $T$ 换成有效长度后按层求和。

nanochat 的 `GPT.estimate_flops` 采用另一条等价核算路径：矩阵参数每个在前向计 $2$ FLOPs、反向计 $4$，合计 $6$；注意力部分每层每 token 计

$$
12\,h\,q\,T_{\text{eff}},
$$

其中 $h$ 为头数、$q$ 为每头维度、$T_{\text{eff}}$ 为该层有效长度。推导是：每个 token 的打分需要 $h\cdot T_{\text{eff}}$ 次长度为 $q$ 的点积，前向 $2hT_{\text{eff}}q$，加权求和同样 $2hT_{\text{eff}}q$，前向合计 $4hT_{\text{eff}}q$；乘以前向加反向的系数 $3$ 得 $12hT_{\text{eff}}q$。实现中 `effective_seq = t if window < 0 else min(window, t)`，`window` 取 `(left, right)` 的第一个分量。

### 在 nanochat 中的落地

相关代码集中在 `nanochat/gpt.py` 的 `CausalSelfAttention` 与 `nanochat/flash_attention.py`。逐段说明如下。

**构造函数。** `__init__` 先算 `head_dim = n_embd // n_head`，断言 `n_embd % n_head == 0` 与 `n_kv_head <= n_head and n_head % n_kv_head == 0`，再建立四个无偏置 `Linear`：

```python
self.c_q = Linear(self.n_embd, self.n_head * self.head_dim, bias=False)
self.c_k = Linear(self.n_embd, self.n_kv_head * self.head_dim, bias=False)
self.c_v = Linear(self.n_embd, self.n_kv_head * self.head_dim, bias=False)
self.c_proj = Linear(self.n_embd, self.n_embd, bias=False)
```

`c_q` 的输出维恰好等于 $C$；`c_k`、`c_v` 在 GQA 下才缩小。无偏置不是省略，而是设计：偏置在 LayerNorm/RMSNorm 之后作用有限，去掉可减少参数与内核分支，也与后续层零初始化配合（见 [[残差连接与LayerNorm]]）。

**前向的五个阶段。** 第一，投影并拆头，保持 FA3 布局：

```python
q = self.c_q(x).view(B, T, self.n_head, self.head_dim)      # (B,T,H,D)
k = self.c_k(x).view(B, T, self.n_kv_head, self.head_dim)
v = self.c_v(x).view(B, T, self.n_kv_head, self.head_dim)
```

`view` 沿最后一维按行优先切分，第 $i$ 个头占据通道区间 $[i d_k,(i+1)d_k)$。**不转置**是 nanochat 与教科书实现最明显的差别：FA3 的原生布局就是 $(B,T,H,d_k)$，转置只会增加一次非连续访问；SDPA 回退路径在 `flash_attention.py` 内部自行转置为 $(B,H,T,d_k)$，调用方不必关心。

第二，值残差（ResFormer）。若该层有 value embedding，`ve` 先被 reshape 到 $(B,T,H_{kv},d_k)$，再用输入前 $12$ 个通道算出的门控加到 `v` 上：

```python
gate = 3 * torch.sigmoid(self.ve_gate(x[..., :self.ve_gate_channels]))
v = v + gate.unsqueeze(-1) * ve
```

门控取值在 $(0,3)$，初始权重很小，接近中性。这一支路只改值、不改查询与键，因此不影响注意力权重，只改变被搬运的内容。

第三，RoPE 与 QK norm。`cos_sin` 由 `GPT.forward` 按当前序列长度切好传入；`apply_rotary_emb` 对 `q`、`k` 的成对通道做旋转（细节见 [[位置编码与RoPE]]）。随后

```python
q, k = norm(q), norm(k)   # QK 归一化
q = q * 1.2               # 更尖锐的注意力
k = k * 1.2
```

`norm` 是 `nanochat/gpt.py` 顶部的函数 `F.rms_norm(x, (x.size(-1),))`，对最后一个维度（即每头的 $d_k$）归一，无可学习增益。QK norm 的作用是消除查询与键的尺度漂移：若不做，某些头在训练中范数持续增大，logits 饱和，softmax 梯度消失；做了之后每个头的输入 RMS 固定为 $1$，logits 的量级只由内容相关性决定。之后的 $1.2$ 是显式的锐化因子，作者在注释中说明这是把缩放“分给 Q 与 K 各一部分”，其等效温度为 $1.44$。顺序上先 RoPE 再 norm；由于 RMSNorm 只按范数缩放、不做逐通道增益，它与旋转可交换（差值为浮点舍入量级），因此这个顺序不是数值上的硬约束，但写成“先生成相对位置、再统一尺度”更便于解释。

第四，注意力内核。训练分支与推理分支分开，前者无缓存、后者读写 KV 缓存：

```python
if kv_cache is None:
    y = flash_attn.flash_attn_func(q, k, v, causal=True, window_size=window_size)
else:
    k_cache, v_cache = kv_cache.get_layer_cache(self.layer_idx)
    y = flash_attn.flash_attn_with_kvcache(
        q, k_cache, v_cache, k=k, v=v,
        cache_seqlens=kv_cache.cache_seqlens,
        causal=True, window_size=window_size,
    )
    if self.layer_idx == kv_cache.n_layers - 1:
        kv_cache.advance(T)
```

推理分支有两处容易误读。其一，`k`、`v` 是“新 token 的键值”，内核把它们原地写入 `k_cache`、`v_cache` 的当前位置，并返回对全缓存（截至当前）的注意力结果；因此第 $l$ 层写入的缓存位置相同，位置推进只在最后一层执行一次，`advance(T)` 放在 `layer_idx == n_layers - 1` 的判断里。其二，RoPE 的切片偏移在 `GPT.forward` 中完成：`T0 = kv_cache.get_pos()`，`cos_sin = self.cos[:, T0:T0+T]`；若忘记偏移，解码时每个新 token 都会被当作位置 $0$，缓存中的键与查询的相对位置全部错位。

第五，拼头与输出投影。`y` 的形状是 $(B,T,H,d_k)$，直接 `view(B,T,-1)` 合并为 $(B,T,C)$，再过 `c_proj` 回到残差流。这里 `contiguous()` 是必要的：FA3 的输出布局与 `view` 期望的连续布局不一定一致，先复制再 `view` 可以避免步长错误。合并顺序与拆分顺序互逆，第 $i$ 个头的 $d_k$ 个通道回到输出通道区间 $[i d_k,(i+1)d_k)$。

**回退路径。** `nanochat/flash_attention.py` 在导入时尝试加载 FA3；若不可用或计算精度不是 bf16（FA3 的 Hopper 内核只支持 bf16 与 fp8），`USE_FA3` 为 `False`，`flash_attn_func` 走 SDPA：把 $(B,T,H,d_k)$ 转置为 $(B,H,T,d_k)$，`enable_gqa = q.size(1) != k.size(1)`，滑动窗口用显式布尔掩码 `mask & ((row_idx - col_idx) <= window)` 实现，最后转置回原布局。这条路径在 CPU 与老 GPU 上可运行，但显存与速度都差于 FA3；`dev/LOG.md` 2026-01-16 的记录给出测试方法：同一输入分别强制 FA3 与 SDPA，比较最大差值。

**去掉各组件会怎样。** 若令 $\mathbf{V}=\mathbf{X}$（去掉值投影），值直接取自输入，键与值共享同一表示，模型无法分别学习“匹配什么”与“搬运什么”；去掉 QK norm 后 logits 随训练漂移，长训练不稳定；去掉 $1.2$ 只是让分布略平缓，属于超参数级差异；去掉滑动窗口回到全长注意力，显存与 FLOPs 按层上升；去掉因果性则训练损失可被复制路径刷低，生成不可用。

## 关键直觉

> [!tip] 机制性表述
> 自注意力对每一行独立执行同一件事：用查询与所有键的内积打分，经缩放与 softmax 把打分变成允许集合上的概率分布，再用它加权求和值向量。缩放的作用是让打分方差保持在 $O(1)$，使 softmax 处在线性响应区；行归一化保证输出是凸组合且尺度与序列长度无关；因果掩码只改变每行的允许集合，不改变上述三步的结构。nanochat 把掩码与 softmax 交给融合内核，因此张量始终保持 $(B,T,H,d_k)$ 布局；QK norm 与 $1.2$ 缩放则把每个头的打分尺度固定在可控范围。

该表述与严格定义的关系：第 1 节给出四式的矩阵定义，第 2 节从独立同分布假设推出缩放因子，第 3 节从行和为 $1$ 推出凸组合与尺度无关性，第 4 节给出掩码对允许集合的修改，「在 nanochat 中的落地」一节把这些步骤逐一对应到 `CausalSelfAttention.forward` 的语句。所谓“内核完成掩码”并不改变数学，只是把 $-\infty$ 加法与 softmax 的归一化在分块层面融合，等价性由 `tests/test_attention_fallback.py` 的对照测试保证。

## 例子与代码

### 例 1：可手算的三位置注意力

取 $T=3$、$d_k=2$、$H=1$，不用投影，直接给定

$$
\mathbf{Q}=\begin{pmatrix}1&0\\0&1\\1&1\end{pmatrix},\quad
\mathbf{K}=\begin{pmatrix}1&0\\0&1\\1&0\end{pmatrix},\quad
\mathbf{V}=\begin{pmatrix}1&0\\0&1\\0&0\end{pmatrix}.
$$

先算未缩放打分 $\mathbf{Q}\mathbf{K}^{\top}$，再除以 $\sqrt{2}$：

```python
import numpy as np

def softmax(x, axis=-1):
    x = x - x.max(axis=axis, keepdims=True)
    e = np.exp(x)
    return e / e.sum(axis=axis, keepdims=True)

Q = np.array([[1., 0.], [0., 1.], [1., 1.]])
K = np.array([[1., 0.], [0., 1.], [1., 0.]])
V = np.array([[1., 0.], [0., 1.], [0., 0.]])

S = Q @ K.T / np.sqrt(2)                                   # 打分
causal = np.triu(np.ones((3, 3), dtype=bool), k=1)         # True 表示未来位置
A = softmax(np.where(causal, -np.inf, S), -1)              # 掩码后行归一化
print("S =\n", S.round(4))
print("A =\n", A.round(4))
print("行和", A.sum(-1))
print("O =\n", (A @ V).round(4))
```

```text
S =
 [[0.7071 0.     0.7071]
 [0.     0.7071 0.    ]
 [0.7071 0.7071 0.7071]]
A =
 [[1.     0.     0.    ]
 [0.3302 0.6698 0.    ]
 [0.3333 0.3333 0.3333]]
行和 [1. 1. 1.]
O =
 [[1.     0.    ]
 [0.3302 0.6698]
 [0.3333 0.3333]]
```

逐行核对。第 $0$ 行只允许 $j=0$，权重为 $[1,0,0]$，输出就是 $\mathbf{v}_0=(1,0)$。第 $1$ 行的允许集合是 $\{0,1\}$，打分为 $[0,0.7071]$，softmax 得 $[0.3302,0.6698]$；这两个数与 $\exp(0.7071)/(1+\exp(0.7071))$ 一致，可直接用计算器复核。第 $2$ 行三个打分相等，权重为均匀的 $1/3$，输出是三个值向量的平均 $(1/3,1/3)$。三行的和都等于 $1$，且未来位置的权重精确为 $0$。

若把缩放去掉，第 $1$ 行打分变为 $[0,1]$，权重变为 $[0.2689,0.7311]$，分布更尖锐；第 $2$ 行的打分仍相等，权重不变。这一例子说明缩放影响的是行内相对差距的放大程度，而不是归一化本身。

### 例 2：因果性与参数量的单元检验

下面的实现与 `CausalSelfAttention` 的数学一致（省略 RoPE、GQA、QK norm 与 FA3），用于检验因果性与形状。核心是把 $(B,T,C)$ 拆成 $(B,H,T,d_k)$ 后调用 SDPA，再合并回 $(B,T,C)$。

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

class CausalSelfAttention(nn.Module):
    def __init__(self, n_embd=768, n_head=6):
        super().__init__()
        assert n_embd % n_head == 0
        self.n_head, self.head_dim = n_head, n_embd // n_head
        self.c_q = nn.Linear(n_embd, n_embd, bias=False)
        self.c_k = nn.Linear(n_embd, n_embd, bias=False)
        self.c_v = nn.Linear(n_embd, n_embd, bias=False)
        self.c_proj = nn.Linear(n_embd, n_embd, bias=False)

    def forward(self, x):
        B, T, C = x.shape
        q = self.c_q(x).view(B, T, self.n_head, self.head_dim).transpose(1, 2)
        k = self.c_k(x).view(B, T, self.n_head, self.head_dim).transpose(1, 2)
        v = self.c_v(x).view(B, T, self.n_head, self.head_dim).transpose(1, 2)
        y = F.scaled_dot_product_attention(q, k, v, is_causal=True)
        y = y.transpose(1, 2).contiguous().view(B, T, C)
        return self.c_proj(y)

torch.manual_seed(3)
m = CausalSelfAttention()
x = torch.randn(2, 8, 768)
y = m(x)
x2 = x.clone()
x2[:, -1, :] += 5.0                    # 只扰动最后一个位置
y2 = m(x2)
print("输出形状", tuple(y.shape))
print("参数量", sum(p.numel() for p in m.parameters()))
print("前 7 个位置的最大变化", (y[:, :-1] - y2[:, :-1]).abs().max().item())
print("最后位置的最大变化", (y[:, -1] - y2[:, -1]).abs().max().item())
```

```text
输出形状 (2, 8, 768)
参数量 2359296
前 7 个位置的最大变化 0.0
最后位置的最大变化 3.0586869716644287
```

前 $7$ 个位置的变化精确为 $0$，说明因果性成立；最后位置变化 $3.06$，说明扰动确实进入了计算。参数量为 $4\times768^2=2\,359\,296$，与第 1 节的核算一致。这一测试可以推广为任何实现的单元检验：随机初始化一层注意力，扰动位置 $t$，检查所有 $t'<t$ 的输出是否逐元素不变。

如果误把 FA3 布局当作 SDPA 布局，直接对 $(B,T,H,d_k)$ 做 `q @ q.transpose(-2, -1)`，得到的不是注意力矩阵，而是同一位置不同头之间的 $H\times H$ 内积：形状为 $(B,T,H,H)$，`softmax` 会沿头维归一化，程序不报错，语义完全错误。这类错误的检验方法是打印打分张量的形状，确认第二维是 $T$ 而不是 $H$。

### 例 3：仓库中的前向核心

下面是 `nanochat/gpt.py` 的 `CausalSelfAttention.forward` 主体（省略 value embedding 与注释），可与上文逐段对照：

```python
def forward(self, x, ve, cos_sin, window_size, kv_cache):
    B, T, C = x.size()
    q = self.c_q(x).view(B, T, self.n_head, self.head_dim)      # (B,T,H,D)
    k = self.c_k(x).view(B, T, self.n_kv_head, self.head_dim)
    v = self.c_v(x).view(B, T, self.n_kv_head, self.head_dim)

    cos, sin = cos_sin
    q, k = apply_rotary_emb(q, cos, sin), apply_rotary_emb(k, cos, sin)
    q, k = norm(q), norm(k)      # QK 归一化
    q = q * 1.2
    k = k * 1.2

    if kv_cache is None:
        y = flash_attn.flash_attn_func(q, k, v, causal=True, window_size=window_size)
    else:
        k_cache, v_cache = kv_cache.get_layer_cache(self.layer_idx)
        y = flash_attn.flash_attn_with_kvcache(
            q, k_cache, v_cache, k=k, v=v,
            cache_seqlens=kv_cache.cache_seqlens,
            causal=True, window_size=window_size,
        )
        if self.layer_idx == kv_cache.n_layers - 1:
            kv_cache.advance(T)

    y = y.contiguous().view(B, T, -1)
    y = self.c_proj(y)
    return y
```

对照要点有三条。第一，`q` 的形状是 $(B,T,H,d_k)$，没有 `.transpose(1,2)`；SDPA 回退在 `flash_attention.py` 内部完成转置，因此上层代码只写一套。第二，`window_size` 是 `(left, right)` 元组，训练与推理传同一个值；`GPT.forward` 按层取 `self.window_sizes[i]`。第三，`kv_cache` 分支只影响键值的来源与位置推进，不改变查询、键的投影与 RoPE 的计算方式；训练与推理共用同一套权重与同一套旋转。

## 易错点

> [!warning] 以下六条均可在形状、数值或单元测试中直接检验。
> 1. 布局与转置混用。FA3 布局 $(B,T,H,d_k)$ 下若要手写打分，必须写成 `torch.einsum("bthd,bshd->bhts", q, k)` 或先 `transpose(1,2)`；写成 `q @ k.transpose(-2,-1)` 得到 $(B,T,H,H)$，沿头维做 softmax，形状与运行都不报错，语义完全错误。检验方法：打印打分形状，第二维必须是 $T$。
> 2. 缩放维度或次数错误。缩放因子应为 $1/\sqrt{d_k}$，其中 $d_k=C/H$；用 $\sqrt{C}$ 会过度缩小，等价于提高温度；同时在打分与查询上各除一次，等效因子为 $1/d_k$，分布过平且梯度尺度异常。检验方法：随机初始化后打印打分标准差，缩放后应约为 $1$（nanochat 因 $1.2^2$ 约为 $1.44$）。
> 3. 因果掩码方向反了。布尔掩码的 `True` 与 `-inf` 语义、`triu` 与 `tril` 的选择只要错一处，模型就变成“只能看未来”；损失通常仍会下降（因为最后一个位置可看到全部输入），但生成质量崩溃。检验方法：扰动最后一个 token，检查前面位置的输出是否逐元素不变。
> 4. 推理时 RoPE 未按缓存位置偏移。解码阶段 `T0 = kv_cache.get_pos()`，`cos_sin` 取 `self.cos[:, T0:T0+T]`；若固定取 `self.cos[:, :T]`，每个新 token 都被当作位置 $0$，查询与缓存中键的相对位置全错，输出会退化为乱码而不报错。
> 5. `window_size` 的端点语义。nanochat 传 `(left, 0)`，FA3 与 SDPA 回退都按“距离不超过 `left`”实现，即包含当前 token，最多 `left + 1` 个键；把 `left` 当作“总键数”会少算一个位置。SDPA 回退的掩码写作 `(row_idx - col_idx) <= window`，可直接核对端点。
> 6. 在错误精度下调用 FA3。FA3 的 Hopper 内核只支持 bf16 与 fp8；fp16 或 fp32 时 `USE_FA3` 为 `False`，自动回退 SDPA。若强制把 `_override_impl` 设为 `'fa3'`，`_resolve_use_fa3` 只断言 FA3 可用、不再检查 dtype，fp16/fp32 输入会在内核处失败或给出错误结果；若忽略警告，训练速度会显著下降，`dev/LOG.md` 2026-01-16 记录了这一回退的代价。

## 关联笔记

- 前置 [[注意力机制与QKV]]（跨库）：该篇给出缩放点积注意力的来源、QKV 的几何解释与标准多头形式；本篇只补充方差推导、因果掩码的工程含义与 nanochat 的落地差异。
- 后续 [[多头注意力]]：本篇按“单头”叙述并给出 $H$ 个头的通用形式，该篇展开拆分与合并的形状链、head_dim 选择、GQA 的参数与缓存收益。
- 后续 [[位置编码与RoPE]]：注意力对位置是置换等变的，必须由外部注入位置信息；该篇给出 nanochat 的旋转实现与 `rotary_seq_len` 缓存。
- 后续 [[FlashAttention与高效注意力]]：本篇的 `flash_attn_func` 调用只是接口，该篇解释分块、重计算与 FA3 的布局约束，以及 SDPA 回退的差异。
- 后续 [[KV Cache原理]]：本篇「在 nanochat 中的落地」一节的推理分支只说明缓存读写的位置，该篇给出缓存形状、显存公式与 prefill/decode 的代价分解。

## 达标检测

- [ ] 写出自注意力的四式定义，并说明 $\mathbf{W}_Q$、$\mathbf{W}_K$、$\mathbf{W}_V$、$\mathbf{W}_O$ 各自的形状与参数量；对 d12 与 d24 分别给出单层注意力的参数量。
- [ ] 从 $q_i,k_i$ 独立同分布、均值 $0$、方差 $1$ 的前提出发，推导 $\operatorname{Var}(\mathbf{q}^{\top}\mathbf{k})=d_k$，并说明除以 $\sqrt{d_k}$ 后 softmax 的雅可比为何不再趋零。
- [ ] 用 $T=3$、$d_k=2$ 的手算例子复现例 1 的 $\mathbf{S}$、$\mathbf{A}$、$\mathbf{O}$，并解释第 $1$ 行权重 $[0.3302,0.6698]$ 的来源。
- [ ] 运行例 2，报告扰动最后一个 token 前后前 $7$ 个位置与最后位置的最大变化，并说明该结果与因果掩码的关系。
- [ ] 说明 FA3 布局与 SDPA 布局的差异，指出 `flash_attention.py` 在何处转置，以及 `CausalSelfAttention.forward` 为何不转置。
- [ ] 解释 `window_size=(left, 0)` 的端点语义，并计算 $T=2048$ 时 `"SSSL"` 模式在 d12 中每层实际使用的窗口；指出仓库注释与运行值不一致之处。
- [ ] 写出单层注意力的前向 FLOPs 表达式 $8TC^2+4T^2C$，并代入 d24 的 $C=1536$、$T=2048$ 给出两项数值。

## 参考来源

- Vaswani et al., "Attention Is All You Need", arXiv:1706.03762, 第 3.2.1–3.2.3 节 —— 对应本篇第 1 节的 QKV 投影、第 2 节的 $\sqrt{d_k}$ 缩放与第 4 节的掩码。
- Dao et al., "FlashAttention: Fast and Memory-Efficient Exact Attention with IO-Awareness", arXiv:2205.14135 —— 对应第 4 节把掩码交给内核的实现方式与「在 nanochat 中的落地」一节 FA3/SDPA 两条路径的动机。
- Karpathy, *nanochat*，`nanochat/gpt.py` 的 `CausalSelfAttention`、`nanochat/flash_attention.py`、`dev/LOG.md` 2026-01-11「Sliding Window Attention」与 2026-01-16「Flash Attention 3 Fallback to SDPA」条目（commit 92d63d4）—— 对应第 4 节的窗口公式、「在 nanochat 中的落地」一节的逐段代码与回退路径。
- Chowdhery et al., "PaLM: Scaling Language Modeling with Pathways", arXiv:2204.02311 —— 对应第 5 节 `estimate_flops` 中 $12hqT$ 的注意力 FLOPs 核算方式（`gpt.py` 的注释直接引用该论文）。
- Raschka, *Build a Large Language Model (From Scratch)*, 2024, 第 3 章 —— 对应第 3 节的掩码后 softmax、「在 nanochat 中的落地」一节的形状链与例 2 的实现对照。
