---
tags: [nanochat, transformer, rope]
阶段: 04-Transformer架构
难度: ★★★
created: 2026-10-22
related: "[[自注意力机制]], [[多头注意力]], [[GPT模型类与config]], [[位置编码-正弦与RoPE]]"
---

# 位置编码与RoPE

## 定义

**位置编码**（positional encoding）是向模型注入 token 顺序信息的一类机制；没有它，自注意力对所有位置置换等变，序列被当作无序集合。**旋转位置编码**（rotary position embedding，RoPE）是把查询与键的通道按位置相关的角度成对旋转、使内积中的位置依赖只剩相对位移的编码方式。对第 $i$ 对通道（$i=0,\dots,d/2-1$）定义频率与角度

$$
\omega_i=\text{base}^{-2i/d},\qquad \theta_{t,i}=t\,\omega_i,
$$

其中 $t$ 为位置、$d$ 为每头维度 `head_dim`。位置 $t$ 的向量 $\mathbf{x}\in\mathbb{R}^{d}$ 被旋转为

$$
\tilde{x}_{i}=x_{i}\cos\theta_{t,i}-x_{i+d/2}\sin\theta_{t,i},\qquad
\tilde{x}_{i+d/2}=x_{i}\sin\theta_{t,i}+x_{i+d/2}\cos\theta_{t,i},
$$

即对第 $i$ 对通道 $(x_i,x_{i+d/2})$ 施加角度为 $\theta_{t,i}$ 的二维旋转。

符号与术语如下。

| 符号 | 含义 |
|---|---|
| $T$ | 序列长度 |
| $d$ | 每头维度，代码中 `head_dim`；d12 与 d24 均为 $128$ |
| $i$ | 通道对下标，$0\le i<d/2$；共 $d/2=64$ 对 |
| $\omega_i$ | 第 $i$ 对的角频率，单位为弧度/token |
| $\theta_{t,i}$ | 位置 $t$ 在第 $i$ 对通道上的旋转角，$\theta_{t,i}=t\omega_i$ |
| $\text{base}$ | 频率基数，当前快照默认 $100000$ |
| $\mathbf{R}(\phi)$ | 二维旋转矩阵 $\begin{pmatrix}\cos\phi&-\sin\phi\\\sin\phi&\cos\phi\end{pmatrix}$ |
| $m,n$ | 两个位置；相对位移为 $m-n$ |

**绝对位置编码**（absolute positional encoding）把位置信息作为与 token 嵌入同维的向量加到输入上；**相对位置编码**（relative positional encoding）只让注意力打分依赖 $m-n$。RoPE 属于后者：位置不进入值向量，也不改变输入嵌入。

## 为什么重要

自注意力本身对位置是置换等变的。把输入序列的位置随意打乱，输出的每一行只是跟着打乱，打分与加权的过程完全不变。若不额外注入位置信息，模型无法区分“狗咬人”与“人咬狗”，也无法完成需要精确偏移的任务（复制前一个 token、按括号配对、按顺序做算术）。这是自注意力结构性的缺口，不是训练不充分。

注入位置有两条路线。第一条是把位置向量加到 token 嵌入上（正弦编码或可学习嵌入），实现简单，但绝对位置会随训练长度变化，超出训练长度的位置没有定义。第二条是让注意力打分本身携带相对位置：把查询与键旋转，使内积成为内容与相对位移的函数。RoPE 采用第二条，且不增加参数、不改变注意力计算图，只在投影之后加一次逐元素乘加。

nanochat 只使用 RoPE，没有可学习的位置嵌入：`GPT` 中不存在 `wpe`，位置信息全部来自 `apply_rotary_emb`。这带来三个直接后果。其一，检查点更小，序列长度变化不需要重新定义位置表。其二，位置只作用于查询与键，不作用于值，因此值向量可以原样搬运内容。其三，缓存与位置解耦：KV 缓存只存旋转后的键与未旋转的值，解码时按当前绝对位置切片取 $\cos/\sin$，相对位移自动正确。这一设计是 [[KV Cache原理]] 中“缓存键值、查询每步重算”的前提。

