---
tags: [nanochat, pretraining, 学习率]
阶段: 05-预训练Pretraining
难度: ★★★
created: 2026-10-22
related: "[[梯度下降与AdamW]], [[Muon优化器]], [[训练脚本与speedrun]], [[缩放定律与模型深度]]"
---

# 学习率与 warmup-warmdown

## 定义

**学习率调度**（learning rate schedule）把训练步编号 $it$ 映射为一个无量纲乘子 $\text{lrm}(it)$，各参数组的实际学习率为其初始值乘以该乘子：$\eta_g(it)=\eta_g^{(0)}\cdot\text{lrm}(it)$。nanochat 的预训练调度由三段线性函数组成：线性 warmup、常数平台、线性 warmdown。

本篇出现的符号与术语：

- $N$：总优化步数，`num_iterations`，由 token 预算除以总批大小得到。d24 在 speedrun 配置下为 5568。
- $W$：warmup 步数，`--warmup-steps`，默认 40。
- $R$：warmdown 步数，$R=\text{round}(r\cdot N)$，`--warmdown-ratio` $r$ 默认 0.65。
- $f$：末端学习率比例，`--final-lr-frac`，默认 0.05。
- $\eta_g^{(0)}$：参数组 $g$ 的初始学习率，已包含批大小缩放与宽度缩放，见步骤 6 与 7。
- $\eta_0$：$\eta_g^{(0)}$ 的简写，用于不区分参数组的面积与预算估算。
- $\text{lrm}(it)$：学习率乘子，取值 $[f,1]$。
- $B$：总批大小（token 数），$B_{\text{ref}}=2^{19}=524{,}288$ 为 d12 的参考批。
- $D$：训练 token 总数；$D_{\text{ref}}$ 为 d12 在相同 `--target-param-data-ratio` 下的 token 预算。
- $d_{\text{model}}$：残差流宽度，d12 为 768，d24 为 1536。
- Muon 动量 $\mu$：Muon 优化器一阶动量缓冲的系数，与 AdamW 的 $\beta_1$ 不同，它按训练阶段调度。
- 权重衰减 $\lambda$：Muon 的 cautious weight decay 系数，按训练进度余弦衰减。
- $T_{\text{epoch}}$：有效训练轮次的度量，$T_{\text{epoch}}=B/(\eta\lambda D)$，用于确定 $\lambda$ 随批大小与 token 预算的缩放。

## 为什么重要

- 学习率是训练中最敏感的超参数。同一模型在 $\eta$ 相差 2 倍的配置下，最终 bpb 的差异常大于结构改动的差异；因此 nanochat 把 $\eta$ 从「手工调」改为「从 depth 推导」。
- 调度形状决定末段收敛。warmdown 占总步数的 65%，末期学习率从 1 线性降到 0.05；这一段决定了模型能否把已学到的特征收敛到局部最优点，直接影响最终 CORE 与 bpb。
- 参数分组使「一个学习率」实际是七个。Muon 矩阵、embedding、unembedding、value embedding、resid 标量、x0 标量、smear 各有初始值，且只有部分组受批大小与宽度缩放。把 `--matrix-lr` 当成全局学习率是最常见的误读。
- 调度与批大小、深度、token 预算三者联动。$B$ 变大会放大所有组的初始学习率，$d_{\text{model}}$ 变大会缩小 AdamW 组的学习率，$N$ 变小会让固定 40 步的 warmup 占据更大比例。
- 在全书中的位置：前置为 [[梯度下降与AdamW]]（步长与噪声）、[[Muon优化器]]（动量与正交化更新）与 [[缩放定律与模型深度]]（$N$、$B$、$D$ 的推导链）；后续为 [[训练脚本与speedrun]]（调度在循环中的写入位置）与 [[分布式训练与优化器分片]]（参数组在各 rank 上的一致性）。对应能力目标：懂原理对应「写出分段函数并解释每个常数」，能复现对应「按 depth 复算各组学习率」，懂工程对应「诊断学习率过高/过低的表现」。

## 原理与推导

### 步骤 1 三段式调度的逐行定义

`scripts/base_train.py` 中的实现只有 10 行：

```python
def get_lr_multiplier(it):
    warmup_iters = args.warmup_steps
    warmdown_iters = round(args.warmdown_ratio * num_iterations)
    if it < warmup_iters:
        return (it + 1) / warmup_iters
    elif it <= num_iterations - warmdown_iters:
        return 1.0
    else:
        progress = (num_iterations - it) / warmdown_iters
        return progress * 1.0 + (1 - progress) * args.final_lr_frac
```

写成公式，其中 $W$ 为 warmup 步数、$R=\text{round}(rN)$：

