LLM Guide / 学习笔记 · 更新于 2026-09-23
多头注意力:把形状和掩码写对
用张量形状、完整代码和边界用例检查 MHA 与 GQA。
GitHub 初稿 ↗写注意力时,最容易卡住的地方通常是 transpose 之后的形状,以及 mask 到底屏蔽了谁。先把这两件事对齐,公式对应到代码就比较直接了。下面只讨论同一段输入上的自注意力,不包含位置编码和增量 KV Cache。
一行输出是怎么来的
输入
这里的
以
| 运算 | 结果形状 |
|---|---|
| 线性投影 | [2, 5, 32] |
| 拆成 4 个头并交换维度 | [2, 4, 5, 8] |
q @ k.transpose(-1, -2) |
[2, 4, 5, 5] |
权重乘 v |
[2, 4, 5, 8] |
| 拼接各头并输出投影 | [2, 5, 32] |
分数矩阵倒数第二维对应“谁在查询”,最后一维对应“能看哪些位置”。Softmax 沿最后一维做。把这两个维度弄反,程序仍可能跑通,但算的已经不是预期的注意力。
把 MHA 和 GQA 放在一份实现里
MHA 中,Q、K、V 的头数相同。GQA 保留 Q 的头数,让一组 Query 共享 K、V。下面用 kv_heads 控制区别:等于 heads 时是 MHA,等于 1 时是 MQA,介于两者之间时是 GQA。
import math
import torch
from torch import nn
class SelfAttention(nn.Module):
def __init__(self, dim, heads, kv_heads=None, dropout=0.0):
super().__init__()
kv_heads = heads if kv_heads is None else kv_heads
if heads <= 0 or kv_heads <= 0:
raise ValueError("head counts must be positive")
if dim % heads or heads % kv_heads:
raise ValueError("dim % heads and heads % kv_heads must be zero")
self.heads, self.kv_heads = heads, kv_heads
self.d = dim // heads
self.q = nn.Linear(dim, dim, bias=False)
self.k = nn.Linear(dim, kv_heads * self.d, bias=False)
self.v = nn.Linear(dim, kv_heads * self.d, bias=False)
self.out = nn.Linear(dim, dim, bias=False)
self.drop = nn.Dropout(dropout)
def forward(self, x, padding_mask=None, causal=True):
b, t, dim = x.shape
q = self.q(x).view(b, t, self.heads, self.d).transpose(1, 2)
k = self.k(x).view(b, t, self.kv_heads, self.d).transpose(1, 2)
v = self.v(x).view(b, t, self.kv_heads, self.d).transpose(1, 2)
repeat = self.heads // self.kv_heads
k = k.repeat_interleave(repeat, dim=1)
v = v.repeat_interleave(repeat, dim=1)
# allowed=True 表示可以读取这个 key。
allowed = torch.ones(t, t, dtype=torch.bool, device=x.device)
if causal:
allowed = allowed.tril()
allowed = allowed[None, None, :, :]
if padding_mask is not None:
if padding_mask.shape != (b, t) or padding_mask.dtype != torch.bool:
raise ValueError("padding_mask must be bool with shape [B, T]")
allowed = allowed & ~padding_mask[:, None, None, :]
scores = (q @ k.transpose(-1, -2)).float() / math.sqrt(self.d)
scores = scores.masked_fill(~allowed, float("-inf"))
# 全部 key 都被屏蔽的行单独处理,避免 softmax(-inf, ...) 得到 NaN。
empty = ~allowed.any(dim=-1, keepdim=True)
scores = scores.masked_fill(empty, 0.0)
weights = scores.softmax(dim=-1).masked_fill(~allowed, 0.0)
y = self.drop(weights).to(v.dtype) @ v
y = y.transpose(1, 2).contiguous().view(b, t, dim)
y = self.out(y)
if padding_mask is not None:
y = y.masked_fill(padding_mask[:, :, None], 0.0)
return y
if __name__ == "__main__":
torch.manual_seed(7)
x = torch.randn(2, 5, 32)
pad = torch.tensor([[False, False, False, True, True],
[False, False, False, False, True]])
layer = SelfAttention(dim=32, heads=4, kv_heads=2)
y = layer(x, padding_mask=pad)
assert y.shape == x.shape
assert torch.isfinite(y).all()
assert torch.count_nonzero(y[pad]) == 0
print(y.shape)
这里用 repeat_interleave 展开 K、V,是为了让共享关系容易看清。它会复制数据,不能用这段教学实现的内存占用来证明 GQA 的缓存收益。推理引擎应保存未展开的 KV,并用支持分组读取的内核计算。
两种 mask 别混在一起
因果 mask 限制时间顺序。第 2 个位置可以看 0、1、2,不能看后面的 token。Padding mask 处理补齐位置,与因果关系是两回事。上面约定 padding_mask=True 表示补齐,而内部的 allowed=True 表示允许读取,名字写清楚比记一个布尔值可靠。
PyTorch 的 scaled_dot_product_attention 使用布尔 mask 时,True 表示参与计算;nn.MultiheadAttention 的 key_padding_mask=True 表示忽略。把一个接口的 mask 原样传给另一个接口,很容易把可见区域反过来。
只屏蔽 padding 的 Key,并不会自动让 padding 对应的 Query 输出为零。所以示例最后又清零了这些行。如果接进完整 Transformer,残差分支还可能带回 padding 位置的值,训练 loss 也仍需单独忽略这些位置。
形状正确之后,还要查什么
可以固定随机种子,先关闭 dropout,再和官方 SDPA 的输出比较。接着改动输入末尾的 token:在因果模式下,前面位置的输出应该保持不变。这比只打印一个 [B,T,D] 更能说明 mask 生效了。
还应覆盖左侧 padding、整条输入都是 padding、不同 KV 头数,以及反向传播是否出现非有限值。做增量解码时,Query 长度可能为 1,Key 长度却是整个历史长度;此时因果 mask 要按绝对位置构造,不能直接照搬方形下三角矩阵。
实际项目可以优先使用 PyTorch SDPA。它根据设备、数据类型和形状选择可用实现;调用了这个接口并不保证每次都走 FlashAttention。
相关论文:Attention Is All You Need、GQA。缓存大小的区别放在 显存占用笔记 里算。