---
tags: [nanochat, rl, grpo]
阶段: 07-强化学习对齐RL
难度: ★★★
created: 2026-10-22
related: "[[RLHF与GRPO概览]], [[GSM8K数学任务]], [[RL对模型的影响]], [[有监督微调SFT]]"
---

# GRPO原理与实现

## 定义

**组相对策略优化**（group relative policy optimization，GRPO）指对同一提示采样 $G$ 条完整回复、以组内奖励均值作为基线、不引入价值网络估计优势，再把该优势代入带重要性比值、裁剪与 KL 惩罚的策略梯度目标的一类方法；nanochat 中的「GRPO」是该目标在「一批 rollout 只做一次参数更新」场景下的特化：删除 KL 与比值裁剪、按有效 token 数归一化、优势只取 $r_i-\bar r$，因此数值上等价于**带组内基线的 REINFORCE**。

符号约定如下。$x$ 为提示，$o=(o_1,\dots,o_T)$ 为一条完整回复，$o_{i}$ 为第 $i$ 条采样回复。

| 符号 | 含义 |
|---|---|
| $\theta$ | 策略参数，即模型全部可训练权重 |
| $\pi_\theta(o_t\mid x,o_{<t})$ | 策略，即给定前缀时下一个 token 的条件分布 |
| $\pi_{\theta_{\text{old}}}$ | 采样该批 rollout 时的策略参数快照 |
| $\pi_{\mathrm{ref}}$ | 参考策略，KL 项的锚点，通常为 SFT 模型 |
| $G$ | 每个提示的采样条数，`chat_rl.py` 默认 16 |
| $x$ | 提示，来自训练集 $\mathcal{D}$（此处为 GSM8K 训练集） |
| $r_i$ | 第 $i$ 条回复的奖励，取值 $\{0,1\}$ |
| $\bar r$ | 组内奖励均值，$\bar r=\frac{1}{G}\sum_{j=1}^{G}r_j$ |
| $A_i$ | 第 $i$ 条回复的组内优势，$A_i=r_i-\bar r$ |
| $\lvert o_i\rvert$ | 第 $i$ 条回复的 token 数 |
| $\rho_{i,t}$ | 重要性比值，$\rho_{i,t}=\pi_\theta(o_{i,t}\mid\cdot)/\pi_{\theta_{\text{old}}}(o_{i,t}\mid\cdot)$ |
| $\varepsilon$ | 裁剪半径，PPO 与 GRPO 常取 $0.2$ |
| $\beta$ | KL 惩罚系数，单位为 nat |
| $m_t$ | 损失掩码，$m_t=1$ 表示该目标 token 参与损失 |
| $N_{\text{valid}}$ | 一个前向批次中 $m_t=1$ 的目标数，代码中为 `(targets >= 0).sum()` |
| $\mathcal{L}$ | 反传用的标量损失，$\mathcal{L}=-J$ |
| $\eta_0$ | 初始学习率，由基础学习率乘 `--init-lr-frac` 得到 |
| $\lambda(s)$ | 学习率乘子，$\lambda(s)=1-s/N_{\text{steps}}$ |

术语说明。**rollout** 指用当前策略完整生成一条回复的过程；**on-policy** 指用于计算梯度的轨迹由当前参数采样，且采样后参数尚未更新；**信任域**（trust region）指对策略更新幅度的约束，在 RLHF 中由 KL 项实现；**重要性比值**（importance ratio）指新旧策略在同一动作上的概率比，用于把旧策略采样的数据用于新策略的更新；**裁剪**（clipping）指对比值截断以限制单步更新收益；**基线**（baseline）指从回报中减去的一个只依赖状态的量，它不改变梯度期望但改变方差；**优势**（advantage）是回报减基线；**稀疏奖励**指整条轨迹只有终止时刻一个非零奖励；**可验证奖励**（verifiable reward）指由确定性判分程序给出、不含可学习参数的奖励。

本篇只讨论 nanochat 的实现与其删减，通用 PPO 与 RLHF 目标见 [[RLHF与GRPO概览]]，奖励函数与数据集见 [[GSM8K数学任务]]，对齐后的行为变化见 [[RL对模型的影响]]。

## 为什么重要

SFT 的目标函数只约束「给定前缀时下一个 token 的分布」，不约束「哪条完整回复更好」。GSM8K 的判分程序可以离线判断一条回复是否正确，这个判断不依赖任何标注者，因此可以被直接当作优化目标。本阶段要做的唯一事情，是把该 0/1 判断转化为参数更新方向；GRPO 是这个转化所需的最小机制组合。

没有组内基线，梯度估计的方差由题目难度主导。同一批回复里，简单题的奖励全为 1、难题全为 0，若不减均值，这两类样本都以相同的权重把概率往上推，真正携带信息的「同一道题内部哪条更好」被淹没。减掉组均值后，梯度只保留组内相对差异，这是本阶段唯一的方差缩减手段，也是「组相对」这一名称的来源。

没有逐 token 的掩码，工具输出会被计入损失。GSM8K 的参考答案包含 `<<expr=result>>` 形式的工具调用，返回值由 `nanochat/engine.py` 强制注入；若这些 token 进入策略梯度，模型会学到直接输出计算结果，而 SFT 阶段刻意没有监督这些位置（掩码为 0）。掩码把「策略自己采样的动作」与「运行时注入的 token」分开，是奖励信号能否指向正确动作的前提。

在「懂原理 / 能复现 / 懂工程」三条主线中，本篇覆盖前两条的主体与第三条的全部：策略梯度与组基线的推导属于原理；`logp → advantages → pg_obj → loss` 的四行算术属于复现；负号、归一化分母、`ignore_index`、无梯度裁剪、fp16 无 GradScaler 属于工程。通用策略梯度与 PPO 的完整推导见 [[对齐-RLHF]]，偏好数据的构造与 DPO 见 [[DPO与偏好优化]]，本篇只写 nanochat 在 GSM8K 上的落地。

## 原理与推导

### 1 把生成写成序列决策