$$
\text{lrm}(it)=
\begin{cases}
\dfrac{it+1}{W}, & it < W,\\[4pt]
1, & W\le it\le N-R,\\[4pt]
\dfrac{N-it}{R}+\left(1-\dfrac{N-it}{R}\right)f, & it>N-R.
\end{cases}
$$

第三段可以整理为 $\text{lrm}(it)=f+(1-f)\dfrac{N-it}{R}$，即从 $it=N-R$ 处的 1 线性降到 $it=N$ 处的 $f$。

四个实现细节值得逐一确认：

1. 分子是 $it+1$ 而不是 $it$。第 0 步的乘子为 $1/W=0.025$，不是 0；这样第一步就有非零更新，避免优化器状态在零学习率下积累无意义的动量。
2. 边界用 `<=` 与 `>` 分开。$it=N-R$ 仍返回 1，$it=N-R+1$ 才进入 warmdown，此时 $\text{lrm}\approx1-(1-f)/R$，与平台末端连续。
3. `round` 决定 $R$ 的整数值。d24 的 $N=5568$，$0.65N=3619.2$，$R=3619$，平台结束于 $it=5568-3619=1949$。
4. 最后一步 $it=N$ 只做评测与保存，不执行 `optimizer.step()`，因此末端学习率 $f\eta$ 实际从未被用于更新；最后一次更新发生在 $it=N-1$，其乘子为 $f+(1-f)/R\approx0.0503$。

d24 的关键点如下，乘子保留四位小数：

| $it$ | 阶段 | $\text{lrm}$ | 说明 |
|---|---|---|---|
| 0 | warmup | 0.0250 | 首步仍更新 |
| 20 | warmup | 0.5250 | 手算例见步骤 9 |
| 39 | warmup 末 | 1.0000 | 第 40 步进入平台 |
| 40 | 平台 | 1.0000 | |
| 1949 | 平台末 | 1.0000 | $N-R$ |
| 1950 | warmdown 首 | 0.9997 | 几乎连续 |
| 3760 | warmdown 中 | 0.5246 | 平台与末端的中点 |
| 5567 | 末次更新 | 0.0503 | 实际使用的最小乘子 |
| 5568 | 末步 | 0.0500 | 只评测与保存 |

### 步骤 2 为什么不用余弦

`dev/LOG.md` 中没有余弦调度与线性 warmdown 的对照实验，仓库也没有相关注释，因此下面的分析是机制层面的，不是本仓库的实验结论。把两种常见形状放在同一组约束下比较：

- 余弦：$\text{lrm}(it)=f+(1-f)\cdot\dfrac{1+\cos(\pi\, it/N)}{2}$，定义域覆盖整个训练。
- 线性 warmdown：前 $N-R$ 步为 1，后 $R$ 步线性降到 $f$。

四个可计算的差异：

1. 末端斜率。线性段在 warmdown 内每步下降 $(1-f)/R$，是常数；余弦在 $it\to N$ 时导数趋于 0，最后若干步的学习率变化极小，却仍保持在较高水平。若目标是「在末期持续降温」，线性段的行为更符合直觉：每一步都在减少步长。
2. 非零末端。$f=0.05$ 使模型在训练结束时仍以 5% 学习率更新，便于继续训练或作为 SFT 的热启动起点。余弦若衰减到 0，末端几步几乎不更新，最后阶段的样本对参数没有影响。
3. 学习率面积可闭式比较。忽略 warmup，线性 warmdown 的归一化面积为 $(1-r)\cdot1+r\cdot(1+f)/2$；取 $r=0.65$、$f=0.05$ 得 $0.35+0.341=0.691$。整段余弦 $f+(1-f)(1+\cos(\pi x))/2$ 的平均值为 $f+(1-f)/2=0.525$，因为 $\int_0^1\cos(\pi x)\,dx=0$。线性方案的总面积比余弦大约 32%，并不接近；两者分布也不同：线性方案在平台期以满学习率走完 35% 的步数，余弦方案从第一步就开始缓慢下降。
4. 与后续阶段同构。`chat_sft.py` 使用同一族函数，只是把绝对步数改为进度比例 `progress`；两个脚本只有 `--warmdown-ratio` 与 `--final-lr-frac` 同名同义，预训练用绝对步数 `--warmup-steps`，SFT 用比例 `--warmup-ratio`，`--init-lr-frac` 仅 SFT 有。复用同一族函数降低了跨阶段迁移的认知成本。

这也解释了为什么 nanochat 选择 `warmup/constant/warmdown` 而不是余弦：它对「何时开始降温」有显式控制（$r$），对「降到多少」有显式控制（$f$），两个参数都可以按 horizon 单独调整；余弦只有一个形状参数，末端行为由函数形式固定。

### 步骤 3 warmdown 比例与末端比例的来源

