多头注意力
定义
多头注意力(multi-head attention)是把模型维度 切成 个互不重叠的 维子空间,在每个子空间内独立执行一次缩放点积注意力,再把 个输出沿通道维拼接、经一个共享的输出投影混合的运算。设第 个头的投影为 ,则
其中 表示沿最后一维拼接,。
符号与术语如下。
| 符号 | 含义 |
|---|---|
模型维度,代码中为 n_embd | |
查询头数,代码中为 n_head | |
键、值头数,代码中为 n_kv_head; 时退化为标准多头 | |
每头维度,代码中为 head_dim, | |
| 等 | 第 个头的投影,形状 |
| 输出投影,形状 ,按头分成 个列块 | |
| GQA 的组大小,,每个键值头被 个查询头共享 |
分组查询注意力(grouped-query attention,GQA)是 的多头注意力:查询仍有 个头,键与值只有 个头,第 个查询头使用第 个键值头。 时称为多查询注意力(multi-query attention), 时退化为标准多头。头维度(head dimension) 是每个头独立做 softmax 的向量长度。
为什么重要
单个 softmax 只能给出一个概率分布。当模型需要同时从多个位置读取不同信息时(例如一个头跟踪相邻 token、另一个头定位句法上的主语),单个分布必须在这些位置之间分配质量,导致每个位置分到的权重被摊薄。多头把通道空间切成 份,每份拥有独立的查询、键、值投影与独立的 softmax,因而可以并行地表达 种不同的读取模式。关键在于:在 时,参数量与 FLOPs 与“单个 维头”完全相同,多头没有增加矩阵乘的规模,只增加了张量重排与 次小规模 softmax。
多头也是工程实现中最容易出错的结构。头维与 token 维的先后顺序、拆分与拼接的互逆性、缩放用的是 还是 、GQA 的分组顺序,任何一处错误都可能在形状上完全合法,只表现为训练变慢或指标下降。nanochat 的 CausalSelfAttention 用 view(B,T,H,D) 直接得到 FA3 布局,避免转置;flash_attention.py 的回退路径再把它转成 SDPA 的 。两种布局的换算关系是复现与调试时必须掌握的内容。
GQA 则直接决定推理成本。KV 缓存的大小与 成正比,而解码阶段每步要读入全部缓存;把 从 降到 可以把缓存与读取量降到 ,代价是键值头被多个查询头共享、表达能力略降。nanochat 当前配置把 n_kv_head 设为与 n_head 相等(d24 中两者都是 ),因此训练与推理走的是标准多头;但代码路径、断言与缓存分配都按 GQA 编写,改 GPTConfig 即可启用。
在全书中的位置:本篇承接 自注意力机制 的单头推导,给出多头拆分、合并、head_dim 选择与 GQA 的完整形状链;位置编码与RoPE 在每个头上作用于查询与键的通道对;KV Cache原理 使用本篇的 计算显存。跨库的通用推导见 因果注意力与多头注意力,GQA 的论文背景见 分组查询注意力GQA,本篇只写 nanochat 的落地差异。
原理与推导
1 拆分头的动机与参数核算
把 按列切成 块,每块 列:
对每个 独立执行一次缩放点积注意力(单头形式见 自注意力机制),得到 ,拼接后
其中 是 的第 个列块,形状 。这个分解式说明各头的贡献在输出端被线性混合:损失不分别监督各个头, 汇聚全部头的输出。
参数量的关键事实是它与 无关。三个输入投影各 、输出投影 ,合计
与“一个 维单头”完全相同。计算量也相同:打分的两次矩阵乘合计 ,投影合计 , 只决定这些运算被切成多少个小矩阵乘。拆分头的代价是 次 softmax 的行归一化( 逐元素运算)与张量重排,收益是 个独立的归一化分布。
若启用 GQA(),键与值投影的输出维变为 ,参数量降为
以 d24(、)为例: 时为 ; 时为 ; 时为 。
计算量的核算与参数不同。打分与加权两项只取决于查询头数,与键值头数无关:
因为每个查询头仍要与全部键做内积,GQA 只是让多个查询头读同一份键值。投影项的 FLOPs 为 乘以“各投影输出维之和再乘 ”,因此 GQA 只削减键值投影那一部分。下表给出三种配置的对比()。
| 配置 | c_q 参数 | c_k+c_v 参数 | c_proj 参数 | 每层注意力参数 | 每层投影 FLOPs |
|---|---|---|---|---|---|
| d24, | |||||
| d24, | |||||
| d12, |
表中投影 FLOPs 的前向表达式为 ,d24 稠密配置为 。打分与加权的 在 d24 为 ,与投影项同量级;两项都随 或 增长,没有一项可以被忽略。
2 形状变换:拆分、转置、拼接
以 d12(、、)、、 为例, 时的完整形状链如下。
| 步骤 | 操作 | 形状 |
|---|---|---|
| 输入 | ||
| 查询投影 | c_q(x) | |
| 拆头(FA3 布局) | view(B,T,H,d_h) | |
| 换轴(SDPA 布局) | transpose(1,2) | |
| 打分 | ||
| softmax | 沿最后一维 | |
| 加权 | ||
| 换回 | transpose(1,2) | |
| 拼头 | contiguous().view(B,T,C) | |
| 输出投影 | c_proj |
view(B,T,H,d_h) 的语义是沿最后一维按行优先切分:第 个头占据通道区间 , 维不参与切分。拆分的逆操作是把最后两维合并 view(B,T,C),得到与拆分前相同的通道顺序。只要中间出现过别的重排(例如把 折进头维),就必须有相应的逆操作才能恢复;否则输出投影的列可以补偿一个固定的通道置换,却无法补偿 token 与头的错配。
两种布局的分工如下。FA3 的原生输入输出是 ,nanochat 直接使用该布局,全程不转置;SDPA 的原生布局是 ,回退路径在 flash_attention.py 内部转置。view 要求张量连续,因此从 SDPA 布局换回时必须先 contiguous():transpose 只交换步长,不复制数据,直接 view 会抛出步长错误。
3 head_dim 的选择
与 通过 耦合,给定 时只能二选一。nanochat 的选择是固定 ,让 随深度变化:
| 深度 | ||
|---|---|---|
| d12 | 768 | 6 |
| d20 | 1280 | 10 |
| d24 | 1536 | 12 |
| d26 | 1664 | 13 |
scripts/base_train.py 把 --head-dim 的默认值设为 ,先由 --aspect-ratio(默认 )算出 base_dim = depth * aspect_ratio,再向上取整到 的倍数,保证 model_dim // head_dim 恰好为整数且等于目标头维度。取整只在 不是 的倍数时起作用,也就是奇数深度:以 d25 为例,,,向上取整到 ,头数为 ;偶数深度的 已是 的倍数,不会改变宽度。
的依据来自实验而非公式。dev/LOG.md 2026-01-17 的记录写道,在固定 FLOPs 的扫描中“Head dim definitely prefers to be 128 instead of 64, i.e. fewer bigger heads”,同一段还记录模型偏好更瘦更长的形状(aspect ratio 优于 )。机制上可以给出三条解释:其一, 越大,每个头内可用的特征子空间越大,单头能表达的匹配模式越丰富;其二, 决定 softmax 的输入维度, 缩放后打分方差相同,但头的数量减少会降低 次小规模 softmax 与重排的相对开销;其三,FA3 等内核要求 能被 整除, 是满足约束且对 tensor core 友好的取值。
代价在 KV 缓存:缓存大小正比于 ;在 时它等于 ,与 的取值无关。只有启用 GQA、把 降到 以下,缓存才随 成比例下降。
4 多头与单头的等价性
单头是多头在 时的特例,因此多头是单头的严格推广。反方向需要额外条件。设所有头共享同一组查询、键投影且注意力权重相同(),则
右端是一个单头注意力,其值投影为 、输出投影为单位阵。也就是说,若各头的权重退化到相同,多头可以折叠成一个单头;只要各头的 不同,折叠就不成立。
更一般的表述是:单个头的输出是值向量的一个凸组合,权重和为 ;多头输出是 个凸组合经不同线性映射后的和,一般不在单个凸包内。取 、两个头分别把全部质量放在位置 与 、值投影相同、 的两个列块都把对应头的输出原样写入同一组通道,则输出在该组通道上是 ;要由单个凸组合得到该向量,需要权重之和为 ,与归一化矛盾。这一对照说明多头的表达能力不是“把单个头算 遍”,而是“ 个分布经共享输出投影混合”。
5 GQA:键值头共享
GQA 令 ,第 个查询头使用第 个键值头,。等价实现是把键值头按组复制 份再送入标准多头;这在数学上与“共享”完全一致,但复制会浪费显存,因此内核直接在索引层面处理。
收益有两项。第一,参数:键值投影从 降为 。第二,推理缓存:KV 缓存每 token 的字节数为
其中 为层数、因子 对应键与值。d24(、、bf16 每元素 字节)在 时为 字节( KiB)/token, 个 token 为 MiB; 时为 KiB/token、 MiB; 时为 KiB/token、 MiB。解码每步要读入全部缓存,因此这项下降直接转化为吞吐提升。
代价是键值表示被 个查询头共用,模型不能为每个头学习独立的键值子空间。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,默认值均为 (d12 的默认配置)。CausalSelfAttention.__init__ 中:
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)
两条断言分别保证 能被 整除、 能整除 。第二条断言同时排除了 的情形;若把它写反(self.n_kv_head % self.n_head == 0), 时仍能通过,但 GQA 配置会在下游形状处失败。c_k、c_v 的输出维是 ,不是 ;在默认配置下两者恰好相等,容易在启用 GQA 后忘记这一点。
拆分与合并。 前向使用 FA3 布局,查询、键、值各自 view 到自己的头数:
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) 把 合并为 ;这里的 -1 由内存布局决定,等于 。若误写成 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 在内部按 分组。回退路径在 flash_attention.py 中:
enable_gqa = q.size(1) != k.size(1)
y = _sdpa_attention(q, k, v, window_size, enable_gqa)
enable_gqa 由头数是否相等自动推出,SDPA 按“查询头 使用键值头 ”的约定展开。测试中把头数相同的标准多头与 enable_gqa=True 的 GQA 输出比较,最大差值为 (见例 2)。
KV 缓存。 nanochat/engine.py 的 KVCache 以 num_heads 为参数分配 (n_layers, B, T, H, D),调用方传入的是 m.n_kv_head:
kv_model_kwargs = {"num_heads": m.n_kv_head, "head_dim": m.n_embd // m.n_head, "num_layers": m.n_layer}
因此缓存的实际头数是 ,不是 。若这里误传 n_head,启用 GQA 后缓存会多分配 倍,且 FA3 的 flash_attn_with_kvcache 会因头数不匹配报错;在默认配置下两者相等,错误被掩盖到切换 GQA 时才暴露。
关键直觉
机制性表述
多头把通道空间分成 份,每份独立做一次“打分—softmax—加权”,因此得到 个互不相同的归一化分布;拼接后用同一个 混合。参数量与计算量在 时与单头相同,多出来的是 次 softmax 与重排。 决定每个头内部 softmax 的维度,nanochat 固定 ; 决定推理时缓存与带宽,nanochat 的代码支持 GQA,但当前默认 。
该表述与严格定义的关系:第 1 节给出逐头的分解式与 参数量,第 2 节给出拆分与拼接的形状链,第 3 节给出 的实验依据,第 4 节给出多头折叠为单头的条件,第 5 节给出 GQA 的索引约定与缓存公式。四者合起来说明:多头的“独立”只成立于参数与 softmax 两个层面,输出端始终由 混合。
例子与代码
例 1:NumPy 最小多头实现与 PyTorch 对照
下面的 NumPy 实现显式完成“投影—拆头—掩码—softmax—加权—拼头—输出投影”,PyTorch 版本用 F.scaled_dot_product_attention 作为参照。取 、、、,。
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))
输出形状 (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 舍入量级,说明拆分、掩码、拼接的顺序正确。第 行只有一个允许位置,权重为 one-hot;每行权重和精确为 。若把 NumPy 的 .reshape(B,T,H,Dh).transpose(0,2,1,3) 换成 .reshape(B,H,T,Dh),元素总数相同、形状也合法,但 token 与头错配;输出不会报错,只是与 PyTorch 的差值升到 。这正是多头实现最隐蔽的错误类型。
例 2:GQA 的展开与缓存核算
PyTorch 的 SDPA 支持 enable_gqa=True。把 、 的键值头按 repeat_interleave 展开后与 enable_gqa 路径比较,可以验证分组顺序。
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))
两种展开的最大差 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) 把每个键值头连续复制 份,得到 的顺序,第 个查询头对应第 个键值头;若误用 repeat(平铺),顺序变为 ,查询头 会去匹配键值头 ,分组整体错位且不报错。缓存数字与第 5 节的公式一致: 字节。
例 3:仓库中的配置与形状
nanochat/gpt.py 的 GPTConfig 与 CausalSelfAttention.__init__ 是上述结论的直接来源:
@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 的形状:、、。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 的输出维自动缩小。
易错点
以下六条均可由形状、数值或对照实验直接检验。
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. 缩放用错维度。缩放因子是 ,不是 ;d12 中 、,两者相差 。用错会让 softmax 过平或过尖,且不会报错。
4. GQA 分组顺序错误。应使用
repeat_interleave(g, dim=1)或内核的enable_gqa,得到 ;用repeat得到交错顺序,查询头与键值头的对应关系整体错位,形状不变。5. KV 缓存按
n_head分配。启用 GQA 后缓存应为 ;按 分配会多占 倍显存,并在flash_attn_with_kvcache处因头数不匹配报错。默认配置下 ,错误被掩盖。6. 断言写反或省略。
assert self.n_kv_head <= self.n_head and self.n_head % self.n_kv_head == 0同时排除 与不整除;写成n_kv_head % n_head == 0在默认配置下仍通过,直到启用 GQA 才暴露。n_embd % n_head == 0同样不可省:省略后head_dim被整数除法截断,拼接结果在c_proj处出现形状错误。
关联笔记
- 前置 自注意力机制:该篇给出单头的缩放点积推导、因果掩码与 nanochat 前向的逐段代码;本篇把“一个头”扩展为 个头并核算参数与 FLOPs。
- 后续 位置编码与RoPE:位置旋转作用在每个头的查询与键上,形状为 ,按头广播;该篇给出频率、约定与缓存。
- 后续 KV Cache原理:本篇的 是缓存大小的决定项,该篇给出 prefill/decode 的完整代价分解与显存公式。
- 对照 因果注意力与多头注意力(跨库):该篇给出因果掩码的归纳证明、掩码实现对照与注意力头专门化的解释边界;本篇只保留多头拆分、GQA 与 nanochat 落地。
- 对照 分组查询注意力GQA(跨库):该篇给出 GQA 的论文动机与实验结论;本篇给出 nanochat 的断言、
enable_gqa回退路径与缓存核算。
达标检测
- [ ] 写出多头的逐头定义式与拼接式,并证明 时参数量为 、与 无关。
- [ ] 画出 d12、、 从输入到输出的完整形状链,标出 FA3 布局与 SDPA 布局的分歧点。
- [ ] 说明 的三条依据,并计算 d12、d20、d24、d26 的头数。
- [ ] 给出多头折叠为单头的充分条件,并用 的例子说明多头输出一般不在单个凸包内。
- [ ] 运行例 1,报告 NumPy 与 PyTorch 的最大差、注意力形状与第 0 行权重;解释把拆分写成
view(B,H,T,d_h)后差值为何升到 。 - [ ] 运行例 2,报告
enable_gqa与repeat_interleave的最大差,并计算 d24 在 时的每 token 缓存字节数。 - [ ] 指出
CausalSelfAttention的两条断言各排除什么错误配置,并说明KVCache为何接收n_kv_head。
参考来源
- Vaswani et al., "Attention Is All You Need", arXiv:1706.03762, 第 3.2.2 节 —— 对应本篇第 1 节的逐头投影、拼接与 参数量。
- 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.md2026-01-17「Various experiments」条目(commit 92d63d4)—— 对应第 3 节的 head_dim 实验记录与「在 nanochat 中的落地」一节的断言、形状与缓存参数。 - Raschka, Build a Large Language Model (From Scratch), 2024, 第 3 章 —— 对应第 2 节的拆头与合并实现,以及例 1 的对照方法。