在全书中的位置：本篇承接 [[自注意力机制]] 的查询—键内积与 [[多头注意力]] 的头维度，解释“为什么内积需要旋转”；[[GPT模型类与config]] 会展示 `GPT.forward` 如何切片并传递 `cos_sin`；[[FlashAttention与高效注意力]] 说明旋转后的张量如何进入内核。正弦编码与相对位置的一般理论见跨库 [[位置编码-正弦与RoPE]]，本篇只写 RoPE 的推导与 nanochat 的约定。

## 原理与推导

### 1 置换等变性：为什么必须注入位置

设 $\pi$ 是 $\{1,\dots,T\}$ 的一个置换，$(\pi\mathbf{X})_t=\mathbf{x}_{\pi(t)}$。对单头注意力，

$$
\mathbf{S}=\frac{(\pi\mathbf{X})\mathbf{W}_Q\big((\pi\mathbf{X})\mathbf{W}_K\big)^{\top}}{\sqrt{d}}
=\mathbf{P}_\pi\,\mathbf{X}\mathbf{W}_Q\mathbf{W}_K^{\top}\mathbf{X}^{\top}\mathbf{P}_\pi^{\top},
$$

其中 $\mathbf{P}_\pi$ 是置换矩阵。softmax 逐行作用，而行内元素的置换不改变归一化结果，于是

$$
\operatorname{softmax}(\mathbf{S})=\mathbf{P}_\pi\operatorname{softmax}(\mathbf{S}_0)\mathbf{P}_\pi^{\top},\qquad
\operatorname{Attn}(\pi\mathbf{X})=\mathbf{P}_\pi\operatorname{Attn}(\mathbf{X}).
$$

输出只是跟着输入一起置换。前馈层、残差、归一化都逐位置作用，不破坏这一性质。因此若 $\mathbf{X}$ 只由 token 嵌入构成，整个模型对词序不敏感；位置信息必须在进入第一层之前或注意力内部加入。

### 2 从绝对位置到相对位置

绝对位置编码把 $\mathbf{p}_t$ 加到 $\mathbf{x}_t$ 上。正弦编码 $\mathbf{p}_t$ 由不同频率的正弦、余弦组成，可学习编码则是一张 $T_{\max}\times C$ 的表。两者都使模型能区分位置，但目标性质不同：语言中的许多关系是平移不变的，位置 $t$ 与 $t+\Delta$ 之间的关系，与 $t'$ 与 $t'+\Delta$ 之间的关系应当用同一套参数描述。绝对编码不直接提供这一性质，模型必须从数据中学会组合。

RoPE 的目标是让打分满足

$$
\langle \tilde{\mathbf{q}}_m,\tilde{\mathbf{k}}_n\rangle=f(\mathbf{q}_m,\mathbf{k}_n,m-n),
$$

即内积只通过 $m-n$ 依赖位置。实现方式是对查询与键施加与位置有关的正交变换：正交变换保持向量范数，因而注意力打分的尺度不会被位置改变；两个变换的相对组合给出只与位移有关的旋转。

### 3 二维旋转与复数形式

对一对通道 $(x_1,x_2)$，旋转角 $\phi$ 的标准二维旋转为

$$
\begin{pmatrix}\tilde{x}_1\\\tilde{x}_2\end{pmatrix}
=\begin{pmatrix}\cos\phi&-\sin\phi\\\sin\phi&\cos\phi\end{pmatrix}
\begin{pmatrix}x_1\\x_2\end{pmatrix}.
$$

用复数 $z=x_1+\mathrm{i}x_2$ 表示，旋转等价于乘以 $e^{\mathrm{i}\phi}$：

$$
z\,e^{\mathrm{i}\phi}=(x_1+\mathrm{i}x_2)(\cos\phi+\mathrm{i}\sin\phi)
=(x_1\cos\phi-x_2\sin\phi)+\mathrm{i}(x_1\sin\phi+x_2\cos\phi).
$$