`scripts/base_train.py` 的默认值是 `--warmdown-ratio=0.65`、`--final-lr-frac=0.05`、`--warmup-steps=40`。仓库中没有记录这三个值的消融实验，能核对的只有两处旁证：

- `dev/LOG.md` 2026-02-16 记录 SFT 的调度改造：把「常数 80% 后线性到 0」改为与 `base_train.py` 一致的 warmup/constant/warmdown，并报告 `warmdown ratio` 取 0.5 最好，`--init-lr-frac` 从 1.0 降到 0.8。这是 SFT 的结论，不是预训练的结论，但说明该族函数的比例需要按阶段单独调。
- `scripts/chat_sft.py` 的注释说明预训练 warmdown 会把学习率带到接近 0，因此 SFT 必须保存并恢复自己的学习率。预训练末端的乘子是 0.05，接近 0 但非零；这个值对继续训练足够，对 SFT 的初始阶段不足，所以 SFT 用 `--init-lr-frac=0.8` 取预训练初始学习率的 80% 重新起步。

$r=0.65$ 属于长退火配置。常见的短退火在 10% 至 20% 之间，$0.65$ 意味着 65% 的步数都在降温，平台只占约 35%。机制上的后果可以直接算：d24 的 5568 步中只有第 40 至 1949 步共 1910 步在满学习率下训练，其余约 3618 步的学习率从 1 线性降到 0.05。对短 horizon 的训练，这种安排把更多步数分配给「精细收敛」而不是「快速下降」。

代价是前期探索不足。若数据或模型改动需要较长时间才能显现效果，长 warmdown 会让大部分训练都在较低学习率下进行，改动之间的差异被压缩。这也是 d12（默认 ratio 12 时 2520 步，ratio 8 时 1680 步）比 d24 更适合做消融的原因之一：以 2520 步计，warmup 占 1.6%、平台占 33.4%、warmdown 占 65.0%，与 d24 的比例接近，但绝对时间短。

### 步骤 4 Muon 动量调度

Muon 的动量系数不是常数，而是分三段：

```python
def get_muon_momentum(it):
    warmdown_iters = round(args.warmdown_ratio * num_iterations)
    warmdown_start = num_iterations - warmdown_iters
    if it < 400:
        frac = it / 400
        return (1 - frac) * 0.85 + frac * 0.97
    elif it >= warmdown_start:
        progress = (it - warmdown_start) / warmdown_iters
        return 0.97 * (1 - progress) + 0.90 * progress
    else:
        return 0.97
```

即：

$$
\mu(it)=
\begin{cases}
0.85+0.12\cdot\dfrac{it}{400}, & it<400,\\
0.97, & 400\le it<N-R,\\
0.97-0.07\cdot\dfrac{it-(N-R)}{R}, & it\ge N-R.
\end{cases}
$$

机制上，动量系数是一阶动量缓冲的衰减率：$\mu$ 越大，更新方向越接近过去若干步梯度的指数平均，方差越小、惯性越大。训练初期参数远离最优点，较小的 $\mu$ 让方向快速调整；训练中期 $\mu=0.97$ 对应约 33 步的有效平均窗口，降低小批量梯度的噪声。warmdown 期学习率本身在下降，若动量保持 0.97，累积的旧方向会让更新越过当前最优点；把 $\mu$ 降到 0.90 缩短有效窗口，使末段更新更依赖近期梯度。

调度只作用于 `kind == 'muon'` 的参数组。AdamW 组的 $\beta_1$ 固定为 0.8 或 0.96，不随训练变化。`chat_sft.py` 使用更短、更低的版本：300 步内从 0.85 升到 0.95，没有 warmdown 段，原因是 SFT 步数少且从预训练动量热启动。

### 步骤 5 权重衰减调度与 $T_{\text{epoch}}$

Muon 的权重衰减按余弦从满值降到 0：

```python
def get_weight_decay(it):
    return weight_decay_scaled * 0.5 * (1 + math.cos(math.pi * it / num_iterations))
```

$$
\lambda(it)=\lambda_{\text{scaled}}\cdot\frac{1+\cos(\pi\,it/N)}{2}.
$$

$\lambda_{\text{scaled}}$ 由两部分缩放相乘：

```python
weight_decay_scaled = args.weight_decay * math.sqrt(total_batch_size / B_REF) * (D_REF / target_tokens)
```

推导依据是 $T_{\text{epoch}}$ 框架（arXiv:2405.13698）：要求

$$
T_{\text{epoch}}=\frac{B}{\eta\lambda D}
$$

在缩放前后保持不变。设参考配置为 $B_{\text{ref}},\eta_{\text{ref}},\lambda_{\text{ref}},D_{\text{ref}}$，则