一条回复的生成可以写成有限回合的马尔可夫决策过程。状态 $s_t=(x,o_{<t})$，动作 $o_t$ 取自词表 $\mathcal V$，转移是确定性拼接 $s_{t+1}=(x,o_{\le t})$，奖励只在终止时刻给出：

$$
r_t=0\ (t<T),\qquad r_T=R(x,o).
$$

折扣因子取 $\gamma=1$，于是回合回报等于终止奖励 $\sum_{t=1}^{T}r_t=R(x,o)$。优化目标是

$$
J(\theta)=\mathbb E_{x\sim\mathcal D}\ \mathbb E_{o\sim\pi_\theta(\cdot\mid x)}\bigl[R(x,o)\bigr].
$$

这一写法把「最大化期望奖励」与语言模型的采样过程接起来：$\pi_\theta(\cdot\mid x)$ 是自回归分布的联合分布，采样就是逐 token 抽取。$R$ 没有梯度，它由字符串比较给出，因此 $J$ 不能直接对 $\theta$ 求导，只能通过采样估计梯度。

### 2 策略梯度定理与 REINFORCE

从 $J$ 的定义出发，只有 $\pi_\theta$ 依赖 $\theta$。固定 $x$ 并对 $\theta$ 求梯度：

$$
\nabla_\theta J=\sum_{o}R(x,o)\,\nabla_\theta\pi_\theta(o\mid x)
=\sum_{o}\pi_\theta(o\mid x)\,R(x,o)\,\nabla_\theta\log\pi_\theta(o\mid x)
=\mathbb E_{o\sim\pi_\theta}\bigl[R(x,o)\nabla_\theta\log\pi_\theta(o\mid x)\bigr].
$$

第二步用了恒等式 $\nabla_\theta\pi_\theta=\pi_\theta\nabla_\theta\log\pi_\theta$，它要求 $\pi_\theta(o\mid x)>0$，对 softmax 参数化始终成立。这一步是全部策略梯度方法的基础：把一个无法直接求导的期望回报，变成可以对采样求导的对数概率加权和。

序列的对数概率按链式法则分解：

$$
\log\pi_\theta(o\mid x)=\sum_{t=1}^{T}\log\pi_\theta(o_t\mid x,o_{<t}),
$$

故

$$
\nabla_\theta J=\mathbb E\left[\sum_{t=1}^{T}\nabla_\theta\log\pi_\theta(o_t\mid x,o_{<t})\,R(x,o)\right].
$$

注意 $R(x,o)$ 在求和号内部是常数：奖励只在终止时刻给出，一条轨迹上的所有 token 共享同一个回报。这解释了 `chat_rl.py` 为什么能把形状 $(B,)$ 的优势广播成 $(B,T)$ 与逐 token 对数概率相乘。

用 $G$ 条独立采样做蒙特卡洛估计，得到 REINFORCE 估计器：

$$
\hat g=\frac{1}{G}\sum_{i=1}^{G}\sum_{t=1}^{T_i}\nabla_\theta\log\pi_\theta(o_{i,t}\mid x,o_{i,<t})\,R(x,o_i).
$$

它的期望等于 $\nabla_\theta J$，方差随 $R$ 的量级增长。当奖励是 0/1、且不同提示的难度差异很大时，方差主要来自提示之间的差异，而不是同一提示内部的差异。

### 3 组内基线：无偏性与 $(G-1)/G$ 因子

设 $b$ 是与动作 $o$ 独立的量（只依赖 $x$ 或由外部给定）。由归一化条件 $\sum_o\pi_\theta(o\mid x)=1$，

$$
\mathbb E_{o\sim\pi_\theta}\bigl[b\,\nabla_\theta\log\pi_\theta(o\mid x)\bigr]
=b\sum_o\nabla_\theta\pi_\theta(o\mid x)=b\,\nabla_\theta 1=0.
$$

因此对任意与动作独立的 $b$，$R-b$ 给出的估计器与原估计器同期望，但方差更小：

$$
\mathrm{Var}\bigl[(R-b)\nabla_\theta\log\pi_\theta\bigr]
=\mathbb E\bigl[(R-b)^2\lVert\nabla_\theta\log\pi_\theta\rVert^2\bigr]-\lVert\nabla_\theta J\rVert^2 .
$$

GRPO 不训练 $b$，而是用同一提示下的其余采样直接估计：$b=\bar r$。这与「用价值网络估计状态价值」的区别在于，它不需要额外参数、额外前向，也不引入价值网络自身的偏差。

一个必须交代的细节：$\bar r$ 与 $r_i$ 不独立，因为 $\bar r$ 包含 $r_i$。逐项计算

$$
\mathbb E\Bigl[\sum_{i=1}^{G}\nabla_\theta\log\pi_\theta(o_i)\,(r_i-\bar r)\Bigr]
=G\nabla_\theta J-\frac{1}{G}\sum_{j=1}^{G}\sum_{i=1}^{G}\mathbb E\bigl[\nabla_\theta\log\pi_\theta(o_i)\,r_j\bigr].
$$

当 $i\ne j$ 时两条采样独立，期望拆成 $\mathbb E[\nabla_\theta\log\pi_\theta]\cdot\mathbb E[r_j]=0$；当 $i=j$ 时期望为 $\nabla_\theta J$。于是内层双重求和等于 $G\nabla_\theta J$，整体为

$$
G\nabla_\theta J-\nabla_\theta J=(G-1)\nabla_\theta J.
$$

除以 $G$ 后，估计器的期望是 $\frac{G-1}{G}\nabla_\theta J$。方向无偏，幅度被固定因子 $\frac{G-1}{G}$ 缩小，$G=16$ 时为 $0.9375$；该因子可并入学习率。若改用留一均值 $b_i=\frac{1}{G-1}\sum_{j\ne i}r_j$，则对每个 $i$ 都有 $\mathbb E[\nabla_\theta\log\pi_\theta(o_i)(r_i-b_i)]=\nabla_\theta J$，估计器严格无偏。nanochat 用前者，因为一次矩阵求和即可得到全部优势，实现更短。

