大模型原理与训练 / 系统课时
实现带因果掩码的多头注意力
实现带因果掩码的多头注意力
这一节直接实现 GPT 最核心的因果多头自注意力:一次生成 Q、K、V,拆成多个头,屏蔽未来位置,再合并各头结果。完成后会用形状断言和注意力矩阵检查,确认张量流向与因果约束都正确。
学习目标
- 能把
[B, T, C]输入投影并重排为多头 Q、K、V。 - 能构造下三角因果 Mask,保证当前位置看不到未来 Token。
- 能用形状断言和权重检查验证注意力实现。
从输入到注意力输出的数据流
设批量大小为 B、序列长度为 T、嵌入维度为 C、头数为 H,则每个头的维度是 D=C/H。QKV 线性层先把最后一维从 C 扩展到 3C,再切成三份并重排为 [B, H, T, D]。

缩放点积中的除数 sqrt(D) 用来避免头维度增大时点积幅度过大。Mask 必须在 softmax 之前作用于分数矩阵,否则未来位置已经参与归一化,无法真正满足自回归约束。
编写因果多头注意力
下面的示例只依赖 PyTorch。register_buffer 保存因果 Mask,使它随模块迁移设备但不参与梯度更新;三个形状断言分别检查分头、注意力矩阵和最终输出。
import math
import torch
import torch.nn as nn
class CausalMultiHeadAttention(nn.Module):
def __init__(self, embed_dim: int, num_heads: int, max_seq_len: int):
super().__init__()
if embed_dim % num_heads != 0:
raise ValueError("embed_dim must be divisible by num_heads")
self.embed_dim = embed_dim
self.num_heads = num_heads
self.head_dim = embed_dim // num_heads
self.qkv = nn.Linear(embed_dim, 3 * embed_dim, bias=False)
self.out_proj = nn.Linear(embed_dim, embed_dim, bias=False)
mask = torch.tril(
torch.ones(max_seq_len, max_seq_len, dtype=torch.bool)
)
self.register_buffer(
"causal_mask",
mask.view(1, 1, max_seq_len, max_seq_len),
)
def forward(self, x: torch.Tensor):
if x.ndim != 3:
raise ValueError("x must have shape [B, T, C]")
bsz, seq_len, channels = x.shape
if channels != self.embed_dim:
raise ValueError("last dimension does not match embed_dim")
if seq_len > self.causal_mask.size(-1):
raise ValueError("sequence length exceeds max_seq_len")
q, k, v = self.qkv(x).chunk(3, dim=-1)
# [B, T, C] -> [B, H, T, D],让每个头独立计算注意力。
q = q.view(
bsz, seq_len, self.num_heads, self.head_dim
).transpose(1, 2)
k = k.view(
bsz, seq_len, self.num_heads, self.head_dim
).transpose(1, 2)
v = v.view(
bsz, seq_len, self.num_heads, self.head_dim
).transpose(1, 2)
scores = (q @ k.transpose(-2, -1)) / math.sqrt(self.head_dim)
mask = self.causal_mask[:, :, :seq_len, :seq_len]
scores = scores.masked_fill(
~mask, torch.finfo(scores.dtype).min
)
attn = torch.softmax(scores, dim=-1)
context = attn @ v
context = context.transpose(1, 2).contiguous().view(
bsz, seq_len, channels
)
output = self.out_proj(context)
assert q.shape == (
bsz, self.num_heads, seq_len, self.head_dim
)
assert attn.shape == (
bsz, self.num_heads, seq_len, seq_len
)
assert output.shape == x.shape
return output, attn
torch.manual_seed(7)
layer = CausalMultiHeadAttention(
embed_dim=16,
num_heads=4,
max_seq_len=8,
)
x = torch.randn(2, 4, 16)
y, attn = layer(x)
print("output shape:", tuple(y.shape))
print("attention shape:", tuple(attn.shape))
print(
"future positions masked:",
bool(torch.all(torch.triu(attn, diagonal=1) == 0)),
)预期输出如下:
output shape: (2, 4, 16)
attention shape: (2, 4, 4, 4)
future positions masked: True最后一个 True 比只看输出形状更关键:它直接验证了注意力矩阵右上三角的未来位置权重为零。如果这里失败,即使张量维度完全正确,模型仍然可能在训练时偷看后文。
形状为什么这样变化
Q、K、V 分头后都是 [B,H,T,D]。Q @ K^T 只在最后两个维度做矩阵乘法,因此得到 [B,H,T,T];每个查询位置都拥有一行长度为 T 的注意力分布。再与 [B,H,T,D] 的 V 相乘,就回到 [B,H,T,D]。
随后要先 transpose 再 contiguous().view(...)。转置后的张量通常不是连续内存布局,直接用 view 可能报错或表达错误的重排意图。合并头后恢复 [B,T,C],输出投影再混合各头信息。
实现时最容易错的边界
embed_dim 必须能被 num_heads 整除,否则每个头无法获得相同的 D。输入序列长度也不能超过预先创建的 max_seq_len,除非改成按需生成 Mask 或扩展缓存。
因果 Mask 的方向同样值得单独检查:允许区域应是主对角线及其左下方,而不是右上方。只要同时检查输出形状、注意力形状和未来位置权重,就能在接入完整 GPT 之前发现大多数张量布局与掩码错误。