$$
\lambda=\lambda_{\text{ref}}\cdot\frac{B}{B_{\text{ref}}}\cdot\frac{\eta_{\text{ref}}}{\eta}\cdot\frac{D_{\text{ref}}}{D}.
$$

代入 $\eta/\eta_{\text{ref}}=\sqrt{B/B_{\text{ref}}}$，得

$$
\lambda=\lambda_{\text{ref}}\cdot\sqrt{\frac{B}{B_{\text{ref}}}}\cdot\frac{D_{\text{ref}}}{D}.
$$

这正是代码中的表达式。对 d12：$B=B_{\text{ref}}$、$D=D_{\text{ref}}$，$\lambda=0.28$。对 d24：$\sqrt{2}\approx1.4142$，$D_{\text{ref}}/D=880{,}807{,}296/5{,}838{,}484{,}992\approx0.1509$，故 $\lambda\approx0.28\times1.4142\times0.1509\approx0.0597$。

两个易被忽略的细节：

- 该调度只写入 Muon 组。训练循环中 `if group['kind'] == 'muon'` 才设置 `weight_decay`，AdamW 组的衰减是 `setup_optimizer` 中硬编码的常数：lm_head 0.01、embedding 0.001、value embedding 0.01、resid 0.05、x0 0、smear 0。
- Muon 使用的是 cautious weight decay：只有更新方向与权重同号时才衰减，异号时跳过。因此同一 $\lambda$ 在不同参数上的有效衰减不同，调度给出的是上界。

> [!info] 版本说明
> `dev/LOG.md` 2026-01-10 记录的权重衰减方案是「默认 0.2，按 $1/\text{width}^2$ 缩放，线性从 1 降到 0」。当前 master 的默认值是 0.28，缩放改为 $T_{\text{epoch}}$ 框架的 $\sqrt{B/B_{\text{ref}}}\cdot D_{\text{ref}}/D$，调度改为余弦。两者都基于同一组实验方向，但数值与公式不同，引用旧日志时必须注明版本。

### 步骤 6 按批大小缩放学习率

`base_train.py` 在构造优化器前计算：

```python
batch_lr_scale = 1.0
batch_ratio = total_batch_size / B_REF
if batch_ratio != 1.0:
    batch_lr_scale = batch_ratio ** 0.5   # η ∝ √(B/B_ref)
```

四个参数组的初始值都乘以它：`unembedding_lr`、`embedding_lr`、`scalar_lr`、`matrix_lr`。注释同时说明来源与置信度：SGD 用线性缩放，AdamW 用平方根缩放是标准做法，Muon 沿用 AdamW 的平方根缩放属于假设（注释原文 `not studied carefully, assumption!`）。

平方根缩放的机制解释：批大小 $B$ 下的梯度是 $B$ 个样本梯度的平均，其噪声标准差 $\sigma$ 约按 $1/\sqrt{B}$ 下降；在最优点附近，最优步长与梯度噪声的标准差成反比，因此 $\eta\propto1/\sigma\propto\sqrt{B}$。线性缩放对应的是「梯度信号与噪声同比放大」的情形，适用于 SGD，不适用于对每个坐标归一化的 AdamW 与 Muon。

d24 的 $B=2^{20}=1{,}048{,}576$，$B/B_{\text{ref}}=2$，故 `batch_lr_scale` $=\sqrt{2}\approx1.4142$。矩阵学习率从 0.02 变为 0.0283，embedding 从 0.3 变为 0.4243。

### 步骤 7 按宽度缩放学习率

`nanochat/gpt.py` 的 `setup_optimizer` 中另有一个缩放：

```python
# Scale the LR for the AdamW parameters by ∝1/√dmodel (tuned for 768 dim model)
dmodel_lr_scale = (model_dim / 768) ** -0.5
```

它只作用于三个 AdamW 组：`lm_head`、`token embedding`、`value embedding`。Muon 矩阵组与标量组不使用该因子。d12 的 $d_{\text{model}}=768$，因子为 1；d24 的 $d_{\text{model}}=1536$，因子为 $1/\sqrt2\approx0.7071$。

机制上，AdamW 的更新对每个坐标近似做了归一化，单步更新幅度约等于学习率，与梯度的绝对大小无关。宽度增加时，残差流中每个坐标承担的通道数增加，若保持每坐标的更新幅度不变，激活的相对变化会随宽度增大；muP 类参数化的常见结论是把 AdamW 类参数的学习率按 $1/\sqrt{d_{\text{model}}}$ 缩小，以保持激活尺度不随宽度漂移。nanochat 的注释写作「tuned for 768 dim model」，说明该指数是经验拟合而非从第一性推出。

一个数值巧合值得注意：d24 的批大小缩放 $\sqrt2$ 与宽度缩放 $1/\sqrt2$ 相乘恰好为 1，因此 d24 的 embedding 有效学习率仍是 0.3，与 d12 相同。这不是设计目标，而是「批大小翻倍、宽度翻倍」同时发生的结果；若 `--target-param-data-ratio` 或 `--aspect-ratio` 改动，这个抵消会消失。