因此“对第 $i$ 对通道旋转 $\theta_{t,i}$”可以写成“把该对通道视为复数、乘以 $e^{\mathrm{i}t\omega_i}$”。$d$ 维向量被分成 $d/2$ 个这样的二维子空间，每个子空间有自己的频率 $\omega_i$。

频率的取法沿用 Transformer 正弦编码的几何级数：

$$
\omega_i=\text{base}^{-2i/d},\qquad i=0,\dots,d/2-1.
$$

$i=0$ 时 $\omega_0=1$，波长 $2\pi$；$i=d/2-1$ 时 $\omega$ 最小，波长最长。原论文取 $\text{base}=10000$；nanochat 的 `_precompute_rotary_embeddings` 当前默认 $\text{base}=100000$，把最长波长放大约 $10$ 倍，以缓解长距离上的相位混叠。

### 4 相对位置性质

把 $d$ 维向量按通道对分块，记 $\mathbf{R}_t=\operatorname{diag}\big(\mathbf{R}(t\omega_0),\dots,\mathbf{R}(t\omega_{d/2-1})\big)$。标准约定下 $\tilde{\mathbf{q}}_m=\mathbf{R}_m\mathbf{q}_m$、$\tilde{\mathbf{k}}_n=\mathbf{R}_n\mathbf{k}_n$，于是

$$
\tilde{\mathbf{q}}_m^{\top}\tilde{\mathbf{k}}_n
=\mathbf{q}_m^{\top}\mathbf{R}_m^{\top}\mathbf{R}_n\mathbf{k}_n
=\mathbf{q}_m^{\top}\mathbf{R}_{n-m}\mathbf{k}_n .
$$

推导只用两条性质：$\mathbf{R}(\phi)^{\top}=\mathbf{R}(-\phi)$，以及同频率旋转可加 $\mathbf{R}(\phi)\mathbf{R}(\psi)=\mathbf{R}(\phi+\psi)$。右端只通过 $n-m$ 依赖位置，内容部分仍由 $\mathbf{q}_m,\mathbf{k}_n$ 决定。

nanochat 采用相反的旋转方向。`apply_rotary_emb` 计算

$$
\tilde{x}_i=x_i\cos\theta+x_{i+d/2}\sin\theta,\qquad
\tilde{x}_{i+d/2}=-x_i\sin\theta+x_{i+d/2}\cos\theta,
$$

这正是 $\mathbf{R}(-\theta)$ 作用在 $(x_i,x_{i+d/2})$ 上。于是 $\tilde{\mathbf{q}}_m=\mathbf{R}_{-m}\mathbf{q}_m$、$\tilde{\mathbf{k}}_n=\mathbf{R}_{-n}\mathbf{k}_n$，内积为

$$
\tilde{\mathbf{q}}_m^{\top}\tilde{\mathbf{k}}_n
=\mathbf{q}_m^{\top}\mathbf{R}_{-m}^{\top}\mathbf{R}_{-n}\mathbf{k}_n
=\mathbf{q}_m^{\top}\mathbf{R}_{m}\mathbf{R}_{-n}\mathbf{k}_n
=\mathbf{q}_m^{\top}\mathbf{R}_{m-n}\mathbf{k}_n .
$$

两种约定的差别只是 $m-n$ 的符号：标准约定给出 $n-m$，nanochat 给出 $m-n$。两者都只依赖相对位移，因此对从零训练的模型功能等价；差别体现在检查点兼容性上，仓库注释说明保留该约定是为了与已有检查点一致。

### 5 外推问题

RoPE 只保证“训练中见过的相对位移被一致地编码”，不保证“未见过的位移能被正确推断”。原因在频率的周期性。第 $i$ 对的相对角为 $(m-n)\omega_i$，它只在模 $2\pi$ 意义下确定旋转；当 $|m-n|\omega_i$ 超过 $2\pi$ 后，不同位移可以给出相同或相近的角度。以 $d=128$、$\text{base}=100000$ 为例，各通道的波长与 $\Delta=2048$ 时的相对角如下。

| 通道对 $i$ | 波长 $2\pi/\omega_i$ | $\Delta=2048$ 的相对角（弧度） |
|---|---|---|
| 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 |

