LLM Guide / 学习笔记 · 更新于 2026-09-23

多头注意力:把形状和掩码写对

用张量形状、完整代码和边界用例检查 MHA 与 GQA。

GitHub 初稿 ↗

写注意力时,最容易卡住的地方通常是 transpose 之后的形状,以及 mask 到底屏蔽了谁。先把这两件事对齐,公式对应到代码就比较直接了。下面只讨论同一段输入上的自注意力,不包含位置编码和增量 KV Cache。

一行输出是怎么来的

输入 XX 的形状是 [B,T,D][B,T,D]。每个 token 经过三个线性投影,得到 Query、Key 和 Value。Query 与各个 Key 的点积给出分数,Softmax 把分数归一化,再对 Value 加权求和:

O=softmax⁡(QK⊤d+M)V O=\operatorname{softmax}\left(\frac{QK^\top}{\sqrt{d}}+M\right)V

这里的 dd 是单个头的维度,MM 在允许访问的位置取 0,屏蔽的位置取负无穷。除以 d\sqrt d 是为了控制点积的尺度;如果各维分量近似独立、方差为 1,点积方差会随 dd 增长,Softmax 就更容易进入很尖锐的区域。

以 B=2,T=5,D=32,H=4B=2,T=5,D=32,H=4 为例,单头维度是 8:

运算 结果形状
线性投影 [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。缓存大小的区别放在 显存占用笔记 里算。

← 返回学习笔记