### 步骤 8 参数组的初始学习率表

综合步骤 5 至 7，d12 与 d24 在 speedrun 配置下的初始学习率如下。表中「有效」列已含批大小与宽度缩放，「warmup 第 20 步」列再乘以 $\text{lrm}=0.525$。

| 参数组 | 优化器 | d12 有效 | d24 有效 | d24 warmup@20 | 缩放来源 |
|---|---|---|---|---|---|
| transformer 矩阵 | Muon | 0.0200 | 0.0283 | 0.0148 | 仅批大小 |
| token embedding | AdamW | 0.3000 | 0.3000 | 0.1575 | 批大小 × 宽度 |
| lm_head | AdamW | 0.0080 | 0.0080 | 0.0042 | 批大小 × 宽度 |
| value embedding | AdamW | 0.1500 | 0.1500 | 0.0788 | 批大小 × 宽度 × 0.5 |
| resid 标量 | AdamW | 0.0050 | 0.0071 | 0.0037 | 批大小，再乘 0.01 |
| x0 标量 | AdamW | 0.5000 | 0.7071 | 0.3712 | 仅批大小 |
| smear 门控 | AdamW | 0.2000 | 0.2000 | 0.1050 | 无缩放（硬编码） |
| Muon 权重衰减 | Muon | 0.2800 | 0.0597 | 0.0597 | $\sqrt{B/B_{\text{ref}}}\cdot D_{\text{ref}}/D$ |

表中 d12 的 value embedding 为 $0.3\times0.5=0.15$，resid 为 $0.5\times0.01=0.005$，x0 为 0.5。d24 的 value embedding 为 $0.4243\times0.7071\times0.5=0.15$，resid 为 $0.7071\times0.01=0.007071$。smear 组的学习率在 `setup_optimizer` 中硬编码为 0.2，不参与批大小与宽度缩放，但仍乘以 $\text{lrm}$。

### 步骤 9 手算 warmup 第 20 步

取 d24 配置：$W=40$、$N=5568$、$R=3619$、$f=0.05$、$\lambda_{\text{scaled}}=0.0597$。

乘子：

$$
\text{lrm}(20)=\frac{20+1}{40}=0.525.
$$

矩阵学习率：$0.02828\times0.525=0.01485$。embedding：$0.3\times0.525=0.1575$。lm_head：$0.008\times0.525=0.0042$。x0 标量：$0.7071\times0.525=0.3712$。

权重衰减：

$$
\lambda(20)=0.0597\times\frac{1+\cos(\pi\cdot20/5568)}{2}
=0.0597\times\frac{1+\cos(0.01129)}{2}\approx0.0597\times0.999968\approx0.05970.
$$

余弦在 $it\ll N$ 时几乎为 1，因此 warmup 阶段的权重衰减基本保持满值；这与「先正则化、后退火」的设计一致。

Muon 动量：

$$
\mu(20)=0.85+0.12\times\frac{20}{400}=0.856.
$$

同一时刻若取 $it=3760$（warmdown 中点，训练进度约 67.5%），乘子为 $0.5246$，权重衰减为 $0.0597\times0.5(1+\cos(\pi\cdot3760/5568))\approx0.0597\times0.2382\approx0.0142$，动量为 $0.9350$。三个量同时下降，构成末段的「三重降温」。

### 步骤 10 调度与批大小、深度的联动

把三个缩放放在一起，可以看到它们各自解决不同的问题，且相互耦合：

1. 批大小决定梯度噪声，噪声决定步长。$B$ 翻倍使 $\sigma$ 降为 $1/\sqrt2$，最优步长升为 $\sqrt2$ 倍；这是 `batch_lr_scale` 的唯一依据，与模型宽度无关。
2. 宽度决定激活尺度的敏感性。$d_{\text{model}}$ 翻倍时，AdamW 组的学习率降为 $1/\sqrt2$，以保持每层激活的相对变化；Muon 组不缩放，因为正交化更新已经把更新矩阵的谱范数归一化，宽度的影响被吸收在矩阵形状里。
3. token 预算决定训练时长与衰减比例。$D$ 越大，$N=D/B$ 越大，warmup 的 40 步占比越小，warmdown 的绝对步数 $R=0.65N$ 越大；权重衰减按 $D_{\text{ref}}/D$ 缩小，因为同样步数下更长的训练需要更弱的正则化。
4. 三者的耦合产生可检验的预测。d12 的 $N=2520$（默认 ratio 12），warmup 占 1.6%；d24 的 $N=5568$，warmup 占 0.72%。若把 d12 的 `--num-iterations` 设为 20 做冒烟测试，warmup 的 40 步会覆盖全部训练，学习率峰值只有 $20/40=0.5$，此时任何 loss 曲线都不代表正式配置。这是 `base_train.py` 文档字符串中的 CPU 示例必须同时改 `--num-iterations=20` 与其他参数的原因。

