---
tags: [nanochat, transformer, multihead]
阶段: 04-Transformer架构
难度: ★★★
created: 2026-10-22
related: "[[自注意力机制]], [[位置编码与RoPE]], [[KV Cache原理]], [[分组查询注意力GQA]]"
---

# 多头注意力

## 定义

**多头注意力**（multi-head attention）是把模型维度 $C$ 切成 $H$ 个互不重叠的 $d_h$ 维子空间，在每个子空间内独立执行一次缩放点积注意力，再把 $H$ 个输出沿通道维拼接、经一个共享的输出投影混合的运算。设第 $i$ 个头的投影为 $\mathbf{W}_Q^{i},\mathbf{W}_K^{i},\mathbf{W}_V^{i}\in\mathbb{R}^{C\times d_h}$，则

$$
\mathbf{O}_i=\operatorname{softmax}\!\left(\frac{\mathbf{X}\mathbf{W}_Q^{i}\big(\mathbf{X}\mathbf{W}_K^{i}\big)^{\top}}{\sqrt{d_h}}+\mathbf{M}\right)\mathbf{X}\mathbf{W}_V^{i},
\qquad
\mathbf{Y}=\Big[\mathbf{O}_1;\dots;\mathbf{O}_H\Big]\mathbf{W}_O,
$$

其中 $[\cdot;\cdot]$ 表示沿最后一维拼接，$\mathbf{W}_O\in\mathbb{R}^{C\times C}$。

符号与术语如下。

| 符号 | 含义 |
|---|---|
| $C$ | 模型维度，代码中为 `n_embd` |
| $H$ | 查询头数，代码中为 `n_head` |
| $H_{kv}$ | 键、值头数，代码中为 `n_kv_head`；$H_{kv}=H$ 时退化为标准多头 |
| $d_h$ | 每头维度，代码中为 `head_dim`，$d_h=C/H$ |
| $\mathbf{W}_Q^{i}$ 等 | 第 $i$ 个头的投影，形状 $(C,d_h)$ |
| $\mathbf{W}_O$ | 输出投影，形状 $(C,C)$，按头分成 $H$ 个列块 |
| $g$ | GQA 的组大小，$g=H/H_{kv}$，每个键值头被 $g$ 个查询头共享 |

**分组查询注意力**（grouped-query attention，GQA）是 $H_{kv}<H$ 的多头注意力：查询仍有 $H$ 个头，键与值只有 $H_{kv}$ 个头，第 $i$ 个查询头使用第 $\lfloor i/g\rfloor$ 个键值头。$H_{kv}=1$ 时称为多查询注意力（multi-query attention），$H_{kv}=H$ 时退化为标准多头。**头维度**（head dimension）$d_h$ 是每个头独立做 softmax 的向量长度。

## 为什么重要

单个 softmax 只能给出一个概率分布。当模型需要同时从多个位置读取不同信息时（例如一个头跟踪相邻 token、另一个头定位句法上的主语），单个分布必须在这些位置之间分配质量，导致每个位置分到的权重被摊薄。多头把通道空间切成 $H$ 份，每份拥有独立的查询、键、值投影与独立的 softmax，因而可以并行地表达 $H$ 种不同的读取模式。关键在于：在 $H_{kv}=H$ 时，参数量与 FLOPs 与“单个 $C$ 维头”完全相同，多头没有增加矩阵乘的规模，只增加了张量重排与 $H$ 次小规模 softmax。

多头也是工程实现中最容易出错的结构。头维与 token 维的先后顺序、拆分与拼接的互逆性、缩放用的是 $d_h$ 还是 $C$、GQA 的分组顺序，任何一处错误都可能在形状上完全合法，只表现为训练变慢或指标下降。nanochat 的 `CausalSelfAttention` 用 `view(B,T,H,D)` 直接得到 FA3 布局，避免转置；`flash_attention.py` 的回退路径再把它转成 SDPA 的 $(B,H,T,D)$。两种布局的换算关系是复现与调试时必须掌握的内容。