高频通道（$i$ 小）在 $\Delta=2048$ 内已绕多圈，相位对位移的分辨被 $2\pi$ 混叠限制；低频通道（$i$ 大）在 $2048$ 内只转动零点几弧度，对短距离的分辨率很低。位置编码的“分辨率”由整组频率共同决定：短距离主要靠高频通道，长距离主要靠低频通道。超出训练长度后，低频通道落入未训练的相位区间，注意力打分的分布发生偏移，模型质量下降。`rotary_seq_len=sequence_len*10` 只是把可计算的 $\cos/\sin$ 缓存放大，并不等于模型在 10 倍长度上仍有效。

nanochat 没有实现位置插值或频率缩放。若要把上下文扩展到训练长度之外，需要改 `rotary_seq_len` 之外的东西（例如调整 `base` 或对位置索引缩放），并重新训练或至少继续训练；仅把缓存放大只解决“切片越界断言”，不解决分布外推。`dev/LOG.md` 2026-03-24 记录了对每头维度前 $1/4$ 施加 RoPE 的尝试（partial RoPE），结论为 slightly worse，未采用；这相当于保留高频通道、放弃低频通道，而在 $2048$ 的上下文里低频通道承担长距离分辨，截断它会削弱长距离信息。

### 在 nanochat 中的落地

**频率与缓存预计算。** `GPT.__init__` 先设 `rotary_seq_len = config.sequence_len * 10`，再调用 `_precompute_rotary_embeddings`：

```python
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` 步长为 $2$，取值为 $0,2,\dots,d-2$，除以 $d$ 后得到指数 $0,2/d,\dots,(d-2)/d$，即 $2i/d$；这对应半拆分约定，而不是交错配对。第二，`torch.outer(t, inv_freq)` 生成 $(T,d/2)$ 的角度表，第 $t$ 行第 $i$ 列是 $t\omega_i$。第三，`cos`、`sin` 被转成 `COMPUTE_DTYPE`（SM80+ 为 bf16），并扩成 $(1,T,1,d/2)$，前两维用于批量与头广播，第三维 `1` 表示所有头共用同一组频率。第四，函数在 `__init__` 中被调用时模型处于 meta device 上下文，返回的只是形状与 dtype 正确的元张量；真正的数值在 `init_weights` 中重新计算并赋给 `self.cos`、`self.sin`，同时注册为 `persistent=False` 的缓冲区，不写入检查点。

**旋转。** `apply_rotary_emb` 只做逐元素运算：

```python
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)
```

输入必须四维 $(B,T,H,d)$；`x1`、`x2` 是通道的前半与后半，不是相邻的奇偶通道。返回值用 `cat` 拼回原顺序。该函数只对 `q`、`k` 调用，不对 `v` 调用：位置只进入匹配，不改变被搬运的内容。注释明确写出“按 $-\theta$ 旋转，是教科书约定的转置；功能等价，保留是为了检查点兼容”，这正是第 4 节推导的符号差异。

**前向中的切片与断言。** `GPT.forward` 在前向开始时取当前序列长度对应的角度，并做三条检查：