### 4 组内优势与 z-score

GRPO 论文的原始优势按组内标准化给出：

$$
\hat A_i=\frac{r_i-\bar r}{\sigma_r+\epsilon},\qquad \sigma_r=\sqrt{\frac{1}{G}\sum_{j=1}^{G}(r_j-\bar r)^2}.
$$

标准化的目的是让不同提示、不同任务的奖励尺度可比。代价有两项。其一是当 $\sigma_r=0$ 时（组内奖励完全相同）出现 $0/0$，需要 $\epsilon$ 兜底，而兜底值的选择会静默改变梯度尺度。其二是奖励为 0/1 时 $\sigma_r=\sqrt{\hat p(1-\hat p)}$，$\hat p$ 很小时 $\sigma_r$ 很小，除以它会把梯度放大约 $1/\sigma_r$ 倍。

nanochat 只减均值、不除标准差，对应 `chat_rl.py` 的注释「only use (r - mu) as the advantage」。理由是可验证的：只有一个任务（GSM8K），奖励尺度在训练中不变，不需要跨任务可比；去掉除法后梯度尺度只由 $p$ 与序列长度决定，学习率调参更稳定。

### 5 通用目标：比值、裁剪与 KL

GRPO 论文给出的通用形式是（$q$ 为提示，$o_i$ 为第 $i$ 条采样）：

$$
J_{\text{GRPO}}(\theta)=\mathbb E_{q,\{o_i\}}\left[\frac{1}{G}\sum_{i=1}^{G}\frac{1}{\lvert o_i\rvert}\sum_{t=1}^{\lvert o_i\rvert}\left(\min\Bigl(\rho_{i,t}\hat A_{i,t},\ \mathrm{clip}(\rho_{i,t},1-\varepsilon,1+\varepsilon)\hat A_{i,t}\Bigr)-\beta\,D_{i,t}\right)\right],
$$

其中 $D_{i,t}$ 是逐 token 的 KL 估计，$\rho_{i,t}=\pi_\theta(o_{i,t}\mid q,o_{i,<t})/\pi_{\theta_{\text{old}}}(o_{i,t}\mid q,o_{i,<t})$。当 $\hat A>0$ 且 $\rho>1+\varepsilon$ 时，$\min$ 取 $(1+\varepsilon)\hat A$，对 $\theta$ 的梯度为零：策略在该动作上已比采样时更自信，继续增大比值不再获得收益。当 $\hat A>0$ 且 $\rho<1-\varepsilon$ 时 $\min$ 取未裁剪项，梯度保留。$\hat A<0$ 的两个方向对称：越界的一侧被替换为常数，梯度为零。

KL 项常用 k3 估计，它对 $\mathrm{KL}(\pi_\theta\lVert\pi_{\mathrm{ref}})$ 无偏且逐 token 非负：

$$
D_{i,t}=\frac{\pi_{\mathrm{ref}}(o_{i,t}\mid\cdot)}{\pi_\theta(o_{i,t}\mid\cdot)}-\log\frac{\pi_{\mathrm{ref}}(o_{i,t}\mid\cdot)}{\pi_\theta(o_{i,t}\mid\cdot)}-1 .
$$

nanochat 把 $\beta$ 置零，即整项删除。删除的后果在第 8 节单独讨论。

### 6 on-policy 单步更新：比值恒为 1

nanochat 的每个 rollout 批次只对应一次参数更新：`get_batch()` 产出一个提示的 16 条采样，`chat_rl.py` 对其中每个前向批次调用一次 `loss.backward()`，全部反传累积梯度后在循环末尾调用一次 `optimizer.step()`。反传次数由 `num_passes × examples_per_rank` 决定：8 卡默认配置为 $2\times2=4$ 次，单卡为 $2\times16=32$ 次。在整个批次的反传过程中 $\theta$ 不变，因此

$$
\pi_\theta(o_{i,t}\mid\cdot)=\pi_{\theta_{\text{old}}}(o_{i,t}\mid\cdot)\ \Longrightarrow\ \rho_{i,t}=\exp(0)=1,
$$

$\mathrm{clip}(1,1-\varepsilon,1+\varepsilon)=1$，$\min$ 的两个参数相等，裁剪算子退化为恒等映射。于是通用目标退化为

$$
J_{\text{nanochat}}(\theta)=\mathbb E\left[\frac{1}{G}\sum_{i=1}^{G}\frac{1}{\lvert o_i\rvert}\sum_{t=1}^{\lvert o_i\rvert}\log\pi_\theta(o_{i,t}\mid x,o_{i,<t})\,A_i\right],
$$

即「带组内基线的 REINFORCE」。这与 `chat_rl.py` 的注释「there is no need to add PPO ratio+clip because we are on policy」完全一致。反过来，比值与裁剪只在两种情形下必要：同一批数据做多轮更新（PPO 的 inner epochs），或采样与更新异步（rollout 由旧参数产生）。nanochat 两者都不做。

### 7 token 级与序列级归一化

通用目标里的 $1/\lvert o_i\rvert$ 是序列级归一化：先对每条回复求平均，再对 $G$ 条求平均，每条回复权重相同。DAPO 改成 token 级：

$$
J_{\text{DAPO}}(\theta)=\mathbb E\left[\frac{1}{\sum_{i=1}^{G}\lvert o_i\rvert}\sum_{i=1}^{G}\sum_{t=1}^{\lvert o_i\rvert}\log\pi_\theta(o_{i,t}\mid\cdot)\,\hat A_{i,t}\right].
$$

两者的差别只在权重。写开序列级：$\frac{1}{G}\sum_i\frac{1}{\lvert o_i\rvert}\sum_t$；写开 token 级：$\sum_i\frac{\lvert o_i\rvert}{\sum_j\lvert o_j\rvert}\cdot\frac{1}{\lvert o_i\rvert}\sum_t$。故 token 级等价于给第 $i$ 条回复乘上权重 $\lvert o_i\rvert/\sum_j\lvert o_j\rvert$，长回复权重更大。DAPO 的理由是避免长序列的逐 token 贡献被自身长度稀释，也是为了让「同一批内所有 token 等权」这一性质成立。