### 在 nanochat 中的落地

调度不是在优化器内部实现的，而是训练循环每次更新前把三个值写入参数组，优化器在 `step()` 中读取。这条链路将本笔记的所有公式与代码对应起来：

| 位置 | 作用 | 去掉或写错会怎样 |
|---|---|---|
| `scripts/base_train.py:get_lr_multiplier` | 三段式乘子 | 若写成余弦，末端不再是 0.05，且 $r$、$f$ 失去显式含义 |
| `scripts/base_train.py:get_muon_momentum` | 0.85→0.97→0.90 的动量调度 | 常数 0.97 会让末段更新带惯性，warmdown 的收敛变差 |
| `scripts/base_train.py:get_weight_decay` | 余弦衰减到 0 | 常数衰减会让末段仍被正则化，且与 $T_{\text{epoch}}$ 框架不一致 |
| `base_train.py` 训练循环的 `for group in optimizer.param_groups` | `group["lr"] = group["initial_lr"] * lrm`，并对 Muon 组写入动量与衰减 | 若直接累乘 `group["lr"]` 会在 resume 后重复缩放 |
| `base_train.py` 的 `batch_lr_scale` 与 `weight_decay_scaled` | 批大小与 $T_{\text{epoch}}$ 缩放 | 缩放只做一次，在 `setup_optimizer` 调用时传入 |
| `nanochat/gpt.py:setup_optimizer` | 七个参数组的初始值、`dmodel_lr_scale`、AdamW 组硬编码衰减 | 组划分错误会让 Muon 作用在 embedding 上或 AdamW 作用在矩阵上 |
| `gpt.py:setup_optimizer` 末尾的 `group["initial_lr"] = group["lr"]` | 快照基准值 | 没有快照则每步乘子会叠加，学习率指数衰减 |
| `nanochat/optim.py:MuonAdamW.step` | 读取 `group["lr"]`、`group["momentum"]`、`group["weight_decay"]` | 组内字段名不匹配会静默使用默认值 |
| `scripts/chat_sft.py:get_lr_multiplier(progress)` | SFT 的同族调度，按进度而非步数 | SFT 不知道总步数，用绝对步数会越界 |

两处只有读优化器源码才能看到的细节：

- Muon 的实际学习率还乘了一个形状因子：`group["lr"] * max(1.0, shape[-2] / shape[-1])**0.5`。对 d24 的 MLP，`c_fc` 形状为 $6144\times1536$，因子为 2，实际学习率约 0.0566；`c_proj` 为 $1536\times6144$，因子为 1，仍为 0.0283；注意力的四个投影是方阵，因子为 1。这个启发式在 `dev/LOG.md` 2026-02-03 被尝试翻转（改为放大宽矩阵），结果在 d12 上略差，未采纳。
- `setup_optimizer` 在返回前为每个组写入 `initial_lr`，训练循环只做乘法而不再读取命令行参数。因此 resume 时 `optimizer.load_state_dict` 会用 checkpoint 中的参数组覆盖当前组，包括 `lr` 与 `initial_lr`；`chat_sft.py` 因此必须在加载优化器之后重新保存并恢复 SFT 自己的学习率，注释写明了这一点。

`chat_sft.py` 的调度参数与预训练不同：`--warmup-ratio=0.0`、`--warmdown-ratio=0.5`、`--init-lr-frac=0.8`、`--final-lr-frac=0.0`。它按 `progress`（已消费数据比例或步数比例）计算，而不是按绝对步数，因为 SFT 常在不知道总步数的情况下按 epoch 停止。`--init-lr-frac=0.8` 表示 SFT 的初始学习率取预训练初始值的 80%，再经过 warmdown 到 0。

## 关键直觉

> [!tip] 调度问题本质上是「学习率对步数的积分」问题：模型在训练中累计的有效步长约为 $\sum_{it}\eta(it)$，而形状决定了这份预算如何分配。nanochat 的三段线性把积分写成闭式：warmup 段贡献 $W\eta_0/2$，平台段贡献 $(N-R-W)\eta_0$，warmdown 段贡献 $R\eta_0(1+f)/2$，三项相加给出总步长预算。批大小、宽度与深度只改变 $\eta_0$ 与 $N$，不改变形状本身；因此调度的形状可以跨 depth 复用，而初始值与衰减系数必须随 $B$、$d_{\text{model}}$、$D$ 重算。该表述与步骤 1 的分段函数、步骤 5 的 $T_{\text{epoch}}$、步骤 6 与 7 的两个缩放逐一对应。