```python
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 都被当作位置 $0$，相对位置整体错位。

**缓存大小。** $T=2048$ 时 `rotary_seq_len=20480`，每张表 $20480\times64$ 个元素，cos 与 sin 各一份，bf16 下约 $5.2$ MB。仓库注释说明这是“10 倍过度计算，很小很便宜；超过就断言失败”。这一取舍的边界是：缓存放大不改变模型的训练长度，也不改变外推能力，只避免“写长文本时切片越界”这类实现层失败。

**与滑动窗口的关系。** `window_size` 只限制注意力的允许集合，不改变位置编号。短窗层仍然使用全局位置 $t$，而不是在窗口内重新从 $0$ 计数；因此同一 token 在不同层、不同窗口模式下看到的相对位移是一致的。若把窗口内的位置重新编号，RoPE 的相对关系会随窗口滑动而跳变，这是实现滑动窗口时容易犯的错误。

## 关键直觉

> [!tip] 机制性表述
> RoPE 把每头向量的 $d/2$ 个通道对视为复数，按位置乘上 $e^{\mathrm{i}t\omega_i}$。查询与键各自旋转后，内积中的绝对角度相消，只剩 $m-n$ 决定的相对旋转；范数不变，所以注意力打分的尺度不被位置改变。nanochat 对查询与键使用同一套 $\cos/\sin$，向量按前后半拆分，旋转方向取 $-\theta$，缓存按 $10$ 倍序列长度预计算并在前向按当前位置切片。

该表述与严格定义的关系：第 3 节给出旋转矩阵与复数乘法的等价性，第 4 节用 $\mathbf{R}(\phi)^{\top}=\mathbf{R}(-\phi)$ 与角度可加性证明相对性，并说明 $-θ$ 约定只翻转相对角的符号；「在 nanochat 中的落地」一节把频率、拆分方式、dtype、切片偏移逐一对应到 `_precompute_rotary_embeddings` 与 `apply_rotary_emb`。缓存放大与外推能力的区别由第 5 节的频率表说明。

## 例子与代码

### 例 1：二维旋转的手算

取 $\omega=0.5$、$d=2$（只有一对通道），查询内容 $\mathbf{q}=(1,0)$ 位于 $m=0$，键内容 $\mathbf{k}=(1,0)$ 位于 $n=1$。标准约定下 $\tilde{\mathbf{q}}=\mathbf{R}(0)\mathbf{q}=(1,0)$，$\tilde{\mathbf{k}}=\mathbf{R}(0.5)\mathbf{k}=(\cos0.5,\sin0.5)\approx(0.8776,0.4794)$，内积为 $0.8776=\cos0.5$。

```python
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)
```

```text
标准约定内积 0.8775825618903728
nanochat 约定内积 0.8775825618903728
cos(m-n)w 0.8775825618903728
标准约定 R((n-m)w) 的结果 0.8775825618903728
```

两种约定给出相同的内积，因为这里 $m=0$、$n=1$，且内容向量为 $(1,0)$、$(1,0)$，而余弦是偶函数。取一般内容向量并令 $m=2$、$n=5$，标准约定的内积为 $\mathbf{q}^{\top}\mathbf{R}(3\omega)\mathbf{k}$，nanochat 约定为 $\mathbf{q}^{\top}\mathbf{R}(-3\omega)\mathbf{k}=\mathbf{q}^{\top}\mathbf{R}(3\omega)^{\top}\mathbf{k}$；两者都只依赖 $m-n$，但作为 $\mathbf{q},\mathbf{k}$ 的双线性型不同。对从零训练的模型，这一差异等价于把相对位移的方向整体取反，模型可以学到同一类函数；差异只在跨约定加载检查点时才会造成损失上升。

### 例 2：相对位移的数值验证

用 nanochat 的两个函数处理 $T=6$、$d=8$、$H=1$ 的输入。为了让同一行内的内容相同，把同一个 $\mathbf{q}$、$\mathbf{k}$ 复制到所有位置，再按位置旋转；于是同一相对位移的所有配对应当给出相同的内积。

```python
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)))
```

```text
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 舍入范围内相同，极差约 $10^{-7}$，说明内积只依赖相对位移。若把 `x[..., :d]`、`x[..., d:]` 改成相邻奇偶通道配对（交错约定），这一性质仍成立，但需同时改 `_precompute_rotary_embeddings` 的频率排列；两种约定混用会让 $\cos/\sin$ 与通道对不上，打分中的位置信息退化为噪声，而形状完全不报错。

### 例 3：频率表与缓存形状

下面的代码复现第 5 节的波长表，并给出 d12 的缓存形状。

```python
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)
```

```text
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
```

$i=0$ 的波长为 $2\pi\approx6.3$，在 $2048$ 个 token 内绕约 $326$ 圈；$i=63$ 的波长约 $5.25\times10^5$，在 $2048$ 内只转 $0.0245$ 弧度。缓存为 $20480\times64$ 的 cos 与 sin 各一份，bf16 共 $5\,242\,880$ 字节（约 $5.0$ MiB）。这些数字解释了为什么 `rotary_seq_len` 可以“过度计算 10 倍”：缓存的绝对值小，而按需增长需要处理设备、dtype 与断言，复杂度不划算。