nanochat 的归一化是

```python
num_valid = (targets >= 0).sum().clamp(min=1)
pg_obj = pg_obj / (num_valid * num_passes * examples_per_rank)
```

`num_valid` 是一个前向批次内全部有效目标数，因此是 token 级。三处细节需要核对：其一，`num_valid` 按 pass 分别统计，pass 之间再等权平均（除以 `num_passes`），所以当两个 pass 的 token 总数不同时，与 DAPO 的全局 token 平均有偏差；其二，`examples_per_rank` 让每个提示等权，不按 token 数加权；其三，`clamp(min=1)` 防止整批全被掩码时除零。

### 8 KL 项的作用与删除后的后果

KL 项改变最优解，不是可选的稳定技巧。带 KL 的目标

$$
\max_\pi\ \mathbb E_{\pi}[r]-\beta\,\mathrm{KL}\bigl(\pi\lVert\pi_{\mathrm{ref}}\bigr)
$$

的闭式最优解为 $\pi^\star\propto\pi_{\mathrm{ref}}\exp(r/\beta)$（推导见 [[对齐-RLHF]]），即参考策略按奖励指数加权的倾斜分布。$\beta\to\infty$ 时 $\pi^\star\to\pi_{\mathrm{ref}}$，$\beta\to0$ 时质量集中到 $\arg\max r$。

删除 KL 后，最优策略退化为「把全部概率质量放到奖励最高的一条回复上」。在语言模型上这一退化沿四条路径表现。

第一，无锚点。策略可以漂移到奖励函数的高分区域，而该区域不必对应「会做数学题」，只对应「判分器会返回 1」。GSM8K 的判分只看 `####` 后的数字，因此「猜一个数字并加上 `####`」也是高分策略。

第二，熵塌缩。若某一模板在早期批次中偶然得分，策略会反复生成它，16 条采样的差异缩小，组内方差随之下降，优势趋于零，学习停止在半收敛状态。这是没有 KL 时最常见的失败模式，且与「训练损失下降、pass@k 不动」同时出现。

第三，无回拉机制。KL 项同时充当步长控制器：偏离越大，惩罚越大。删除后，一次异常批次（例如某条超长回复的优势被 token 级归一化放大）可以直接推动参数，且 nanochat 不做梯度裁剪。

第四，代价与收益互换。删除 KL 省去一份冻结的参考模型、每 token 一次参考前向与 $\log\pi_{\mathrm{ref}}$ 的存储；对 d24 规模，这是可观的一份显存与按生成长度线性增长的额外前向计算。换来的是上述三项风险。`chat_rl.py` docstring 把「Delete trust region」列为第一条删减，说明这是有意的取舍而非疏漏。

### 9 掩码：只有策略采样的 token 参与损失

`nanochat/engine.py` 的 `generate` 在每步产出一个 `token_masks` 列表：若该 token 是从策略分布采样得到的，掩码为 1；若该 token 是从 `RowState.forced_tokens` 队列中取出的，掩码为 0。工具调用的返回值正是后者：`<|python_start|>` 与表达式由模型采样（掩码 1），`<|output_start|>`、计算结果、`<|output_end|>` 由引擎强制写入（掩码 0）。`generate_batch` 把提示部分的掩码置 0，并丢弃终止 token。

`get_batch` 把该掩码右移一位后写入 `targets`：

```python
inputs = ids[:, :-1]
targets = ids[:, 1:].clone()
targets[mask_ids[:, 1:] == 0] = -1   # -1 是 ignore_index
```

右移的理由与 SFT 相同：位置 $t$ 的 logits 预测的是 $\mathrm{ids}_{t+1}$，掩码也必须取该目标 token 的掩码。`F.cross_entropy(..., ignore_index=-1, reduction='none')` 在被忽略位置上返回 0，因此这些位置既不计入分子，也不进入 `num_valid` 的分母。

若不做掩码，工具输出会以同一优势进入损失。由于 $A_i>0$ 时最大化 $\log\pi_\theta$ 会提高对应位置的概率，模型会被训练成「自己输出计算结果」，而这正是 SFT 阶段刻意不监督的行为（`render_conversation` 给 `python_output` 分片掩码 0）。后果不是数值偏移，而是行为反转：模型不再发起工具调用，直接写出一个可能错误的数字。

### 10 退化：组内全对与全错

由 $\bar r=\frac{1}{G}\sum_j r_j$，当组内奖励全部相同时 $A_i=r_i-\bar r=0$ 对全部 $i$ 成立，`pg_obj` 恒为 0，损失恒为 0，该批不产生任何梯度。对 0/1 奖励与每组 $G$ 条采样，设单条采样答对的概率为 $p$，则

$$
P(\text{全错})=(1-p)^{G},\qquad P(\text{全对})=p^{G},\qquad \mathbb E[\text{答对条数}]=Gp .
$$

表 1 给出 $G=16$ 时的数值。

表 1 组内全错的概率

| 单条答对概率 $p$ | $\mathbb E[\text{答对条数}]$ | $P(\text{全错})$ | $P(\text{全对})$ |
|---|---|---|---|
| 0.01 | 0.16 | 0.8515 | $1.0\times10^{-32}$ |
| 0.02 | 0.32 | 0.7238 | $6.6\times10^{-28}$ |
| 0.05 | 0.80 | 0.4401 | $1.5\times10^{-21}$ |
| 0.10 | 1.60 | 0.1853 | $1.0\times10^{-16}$ |
| 0.20 | 3.20 | 0.0281 | $6.6\times10^{-12}$ |
| 0.50 | 8.00 | $1.5\times10^{-5}$ | $1.5\times10^{-5}$ |