GQA 则直接决定推理成本。KV 缓存的大小与 $H_{kv}d_h$ 成正比，而解码阶段每步要读入全部缓存；把 $H_{kv}$ 从 $H$ 降到 $H/6$ 可以把缓存与读取量降到 $1/6$，代价是键值头被多个查询头共享、表达能力略降。nanochat 当前配置把 `n_kv_head` 设为与 `n_head` 相等（d24 中两者都是 $12$），因此训练与推理走的是标准多头；但代码路径、断言与缓存分配都按 GQA 编写，改 `GPTConfig` 即可启用。

在全书中的位置：本篇承接 [[自注意力机制]] 的单头推导，给出多头拆分、合并、head_dim 选择与 GQA 的完整形状链；[[位置编码与RoPE]] 在每个头上作用于查询与键的通道对；[[KV Cache原理]] 使用本篇的 $H_{kv}d_h$ 计算显存。跨库的通用推导见 [[因果注意力与多头注意力]]，GQA 的论文背景见 [[分组查询注意力GQA]]，本篇只写 nanochat 的落地差异。

## 原理与推导

### 1 拆分头的动机与参数核算

把 $\mathbf{W}_Q$ 按列切成 $H$ 块，每块 $d_h$ 列：

$$
\mathbf{W}_Q=\big[\mathbf{W}_Q^{1}\;\big|\;\cdots\;\big|\;\mathbf{W}_Q^{H}\big],\qquad
\mathbf{Q}_i=\mathbf{X}\mathbf{W}_Q^{i}\in\mathbb{R}^{T\times d_h}.
$$

对每个 $\mathbf{Q}_i,\mathbf{K}_i,\mathbf{V}_i$ 独立执行一次缩放点积注意力（单头形式见 [[自注意力机制]]），得到 $\mathbf{O}_i\in\mathbb{R}^{T\times d_h}$，拼接后

$$
\mathbf{Y}=\big[\mathbf{O}_1;\dots;\mathbf{O}_H\big]\mathbf{W}_O
=\sum_{i=1}^{H}\mathbf{W}_O^{i}\mathbf{O}_i,
$$

其中 $\mathbf{W}_O^{i}$ 是 $\mathbf{W}_O$ 的第 $i$ 个列块，形状 $(d_h,C)$。这个分解式说明各头的贡献在输出端被线性混合：损失不分别监督各个头，$\partial\mathcal{L}/\partial\mathbf{W}_O$ 汇聚全部头的输出。

参数量的关键事实是它与 $H$ 无关。三个输入投影各 $C\times C$、输出投影 $C\times C$，合计

$$
3C^2+C^2=4C^2,
$$

与“一个 $C$ 维单头”完全相同。计算量也相同：打分的两次矩阵乘合计 $4T^2C$，投影合计 $8TC^2$，$H$ 只决定这些运算被切成多少个小矩阵乘。拆分头的代价是 $H$ 次 softmax 的行归一化（$O(T^2H)$ 逐元素运算）与张量重排，收益是 $H$ 个独立的归一化分布。

若启用 GQA（$H_{kv}<H$），键与值投影的输出维变为 $H_{kv}d_h$，参数量降为

$$
C^2+2CH_{kv}d_h+C^2=2C^2+2CH_{kv}d_h .
$$

以 d24（$C=1536$、$d_h=128$）为例：$H_{kv}=12$ 时为 $9\,437\,184$；$H_{kv}=4$ 时为 $2\times1536^2+2\times1536\times512=6\,291\,456$；$H_{kv}=2$ 时为 $4\,718\,592+2\times1536\times256=5\,505\,024$。

计算量的核算与参数不同。打分与加权两项只取决于查询头数，与键值头数无关：

$$
H\cdot 2T^{2}d_h+H\cdot2T^{2}d_h=4T^{2}C,
$$

因为每个查询头仍要与全部键做内积，GQA 只是让多个查询头读同一份键值。投影项的 FLOPs 为 $2T$ 乘以“各投影输出维之和再乘 $C$”，因此 GQA 只削减键值投影那一部分。下表给出三种配置的对比（$T=2048$）。

| 配置 | `c_q` 参数 | `c_k`+`c_v` 参数 | `c_proj` 参数 | 每层注意力参数 | 每层投影 FLOPs |
|---|---|---|---|---|---|
| d24，$H_{kv}=12$ | $2\,359\,296$ | $4\,718\,592$ | $2\,359\,296$ | $9\,437\,184$ | $3.87\times10^{10}$ |
| d24，$H_{kv}=4$ | $2\,359\,296$ | $1\,572\,864$ | $2\,359\,296$ | $6\,291\,456$ | $2.58\times10^{10}$ |
| d12，$H_{kv}=6$ | $589\,824$ | $1\,179\,648$ | $589\,824$ | $2\,359\,296$ | $9.66\times10^{9}$ |

