位置编码与RoPE
定义
位置编码(positional encoding)是向模型注入 token 顺序信息的一类机制;没有它,自注意力对所有位置置换等变,序列被当作无序集合。旋转位置编码(rotary position embedding,RoPE)是把查询与键的通道按位置相关的角度成对旋转、使内积中的位置依赖只剩相对位移的编码方式。对第 对通道()定义频率与角度
其中 为位置、 为每头维度 head_dim。位置 的向量 被旋转为
即对第 对通道 施加角度为 的二维旋转。
符号与术语如下。
| 符号 | 含义 |
|---|---|
| 序列长度 | |
每头维度,代码中 head_dim;d12 与 d24 均为 | |
| 通道对下标,;共 对 | |
| 第 对的角频率,单位为弧度/token | |
| 位置 在第 对通道上的旋转角, | |
| 频率基数,当前快照默认 | |
| 二维旋转矩阵 | |
| 两个位置;相对位移为 |
绝对位置编码(absolute positional encoding)把位置信息作为与 token 嵌入同维的向量加到输入上;相对位置编码(relative positional encoding)只让注意力打分依赖 。RoPE 属于后者:位置不进入值向量,也不改变输入嵌入。
为什么重要
自注意力本身对位置是置换等变的。把输入序列的位置随意打乱,输出的每一行只是跟着打乱,打分与加权的过程完全不变。若不额外注入位置信息,模型无法区分“狗咬人”与“人咬狗”,也无法完成需要精确偏移的任务(复制前一个 token、按括号配对、按顺序做算术)。这是自注意力结构性的缺口,不是训练不充分。
注入位置有两条路线。第一条是把位置向量加到 token 嵌入上(正弦编码或可学习嵌入),实现简单,但绝对位置会随训练长度变化,超出训练长度的位置没有定义。第二条是让注意力打分本身携带相对位置:把查询与键旋转,使内积成为内容与相对位移的函数。RoPE 采用第二条,且不增加参数、不改变注意力计算图,只在投影之后加一次逐元素乘加。
nanochat 只使用 RoPE,没有可学习的位置嵌入:GPT 中不存在 wpe,位置信息全部来自 apply_rotary_emb。这带来三个直接后果。其一,检查点更小,序列长度变化不需要重新定义位置表。其二,位置只作用于查询与键,不作用于值,因此值向量可以原样搬运内容。其三,缓存与位置解耦:KV 缓存只存旋转后的键与未旋转的值,解码时按当前绝对位置切片取 ,相对位移自动正确。这一设计是 KV Cache原理 中“缓存键值、查询每步重算”的前提。
在全书中的位置:本篇承接 自注意力机制 的查询—键内积与 多头注意力 的头维度,解释“为什么内积需要旋转”;GPT模型类与config 会展示 GPT.forward 如何切片并传递 cos_sin;FlashAttention与高效注意力 说明旋转后的张量如何进入内核。正弦编码与相对位置的一般理论见跨库 位置编码-正弦与RoPE,本篇只写 RoPE 的推导与 nanochat 的约定。
原理与推导
1 置换等变性:为什么必须注入位置
设 是 的一个置换,。对单头注意力,
其中 是置换矩阵。softmax 逐行作用,而行内元素的置换不改变归一化结果,于是
输出只是跟着输入一起置换。前馈层、残差、归一化都逐位置作用,不破坏这一性质。因此若 只由 token 嵌入构成,整个模型对词序不敏感;位置信息必须在进入第一层之前或注意力内部加入。
2 从绝对位置到相对位置
绝对位置编码把 加到 上。正弦编码 由不同频率的正弦、余弦组成,可学习编码则是一张 的表。两者都使模型能区分位置,但目标性质不同:语言中的许多关系是平移不变的,位置 与 之间的关系,与 与 之间的关系应当用同一套参数描述。绝对编码不直接提供这一性质,模型必须从数据中学会组合。
RoPE 的目标是让打分满足
即内积只通过 依赖位置。实现方式是对查询与键施加与位置有关的正交变换:正交变换保持向量范数,因而注意力打分的尺度不会被位置改变;两个变换的相对组合给出只与位移有关的旋转。
3 二维旋转与复数形式
对一对通道 ,旋转角 的标准二维旋转为
用复数 表示,旋转等价于乘以 :
因此“对第 对通道旋转 ”可以写成“把该对通道视为复数、乘以 ”。 维向量被分成 个这样的二维子空间,每个子空间有自己的频率 。
频率的取法沿用 Transformer 正弦编码的几何级数:
时 ,波长 ; 时 最小,波长最长。原论文取 ;nanochat 的 _precompute_rotary_embeddings 当前默认 ,把最长波长放大约 倍,以缓解长距离上的相位混叠。
4 相对位置性质
把 维向量按通道对分块,记 。标准约定下 、,于是
推导只用两条性质:,以及同频率旋转可加 。右端只通过 依赖位置,内容部分仍由 决定。
nanochat 采用相反的旋转方向。apply_rotary_emb 计算
这正是 作用在 上。于是 、,内积为
两种约定的差别只是 的符号:标准约定给出 ,nanochat 给出 。两者都只依赖相对位移,因此对从零训练的模型功能等价;差别体现在检查点兼容性上,仓库注释说明保留该约定是为了与已有检查点一致。
5 外推问题
RoPE 只保证“训练中见过的相对位移被一致地编码”,不保证“未见过的位移能被正确推断”。原因在频率的周期性。第 对的相对角为 ,它只在模 意义下确定旋转;当 超过 后,不同位移可以给出相同或相近的角度。以 、 为例,各通道的波长与 时的相对角如下。
| 通道对 | 波长 | 的相对角(弧度) |
|---|---|---|
| 0 | 6.3 | 5.965 |
| 1 | 7.5 | 1.796 |
| 8 | 26.5 | 1.852 |
| 16 | 111.7 | 2.070 |
| 32 | 1986.9 | 0.193 |
| 48 | 35332.9 | 0.364 |
| 63 | 524873.8 | 0.0245 |
高频通道( 小)在 内已绕多圈,相位对位移的分辨被 混叠限制;低频通道( 大)在 内只转动零点几弧度,对短距离的分辨率很低。位置编码的“分辨率”由整组频率共同决定:短距离主要靠高频通道,长距离主要靠低频通道。超出训练长度后,低频通道落入未训练的相位区间,注意力打分的分布发生偏移,模型质量下降。rotary_seq_len=sequence_len*10 只是把可计算的 缓存放大,并不等于模型在 10 倍长度上仍有效。
nanochat 没有实现位置插值或频率缩放。若要把上下文扩展到训练长度之外,需要改 rotary_seq_len 之外的东西(例如调整 base 或对位置索引缩放),并重新训练或至少继续训练;仅把缓存放大只解决“切片越界断言”,不解决分布外推。dev/LOG.md 2026-03-24 记录了对每头维度前 施加 RoPE 的尝试(partial RoPE),结论为 slightly worse,未采用;这相当于保留高频通道、放弃低频通道,而在 的上下文里低频通道承担长距离分辨,截断它会削弱长距离信息。
在 nanochat 中的落地
频率与缓存预计算。 GPT.__init__ 先设 rotary_seq_len = config.sequence_len * 10,再调用 _precompute_rotary_embeddings:
def _precompute_rotary_embeddings(self, seq_len, head_dim, base=100000, device=None):
if device is None:
device = self.transformer.wte.weight.device
channel_range = torch.arange(0, head_dim, 2, dtype=torch.float32, device=device)
inv_freq = 1.0 / (base ** (channel_range / head_dim))
t = torch.arange(seq_len, dtype=torch.float32, device=device)
freqs = torch.outer(t, inv_freq)
cos, sin = freqs.cos(), freqs.sin()
cos, sin = cos.to(COMPUTE_DTYPE), sin.to(COMPUTE_DTYPE)
cos, sin = cos[None, :, None, :], sin[None, :, None, :]
return cos, sin
四个细节决定正确性。第一,channel_range 步长为 ,取值为 ,除以 后得到指数 ,即 ;这对应半拆分约定,而不是交错配对。第二,torch.outer(t, inv_freq) 生成 的角度表,第 行第 列是 。第三,cos、sin 被转成 COMPUTE_DTYPE(SM80+ 为 bf16),并扩成 ,前两维用于批量与头广播,第三维 1 表示所有头共用同一组频率。第四,函数在 __init__ 中被调用时模型处于 meta device 上下文,返回的只是形状与 dtype 正确的元张量;真正的数值在 init_weights 中重新计算并赋给 self.cos、self.sin,同时注册为 persistent=False 的缓冲区,不写入检查点。
旋转。 apply_rotary_emb 只做逐元素运算:
def apply_rotary_emb(x, cos, sin):
assert x.ndim == 4
d = x.shape[3] // 2
x1, x2 = x[..., :d], x[..., d:]
y1 = x1 * cos + x2 * sin
y2 = x1 * (-sin) + x2 * cos
return torch.cat([y1, y2], 3)
输入必须四维 ;x1、x2 是通道的前半与后半,不是相邻的奇偶通道。返回值用 cat 拼回原顺序。该函数只对 q、k 调用,不对 v 调用:位置只进入匹配,不改变被搬运的内容。注释明确写出“按 旋转,是教科书约定的转置;功能等价,保留是为了检查点兼容”,这正是第 4 节推导的符号差异。
前向中的切片与断言。 GPT.forward 在前向开始时取当前序列长度对应的角度,并做三条检查:
assert T <= self.cos.size(1), f"Sequence length grew beyond the rotary embeddings cache: {T} > {self.cos.size(1)}"
assert idx.device == self.cos.device, f"Rotary embeddings and idx are on different devices: {idx.device} != {self.cos.device}"
assert self.cos.dtype == COMPUTE_DTYPE, f"Rotary embeddings must be in {COMPUTE_DTYPE}, got {self.cos.dtype}"
T0 = 0 if kv_cache is None else kv_cache.get_pos()
cos_sin = self.cos[:, T0:T0+T], self.sin[:, T0:T0+T]
第一条防止序列长度超过预计算缓存;第二条防止设备不一致(缓冲区随模型迁移,正常路径不会触发,手动搬运张量时可能触发);第三条防止 dtype 不一致导致内核隐式转换。T0 是缓存中的当前位置,解码阶段每步 T=1,切片取出的是第 T0 个位置的角度;这样缓存中的键(在各自位置旋转过)与新查询(在当前位置旋转)之间的相对角度仍然正确。若漏掉 T0 偏移,每个新 token 都被当作位置 ,相对位置整体错位。
缓存大小。 时 rotary_seq_len=20480,每张表 个元素,cos 与 sin 各一份,bf16 下约 MB。仓库注释说明这是“10 倍过度计算,很小很便宜;超过就断言失败”。这一取舍的边界是:缓存放大不改变模型的训练长度,也不改变外推能力,只避免“写长文本时切片越界”这类实现层失败。
与滑动窗口的关系。 window_size 只限制注意力的允许集合,不改变位置编号。短窗层仍然使用全局位置 ,而不是在窗口内重新从 计数;因此同一 token 在不同层、不同窗口模式下看到的相对位移是一致的。若把窗口内的位置重新编号,RoPE 的相对关系会随窗口滑动而跳变,这是实现滑动窗口时容易犯的错误。
关键直觉
机制性表述
RoPE 把每头向量的 个通道对视为复数,按位置乘上 。查询与键各自旋转后,内积中的绝对角度相消,只剩 决定的相对旋转;范数不变,所以注意力打分的尺度不被位置改变。nanochat 对查询与键使用同一套 ,向量按前后半拆分,旋转方向取 ,缓存按 倍序列长度预计算并在前向按当前位置切片。
该表述与严格定义的关系:第 3 节给出旋转矩阵与复数乘法的等价性,第 4 节用 与角度可加性证明相对性,并说明 约定只翻转相对角的符号;「在 nanochat 中的落地」一节把频率、拆分方式、dtype、切片偏移逐一对应到 _precompute_rotary_embeddings 与 apply_rotary_emb。缓存放大与外推能力的区别由第 5 节的频率表说明。
例子与代码
例 1:二维旋转的手算
取 、(只有一对通道),查询内容 位于 ,键内容 位于 。标准约定下 ,,内积为 。
import math
import numpy as np
def rot(phi):
return np.array([[math.cos(phi), -math.sin(phi)],
[math.sin(phi), math.cos(phi)]])
def rot_neg(phi): # nanochat 的 -theta 约定
return np.array([[math.cos(phi), math.sin(phi)],
[-math.sin(phi), math.cos(phi)]])
q = np.array([1.0, 0.0])
k = np.array([1.0, 0.0])
w = 0.5
m, n = 0, 1
print("标准约定内积", (rot(m * w) @ q) @ (rot(n * w) @ k))
print("nanochat 约定内积", (rot_neg(m * w) @ q) @ (rot_neg(n * w) @ k))
print("cos(m-n)w", math.cos((m - n) * w))
print("标准约定 R((n-m)w) 的结果", q @ rot((n - m) * w) @ k)
标准约定内积 0.8775825618903728
nanochat 约定内积 0.8775825618903728
cos(m-n)w 0.8775825618903728
标准约定 R((n-m)w) 的结果 0.8775825618903728
两种约定给出相同的内积,因为这里 、,且内容向量为 、,而余弦是偶函数。取一般内容向量并令 、,标准约定的内积为 ,nanochat 约定为 ;两者都只依赖 ,但作为 的双线性型不同。对从零训练的模型,这一差异等价于把相对位移的方向整体取反,模型可以学到同一类函数;差异只在跨约定加载检查点时才会造成损失上升。
例 2:相对位移的数值验证
用 nanochat 的两个函数处理 、、 的输入。为了让同一行内的内容相同,把同一个 、 复制到所有位置,再按位置旋转;于是同一相对位移的所有配对应当给出相同的内积。
import torch
def apply_rotary_emb(x, cos, sin):
d = x.shape[3] // 2
x1, x2 = x[..., :d], x[..., d:]
y1 = x1 * cos + x2 * sin
y2 = x1 * (-sin) + x2 * cos
return torch.cat([y1, y2], 3)
def precompute(seq_len, head_dim, base=100000):
cr = torch.arange(0, head_dim, 2, dtype=torch.float32)
inv_freq = 1.0 / (base ** (cr / head_dim))
t = torch.arange(seq_len, dtype=torch.float32)
freqs = torch.outer(t, inv_freq)
return freqs.cos()[None, :, None, :], freqs.sin()[None, :, None, :]
torch.manual_seed(1)
T, D = 6, 8
cos, sin = precompute(T, D)
q0 = torch.randn(1, 1, 1, D)
k0 = torch.randn(1, 1, 1, D)
q = q0.expand(1, T, 1, D).clone()
k = k0.expand(1, T, 1, D).clone()
qr, kr = apply_rotary_emb(q, cos, sin), apply_rotary_emb(k, cos, sin)
for delta in range(T):
vals = [(qr[0, m, 0] * kr[0, m - delta, 0]).sum().item() for m in range(delta, T)]
print("delta=%d 内积=%s 极差=%.2e" % (delta, ["%.6f" % v for v in vals], max(vals) - min(vals)))
delta=0 内积=['-1.213566', '-1.213566', '-1.213566', '-1.213566', '-1.213566', '-1.213566'] 极差=2.38e-07
delta=1 内积=['-0.418286', '-0.418286', '-0.418286', '-0.418286', '-0.418286'] 极差=8.94e-08
delta=2 内积=['0.211316', '0.211316', '0.211316', '0.211316'] 极差=1.94e-07
delta=3 内积=['0.118229', '0.118229', '0.118229'] 极差=7.45e-08
delta=4 内积=['-0.590258', '-0.590258'] 极差=5.96e-08
delta=5 内积=['-1.241253'] 极差=0.00e+00
每个 delta 下的内积在 float32 舍入范围内相同,极差约 ,说明内积只依赖相对位移。若把 x[..., :d]、x[..., d:] 改成相邻奇偶通道配对(交错约定),这一性质仍成立,但需同时改 _precompute_rotary_embeddings 的频率排列;两种约定混用会让 与通道对不上,打分中的位置信息退化为噪声,而形状完全不报错。
例 3:频率表与缓存形状
下面的代码复现第 5 节的波长表,并给出 d12 的缓存形状。
import math
import torch
base, d = 100000.0, 128
for i in (0, 1, 8, 16, 32, 48, 63):
w = base ** (-2 * i / d)
angle = (2048 * w) % (2 * math.pi)
print("i=%2d 波长=%12.1f 相对角(2048)=%.4f" % (i, 2 * math.pi / w, angle))
T, head_dim = 2048 * 10, 128
cr = torch.arange(0, head_dim, 2, dtype=torch.float32)
inv_freq = 1.0 / (base ** (cr / head_dim))
freqs = torch.outer(torch.arange(T, dtype=torch.float32), inv_freq)
print("freqs 形状", tuple(freqs.shape))
print("cos 形状", (freqs.cos()[None, :, None, :]).shape)
print("缓存元素数", 2 * T * (head_dim // 2), "bf16 字节", 2 * T * (head_dim // 2) * 2)
i= 0 波长= 6.3 相对角(2048)=5.9648
i= 1 波长= 7.5 相对角(2048)=1.7961
i= 8 波长= 26.5 相对角(2048)=1.8521
i=16 波长= 111.7 相对角(2048)=2.0702
i=32 波长= 1986.9 相对角(2048)=0.1932
i=48 波长= 35332.9 相对角(2048)=0.3642
i=63 波长= 524873.8 相对角(2048)=0.0245
freqs 形状 (20480, 64)
cos 形状 (1, 20480, 1, 64)
缓存元素数 2621440 bf16 字节 5242880
的波长为 ,在 个 token 内绕约 圈; 的波长约 ,在 内只转 弧度。缓存为 的 cos 与 sin 各一份,bf16 共 字节(约 MiB)。这些数字解释了为什么 rotary_seq_len 可以“过度计算 10 倍”:缓存的绝对值小,而按需增长需要处理设备、dtype 与断言,复杂度不划算。
例 4:仓库中的旋转函数
def _precompute_rotary_embeddings(self, seq_len, head_dim, base=100000, device=None):
if device is None:
device = self.transformer.wte.weight.device
channel_range = torch.arange(0, head_dim, 2, dtype=torch.float32, device=device)
inv_freq = 1.0 / (base ** (channel_range / head_dim))
t = torch.arange(seq_len, dtype=torch.float32, device=device)
freqs = torch.outer(t, inv_freq)
cos, sin = freqs.cos(), freqs.sin()
cos, sin = cos.to(COMPUTE_DTYPE), sin.to(COMPUTE_DTYPE)
cos, sin = cos[None, :, None, :], sin[None, :, None, :]
return cos, sin
def apply_rotary_emb(x, cos, sin):
assert x.ndim == 4
d = x.shape[3] // 2
x1, x2 = x[..., :d], x[..., d:]
y1 = x1 * cos + x2 * sin
y2 = x1 * (-sin) + x2 * cos
return torch.cat([y1, y2], 3)
这两个函数与例 2 的实现逐字一致,差别只在例 2 省略了 COMPUTE_DTYPE 转换。base 的默认值是 ,但函数体内首行仍保留着“bump base theta more? e.g. 100K is more common more recently”的注释,说明该默认值经历过修改而注释未同步;以签名与调用为准。
易错点
以下六条均可由形状、数值或对照实验直接检验。
1. 配对方式混用。nanochat 用前后半拆分(
x[..., :d]与x[..., d:]),不是相邻奇偶配对;若apply_rotary_emb与_precompute_rotary_embeddings采用不同配对,形状仍合法,位置信息退化为噪声。检验方法:固定内容向量,比较不同位置的同一相对位移内积是否一致。2. 对值向量也施加旋转。RoPE 只作用于查询与键;若误加到
v,被搬运的内容随位置旋转,模型需要额外容量抵消,通常表现为训练变慢。检查方法:在CausalSelfAttention.forward中确认只有q、k被传入apply_rotary_emb。3. 解码时忘记位置偏移。KV 缓存推理必须用
T0 = kv_cache.get_pos()切片self.cos[:, T0:T0+T];固定取前 行会让每个新 token 都按位置 旋转,缓存中键的相对位置全部错位。4. 频率基数与检查点不匹配。当前代码默认
base=100000;若检查点在训练时使用其它基数(例如常见默认值 ),加载时必须使用训练时的基数,否则 全线偏移,损失升高但不报错。检查方法:打印inv_freq[0]与inv_freq[-1],与训练配置对照。5.
cos/sin形状广播错误。正确形状是 ;若写成 或 ,与 相乘时会触发形状错误,或在 等巧合下静默广播到错误维度。检查方法:打印形状并确认第三维为 。6. 把缓存放大当作外推能力。
rotary_seq_len = sequence_len * 10只保证切片不越界;超过训练长度的位置落入未训练的相位分布,质量下降是模型性质,不是实现 bug。扩展到更长上下文需要改频率或继续训练,并重新评测。
关联笔记
- 前置 自注意力机制:该篇给出查询—键内积与缩放,本篇说明为什么内积需要旋转、旋转如何保持范数。
- 前置 多头注意力:频率表按头广播,每头共享同一组 ;该篇给出头维度与布局,本篇给出 的广播形状。
- 后续 GPT模型类与config:
rotary_seq_len是GPTConfig之外的模型属性,该篇解释__init__的 meta device 上下文与init_weights的重新计算。 - 对照 位置编码-正弦与RoPE(跨库):该篇给出正弦编码、可学习编码与 RoPE 的完整对比和外推方法;本篇只保留 nanochat 的 约定、频率基数与缓存实现。
- 后续 KV Cache原理:缓存保存旋转后的键,解码按当前位置切片角度;该篇给出缓存布局与显存公式。
达标检测
- [ ] 证明自注意力对位置置换等变,并说明为什么仅靠 token 嵌入无法区分词序。
- [ ] 从复数乘法推导二维旋转矩阵,写出 RoPE 对 的变换式,并说明
base与 的关系。 - [ ] 用 与角度可加性证明 只依赖 ;再说明 nanochat 的 约定为何只改变符号。
- [ ] 运行例 2,报告每个
delta的内积极差,并解释极差为何在 float32 舍入量级。 - [ ] 计算 、、 的波长与 的相对角,说明 RoPE 在长距离上的混叠来源。
- [ ] 写出 d12 在 时的
rotary_seq_len、cos形状与 bf16 缓存字节数,并解释为何用 10 倍预计算。 - [ ] 指出解码阶段 RoPE 切片偏移写错时的可观测症状,并给出一个检测该错误的单元测试。
参考来源
- Su et al., "RoFormer: Enhanced Transformer with Rotary Position Embedding", arXiv:2104.09864 —— 对应本篇第 3 节的复数旋转推导、第 4 节的相对位置性质与第 5 节的外推讨论。
- Vaswani et al., "Attention Is All You Need", arXiv:1706.03762, 第 3.5 节 —— 对应第 3 节频率取法 的来源与第 5 节的波长分析。
- Karpathy, nanochat,
nanochat/gpt.py的_precompute_rotary_embeddings、apply_rotary_emb、GPT.forward,dev/LOG.md2026-03-04「Remove autocast, explicit dtype management」与 2026-03-24「Parameter-Golf Ideas Sweep」(commit 92d63d4)—— 对应「在 nanochat 中的落地」一节的缓存、dtype 与断言,以及 约定与 partial RoPE 负结果的记录。 - Raschka, Build a Large Language Model (From Scratch), 2024, 第 3 章 —— 对应第 3 节的位置信息注入方式与例 1 的旋转实现对照。