表 1 说明两个门限。第一个是信号门限：$Gp\gtrsim1$ 时多数步至少有一条采样答对，即 $p\gtrsim1/G=0.0625$；$p=0.05$ 时 44% 的优化步梯度为零，$p=0.02$ 时该比例升到 72%。第二个是饱和门限：$p$ 较高时全对概率上升，梯度同样消失，但对 16 条采样几乎不会发生（$p=0.5$ 时为 $1.5\times10^{-5}$），因此退化在 nanochat 中主要表现为「开始时没有信号」，而不是「学会后没有信号」。

全错时组内并非没有信息：把 16 条错误回复与正确答案比较仍然可以构造稠密奖励（编辑距离、格式得分、步骤数），但那需要奖励设计，超出 `reward = float(evaluate(...))` 的范围。nanochat 选择保持 0/1 奖励与零梯度，代价是训练初期大量空步。

### 11 一次更新的完整算术

把第 6 至 8 节合起来，`chat_rl.py` 每个优化步最小化的标量是

$$
\mathcal L(\theta)=-\frac{1}{N_{\text{pass}}N_{\text{ex}}}\sum_{p=1}^{N_{\text{pass}}}\frac{1}{T_p}\sum_{i\in p}\ \sum_{t=1}^{T}m_{i,t}\,\log\pi_\theta(o_{i,t}\mid x,o_{i,<t})\,A_i ,
$$

其中 $T_p=\sum_{i\in p}m_{i,t}$ 是该 pass 的有效 token 数，$N_{\text{pass}}$ 是 `num_passes`，$N_{\text{ex}}$ 是 `examples_per_rank`。负号来自「最大化目标」与「最小化损失」的互换，它是最容易写错的一处：若写成 $\mathcal L=+\frac{1}{T}\sum\log\pi_\theta A_i$，梯度下降会压低高优势回复的概率。

单卡默认配置下的算术如下。`examples_per_step=16`，`examples_per_rank=16`，`num_samples=16`，`device_batch_size=8`，故每个提示分两次采样（`num_sampling_steps=2`），每次 8 条；`num_passes=2`；每个优化步包含 16 个 `example_step`、每步 2 次反传，共 32 次反传后一次 `optimizer.step()`。每一步处理 $16\times16=256$ 条 rollout，`chat_rl.py` 打印的 `Total sequences per step: 256` 即来自 `examples_per_step * num_samples`。

学习率从基础值乘 `--init-lr-frac=0.05` 起步，再乘线性下降到零的乘子：

```python
def get_lr_multiplier(it):
    lrm = 1.0 - it / num_steps
    return lrm
```

对 d24、`model_dim=1536`，`setup_optimizer` 对 AdamW 组乘以 $(1536/768)^{-1/2}=0.7071$。代入默认值得到表 2。

表 2 学习率与乘子（d24，`--num-epochs=1`，467 步）

| 参数组 | 名义值 | 代码中的缩放 | 第 0 步学习率 | 第 233 步学习率 |
|---|---|---|---|---|
| 矩阵（Muon） | 0.02 | 无 dmodel 缩放，乘 `init_lr_frac` | $0.02\times0.05=0.001$ | 0.000501 |
| 嵌入（AdamW） | 0.2 | 乘 $0.7071$，再乘 `init_lr_frac` | 0.007071 | 0.003544 |
| 反嵌入（AdamW） | 0.004 | 乘 $0.7071$，再乘 `init_lr_frac` | 0.0001414 | $7.09\times10^{-5}$ |

第 233 步的乘子为 $1-233/467=0.5011$；第 466 步为 0.00214，不会精确到零。`num_steps` 由 `(len(train_task) // examples_per_step) * num_epochs` 给出，GSM8K 训练集约 7.5K 行，$7473//16=467$，$467\times16=7472$，因此每轮末尾有 1 行未被本轮使用。

### 在 nanochat 中的落地

```mermaid
flowchart TD
    A["load_model sft<br/>phase=eval"] --> B["Engine 用于 rollout"]
    B --> C["render_for_completion<br/>删掉最后助手消息并加 assistant_start"]
    C --> D["generate_batch 8 条 x 2 次<br/>temperature 1.0 top-k 50 上限 256"]
    D --> E["decode 生成段<br/>reward = evaluate"]
    E --> F["组内均值 mu<br/>advantages = r - mu"]
    F --> G["pad 到 max_length<br/>mask 补 0"]
    G --> H["inputs / targets<br/>targets[mask=0] = -1"]
    H --> I["logp = -model 的逐 token NLL"]
    I --> J["pg_obj = sum logp * A<br/>除以有效 token 数"]
    J --> K["loss = -pg_obj 反传"]
    K --> L["lrm 线性下降<br/>optimizer.step"]
```

| 位置 | 关键语句 | 作用 | 去掉会怎样 |
|---|---|---|---|
| `chat_rl.py` 顶部 | `load_model("sft", ...)` | 以 SFT 检查点为策略初值 | 从 base 开始采样，几乎拿不到正确回复 |
| `get_batch` | `tokenizer.render_for_completion(conversation)` | 构造以助手起始符结尾的前缀 | 把参考答案留在提示里，奖励恒为 1 |
| `get_batch` | `engine.generate_batch(..., num_samples=8, seed=...)` | 一次 prefill 复制 KV 后并行采样 | 逐条采样，成本乘以 8 |
| `get_batch` | `train_task.reward(conversation, generated_text)` | 0/1 可验证奖励 | 无训练信号 |
| `get_batch` | `mu = rewards.mean(); advantages = rewards - mu` | 组内基线 | 梯度方差由题目难度主导 |
| `get_batch` | `targets[mask_ids[:, 1:] == 0] = -1` | 只在采样 token 上计损失 | 提示与工具输出被训练 |
| 训练循环 | `logp = -model(inputs, targets, loss_reduction='none')` | 把 NLL 变回对数概率 | 符号反了，压低正确回复 |
| 训练循环 | `(logp * advantages.unsqueeze(-1)).sum()` | 逐 token 加权求和 | 序列级权重与实现不符 |
| 训练循环 | `num_valid = (targets >= 0).sum().clamp(min=1)` | token 级归一化分母 | 短回复被长回复淹没 |
| 训练循环 | `loss = -pg_obj; loss.backward()` | 累积梯度 | 没有更新 |
| 训练循环 | `group["lr"] = group["initial_lr"] * lrm` | 线性退火 | 后期步长过大 |
| 保存 | `save_checkpoint(..., None, ...)` | 只存模型权重 | 与代码一致；但无法续训 |

