RoPE分别按位置旋转query和key，却能让它们的点积只显式依赖相对位置。关键不在“把位置加进向量”，而在两个旋转矩阵相乘时，角度会相减。理解这个恒等式，也就有了检查位置编号、旋转方向和缓存偏移的直接办法。

下面先从二维旋转推到分块实现，再用可运行测试检查性质。Read in English。

先把要解决的问题写清楚

固定两个已经投影得到的内容向量q与k，位置分别是m和n。如果把两者位置同时加上相同偏移，二者的相对距离没有变化。我们希望显式位置变换后的配对分数也保持不变；这不等于要求不同内容的两个token分数相同。

RoPE来自RoFormer论文。本文核对的是2023年11月8日的arXiv v5原文，初稿于2021年公开；它是基础技术解读，不是今天的新研究发布。下面的数字与测试是为解释恒等式自行构造的，不引用论文的模型成绩。

二维旋转为什么会留下角度差

记R(a)为二维旋转：对(x,y)输出(x cos a−y sin a，x sin a+y cos a)。旋转的转置等于反向旋转，所以R(a)ᵀR(b)=R(b−a)。这是普通平面旋转的性质，不需要借助训练结果才能成立。

按本篇列向量约定，q在m位置转mθ，k在n位置转nθ。两者点积是(R(mθ)q)ᵀ(R(nθ)k)=qᵀR((n−m)θ)k。式子里只剩n−m，绝对位置消去了。若交换q、k或采用不同记号，正负号也要随之检查，不能只凭记住一个m−n。

从二维到多组频率

高维向量可以分成若干二维子空间，每一对使用自己的频率。各对子空间保留同样的相对位置恒等式，再把点积求和。这里用相邻维度配对，四维向量就是(0,1)与(2,3)两组。

教学代码采用θⱼ=10000^(−2j/d)，j从0开始，d为旋转维度。第一组相位变化快，后面的组更慢。实际模型可能只旋转部分维度，或使用不同频率与缩放配置；Transformers旋转位置工具文档列有这些配置，不能把本例默认值硬套到所有检查点。

实现上没必要构造完整d×d矩阵。每对只做几次乘加和三角函数取值，单个向量的旋转工作量随d线性增长。这是旋转操作的复杂度，不是整层注意力或整次生成的复杂度。

把数学性质变成能失败的测试

只检查输出形状，抓不到位置偏移错误。更有用的断言是：同一向量旋转前后范数不变；直接双边旋转与相对旋转给出相同点积；两位置同时平移后点积不变；不支持的奇数维输入明确拒绝。

# Small adjacent-pair RoPE model, not a model inference implementation.
import math

def rotate(v, pos, theta=10000.0):
    if not v or len(v) % 2:
        raise ValueError("nonempty even dimension required")
    out = []
    for j in range(len(v)//2):
        angle = pos * theta ** (-2*j/len(v))
        c, sn = math.cos(angle), math.sin(angle)
        x, y = v[2*j:2*j+2]
        out.extend([x*c-y*sn, x*sn+y*c])
    return out

def dot(a, b):
    return sum(x*y for x,y in zip(a,b))

q, k = [1.,2.,3.,4.], [2.,-1.,0.5,3.]
for m,n in [(0,0),(2,7),(7,2),(-3,8)]:
    lhs = dot(rotate(q,m), rotate(k,n))
    rhs = dot(q, rotate(k,n-m))
    assert math.isclose(lhs, rhs, abs_tol=1e-10)
    shifted = dot(rotate(q,m+23), rotate(k,n+23))
    assert math.isclose(lhs, shifted, abs_tol=1e-10)
assert math.isclose(dot(q,q), dot(rotate(q,9),rotate(q,9)))
try:
    rotate([1.,2.,3.],0)
except ValueError:
    pass
else:
    raise AssertionError("odd dimension was accepted")
# A single-frequency score is periodic, not monotonically decreasing.
assert math.cos(2*math.pi) > math.cos(math.pi)
print("relative offset, shared shift, norm, and odd dimension checks passed")

代码已经本地运行。测试覆盖同位置、正负相对偏移、整体平移、范数与奇数维输入，采用小向量和双精度浮点数，没有运行模型推理。容差只服务于这些数值条件，不能视为任何半精度内核的通用验收阈值。

为什么只检查范数还不够

若query与key使用了不同的频率配置，二者各自仍然是旋转，范数测试可能全部通过。但合并后的相位不再是共同频率乘位置差；共同平移就可能改变点积。问题不在旋转是否正交，而在两侧是否使用了同一个坐标契约。

本地另外构造了query底数10000、key底数1000的四维反例：各自范数保留，但共享位置平移23后分数变化。它提醒我们，单个不变量通过不足以证明实现正确。排查应把范数、相对点积、整体平移与已知数值对照组合起来。

相对位置成立，不代表距离越远分数越低

取二维q=k=(1,0)，分数就是cos((n−m)θ)。角度差为π时是−1，变成2π时反而回到1。这个反例直接说明：不能把RoPE理解成对每一对token都强制单调衰减的距离惩罚。

不同频率叠加与学习到的内容向量可以形成复杂模式，但单个分数仍同时受内容和相位影响。观察论文中的整体性质或统计趋势时，不应把它改写成每个点积都遵守的单调规则。该反例不否定位置编码的作用，只划清了一个常见过度推断。

缓存中的位置必须和计算坐标对齐

增量生成时，新token的物理数组下标不一定等于它的逻辑位置。例如已经处理了若干token，下一步输入只有一个token，它在当前小张量中位于0，但不能因此把它当作整个序列的位置0。位置由当前推理协议决定。

做一个容易理解的检查：保持相同内容和逻辑位置，分别一次性计算与分段计算旋转后的键，比较对应位置的结果。若分段版本每次从零开始编号，而旧键沿用原编号，相对角度就变了；这种偏差可能不会触发任何形状报错。

若缓存里已经保存旋转后的键，读取时再次旋转也会改变相位。实际存储约定要查看所用实现，不能仅凭缓存变量的名字判断。这里提供的是对照思路，没有声称所有框架都保存同一种表示。

换维度配对方式时，先检查权重约定

相邻维度配对和前后半维配对可以表达相同的数学结构，但它们对应的坐标布局不同。只有权重、数据排列与旋转操作一起保持一致，才能比较输出；只替换一个rotate函数，未必兼容原模型。

排错时固定一个小向量，逐组列出参与配对的坐标、频率和角度。先对照单组旋转，再对照点积，最后进入完整注意力。这样可以把布局错误与位置编号错误拆开，避免直接在长文本输出上猜原因。

最开始的相对位置推导还固定了q和k的内容部分。把整段输入放进真实多层网络时，掩码、上下文和前层输出都可能变化，不能只凭这个局部恒等式宣称完整模型任意平移或任意延长后输出完全相同。

能够算更长，不等于能够可靠理解更长

三角函数可以在训练长度之外计算，但公式有定义只是实现条件。更远的相位组合、数值精度及任务难度，都需要目标模型的实际验证。扩大最大位置或改变缩放参数后能返回文本，不足以证明长上下文质量保持不变。

可以把验证分成两步：先用本文的恒等式排除实现错误，再在目标长度与任务上评测模型行为。数学检查失败，就先修位置或布局；数学检查通过，也仍要保留模型评测这一关。若这些小测试帮你定位过一次RoPE问题，欢迎通过文末自愿支持。

资料与验证范围

RoFormer原文，arXiv v5；Transformers RoPE工具文档。图、反例与测试为原创教学内容，无训练或GPU性能测量。10月15日晚补发，文章日期保留当天14:00。