表中投影 FLOPs 的前向表达式为 $2T C\,(C+2H_{kv}d_h+C)$，d24 稠密配置为 $2\times2048\times1536\times6144\approx3.87\times10^{10}$。打分与加权的 $4T^2C$ 在 d24 为 $2.58\times10^{10}$，与投影项同量级；两项都随 $T$ 或 $C$ 增长，没有一项可以被忽略。

### 2 形状变换：拆分、转置、拼接

以 d12（$C=768$、$H=6$、$d_h=128$）、$B=2$、$T=16$ 为例，$H_{kv}=H$ 时的完整形状链如下。

| 步骤 | 操作 | 形状 |
|---|---|---|
| 输入 | $\mathbf{X}$ | $(2,16,768)$ |
| 查询投影 | `c_q(x)` | $(2,16,768)$ |
| 拆头（FA3 布局） | `view(B,T,H,d_h)` | $(2,16,6,128)$ |
| 换轴（SDPA 布局） | `transpose(1,2)` | $(2,6,16,128)$ |
| 打分 | $\mathbf{Q}\mathbf{K}^{\top}/\sqrt{d_h}$ | $(2,6,16,16)$ |
| softmax | 沿最后一维 | $(2,6,16,16)$ |
| 加权 | $\mathbf{A}\mathbf{V}$ | $(2,6,16,128)$ |
| 换回 | `transpose(1,2)` | $(2,16,6,128)$ |
| 拼头 | `contiguous().view(B,T,C)` | $(2,16,768)$ |
| 输出投影 | `c_proj` | $(2,16,768)$ |

`view(B,T,H,d_h)` 的语义是沿最后一维按行优先切分：第 $i$ 个头占据通道区间 $[i d_h,(i+1)d_h)$，$T$ 维不参与切分。拆分的逆操作是把最后两维合并 `view(B,T,C)`，得到与拆分前相同的通道顺序。只要中间出现过别的重排（例如把 $T$ 折进头维），就必须有相应的逆操作才能恢复；否则输出投影的列可以补偿一个固定的通道置换，却无法补偿 token 与头的错配。

两种布局的分工如下。FA3 的原生输入输出是 $(B,T,H,d_h)$，nanochat 直接使用该布局，全程不转置；SDPA 的原生布局是 $(B,H,T,d_h)$，回退路径在 `flash_attention.py` 内部转置。`view` 要求张量连续，因此从 SDPA 布局换回时必须先 `contiguous()`：`transpose` 只交换步长，不复制数据，直接 `view` 会抛出步长错误。

### 3 head_dim 的选择

$d_h$ 与 $H$ 通过 $C=Hd_h$ 耦合，给定 $C$ 时只能二选一。nanochat 的选择是固定 $d_h=128$，让 $H$ 随深度变化：

| 深度 | $C$ | $H=C/128$ |
|---|---|---|
| d12 | 768 | 6 |
| d20 | 1280 | 10 |
| d24 | 1536 | 12 |
| d26 | 1664 | 13 |

`scripts/base_train.py` 把 `--head-dim` 的默认值设为 $128$，先由 `--aspect-ratio`（默认 $64$）算出 `base_dim = depth * aspect_ratio`，再向上取整到 $128$ 的倍数，保证 `model_dim // head_dim` 恰好为整数且等于目标头维度。取整只在 $depth\times64$ 不是 $128$ 的倍数时起作用，也就是奇数深度：以 d25 为例，$25\times64=1600$，$1600/128=12.5$，向上取整到 $1664$，头数为 $13$；偶数深度的 $depth\times64$ 已是 $128$ 的倍数，不会改变宽度。