两处实现细节需要单列。其一是精度：`README.md` 明确写「SFT supports this too but RL currently does not」，即 `NANOCHAT_DTYPE=float16` 时 RL 没有 GradScaler，梯度下溢的风险由使用者承担。其二是 `@torch.no_grad()` 装饰在 `get_batch` 上，而 `get_batch` 是生成器函数：CPython 下函数体在首次 `next()` 时执行，装饰器的上下文在调用瞬间就已退出，因此该装饰器不覆盖函数体。这里没有实际后果，因为 `Engine.generate` 自身用 `@torch.inference_mode()` 包裹；但把同一写法搬到自定义 rollout 中就会漏掉 no_grad。

## 关键直觉

> [!tip] 「组」是一个方差缩减装置，不是一个新目标函数。减去 $\bar r$ 等价于用同一提示的其余采样估计「这道题的期望得分」，把提示难度从梯度里扣掉，只留下「这条回复比同题平均好多少」。与定义的关系是：$A_i=r_i-\bar r$ 是 $r_i-\mathbb E[r\mid x]$ 的蒙特卡洛估计，$G\to\infty$ 时基线收敛到真实条件期望，估计器方差只剩组内差异；而 $G$ 有限时估计器期望带 $\frac{G-1}{G}$ 因子，方向不变、幅度缩小。这也解释了为什么组内全对或全错时梯度必为零：此时组内没有「相对更好」的信息，而目标函数只使用相对信息。
>
> 第二个结论同样来自定义：nanochat 的损失里没有 $\rho$、没有 KL、没有 $\sigma_r$，只剩 $\log\pi_\theta\cdot A$ 与一个分母。因此它不能用「PPO 的简化版」来理解，只能按「带基线的 REINFORCE + 掩码 + token 级归一化」来理解；凡是 PPO 的解释（信任域、多轮更新、优势自举）在这里都没有对应物。

## 例子与代码

第一段用 2 臂 bandit 手算一组优势与梯度方向，并枚举全部动作序列核对 $(G-1)/G$ 因子。策略为 softmax，参数 $\theta=(0,0)$，两动作概率各 $0.5$；奖励在动作为 1 时为 1，否则为 0；$G=6$，采到的动作为 $(0,1,0,0,1,0)$。

手算过程如下。奖励 $r=(0,1,0,0,1,0)$，均值 $\bar r=2/6=1/3$，优势 $A=(-1/3,2/3,-1/3,-1/3,2/3,-1/3)$，六项之和为零。softmax 的对数概率梯度为 $\partial\log\pi_\theta(a)/\partial\theta=e_a-p$：动作 1 的梯度为 $(-0.5,0.5)$，动作 0 的为 $(0.5,-0.5)$。把优势加权求和：

$$
\sum_i A_i\nabla_\theta\log\pi_\theta(a_i)=\frac{2}{3}\cdot2\cdot(-0.5,0.5)+\Bigl(-\frac{1}{3}\Bigr)\cdot4\cdot(0.5,-0.5)=\Bigl(-\frac{4}{3},\frac{4}{3}\Bigr),
$$

除以 $G=6$ 得 $(-0.2222,0.2222)$。梯度上升使 $\theta_1$ 增大、$\theta_0$ 减小，即提高正确答案（动作 1）的概率，方向正确。

```python
"""组基线的手算与期望核对：2 臂 bandit，G=6，theta=(0,0)。"""
import itertools
import numpy as np

G = 6
group = [0, 1, 0, 0, 1, 0]                  # 依次采到的动作，1 为正确动作
r = np.array([1.0 if a == 1 else 0.0 for a in group])
mu = r.mean()
adv = r - mu
print("rewards", r.tolist())
print("mean", round(float(mu), 4))
print("advantages", np.round(adv, 4).tolist())
print("sum advantages", round(float(adv.sum()), 12))

def grad_logpi(a):
    p = np.array([0.5, 0.5])                # theta=(0,0) 时的 softmax 概率
    e = np.zeros(2)
    e[a] = 1.0
    return e - p                            # d log pi(a) / d theta = e_a - p

pg = sum(adv[i] * grad_logpi(group[i]) for i in range(G)) / G
print("this group gradient", np.round(pg, 4).tolist())

# 枚举全部 2^6 个动作序列，比较三种基线的期望梯度
tot_mean, tot_loo, tot_z = np.zeros(2), np.zeros(2), np.zeros(2)
for acts in itertools.product([0, 1], repeat=G):
    rr = np.array([1.0 if a == 1 else 0.0 for a in acts])
    aa = rr - rr.mean()
    sd = rr.std()
    zz = aa / sd if sd > 0 else np.zeros(G)
    for i, a in enumerate(acts):
        g = grad_logpi(a)
        tot_mean += aa[i] * g
        tot_loo += (rr[i] - np.delete(rr, i).mean()) * g
        tot_z += zz[i] * g
n = 2 ** G
print("E[group mean]/G", np.round(tot_mean / n / G, 5).tolist())
print("E[leave-one-out]/G", np.round(tot_loo / n / G, 5).tolist())
print("E[z-score]/G", np.round(tot_z / n / G, 5).tolist())
print("(G-1)/G * gradJ", round(-(G - 1) / G * 0.25, 5), round((G - 1) / G * 0.25, 5))
print("true gradJ", [-0.25, 0.25])
```

预期输出如下。