## 例子与代码

下面的程序复现 `get_lr_multiplier`、`get_muon_momentum`、`get_weight_decay` 三个函数，并打印 d24 在关键步上的值。它不依赖 torch。

```python
import math

def schedule(N, it, warmup=40, warmdown_ratio=0.65, final_lr_frac=0.05):
    R = round(warmdown_ratio * N)
    if it < warmup:
        lrm = (it + 1) / warmup
    elif it <= N - R:
        lrm = 1.0
    else:
        progress = (N - it) / R
        lrm = progress + (1 - progress) * final_lr_frac
    if it < 400:
        frac = it / 400
        momentum = (1 - frac) * 0.85 + frac * 0.97
    elif it >= N - R:
        progress = (it - (N - R)) / R
        momentum = 0.97 * (1 - progress) + 0.90 * progress
    else:
        momentum = 0.97
    wd = 0.0597 * 0.5 * (1 + math.cos(math.pi * it / N))
    return lrm, momentum, wd

N = 5568
for it in (0, 20, 39, 40, 1949, 1950, 3760, 5567, 5568):
    lrm, mu, wd = schedule(N, it)
    print(f"it={it:>4d} lrm={lrm:.4f} muon_mu={mu:.4f} wd={wd:.4f}")
```

预期输出：

```text
it=   0 lrm=0.0250 muon_mu=0.8500 wd=0.0597
it=  20 lrm=0.5250 muon_mu=0.8560 wd=0.0597
it=  39 lrm=1.0000 muon_mu=0.8617 wd=0.0597
it=  40 lrm=1.0000 muon_mu=0.8620 wd=0.0597
it=1949 lrm=1.0000 muon_mu=0.9700 wd=0.0434
it=1950 lrm=0.9997 muon_mu=0.9700 wd=0.0434
it=3760 lrm=0.5246 muon_mu=0.9350 wd=0.0142
it=5567 lrm=0.0503 muon_mu=0.9000 wd=0.0000
it=5568 lrm=0.0500 muon_mu=0.9000 wd=0.0000
```

注意 $it=39$ 的动量为 $(1-39/400)\cdot0.85+(39/400)\cdot0.97=0.8617$，$it=1949$ 的权重衰减已因余弦降到 0.0434，说明权重衰减的下降比动量更早开始。$it=5568$ 的乘子 0.05 不会被用于更新，因为该步只做评测与保存。

下面的片段计算 d12 与 d24 各参数组的有效初始学习率，可用于核对步骤 8 的表。

```python
import math

def groups(depth, ratio=8, bb=16, T=2048, world=8):
    N_ref = 110_100_912                      # d12 的 scaling params
    N = {12: 110_100_912, 24: 729_810_624}[depth]
    D, D_ref = ratio * N, ratio * N_ref
    B = 2 ** round(math.log2(2**19 * (D / D_ref) ** 0.383))
    batch = (B / 2**19) ** 0.5
    width = (768 if depth == 12 else 1536) / 768
    width = width ** -0.5
    wd = 0.28 * batch * (D_ref / D)
    return {
        "matrix": 0.02 * batch,
        "embedding": 0.3 * batch * width,
        "lm_head": 0.008 * batch * width,
        "value_emb": 0.3 * batch * width * 0.5,
        "resid": 0.5 * batch * 0.01,
        "x0": 0.5 * batch,
        "smear": 0.2,
        "weight_decay": wd,
    }

for d in (12, 24):
    g = groups(d)
    print(d, {k: round(v, 6) for k, v in g.items()})
```

预期输出：

```text
12 {'matrix': 0.02, 'embedding': 0.3, 'lm_head': 0.008, 'value_emb': 0.15, 'resid': 0.005, 'x0': 0.5, 'smear': 0.2, 'weight_decay': 0.28}
24 {'matrix': 0.028284, 'embedding': 0.3, 'lm_head': 0.008, 'value_emb': 0.15, 'resid': 0.007071, 'x0': 0.707107, 'smear': 0.2, 'weight_decay': 0.059738}
```

第二段的 `resid` 与 `x0` 说明了一个容易忽略的事实：`setup_optimizer` 中 `resid_params` 的学习率是 `scalar_lr * 0.01`，且不乘宽度因子；`x0_params` 是 `scalar_lr`，也不乘宽度因子。因此 d24 的 resid 学习率为 $0.5\times1.4142\times0.01=0.007071$，而不是 $0.005\times0.7071$。

## 易错点

