大模型原理与训练 / 系统课时
实现多头注意力模块
实现多头注意力模块
本课将从张量接口出发,实现一个可直接运行的 PyTorch 多头自注意力模块。重点不是调用现成封装,而是亲手完成查询、键和值投影、分头、缩放点积、掩码广播、合并多头,并用形状和掩码结果验证实现正确性。
学习目标
- 实现多头自注意力的完整前向计算
- 掌握
B × L × D与B × H × L × d之间的维度转换 - 正确处理填充掩码的广播与全遮蔽边界
模块接口与张量约定
模块输入 x 的形状为 B × L × D,其中 B 是批次大小,L 是序列长度,D 是模型维度。多头数量为 H 时,每个头的维度为 ,因此必须满足 D 能被 H 整除。
本实现使用一次线性层同时生成查询、键和值,再拆成三个张量。输出仍保持 B × L × D,注意力权重则保留为 B × H × L × L,便于调试每个头对各键位置的分配。
维度转换的执行链路

最容易出错的地方是合并多头。transpose(1, 2) 后张量的内存通常不连续,因此在 view 前必须调用 contiguous(),否则可能报错或依赖不安全的内存布局假设。
完整 PyTorch 实现
下面的实现接受两种常用布尔掩码:B × L 的填充键掩码,以及 B × L × L 的逐查询掩码。掩码中 True 表示允许关注,False 表示屏蔽。
import math
import torch
from torch import nn
class MultiHeadSelfAttention(nn.Module):
def __init__(
self,
d_model: int,
num_heads: int,
dropout: float = 0.0,
) -> None:
super().__init__()
if d_model % num_heads != 0:
raise ValueError("d_model 必须能被 num_heads 整除")
self.d_model = d_model
self.num_heads = num_heads
self.head_dim = d_model // num_heads
self.qkv_proj = nn.Linear(d_model, 3 * d_model)
self.out_proj = nn.Linear(d_model, d_model)
self.dropout = nn.Dropout(dropout)
def forward(
self,
x: torch.Tensor,
attention_mask: torch.Tensor | None = None,
) -> tuple[torch.Tensor, torch.Tensor]:
if x.ndim != 3:
raise ValueError("x 必须是 [batch, length, d_model]")
batch_size, length, d_model = x.shape
if d_model != self.d_model:
raise ValueError("输入最后一维与 d_model 不一致")
# [B, L, 3D] -> [3, B, H, L, d]
qkv = self.qkv_proj(x)
qkv = qkv.view(
batch_size,
length,
3,
self.num_heads,
self.head_dim,
).permute(2, 0, 3, 1, 4)
query, key, value = qkv.unbind(dim=0)
scores = torch.matmul(
query, key.transpose(-2, -1)
) / math.sqrt(self.head_dim)
if attention_mask is not None:
mask = attention_mask.to(
device=x.device, dtype=torch.bool
)
if mask.ndim == 2:
if mask.shape != (batch_size, length):
raise ValueError("二维掩码必须是 [B, L]")
mask = mask[:, None, None, :]
elif mask.ndim == 3:
if mask.shape != (batch_size, length, length):
raise ValueError("三维掩码必须是 [B, L, L]")
mask = mask[:, None, :, :]
else:
raise ValueError("掩码只支持 [B, L] 或 [B, L, L]")
# 每个查询至少保留一个键,避免 Softmax 无有效元素
if not mask.any(dim=-1).all():
raise ValueError("每个查询位置至少要保留一个键")
scores = scores.masked_fill(
~mask, torch.finfo(scores.dtype).min
)
weights = torch.softmax(scores, dim=-1)
weights = self.dropout(weights)
context = torch.matmul(weights, value)
# [B, H, L, d] -> [B, L, D]
context = context.transpose(1, 2).contiguous()
context = context.view(batch_size, length, self.d_model)
output = self.out_proj(context)
return output, weights
torch.manual_seed(7)
attention = MultiHeadSelfAttention(d_model=8, num_heads=2)
inputs = torch.randn(2, 4, 8)
padding_mask = torch.tensor(
[
[True, True, True, False],
[True, True, True, True],
]
)
outputs, weights = attention(inputs, padding_mask)
print("output shape:", tuple(outputs.shape))
print("weights shape:", tuple(weights.shape))
print(
"masked key max:",
float(weights[0, :, :, 3].max().detach()),
)预期输出:
output shape: (2, 4, 8)
weights shape: (2, 2, 4, 4)
masked key max: 0.0第三行验证第一条样本的第 4 个键位置在所有头、所有查询上都没有获得注意力权重。随机初始化会改变未屏蔽位置的具体权重,但不会改变形状与被屏蔽位置为零这一结果。
掩码广播为何有效
填充掩码原始形状为 B × L,它描述每个样本中哪些键位置有效。转换为 B × 1 × 1 × L 后,两个值为 1 的维度会分别广播到所有注意力头和所有查询位置,因此同一样本中的每个查询都会屏蔽相同的填充键。
逐查询掩码使用 B × L × L,扩展为 B × 1 × L × L 后只在头维广播。它可以表达因查询位置而变化的规则,例如因果注意力。若要构造因果掩码,应显式生成每个样本的下三角矩阵,再按三维形式传入,避免把 L × L 与 B × L 的二维语义混淆。
关键边界与验证方法
首先检查 D % H == 0,否则无法把模型维度均匀拆给各个头。其次检查掩码语义:本实现约定 True 为保留,若上游使用相反约定,必须先取反。
仅屏蔽键并不会让填充查询位置的输出自动变为零。训练时通常还会在损失函数中忽略填充位置,或在注意力输出后再次乘以查询有效掩码。开启 dropout 后,返回的 weights 是 dropout 之后的权重,训练模式下各行之和不一定严格等于 1;调试原始概率时应设置 dropout=0 或返回 dropout 前的副本。
本课总结
- 多头注意力的核心是把
D拆成H × d并行计算,再恢复为原模型维度 B × L填充掩码应扩展为B × 1 × 1 × L,从而同时广播到全部头和查询- 形状检查、全遮蔽检查与被屏蔽权重为零,是验证自定义实现的关键手段
下一课预告
下一课将把位置表示与多头注意力接入 Transformer 子层,并继续处理残差连接、层归一化和前馈网络之间的执行顺序。