```text
rewards [0.0, 1.0, 0.0, 0.0, 1.0, 0.0]
mean 0.3333
advantages [-0.3333, 0.6667, -0.3333, -0.3333, 0.6667, -0.3333]
sum advantages 0.0
this group gradient [-0.2222, 0.2222]
E[group mean]/G [-0.20833, 0.20833]
E[leave-one-out]/G [-0.25, 0.25]
E[z-score]/G [-0.4471, 0.4471]
(G-1)/G * gradJ -0.20833 0.20833
true gradJ [-0.25, 0.25]
```

这段代码在做什么：`group` 是六次采样得到的动作，`r` 把它们映射为 0/1 奖励，`adv` 减组均值；`grad_logpi` 给出 softmax 对数概率对 logits 的解析梯度；主循环枚举 $2^6=64$ 个动作序列，分别按组均值、留一均值、z-score 三种方式计算梯度并取平均。

为什么这样看：组均值版本的期望是 $(-0.20833,0.20833)$，恰为真梯度 $(-0.25,0.25)$ 的 $5/6$，与第 3 节推出的 $\frac{G-1}{G}$ 一致；留一版本精确等于真梯度；z-score 版本为 $(-0.4471,0.4471)$，是总体的 $1.788$ 倍。这些数字说明：减均值只缩放不改方向，z-score 会同时改尺度，故「是否除标准差」是学习率之外的第二个尺度来源。

第二段把序列级与 token 级归一化，以及掩码对 `pg_obj` 的影响放在一起核对。

```python
"""归一化方式与掩码对策略梯度目标的影响。"""
import numpy as np

# 两条回复：第一条 2 个 token、优势 1.0；第二条 5 个 token、优势 -0.5
logp = [np.array([-0.2, -0.5]), np.array([-0.1] * 5)]
adv = [1.0, -0.5]

tok = sum((lp * a).sum() for lp, a in zip(logp, adv))
n_tok = sum(len(lp) for lp in logp)
print("token-level", round(float(tok / n_tok), 4))
print("sequence-level", round(float(np.mean([(lp * a).sum() / len(lp)
                                             for lp, a in zip(logp, adv)])), 4))
print("weights", [round(len(lp) / n_tok, 4) for lp in logp])

# 掩码：10 个有效 token（logp=-0.4）+ 6 个被忽略位置（logp=-0.05），优势 0.5
A, lv, li, nv, ni = 0.5, -0.4, -0.05, 10, 6
masked = A * lv * nv
print("masked", round(masked, 4), "per token", round(masked / nv, 4))
print("unmasked", round(masked + A * li * ni, 4),
      "per token", round((masked + A * li * ni) / nv, 4))
```

预期输出如下。

```text
token-level -0.0643
sequence-level -0.15
weights [0.2857, 0.7143]
masked -2.0 per token -0.2
unmasked -2.15 per token -0.215
```

这段代码在做什么：第一组数按两种归一化计算同一个 `pg_obj`，并给出 token 级下每条回复的实际权重；第二组数在优势为正时分别计算带掩码与不带掩码的目标值，分母固定为有效 token 数。

为什么这样看：token 级的绝对值（0.0643）是序列级（0.15）的 $0.4286$ 倍，差值完全由权重 $0.2857$ 与 $0.7143$ 造成——长回复在 token 级下占七成权重。掩码的数值影响很小（$0.215$ 对 $0.2$，$7.5\%$），但方向是错的：优势为正时，被掩码位置的 $\log\pi$ 以正系数进入目标，最小化损失会提高这些位置的 token 概率，即训练模型输出提示词与工具返回值。所以掩码的必要性不能从数值大小判断，只能从梯度方向判断。

第三段复刻 `chat_rl.py` 的 `inputs/targets` 构造，核对只有采样 token 的 `targets` 不为 $-1$。

```python
"""chat_rl.py 的 targets 构造：提示、强制工具输出与 padding 都被置为 -1。"""
ids = [10, 11, 12, 20, 21, 30, 31, 0]   # 提示 3 + 采样 2 + 强制输出 2 + padding 1
mask = [0, 0, 0, 1, 1, 0, 0, 0]         # 1 表示该 token 由策略采样

inputs = ids[:-1]
targets = [t if m == 1 else -1 for t, m in zip(ids[1:], mask[1:])]
print("inputs ", inputs)
print("targets", targets)
print("valid", sum(t != -1 for t in targets))
```

预期输出如下。

```text
inputs  [10, 11, 12, 20, 21, 30, 31]
targets [-1, -1, 20, 21, -1, -1, -1]
valid 2
```

七个预测位置中只有两个计入损失：位置 2（输入 12，目标 20）与位置 3（输入 20，目标 21）。位置 0、1 的目标仍在提示内；位置 4 的目标 30 是强制注入的 `<|output_start|>`，位置 5、6 是工具返回值与 padding，都被 `ignore_index` 跳过。这一结果与 SFT 的掩码表一致：模型从不学习生成 `<|output_start|>` 与返回值，只学习生成文本、表达式与结束符。

第四段是运行入口与一段示例日志，数值随模型与硬件变化。

```bash
# 单卡（--run=dummy 关闭 wandb）
python -m scripts.chat_rl --run=dummy
# 8 卡
torchrun --standalone --nproc_per_node=8 -m scripts.chat_rl -- --run=default
```

```text
Calculated number of steps: 467
Total sequences per step: 256
Calculated examples per rank: 2
Step 0 | Pass@1: 0.1234, Pass@2: 0.1875, Pass@4: 0.2900, Pass@8: 0.4125
Step 0/467 | Example step 0 | Pass 0 | loss: -0.013742 | Average reward: 0.1875
Step 0/467 | Average reward: 0.1875 | Average sequence length: 214.36
```

`Calculated examples per rank: 2` 来自 $16/8$；单卡时为 16。`Average reward: 0.1875` 是 16 条采样的均值（3/16），此时组内优势非零，`loss` 为负说明 `pg_obj` 为正，即当前策略在提高高优势回复的概率。第 0 步的 pass@k 是 SFT 检查点的基线，后续每 60 步刷新一次。

## 易错点