### 例 4：仓库中的旋转函数

```python
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` 的默认值是 $100000$，但函数体内首行仍保留着“bump base theta more? e.g. 100K is more common more recently”的注释，说明该默认值经历过修改而注释未同步；以签名与调用为准。

## 易错点

> [!warning] 以下六条均可由形状、数值或对照实验直接检验。
> 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]`；固定取前 $T$ 行会让每个新 token 都按位置 $0$ 旋转，缓存中键的相对位置全部错位。
> 4. 频率基数与检查点不匹配。当前代码默认 `base=100000`；若检查点在训练时使用其它基数（例如常见默认值 $10000$），加载时必须使用训练时的基数，否则 $\omega_i$ 全线偏移，损失升高但不报错。检查方法：打印 `inv_freq[0]` 与 `inv_freq[-1]`，与训练配置对照。
> 5. `cos`/`sin` 形状广播错误。正确形状是 $(1,T,1,d/2)$；若写成 $(1,T,d/2,1)$ 或 $(T,d/2)$，与 $(B,T,H,d)$ 相乘时会触发形状错误，或在 $H=d/2$ 等巧合下静默广播到错误维度。检查方法：打印形状并确认第三维为 $1$。
> 6. 把缓存放大当作外推能力。`rotary_seq_len = sequence_len * 10` 只保证切片不越界；超过训练长度的位置落入未训练的相位分布，质量下降是模型性质，不是实现 bug。扩展到更长上下文需要改频率或继续训练，并重新评测。

## 关联笔记

- 前置 [[自注意力机制]]：该篇给出查询—键内积与缩放，本篇说明为什么内积需要旋转、旋转如何保持范数。
- 前置 [[多头注意力]]：频率表按头广播，每头共享同一组 $\omega_i$；该篇给出头维度与布局，本篇给出 $(1,T,1,d/2)$ 的广播形状。
- 后续 [[GPT模型类与config]]：`rotary_seq_len` 是 `GPTConfig` 之外的模型属性，该篇解释 `__init__` 的 meta device 上下文与 `init_weights` 的重新计算。
- 对照 [[位置编码-正弦与RoPE]]（跨库）：该篇给出正弦编码、可学习编码与 RoPE 的完整对比和外推方法；本篇只保留 nanochat 的 $-θ$ 约定、频率基数与缓存实现。
- 后续 [[KV Cache原理]]：缓存保存旋转后的键，解码按当前位置切片角度；该篇给出缓存布局与显存公式。

## 达标检测

- [ ] 证明自注意力对位置置换等变，并说明为什么仅靠 token 嵌入无法区分词序。
- [ ] 从复数乘法推导二维旋转矩阵，写出 RoPE 对 $(x_i,x_{i+d/2})$ 的变换式，并说明 `base` 与 $\omega_i$ 的关系。
- [ ] 用 $\mathbf{R}(\phi)^{\top}=\mathbf{R}(-\phi)$ 与角度可加性证明 $\tilde{\mathbf{q}}_m^{\top}\tilde{\mathbf{k}}_n$ 只依赖 $m-n$；再说明 nanochat 的 $-θ$ 约定为何只改变符号。
- [ ] 运行例 2，报告每个 `delta` 的内积极差，并解释极差为何在 float32 舍入量级。
- [ ] 计算 $i=0$、$i=32$、$i=63$ 的波长与 $\Delta=2048$ 的相对角，说明 RoPE 在长距离上的混叠来源。
- [ ] 写出 d12 在 $T=2048$ 时的 `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 节频率取法 $\text{base}^{-2i/d}$ 的来源与第 5 节的波长分析。
- Karpathy, *nanochat*，`nanochat/gpt.py` 的 `_precompute_rotary_embeddings`、`apply_rotary_emb`、`GPT.forward`，`dev/LOG.md` 2026-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 的旋转实现对照。