$d_h=128$ 的依据来自实验而非公式。`dev/LOG.md` 2026-01-17 的记录写道，在固定 FLOPs 的扫描中“Head dim definitely prefers to be 128 instead of 64, i.e. fewer bigger heads”，同一段还记录模型偏好更瘦更长的形状（aspect ratio $64$ 优于 $128$）。机制上可以给出三条解释：其一，$d_h$ 越大，每个头内可用的特征子空间越大，单头能表达的匹配模式越丰富；其二，$d_h$ 决定 softmax 的输入维度，$\sqrt{d_h}$ 缩放后打分方差相同，但头的数量减少会降低 $H$ 次小规模 softmax 与重排的相对开销；其三，FA3 等内核要求 $d_h$ 能被 $8$ 整除，$128$ 是满足约束且对 tensor core 友好的取值。

代价在 KV 缓存：缓存大小正比于 $H_{kv}d_h$；在 $H_{kv}=H$ 时它等于 $C$，与 $d_h$ 的取值无关。只有启用 GQA、把 $H_{kv}$ 降到 $H$ 以下，缓存才随 $H_{kv}$ 成比例下降。

### 4 多头与单头的等价性

单头是多头在 $H=1$ 时的特例，因此多头是单头的严格推广。反方向需要额外条件。设所有头共享同一组查询、键投影且注意力权重相同（$\mathbf{A}_i=\mathbf{A}$），则

$$
\mathbf{Y}=\sum_{i=1}^{H}\mathbf{W}_O^{i}\mathbf{A}\mathbf{X}\mathbf{W}_V^{i}
=\mathbf{A}\mathbf{X}\Big(\sum_{i=1}^{H}\mathbf{W}_O^{i}\mathbf{W}_V^{i}\Big),
$$

右端是一个单头注意力，其值投影为 $\mathbf{W}_V'=\sum_i\mathbf{W}_O^{i}\mathbf{W}_V^{i}$、输出投影为单位阵。也就是说，若各头的权重退化到相同，多头可以折叠成一个单头；只要各头的 $\mathbf{A}_i$ 不同，折叠就不成立。

更一般的表述是：单个头的输出是值向量的一个凸组合，权重和为 $1$；多头输出是 $H$ 个凸组合经不同线性映射后的和，一般不在单个凸包内。取 $H=2$、两个头分别把全部质量放在位置 $j_1$ 与 $j_2$、值投影相同、$\mathbf{W}_O$ 的两个列块都把对应头的输出原样写入同一组通道，则输出在该组通道上是 $\mathbf{v}_{j_1}+\mathbf{v}_{j_2}$；要由单个凸组合得到该向量，需要权重之和为 $2$，与归一化矛盾。这一对照说明多头的表达能力不是“把单个头算 $H$ 遍”，而是“$H$ 个分布经共享输出投影混合”。

### 5 GQA：键值头共享

GQA 令 $H_{kv}<H$，第 $i$ 个查询头使用第 $\lfloor i/g\rfloor$ 个键值头，$g=H/H_{kv}$。等价实现是把键值头按组复制 $g$ 份再送入标准多头；这在数学上与“共享”完全一致，但复制会浪费显存，因此内核直接在索引层面处理。

收益有两项。第一，参数：键值投影从 $2C^2$ 降为 $2CH_{kv}d_h$。第二，推理缓存：KV 缓存每 token 的字节数为

$$
\text{bytes}=L\cdot 2\cdot H_{kv}\cdot d_h\cdot \text{sizeof(dtype)},
$$

其中 $L$ 为层数、因子 $2$ 对应键与值。d24（$L=24$、$d_h=128$、bf16 每元素 $2$ 字节）在 $H_{kv}=12$ 时为 $147\,456$ 字节（$144$ KiB）/token，$2048$ 个 token 为 $288$ MiB；$H_{kv}=4$ 时为 $48$ KiB/token、$96$ MiB；$H_{kv}=2$ 时为 $24$ KiB/token、$48$ MiB。解码每步要读入全部缓存，因此这项下降直接转化为吞吐提升。

代价是键值表示被 $g$ 个查询头共用，模型不能为每个头学习独立的键值子空间。nanochat 的默认配置没有启用 GQA（`n_kv_head = n_head`），但代码、断言与缓存分配全部支持；`GPT.kv_bytes_per_token` 使用的是 `n_kv_head` 而不是 `n_head`，这一细节决定了启用 GQA 时显存估算是否正确。

### 在 nanochat 中的落地

**配置与断言。** `GPTConfig` 同时有 `n_head` 与 `n_kv_head`，默认值均为 $6$（d12 的默认配置）。`CausalSelfAttention.__init__` 中：