> [!warning] 以下六条均可通过读 `base_train.py` 或 `gpt.py` 直接验证。
>
> 1. 把 `lrm` 当成绝对学习率。日志中的 `lrm: 0.53` 是无量纲乘子，实际矩阵学习率是 $0.0283\times0.53$，不是 0.53。
> 2. 认为第 0 步学习率为 0。分子是 $it+1$，第 0 步为 $1/W$；若改成 $it/W$，首步为零更新，优化器动量会先空转一步。
> 3. 认为末端学习率 $f\eta_0$ 参与更新。循环在 $it=N$ 时先评测、保存再 `break`，最后一次 `optimizer.step()` 发生在 $it=N-1$，其乘子为 $0.0503$。
> 4. 在短跑中沿用默认 warmup。`--num-iterations=20` 时 40 步 warmup 覆盖全程，峰值乘子只有 0.5；短跑必须同时降低 `--warmup-steps`，否则 loss 曲线不可解释。
> 5. 认为宽度缩放作用于所有组。`dmodel_lr_scale` 只乘 `lm_head`、embedding、value embedding；Muon 矩阵、resid、x0、smear 都不使用它。
> 6. 认为权重衰减是常数。Muon 组的 $\lambda$ 按余弦降到 0，且只在该组生效；AdamW 组的衰减是硬编码常数，不随训练变化。改动 `--num-iterations` 会同时改变 $\lambda(it)$ 的整条曲线。

## 关联笔记

- 前置：[[梯度下降与AdamW]] —— 步长、噪声与解耦权重衰减的定义，是步骤 6 平方根缩放的推导前提。
- 前置：[[Muon优化器]] —— 动量与正交化更新的语义，决定步骤 4 的动量调度为何与 AdamW 不同。
- 前置：[[缩放定律与模型深度]] —— $N$、$B$、$D$ 三个量的推导链，本篇的调度参数全部由它们决定。
- 后续：[[训练脚本与speedrun]] —— 三个调度函数在训练循环中的写入位置，以及日志字段 `lrm` 的含义。
- 跨库：[[优化器与学习率]] —— 通用原理见该篇，本篇只讲 nanochat 的调度形状、参数分组与缩放律，不重复 AdamW 的收敛性分析。

## 达标检测

- [ ] 能写出三段式 $\text{lrm}(it)$ 的分段公式，并说明 $it+1$、`round`、`<=` 三处实现细节的作用。
- [ ] 给定 $N$ 与 warmdown 比例，能算出平台结束步、warmdown 中点与末次更新的乘子。
- [ ] 能手算 warmup 第 20 步的乘子、矩阵学习率、权重衰减与 Muon 动量，并核对步骤 9 的四个数值。
- [ ] 能说明为什么 LLM 预训练常用 warmup 加衰减而不是常数学习率，并给出至少两条线性 warmdown 相对余弦的机制差异。
- [ ] 能推导 $\lambda=\lambda_{\text{ref}}\sqrt{B/B_{\text{ref}}}\cdot D_{\text{ref}}/D$，并解释 $T_{\text{epoch}}$ 保持常数意味着什么。
- [ ] 能列出 d12 与 d24 的六个参数组有效学习率，并指出哪两组不受宽度缩放影响。
- [ ] 能解释批大小缩放与宽度缩放在 d24 上恰好抵消的数值原因，以及什么条件下会失效。
- [ ] 能指出短 horizon 训练中 warmup 与 warmdown 比例失衡的两种表现，并给出修正方式。

## 参考来源

- Karpathy, *nanochat*（commit `92d63d4`），`scripts/base_train.py` 的 `get_lr_multiplier`、`get_muon_momentum`、`get_weight_decay` —— 对应本篇三段式调度、动量调度与余弦权重衰减的全部公式。
- Karpathy, *nanochat*（commit `92d63d4`），`nanochat/gpt.py` 的 `setup_optimizer` —— 对应七个参数组的初始学习率、`dmodel_lr_scale` 与 AdamW 组的硬编码权重衰减。
- Karpathy, *nanochat* `dev/LOG.md`（2026-01-10、2026-02-05、2026-02-16）—— 对应权重衰减的版本差异、批大小缩放的依据，以及 SFT 调度比例的对照。
- Bergsma et al., *Power Laws for Batch Size, Model Size, and Training Horizon*（arXiv:2505.13738）—— 对应 $B_{\text{opt}}\propto D^{0.383}$，即 $B_{\text{total}}$ 与学习率缩放的输入。
- Hägele et al., *Scaling Laws and Compute-Optimal Training Beyond Fixed Training Durations*（arXiv:2405.13698）—— 对应 $T_{\text{epoch}}$ 框架与权重衰减的 $\sqrt{B/B_{\text{ref}}}\cdot D_{\text{ref}}/D$ 缩放。
- McCandlish et al., *An Empirical Model of Large-Batch Training*（arXiv:1812.06162）—— 对应批大小与梯度噪声、临界批大小的关系，即步骤 6 的平方根缩放依据。