> [!warning] 以下六条均可在损失数值、梯度或显存统计中直接定位。
> 1. `logp` 的负号写反或漏写。`model(inputs, targets, loss_reduction='none')` 返回的是负对数似然，取负才得到 $\log\pi_\theta$；若直接用它乘优势，梯度下降会压低高优势回复的概率。可检验的迹象是 `loss` 恒为正且随训练上升。
> 2. 归一化分母用 `B*T` 而不是有效 token 数。padding 数量随批次内最长序列变化，分母因此漂移，等效于每个 step 换一次学习率；`num_valid` 还要 `clamp(min=1)`，否则整批被掩码时除零。
> 3. 掩码未右移一位。`mask_ids[:, :-1]` 会让「最后一条采样 token」的目标错位，损失仍平滑下降，但模型学的是「从前缀预测前缀」；定位方法是核对 `inputs[t]` 与 `targets[t]` 的相邻关系。
> 4. 把 `num_samples` 设成 `device_batch_size` 的非整数倍。`num_sampling_steps = num_samples // device_batch_size` 向下取整，余数被静默丢弃；例如 `--num-samples=12 --device-batch-size=8` 实际只采 8 条，组内均值在 8 条上计算，与参数名不符，且优势分布随之改变。
> 5. 认为 `get_batch` 上的 `@torch.no_grad()` 覆盖了生成过程。生成器函数体在首次 `next()` 时才执行，装饰器此时已退出；`Engine.generate` 自带 `inference_mode` 才使该处安全。在自定义 rollout 中照搬会保留计算图，显存随 rollout 数线性增长。
> 6. 用 `NANOCHAT_DTYPE=float16` 跑 RL。`chat_rl.py` 没有 `GradScaler`（README 明确说明 RL 目前不支持），策略梯度的数值范围比交叉熵更宽，下溢会表现为损失与奖励同时不动；改用 bf16 或 fp32。
> 7. 以为「on-policy」意味着不需要保存 `logπ_old`。当前实现确实不需要，因为它一批只更新一次；若把 `optimizer.step()` 移进 `pass` 循环做多轮更新，比值立刻偏离 1，此时必须显式实现比值与裁剪，否则每次更新都在用过期数据计算梯度。

## 关联笔记

- 前置 [[有监督微调SFT]]：提供策略初值与掩码约定，其 `ignore_index=-1` 的用法被本篇直接复用；SFT 的 GSM8K 过采样决定了初始 $p$ 是否越过信号门限。
- 前置 [[RLHF与GRPO概览]]：给出 RLHF 三阶段与本篇目标在其中的位置，以及 PPO 与 GRPO 的逐项对比。
- 后续 [[GSM8K数学任务]]：奖励函数、`####` 判分与 pass@k 的计算均在该篇展开，本篇只把它当作黑箱 $R$。
- 后续 [[RL对模型的影响]]：本篇的零梯度退化、无 KL 与无裁剪在训练曲线上表现为特定的失败模式。
- 对照 [[KV Cache原理]]：`Engine.generate` 的一次 prefill 复制缓存是多条采样并行的成本前提。
- 跨库 [[对齐-RLHF]]：KL 正则、PPO 裁剪与价值网络的完整推导；本篇只保留 nanochat 实际使用的部分。跨库 [[DPO与偏好优化]] 给出另一条不使用在线采样的对齐路径。

## 达标检测

- [ ] 写出 $J(\theta)$ 并推出 $\nabla_\theta J=\mathbb E[R\nabla_\theta\log\pi_\theta]$，说明恒等式 $\nabla\pi=\pi\nabla\log\pi$ 成立的条件。
- [ ] 证明与动作独立的基线不改变梯度期望，并推出组均值基线的期望为 $\frac{G-1}{G}\nabla_\theta J$。
- [ ] 手算本篇的 6 条采样例子：写出优势、两个动作的对数概率梯度、加权和与最终方向。
- [ ] 说明为什么一批数据只更新一次时 $\rho\equiv1$，以及什么条件下必须引入比值与裁剪。
- [ ] 写出序列级与 token 级两种归一化，推导 token 级等价于权重 $\lvert o_i\rvert/\sum_j\lvert o_j\rvert$，并解释 DAPO 选择后者的理由。
- [ ] 说明 `targets[mask_ids[:, 1:] == 0] = -1` 中右移一位的必要性，并指出提示、工具输出、padding 三类位置各自的掩码。
- [ ] 用表 1 的公式计算 $p=0.03$、$G=16$ 时的全错概率，并给出把全错概率降到 10% 以下所需的最小 $p$。
- [ ] 列出删除 KL 后的三条后果，各给出一个可在训练日志中观察的指标。
- [ ] 运行第三段代码，把 `mask` 改为全 1，说明 `valid` 与 `pg_obj` 如何变化，以及梯度方向错在哪里。

## 参考来源

- Karpathy, *nanochat*（commit 92d63d4），`scripts/chat_rl.py`、`nanochat/engine.py`、`nanochat/gpt.py`、`README.md` —— 对应全部实现细节、默认超参、docstring 的四条删减与 fp16 缺少 GradScaler 的说明。
- Shao et al., "DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models", arXiv:2402.03300, 2024 —— 对应第 4 节的组内标准化优势、第 5 节的 GRPO 通用目标（含比值、裁剪与 KL 项）。
- Yu et al., "DAPO: An Open-Source LLM Reinforcement Learning System at Scale", arXiv:2503.14476, 2025 —— 对应第 7 节的 token 级策略梯度损失与序列级归一化的对比。
- DeepSeek-AI, "DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning", arXiv:2501.12948, 2025 —— 对应第 1 节与第 5 节：该文同样以可验证的规则奖励（答案正确性与格式）配合 GRPO 做纯 RL，说明 nanochat 的 0/1 奖励不是孤例；其报告的回复长度增长与格式变化在 [[RL对模型的影响]] 中讨论。
- Goodfellow, Bengio, Courville, *Deep Learning*, 2016 —— 对应第 2 节的策略梯度定理表述与第 3 节的基线无偏性、方差分解。