```python
self.head_dim = self.n_embd // self.n_head
assert self.n_embd % self.n_head == 0
assert self.n_kv_head <= self.n_head and self.n_head % self.n_kv_head == 0
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$ 能被 $H$ 整除、$H_{kv}$ 能整除 $H$。第二条断言同时排除了 $H_{kv}>H$ 的情形；若把它写反（`self.n_kv_head % self.n_head == 0`），$H_{kv}=H$ 时仍能通过，但 GQA 配置会在下游形状处失败。`c_k`、`c_v` 的输出维是 $H_{kv}d_h$，不是 $C$；在默认配置下两者恰好相等，容易在启用 GQA 后忘记这一点。

**拆分与合并。** 前向使用 FA3 布局，查询、键、值各自 `view` 到自己的头数：

```python
q = self.c_q(x).view(B, T, self.n_head, self.head_dim)
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)
# 中间经过 RoPE、QK norm、缩放与注意力内核
y = y.contiguous().view(B, T, -1)
y = self.c_proj(y)
```

`view(B,T,-1)` 把 $(B,T,H,d_h)$ 合并为 $(B,T,C)$；这里的 `-1` 由内存布局决定，等于 $H d_h=C$。若误写成 `view(B,T,H)`，形状不匹配会立即报错；若误写成 `view(B,T,d_h)`，元素数不匹配也会报错。真正危险的是把 `view(B,T,H,d_h)` 写成 `view(B,H,T,d_h)`：元素数相同，形状合法，但 token 与头发生错配，没有形状错误可依赖。

**GQA 的内核处理。** 训练时 `flash_attn_func` 直接接收头数不同的 `q` 与 `k`、`v`；FA3 在内部按 $g$ 分组。回退路径在 `flash_attention.py` 中：

```python
enable_gqa = q.size(1) != k.size(1)
y = _sdpa_attention(q, k, v, window_size, enable_gqa)
```

`enable_gqa` 由头数是否相等自动推出，SDPA 按“查询头 $i$ 使用键值头 $\lfloor i/g\rfloor$”的约定展开。测试中把头数相同的标准多头与 `enable_gqa=True` 的 GQA 输出比较，最大差值为 $0$（见例 2）。

**KV 缓存。** `nanochat/engine.py` 的 `KVCache` 以 `num_heads` 为参数分配 `(n_layers, B, T, H, D)`，调用方传入的是 `m.n_kv_head`：

```python
kv_model_kwargs = {"num_heads": m.n_kv_head, "head_dim": m.n_embd // m.n_head, "num_layers": m.n_layer}
```

因此缓存的实际头数是 $H_{kv}$，不是 $H$。若这里误传 `n_head`，启用 GQA 后缓存会多分配 $g$ 倍，且 FA3 的 `flash_attn_with_kvcache` 会因头数不匹配报错；在默认配置下两者相等，错误被掩盖到切换 GQA 时才暴露。

## 关键直觉

> [!tip] 机制性表述
> 多头把通道空间分成 $H$ 份，每份独立做一次“打分—softmax—加权”，因此得到 $H$ 个互不相同的归一化分布；拼接后用同一个 $\mathbf{W}_O$ 混合。参数量与计算量在 $H_{kv}=H$ 时与单头相同，多出来的是 $H$ 次 softmax 与重排。$d_h$ 决定每个头内部 softmax 的维度，nanochat 固定 $d_h=128$；$H_{kv}$ 决定推理时缓存与带宽，nanochat 的代码支持 GQA，但当前默认 $H_{kv}=H$。

该表述与严格定义的关系：第 1 节给出逐头的分解式与 $4C^2$ 参数量，第 2 节给出拆分与拼接的形状链，第 3 节给出 $d_h$ 的实验依据，第 4 节给出多头折叠为单头的条件，第 5 节给出 GQA 的索引约定与缓存公式。四者合起来说明：多头的“独立”只成立于参数与 softmax 两个层面，输出端始终由 $\mathbf{W}_O$ 混合。

## 例子与代码

### 例 1：NumPy 最小多头实现与 PyTorch 对照

下面的 NumPy 实现显式完成“投影—拆头—掩码—softmax—加权—拼头—输出投影”，PyTorch 版本用 `F.scaled_dot_product_attention` 作为参照。取 $B=2$、$T=6$、$C=8$、$H=2$，$d_h=4$。

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

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)

def multi_head_numpy(X, Wq, Wk, Wv, Wo, H):
    B, T, C = X.shape
    Dh = C // H
    Q = (X @ Wq).reshape(B, T, H, Dh).transpose(0, 2, 1, 3)   # (B,H,T,Dh)
    K = (X @ Wk).reshape(B, T, H, Dh).transpose(0, 2, 1, 3)
    V = (X @ Wv).reshape(B, T, H, Dh).transpose(0, 2, 1, 3)
    S = Q @ K.transpose(0, 1, 3, 2) / np.sqrt(Dh)             # (B,H,T,T)
    mask = np.triu(np.ones((T, T), dtype=bool), k=1)          # 未来位置
    A = softmax(np.where(mask, -np.inf, S), -1)
    Y = (A @ V).transpose(0, 2, 1, 3).reshape(B, T, C)        # 拼头
    return Y @ Wo, A

rng = np.random.default_rng(0)
B, T, C, H = 2, 6, 8, 2
X = rng.standard_normal((B, T, C))
Wq, Wk, Wv, Wo = (rng.standard_normal((C, C)) / np.sqrt(C) for _ in range(4))
Y_np, A_np = multi_head_numpy(X, Wq, Wk, Wv, Wo, H)

Xt = torch.tensor(X)
Wqt, Wkt, Wvt, Wot = map(torch.tensor, (Wq, Wk, Wv, Wo))
Dh = C // H
q = (Xt @ Wqt).view(B, T, H, Dh).transpose(1, 2)
k = (Xt @ Wkt).view(B, T, H, Dh).transpose(1, 2)
v = (Xt @ Wvt).view(B, T, H, Dh).transpose(1, 2)
y = F.scaled_dot_product_attention(q, k, v, is_causal=True)
Y_t = (y.transpose(1, 2).contiguous().view(B, T, C) @ Wot).numpy()

print("输出形状", Y_np.shape, "注意力形状", A_np.shape)
print("NumPy 与 PyTorch 最大差", np.abs(Y_np - Y_t).max())
print("第 0 行权重和", A_np.sum(-1)[0, 0])
print("第 0 个头第 0 行权重", A_np[0, 0, 0].round(4))
```

```text
输出形状 (2, 6, 8) 注意力形状 (2, 2, 6, 6)
NumPy 与 PyTorch 最大差 6.661338147750939e-16
第 0 行权重和 [1. 1. 1. 1. 1. 1.]
第 0 个头第 0 行权重 [1. 0. 0. 0. 0. 0.]
```

两者的差值在 float64 舍入量级，说明拆分、掩码、拼接的顺序正确。第 $0$ 行只有一个允许位置，权重为 one-hot；每行权重和精确为 $1$。若把 NumPy 的 `.reshape(B,T,H,Dh).transpose(0,2,1,3)` 换成 `.reshape(B,H,T,Dh)`，元素总数相同、形状也合法，但 token 与头错配；输出不会报错，只是与 PyTorch 的差值升到 $O(1)$。这正是多头实现最隐蔽的错误类型。

### 例 2：GQA 的展开与缓存核算

PyTorch 的 SDPA 支持 `enable_gqa=True`。把 $H=4$、$H_{kv}=2$ 的键值头按 `repeat_interleave` 展开后与 `enable_gqa` 路径比较，可以验证分组顺序。

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

torch.manual_seed(0)
B, T, Dh = 2, 6, 4
Hq, Hkv = 4, 2
q = torch.randn(B, T, Hq, Dh).transpose(1, 2)     # (B,Hq,T,Dh)
k = torch.randn(B, T, Hkv, Dh).transpose(1, 2)    # (B,Hkv,T,Dh)
v = torch.randn(B, T, Hkv, Dh).transpose(1, 2)

y_gqa = F.scaled_dot_product_attention(q, k, v, is_causal=True, enable_gqa=True)
g = Hq // Hkv
k_rep = k.repeat_interleave(g, dim=1)             # 每个键值头连续复制 g 份
v_rep = v.repeat_interleave(g, dim=1)
y_rep = F.scaled_dot_product_attention(q, k_rep, v_rep, is_causal=True)
print("两种展开的最大差", (y_gqa - y_rep).abs().max().item())

L, D, bytes_per = 24, 128, 2
for nkv in (12, 4, 2):
    per_token = L * 2 * nkv * D * bytes_per
    print("H_kv=%2d：%d 字节/token（%.0f KiB），2048 token 缓存 %.0f MiB"
          % (nkv, per_token, per_token / 1024, per_token * 2048 / 2**20))
```

```text
两种展开的最大差 0.0
H_kv=12：147456 字节/token（144 KiB），2048 token 缓存 288 MiB
H_kv= 4：49152 字节/token（48 KiB），2048 token 缓存 96 MiB
H_kv= 2：24576 字节/token（24 KiB），2048 token 缓存 48 MiB
```

`repeat_interleave(g, dim=1)` 把每个键值头连续复制 $g$ 份，得到 $[k_0,k_0,k_1,k_1]$ 的顺序，第 $i$ 个查询头对应第 $\lfloor i/g\rfloor$ 个键值头；若误用 `repeat`（平铺），顺序变为 $[k_0,k_1,k_0,k_1]$，查询头 $1$ 会去匹配键值头 $1$，分组整体错位且不报错。缓存数字与第 5 节的公式一致：$24\times2\times12\times128\times2=147\,456$ 字节。

### 例 3：仓库中的配置与形状

`nanochat/gpt.py` 的 `GPTConfig` 与 `CausalSelfAttention.__init__` 是上述结论的直接来源：

```python
@dataclass
class GPTConfig:
    sequence_len: int = 2048
    vocab_size: int = 32768
    n_layer: int = 12
    n_head: int = 6        # 查询头数
    n_kv_head: int = 6     # 键值头数，GQA 时小于 n_head
    n_embd: int = 768
    window_pattern: str = "SSSL"

class CausalSelfAttention(nn.Module):
    def __init__(self, config, layer_idx):
        super().__init__()
        self.layer_idx = layer_idx
        self.n_head = config.n_head
        self.n_kv_head = config.n_kv_head
        self.n_embd = config.n_embd
        self.head_dim = self.n_embd // self.n_head
        assert self.n_embd % self.n_head == 0
        assert self.n_kv_head <= self.n_head and self.n_head % self.n_kv_head == 0
```

`GPTConfig` 的默认值是 d12 的形状：$C=768$、$H=6$、$d_h=128$。`scripts/base_train.py` 在构造配置时写入 `num_heads = model_dim // args.head_dim`，并令 `n_kv_head=num_heads`；因此按 `--depth` 训练时得到的是标准多头，GQA 需要手动改配置或改脚本。`GPT.kv_bytes_per_token` 使用 `n_kv_head`，`Engine` 构造 `KVCache` 时传入的也是 `m.n_kv_head`，二者可用于核对启用 GQA 后的缓存变化；`GPT.num_scaling_params` 按参数组统计，其中 `transformer_matrices` 一项会随 `c_k`、`c_v` 的输出维自动缩小。

## 易错点

> [!warning] 以下六条均可由形状、数值或对照实验直接检验。
> 1. 拆分顺序错误。`view(B,T,H,d_h)` 与 `view(B,H,T,d_h)` 元素数相同、形状合法；后者把 token 维折进头维，位置与通道错配。检验方法：用三个 token 取相同通道值的输入，检查每个头是否只包含固定通道区间。
> 2. 转置后忘记 `contiguous`。SDPA 布局下 `y.transpose(1,2).view(B,T,C)` 会因步长不连续抛错；正确写法是先 `.contiguous()` 再 `view`，或直接用 `reshape`（隐式复制）。
> 3. 缩放用错维度。缩放因子是 $1/\sqrt{d_h}$，不是 $1/\sqrt{C}$；d12 中 $\sqrt{768}\approx27.7$、$\sqrt{128}\approx11.3$，两者相差 $\sqrt{6}$。用错会让 softmax 过平或过尖，且不会报错。
> 4. GQA 分组顺序错误。应使用 `repeat_interleave(g, dim=1)` 或内核的 `enable_gqa`，得到 $[k_0,k_0,k_1,k_1]$；用 `repeat` 得到交错顺序，查询头与键值头的对应关系整体错位，形状不变。
> 5. KV 缓存按 `n_head` 分配。启用 GQA 后缓存应为 $H_{kv}d_h$；按 $H d_h$ 分配会多占 $g$ 倍显存，并在 `flash_attn_with_kvcache` 处因头数不匹配报错。默认配置下 $H_{kv}=H$，错误被掩盖。
> 6. 断言写反或省略。`assert self.n_kv_head <= self.n_head and self.n_head % self.n_kv_head == 0` 同时排除 $H_{kv}>H$ 与不整除；写成 `n_kv_head % n_head == 0` 在默认配置下仍通过，直到启用 GQA 才暴露。`n_embd % n_head == 0` 同样不可省：省略后 `head_dim` 被整数除法截断，拼接结果在 `c_proj` 处出现形状错误。

## 关联笔记

- 前置 [[自注意力机制]]：该篇给出单头的缩放点积推导、因果掩码与 nanochat 前向的逐段代码；本篇把“一个头”扩展为 $H$ 个头并核算参数与 FLOPs。
- 后续 [[位置编码与RoPE]]：位置旋转作用在每个头的查询与键上，形状为 $(1,T,1,d_h/2)$，按头广播；该篇给出频率、约定与缓存。
- 后续 [[KV Cache原理]]：本篇的 $H_{kv}d_h$ 是缓存大小的决定项，该篇给出 prefill/decode 的完整代价分解与显存公式。
- 对照 [[因果注意力与多头注意力]]（跨库）：该篇给出因果掩码的归纳证明、掩码实现对照与注意力头专门化的解释边界；本篇只保留多头拆分、GQA 与 nanochat 落地。
- 对照 [[分组查询注意力GQA]]（跨库）：该篇给出 GQA 的论文动机与实验结论；本篇给出 nanochat 的断言、`enable_gqa` 回退路径与缓存核算。

## 达标检测

- [ ] 写出多头的逐头定义式与拼接式，并证明 $H_{kv}=H$ 时参数量为 $4C^2$、与 $H$ 无关。
- [ ] 画出 d12、$B=2$、$T=16$ 从输入到输出的完整形状链，标出 FA3 布局与 SDPA 布局的分歧点。
- [ ] 说明 $d_h=128$ 的三条依据，并计算 d12、d20、d24、d26 的头数。
- [ ] 给出多头折叠为单头的充分条件，并用 $H=2$ 的例子说明多头输出一般不在单个凸包内。
- [ ] 运行例 1，报告 NumPy 与 PyTorch 的最大差、注意力形状与第 0 行权重；解释把拆分写成 `view(B,H,T,d_h)` 后差值为何升到 $O(1)$。
- [ ] 运行例 2，报告 `enable_gqa` 与 `repeat_interleave` 的最大差，并计算 d24 在 $H_{kv}=12,4,2$ 时的每 token 缓存字节数。
- [ ] 指出 `CausalSelfAttention` 的两条断言各排除什么错误配置，并说明 `KVCache` 为何接收 `n_kv_head`。

## 参考来源

- Vaswani et al., "Attention Is All You Need", arXiv:1706.03762, 第 3.2.2 节 —— 对应本篇第 1 节的逐头投影、拼接与 $4C^2$ 参数量。
- Ainslie et al., "GQA: Training Generalized Multi-Query Transformer Models from Multi-Head Checkpoints", arXiv:2305.13245 —— 对应第 5 节的键值头共享、组大小与推理缓存收益。
- Dao et al., "FlashAttention: Fast and Memory-Efficient Exact Attention with IO-Awareness", arXiv:2205.14135 —— 对应第 2 节的布局差异与「在 nanochat 中的落地」一节 FA3/SDPA 的转置分工。
- Karpathy, *nanochat*，`nanochat/gpt.py` 的 `GPTConfig` 与 `CausalSelfAttention`、`scripts/base_train.py` 的 `--head-dim`、`nanochat/engine.py` 的 `KVCache`、`dev/LOG.md` 2026-01-17「Various experiments」条目（commit 92d63d4）—— 对应第 3 节的 head_dim 实验记录与「在 nanochat 中的落地」一节的断言、形状与缓存参数。
- Raschka, *Build a Large Language Model (From Scratch)*, 2024, 第 3 章 —— 对应第 2 节的拆头与合并实现，以及例 1 的对照方法。
