上一篇完成了不含位置编码的因果多头自注意力。如果只看那一套矩阵乘法,把输入序列前两个 token 交换顺序(并在因果 mask 允许的范围内看同一个后缀 query 对它们的点积),点积本身并不知道哪个 key 离当前 query 更近、哪个更远。
现代语言模型(LLaMA、Qwen 等)普遍采用 RoPE(Rotary Position Embedding,旋转位置编码) 来注入相对位置信息。这一篇记录 cs336_basics/rope.py 与带 RoPE 的 MultiHeadSelfAttention 的完整推导、形状对齐与单元测试验证。
为什么把 维向量拆成 个二维平面#
在二维平面上,把一个向量 逆时针旋转角度 ,对应的正交变换矩阵是:
如果位置 的 query 二维向量旋转 ,位置 的 key 二维向量旋转 ,那么它们旋转后的点积满足正交旋转群的加性性质:
也就是说,虽然旋转操作是按每个 token 自己的绝对位置 和 独立施加在 和 上的,但点积注意力分数只依赖它们的相对位置差 。
推广到每头维度 (要求 为偶数),RoPE 将第 对相邻分量 视为一个独立的二维子空间,赋予按几何级数递减的角频率:
低维对( 小)波长短、旋转快,对局部相邻 token 顺序敏感;高维对( 大)波长长、旋转慢,负责承载长距离相对位置关系。
预计算 cos_cached 与 sin_cached:为什么用 register_buffer#
因为 只依赖位置编号 、特征对下标 和超参数 ,完全不包含可训练参数,如果在每次 forward 时重新调用 torch.outer 和三角函数,会产生不必要的重复开销。
但也不能直接把预计算好的张量挂在普通属性 self.cos_cached 上——那样调用 model.to(device) 时,普通属性不会跟着模型迁移设备;而如果包进 nn.Parameter,优化器又会误以为它是可训练权重,甚至写进 state_dict 破坏官方权重加载检查。
PyTorch 的标准解法是 self.register_buffer(..., persistent=False):
pair_dims = torch.arange(0, d_k, 2, device=device, dtype=torch.float32)
inv_freq = theta ** (-pair_dims / d_k)
positions = torch.arange(max_seq_len, device=device, dtype=torch.float32)
angles = torch.outer(positions, inv_freq)
self.register_buffer("cos_cached", torch.cos(angles), persistent=False)
self.register_buffer("sin_cached", torch.sin(angles), persistent=False)
这里有三个关键细节:
| 设计点 | 原因 |
|---|---|
torch.arange(0, d_k, 2) | 直接生成偶教学下标 ,恰好对应公式中的 |
torch.outer(positions, inv_freq) | 一次性生成形状为 (max_seq_len, d_k // 2) 的角度表 |
persistent=False | 跟随模块迁移 device,但不写入 state_dict(),保证 load_state_dict 与官方测试快照严格对齐 |
奇偶切片与 torch.stack 交错还原#
在 RotaryPositionalEmbedding.forward(self, x, token_positions) 中,输入 x 的形状是 (..., seq_len, d_k),其中前导维度 ... 可以是 (batch,),也可以是拆头后的 (batch, num_heads)。
我们无需显式拼出稀疏的 分块对角矩阵,只需沿最后一维按步长 2 切出偶数位和奇数位:
cos = self.cos_cached[token_positions]
sin = self.sin_cached[token_positions]
x_even = x[..., 0::2]
x_odd = x[..., 1::2]
rotated_even = x_even * cos - x_odd * sin
rotated_odd = x_even * sin + x_odd * cos
rotate = torch.stack((rotated_even, rotated_odd), dim=-1)
return rotate.reshape(x.shape).to(dtype=x.dtype)
为什么最后要用 torch.stack(..., dim=-1) 再 .reshape(x.shape),而不是直接 torch.cat((rotated_even, rotated_odd), dim=-1)?
用一组 4 维向量对照就能一眼看清:
rotated_even包含新向量的第[0, 2]号分量,形状为(..., seq_len, 2);rotated_odd包含新向量的第[1, 3]号分量,形状为(..., seq_len, 2);- 如果用
torch.cat(..., dim=-1),排出来的顺序会变成[0, 2, 1, 3],把原本成对的相邻坐标拆成了前后两半; - 用
torch.stack(..., dim=-1)先得到(..., seq_len, 2, 2),其中最后两维分别是[[第0分量, 第1分量], [第2分量, 第3分量]],紧接着.reshape(x.shape)按行展平,就精确还原了[0, 1, 2, 3]的交错顺序。
接入多头自注意力:只旋转 Q、K,以及 token_positions 的广播轴#
把 RoPE 放进 MultiHeadSelfAttention 时,有两个极易踩坑的位置:
第一,RoPE 只能作用在拆头后的 和 上,绝对不能作用在 上,而且每个头的旋转维度必须是 d_head = d_model // num_heads,而不是 d_model。因为每个注意力头各自在一个 d_head 维空间内计算点积,所有头共享同一组位置编码规则。
第二,token_positions 与四维张量 (batch, num_heads, seq_len, d_head) 的广播对齐。在官方测试 test_multihead_self_attention_with_rope 中,传入的 token_positions 形状是 (1, seq_len)(二维),而拆头后的 q 形状是 (batch, num_heads, seq_len, d_head)(四维):
q_even 的形状: (batch, num_heads, seq_len, d_head // 2)
直接索引 cos_cached[token_positions]:(1, seq_len, d_head // 2)
如果直接相乘,PyTorch 从右往左对齐维度时,会把 1 对齐到 num_heads(4),完全没问题;但如果调用者传入的 token_positions 形状是 (batch, seq_len)(即 batch > 1 且没有 num_heads 这一维),那么 (batch, seq_len, d_head // 2) 的第 0 维 batch 就会错误地和 q_even 的第 1 维 num_heads 对齐!
为了同时兼容一维 (seq_len,)、二维 (batch, seq_len) 以及带 head 维度的 token_positions,我们在 MultiHeadSelfAttention.forward 中加入显式维度对齐:
if self.rope is not None:
if token_positions is None:
token_positions = torch.arange(seq_len, device=x.device, dtype=torch.long)
elif token_positions.ndim == x.ndim - 1:
token_positions = token_positions.unsqueeze(-2)
q = self.rope(q, token_positions)
k = self.rope(k, token_positions)
当输入 x 是 (batch, seq_len, d_model)(3 维)而 token_positions 是 (batch, seq_len)(2 维)时,unsqueeze(-2) 把它变成 (batch, 1, seq_len)。这样索引 cos_cached 后得到的 (batch, 1, seq_len, d_head // 2) 就能在 num_heads 轴上安全广播给所有头。
官方测试验证结果#
对接 adapters.py 中的 run_rope 与 run_multihead_self_attention_with_rope 后,运行官方测试:
tests/test_model.py::test_rope PASSED
tests/test_model.py::test_multihead_self_attention_with_rope PASSED
两项测试均在 atol=1e-5 容差下与官方快照完全吻合。下一篇继续把带 RoPE 的多头自注意力、RMSNorm 和 SwiGLU 组装成 Pre-Norm Transformer Block 与完整 Transformer LM。
封面使用 aigc-image-generator 辅助生成,属于概念插画;准确的公式、形状与代码逻辑以正文为准。

评论
评论由 GitHub Discussions 驱动,使用 GitHub 账号登录即可留言。