大模型原理与训练 / 系统课时

实现多头注意力模块

实现多头注意力模块

本课将从张量接口出发,实现一个可直接运行的 PyTorch 多头自注意力模块。重点不是调用现成封装,而是亲手完成查询、键和值投影、分头、缩放点积、掩码广播、合并多头,并用形状和掩码结果验证实现正确性。

学习目标

  • 实现多头自注意力的完整前向计算
  • 掌握 B × L × D 与 B × H × L × d 之间的维度转换
  • 正确处理填充掩码的广播与全遮蔽边界

模块接口与张量约定

模块输入 x 的形状为 B × L × D,其中 B 是批次大小,L 是序列长度,D 是模型维度。多头数量为 H 时,每个头的维度为 d=D/Hd=D/H,因此必须满足 D 能被 H 整除。

本实现使用一次线性层同时生成查询、键和值,再拆成三个张量。输出仍保持 B × L × D,注意力权重则保留为 B × H × L × L,便于调试每个头对各键位置的分配。

维度转换的执行链路

多头注意力的张量变换与合并流程

最容易出错的地方是合并多头。transpose(1, 2) 后张量的内存通常不连续,因此在 view 前必须调用 contiguous(),否则可能报错或依赖不安全的内存布局假设。

完整 PyTorch 实现

下面的实现接受两种常用布尔掩码:B × L 的填充键掩码,以及 B × L × L 的逐查询掩码。掩码中 True 表示允许关注,False 表示屏蔽。

python
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()),
)

预期输出:

text
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 子层,并继续处理残差连接、层归一化和前馈网络之间的执行顺序。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现多头注意力模块

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通