---
tags: [nanochat, sft, 训练脚本]
阶段: 06-中段训练与SFT
难度: ★★★
created: 2026-10-22
related: "[[对话数据与SmolTalk]], [[多选与工具使用数据]], [[从生成式到对话式]], [[指令微调SFT]]"
---

# 有监督微调SFT

## 定义

**有监督微调**（supervised fine-tuning，SFT）在 nanochat 中指 `scripts/chat_sft.py` 执行的完整训练阶段：加载预训练检查点，继承其批大小与学习率，热启动优化器动量但重置学习率，在由 SmolTalk、MMLU、GSM8K 组成的混合数据上做一轮带损失掩码的下一 token 预测，周期性评测 ChatCORE，最后保存到 `chatsft_checkpoints/`。

符号约定如下。批次形状为 $(B,T)$：$B$ 是每步行数，$T$ 是上下文长度，$C=T+1$ 是数据加载器每行的容量。

| 符号 | 含义 |
|---|---|
| $B$ | 每步的行数，$B=\text{total\_batch\_size}/T$ |
| $T$ | 上下文长度，继承自预训练检查点，d24 speedrun 为 2048 |
| $C$ | 每行容量，`row_capacity = T + 1` |
| $\mathbf{u}$ | 一行渲染并打包后的 token id 序列，长度 $C$ |
| $\mathbf{m}$ | 与 $\mathbf{u}$ 等长的掩码，$m_t=1$ 表示位置 $t$ 计入损失 |
| $\mathbf{x}$ | 模型输入，$\mathbf{x}=\mathbf{u}_{0:C-1}$ |
| $\mathbf{y}$ | 目标，$\mathbf{y}=\mathbf{u}_{1:C}$，掩码外置为 $-1$ |
| $\ell$ | 一行中实际内容长度（不含 padding），$\ell\le C$ |
| $p$ | 训练进度，取值 $[0,1]$ |
| $\eta_0$ | 继承自预训练的基础学习率 |
| $\lambda(p)$ | 学习率乘子，由 `get_lr_multiplier` 给出 |

**热启动**（warm start）指加载预训练优化器状态的动量缓冲但重置学习率。**best-fit 打包**（best-fit packing）指在缓冲区中挑选能完整放入当前行剩余空间的最大对话填入，放不下时用 BOS 补齐而不是裁剪。**掩码对齐**（mask alignment）指输入与目标错开一位后，掩码也必须错开一位。**ChatCORE** 是 5 个对话任务 centered accuracy 的均值。

## 为什么重要

预训练之后，模型是一个文档续写器：它掌握语言的统计结构，但没有「回合」与「回复」的概念。SFT 是唯一一个把行为分布从续写改写为应答的训练阶段，因此它决定三件事。

第一，它决定后续阶段能否开始。`scripts/chat_rl.py` 加载 `sft` 检查点作为策略初值，rollout 从 `<|assistant_start|>` 之后采样，奖励函数按 GSM8K 的 `####` 约定判分。若 SFT 模型不会在正确位置停止、不会写出 `#### 数值`、不会发起工具调用，强化学习拿不到有效奖励，梯度信号退化为零。

第二，它决定评测的解释力。ChatCORE 的 3 个 categorical 任务读取的是 `<|assistant_start|>` 之后第一个位置的 logits；这个位置的分布形状完全由 SFT 塑造。`chat_sft.py` 把 ChatCORE 作为训练期指标，每 200 步评测一次，因此训练日志里同时有损失、bpb 与下游准确率三类信号。

第三，它决定成本结构。SFT 只跑一个 epoch，约数百步，但 d24 每步要处理 1,048,576 token（继承预训练的总批大小；脚本回退默认值是 524,288）；数据加载器不做裁剪而做补齐，掩码让 padding 位置不产生梯度但仍参与前向。理解这两点，才能解释为什么 SFT 的吞吐低于预训练、为什么显存占用与上下文长度呈平方关系。

在「懂原理 / 能复现 / 懂工程」三条主线中，本篇同时落在三处：掩码的梯度含义属于原理；一条 `torchrun` 命令跑通属于复现；优化器热启动后学习率必须重置、验证集 bpb 与 ChatCORE 的口径不同属于工程。通用 SFT 目标函数与打包理论见 [[指令微调SFT]] 与 [[数据集质量控制]]，本篇只讲 nanochat 的落地。

## 原理与推导

### 1. 全链路

```mermaid
flowchart TD
    A["load_model base<br/>phase=train"] --> B["继承超参<br/>meta + user_config"]
    B --> C["setup_optimizer<br/>weight_decay=0"]
    C --> D["热启动动量<br/>重置 LR"]
    D --> E["init_lr_frac=0.8<br/>记录 initial_lr"]
    E --> F["TaskMixture<br/>792K 行"]
    F --> G["bestfit-pad 打包<br/>render_conversation"]
    G --> H["训练循环<br/>targets[mask=0]=-1"]
    H --> I["val bpb / ChatCORE<br/>每 200 步"]
    I --> J["save_checkpoint<br/>chatsft_checkpoints"]
```

八个步骤的代码位置与作用如下。

| 步骤 | 位置 | 关键语句 | 作用 |
|---|---|---|---|
| 加载基座 | `chat_sft.py` | `load_model("base", device, phase="train")` | 读取参数、分词器与元数据 |
| 继承超参 | 同上 | 六项 `(name, fallback, source)` 循环 | 使 SFT 与预训练的批大小、学习率同源 |
| 建优化器 | 同上 | `model.setup_optimizer(..., weight_decay=0.0)` | Muon 管矩阵、AdamW 管其余 |
| 热启动 | 同上 | `load_optimizer_state("base", ...)` | 复用动量缓冲 |
| 重置学习率 | 同上 | `group["lr"] *= args.init_lr_frac` | 抵消预训练 warmdown 归零 |
| 建数据 | 同上 | `TaskMixture(train_tasks)` | 792K 行混合 |
| 打包 | `sft_data_generator_bos_bestfit` | best-fit 循环 | 每行塞满完整对话 |
| 训练 | 训练循环 | `loss = model(x, y)` | 掩码后交叉熵 |
| 评测 | 同上 | `run_chat_eval` | ChatCORE |
| 保存 | 同上 | `save_checkpoint` | 供 RL 与 CLI 使用 |

### 2. 目标函数与掩码

SFT 的损失是只在监督位置求平均的负对数似然：

$$
\mathcal{L}(\theta)=-\frac{1}{\sum_{t}m_{t}}\sum_{t=1}^{T-1}m_{t}\log \pi_\theta\bigl(y_{t}\mid \mathbf{x}_{\le t}\bigr),
$$

其中 $y_t$ 是目标序列第 $t$ 个元素，$\mathbf{x}_{\le t}$ 是模型在位置 $t$ 能看到的前缀，$m_t\in\{0,1\}$ 是掩码，分母只统计 $m_t=1$ 的位置。nanochat 用 `F.cross_entropy(..., ignore_index=-1, reduction="mean")` 实现，分母自动等于非 $-1$ 目标的数量，因此与上式一致。

对 logits 求梯度得

$$
\frac{\partial \mathcal{L}}{\partial z_{t,v}}=\frac{m_t}{\sum_{t'}m_{t'}}\bigl(p_{t,v}-\mathbf{1}[v=y_t]\bigr),
$$

被掩码的位置梯度严格为零。这条式子只说明「哪些位置产生学习信号」，不说明「模型是否看到提示」：提示 token 仍然进入前向，是条件分布的一部分。由此可以解释一个常见混淆：掩码没有削弱模型对指令的理解，它改变的是容量分配。

### 3. 超参继承与优化器热启动

`chat_sft.py` 用一个三元组列表声明六项继承，`None` 表示继承，显式传值表示覆盖。

```python
pretrain_user_config = meta.get("user_config", {})
for name, fallback, source in [
    ("max_seq_len",       2048,   meta),
    ("device_batch_size", 32,     meta),
    ("total_batch_size",  524288, meta),
    ("embedding_lr",      0.3,    pretrain_user_config),
    ("unembedding_lr",    0.004,  pretrain_user_config),
    ("matrix_lr",         0.02,   pretrain_user_config),
]:
    arg_val = getattr(args, name)
    pretrain_val = source.get(name)
    if arg_val is None:
        resolved = pretrain_val if pretrain_val is not None else fallback
        setattr(args, name, resolved)
        print0(f"Inherited {name}={resolved} from pretrained checkpoint")
```

继承的目的是让 SFT 的批大小与学习率与预训练处于同一尺度。批大小决定每步的梯度方差，学习率按批大小缩放；预训练阶段按 `--target-param-data-ratio` 与 depth 算出的批大小若在 SFT 中被改成另一个值，学习率却沿用旧值，训练动态会失配。`base_train.py` 把 `device_batch_size`、`max_seq_len`、`total_batch_size` 写进检查点元数据，正是为了这一步。

优化器热启动的动机是动量缓冲。Muon 对矩阵参数维护动量，AdamW 对嵌入与标量维护一阶、二阶矩；预训练结束时这些缓冲仍然有效，从头初始化意味着前几百步在重建它们。`dev/LOG.md` 的记录是「Loading the optimizer works slightly better but not by too much」，收益不大却是免费的。

热启动有一个必须先处理的副作用。`load_state_dict` 会连同 `param_groups` 的元数据一起恢复，包括学习率；而预训练的 warmdown 已经把学习率降到接近零。若直接加载，SFT 会以近零学习率开始训练。代码的解法是先用局部变量保存当前学习率，加载后再写回。

```python
base_lrs = [group["lr"] for group in optimizer.param_groups]
optimizer.load_state_dict(optimizer_data)
del optimizer_data
for group, base_lr in zip(optimizer.param_groups, base_lrs):
    group["lr"] = base_lr
```

随后再做一次缩放，把学习率设为继承值的 0.8：

```python
for group in optimizer.param_groups:
    group["lr"] = group["lr"] * args.init_lr_frac
    group["initial_lr"] = group["lr"]
```

`initial_lr` 是新加的字段，后续每个训练步都用 `group["lr"] = group["initial_lr"] * lrm` 覆写学习率，因此必须在初始化时记录基准值。`--init-lr-frac=0.8` 的来源是 SFT sweep：从 1.0 降到 0.8 略好，`dev/LOG.md` 2026-02-16 条目记为「changed from 1.0 slightly lower to 0.8」。

权重衰减置零有明确理由。`setup_optimizer(..., weight_decay=0.0)` 上方的注释说明预训练在结束时已把 weight decay 衰减到零，SFT 延续这一状态；若在 SFT 重新启用衰减，等于在行为迁移的同时收缩参数范数，两者难以分离。

### 4. 数据混合与 epoch 过采样

训练混合由三行构造。

```python
train_tasks = [
    SmolTalk(split="train"),                                              # 460K 行通用对话
    *[MMLU(subset="all", split="auxiliary_train") for _ in range(args.mmlu_epochs)],  # 每份 100K
    *[GSM8K(subset="main", split="train") for _ in range(args.gsm8k_epochs)],         # 每份 8K
]
train_dataset = TaskMixture(train_tasks)
```

默认 `--mmlu-epochs=3`、`--gsm8k-epochs=4`，因此训练流为 $460\text{K}+3\times100\text{K}+4\times8\text{K}=792\text{K}$ 行。过采样的实现方式是重复构造 `Task` 对象：三个独立的 `MMLU` 实例各有自己的 `index_map` 段，`TaskMixture` 的全局 shuffle 把三段打散，效果是每条 MMLU 样本在一个 epoch 中被看 3 次，且 3 次分散在整个训练过程中。

| 任务 | 划分 | 单份行数 | 份数 | 贡献行数 | 占比 |
|---|---|---|---|---|---|
| SmolTalk | train | 460K | 1 | 460K | 58.1% |
| MMLU | auxiliary_train | 100K | 3 | 300K | 37.9% |
| GSM8K | main/train | 8K | 4 | 32K | 4.0% |

过采样比例不是按行数均衡，而是按能力需要：MMLU 每条样本只有 2 个监督 token，需要更多样本才能让「单字母回答」成为稳定模式；GSM8K 每条样本的监督 token 多，但格式更复杂（两次工具调用与 `####` 行），4 个 epoch 保证协议在训练流中频繁出现。验证混合按同样的任务但不同划分构造，MMLU 裁到 5200 行、GSM8K 裁到 420 行，与训练比例大致对应，总约 29.6K 行。

### 5. best-fit pad 打包

数据加载器每步产出 $(B,T)$ 的 `inputs` 与 `targets`。行内由多条完整对话拼接而成，选择规则是「放得下且最长」。

```python
row_capacity = args.max_seq_len + 1  # +1 for target at last position
bos_token = tokenizer.get_bos_token_id()

def refill_buffer():
    nonlocal cursor, epoch
    while len(conv_buffer) < buffer_size:
        conversation = dataset[cursor]
        ids, mask = tokenizer.render_conversation(conversation)
        conv_buffer.append((ids, mask))
        cursor += ddp_world_size
        if cursor >= dataset_size:
            cursor = cursor % dataset_size
            epoch += 1

# 每行：反复取能完整放入剩余空间的最大对话
while len(row) < row_capacity:
    remaining = row_capacity - len(row)
    best_idx, best_len = -1, 0
    for i, (conv, _) in enumerate(conv_buffer):
        conv_len = len(conv)
        if conv_len <= remaining and conv_len > best_len:
            best_idx, best_len = i, conv_len
    if best_idx >= 0:
        conv, conv_mask = conv_buffer.pop(best_idx)
        row.extend(conv); mask_row.extend(conv_mask)
        consumed += ddp_world_size
    else:
        content_len = len(row)
        row.extend([bos_token] * remaining)   # 补齐而非裁剪
        mask_row.extend([0] * remaining)
        padded = True
        break
```

三个不变式保证算法终止且不丢样本。第一，`render_conversation` 在 2048 处截断，因此任何对话长度 $\le 2048 < C=2049$，空行一定能放下至少一条对话。第二，缓冲区在消耗到低于 `buffer_size` 时立即补充，且每个 rank 以 `ddp_world_size` 为步长取不同样本，8 卡训练时各 rank 看到互不重叠的对话。第三，若当前缓冲区的所有对话都放不进剩余空间，就补齐并结束该行，不会无限等待。

为什么补齐而不是裁剪，是这个加载器与预训练加载器的核心差异。预训练数据是连续文档流，任意 token 都是可替换的训练信号，裁掉尾部片段只损失少量信息，换来 100% 的行利用率（见 [[数据加载器dataloader]]）。SFT 的监督信号不是 token 而是「完整对话中有哪些 assistant 段」：裁掉尾部会同时裁掉 `<|assistant_end|>`，该行的停止监督消失；更严重的是若裁剪落在 assistant 段中间，标签变成半句话，模型学到的是截断的回复。

补齐的代价是可以界定的。设一行已有 $k$ 条完整对话、共 $\sum_{i\le k}\ell_i$ 个 token，则剩余空间 $C-\sum_{i\le k}\ell_i$ 全部被补齐。这个空间的每一项都短于缓冲区中任意一条未放入的对话，因此补齐长度小于「最短的未放入对话」的长度。在 2049 容量、平均对话约 250 token 的分布下，每行约 8 条对话，期望补齐约为半条对话，即容量的 5% 至 8%。这部分位置的前向计算没有梯度收益，但它们不改变损失：padding token 的掩码为 0。

打包还带来一个容易被忽略的性质：行内多条对话之间没有块对角注意力掩码。第 $j$ 条对话的 token 可以注意前 $j-1$ 条对话的内容，与推理时「单对话上下文」不一致。nanochat 接受这一近似，理由是每条对话以 `<|assistant_end|>` 结束、下一条以 BOS 开始，模型有明确的边界信号；若要严格隔离，需要变长注意力或块对角掩码，代价是更高的实现复杂度。判断是否可接受的标准是对比训练与推理的损失差：若行内串味显著，验证损失会低于真实留出损失。

### 6. render_conversation 的掩码规则

掩码在渲染阶段一次生成，训练阶段不再推断。逐类列如下。

| token 类 | 掩码 | 理由 |
|---|---|---|
| `<|bos|>` | 0 | 文档边界，由加载器注入 |
| `<|user_start|>` | 0 | 角色控制符，运行时注入 |
| user 内容 | 0 | 条件项，不是要生成的回复 |
| `<|user_end|>` | 0 | 同上 |
| `<|assistant_start|>` | 0 | 由 `chat_cli` 或 `Engine` 注入，不是模型输出 |
| assistant 文本内容 | 1 | 唯一的学习目标 |
| `<|python_start|>` | 1 | 模型必须学会发起调用 |
| python 表达式 | 1 | 模型必须写出表达式 |
| `<|python_end|>` | 1 | 结束调用 |
| `<|output_start|>` | 0 | 运行时注入 |
| python 输出内容 | 0 | 解释器产生，不由模型生成 |
| `<|output_end|>` | 0 | 运行时注入 |
| `<|assistant_end|>` | 1 | 唯一的停止信号 |

两条规则需要单独说明。`<|assistant_start|>` 的掩码为 0，因为它不是回复的一部分：推理时它总是紧接在 `<|user_end|>` 之后由代码追加，模型若在回复中间生成它，运行时会把它当作普通 token 继续解码，产生协议违规。把它排除在损失之外，模型不需要学习「何时输出开始符」，只需要学习「开始符之后输出什么」。

`<|assistant_end|>` 的掩码为 1，因为它是模型必须主动输出的唯一控制符。`Engine` 在生成到该 token 时结束该行，`chat_cli` 在生成因长度上限中断时手工补上它。若它不被监督，模型永远学不会停止，推理会一直生成到 `max_tokens`。

渲染末尾还有一次截断：`ids = ids[:max_tokens]`、`mask = mask[:max_tokens]`，`max_tokens` 默认为 2048。截断是防止 OOM 的保险，代价是超长对话可能失去 `<|assistant_end|>`，该行因此没有停止监督。对于 SmolTalk 与 GSM8K 的绝大多数样本，长度远低于 2048，这一风险只在人工构造的长对话上出现。

### 7. 掩码与 targets 的对齐

数据加载器把渲染结果拼成行后，做四步变换。

```python
batch_tensor = torch.tensor(rows, dtype=torch.long, pin_memory=use_cuda)
inputs = batch_tensor[:, :-1].to(device=device, dtype=torch.int32, non_blocking=use_cuda).contiguous()
targets = batch_tensor[:, 1:].to(device=device, dtype=torch.int64, non_blocking=use_cuda).contiguous()

# mask[1:] 与右移后的 targets 对齐；掩码为 0 的位置写 -1（ignore_index）
mask_tensor = torch.tensor(mask_rows, dtype=torch.int8)
mask_targets = mask_tensor[:, 1:].to(device=device)
targets[mask_targets == 0] = -1

# padding 位置从 content_len-1 起置 -1
for i, content_len in enumerate(row_lengths):
    if content_len < row_capacity:
        targets[i, content_len-1:] = -1
```

位置关系必须逐项核对。原始序列 $\mathbf{u}$ 长度为 $C$；输入取前 $C-1$ 个，目标取后 $C-1$ 个，即 $\mathbf{y}_t=\mathbf{u}_{t+1}$。位置 $t$ 的 logits 要预测的是 $\mathbf{u}_{t+1}$，该位置是否计入损失由 $\mathbf{u}_{t+1}$ 的掩码决定，所以掩码也必须右移一位：`mask_targets[t] = mask[t+1]`。若直接用 `mask[:, :-1]`，掩码与目标错开一位，损失仍能计算且数值相近，属于静默错误：第一个 assistant 内容 token 失去监督，而 `<|assistant_end|>` 之后紧跟的 BOS（或下一轮的 user 标记）被误监督。前者让回复开头缺少训练信号，后者让非回复内容参与损失。

以一条 6 token 的对话为例。渲染结果为 $\mathbf{u}=[\text{BOS},\ \texttt{<|user\_start|>},\ x,\ \texttt{<|user\_end|>},\ \texttt{<|assistant\_start|>},\ y]$，掩码 $\mathbf{m}=[0,0,0,0,0,1]$，即用户内容为单个 token、assistant 内容为单个 token。

| $t$ | $\mathbf{u}_t$ | $m_t$ | 输入 $\mathbf{x}_t=\mathbf{u}_t$ | 原始目标 $\mathbf{u}_{t+1}$ | $m_{t+1}$ | 最终 $\mathbf{y}_t$ |
|---|---|---|---|---|---|---|
| 0 | BOS | 0 | BOS | `<|user_start|>` | 0 | -1 |
| 1 | `<|user_start|>` | 0 | `<|user_start|>` | $x$ | 0 | -1 |
| 2 | $x$ | 0 | $x$ | `<|user_end|>` | 0 | -1 |
| 3 | `<|user_end|>` | 0 | `<|user_end|>` | `<|assistant_start|>` | 0 | -1 |
| 4 | `<|assistant_start|>` | 0 | `<|assistant_start|>` | $y$ | 1 | $y$ |
| 5 | $y$ | 1 | 只作为目标 | 无 | 无 | 无 |

6 个 token 产生 5 个预测位置，只有位置 4 的预测计入损失：输入是 `<|assistant_start|>`，目标是 $y$。这是训练与推理对齐的最小单位——推理时模型看到以 `<|assistant_start|>` 结尾的提示，采样下一个 token，正好是训练中被监督的那个位置。

补上 `<|assistant_end|>` 后（第 7 个 token，掩码 1），位置 5 也进入监督：输入 $y$，目标是结束符。两处监督构成最小的完整样本。

padding 的偏移同样要按右移关系计算。若内容长度 $\ell<C$，最后一个内容 token 在索引 $\ell-1$；它的预测目标是索引 $\ell$，即第一个 padding BOS，掩码为 0，本来就会被置 $-1$。代码仍然显式写 `targets[i, content_len-1:] = -1`，作用是对「padding 的掩码被误写成 1」这一错误做二次防线：即使掩码写错，该位置的目标也已被置为忽略值。两处逻辑重复，但代价为零。

### 8. 为什么不能对 user token 算损失

四条论证，从强到弱。

目标函数不匹配。SFT 要建模的是条件分布 $\pi_\theta(y\mid x)$，其中 $x$ 是用户侧提示、$y$ 是回复。把 user token 计入损失，优化的目标变成联合分布 $\pi_\theta(x,y)$，其最小化解是数据的联合分布，而不是给定提示时的回复分布。两者在贝叶斯意义下不同：前者需要为「用户会问什么」分配概率，而推理时用户输入由外部给出，这部分概率永远用不到。

容量分配错误。参数容量有限，梯度会流向能降低损失的方向。user token 的分布由人类提问习惯决定，模式相对简单且与「如何回答」无关；把这些位置纳入损失，模型会把容量用于复述输入，而不是组织输出。可观察的后果是回复中出现对问题的重复，或回复开头复读关键词。

归一化分母被污染。损失按有效 token 平均，若 user token 计入分母，分母由提示长度主导，回复长度的变化被稀释。同样一条回复，在长提示下损失更小，梯度更小，等效于对长提示样本降权。这会与数据分布耦合：SmolTalk 与 MMLU 的提示长度差异很大，混合比例的实际权重随之漂移。

与推理路径不一致。推理时 `chat_cli` 把用户输入编码后直接拼进上下文，模型从不「生成」用户输入。训练时若对 user token 计损失，等于训练一个推理时不会被使用的行为，属于纯浪费；更糟的是它会让模型在自由生成时倾向于模仿用户语气，产生角色混淆。

### 9. 学习率调度与 Muon 动量

学习率由进度驱动，而不是由绝对步数驱动。

```python
def get_lr_multiplier(progress):
    if progress < args.warmup_ratio:
        return (progress + 1e-8) / args.warmup_ratio      # 线性升温
    elif progress <= 1.0 - args.warmdown_ratio:
        return 1.0                                        # 恒定
    else:
        decay = (progress - (1.0 - args.warmdown_ratio)) / args.warmdown_ratio
        return (1 - decay) * 1.0 + decay * args.final_lr_frac   # 线性降到 final
```

默认 `--warmup-ratio=0.0`、`--warmdown-ratio=0.5`、`--final-lr-frac=0.0`。代入得下表。

| 进度 $p$ | $\lambda(p)$ | 矩阵学习率 $\eta=0.8\times0.02\times\lambda$ |
|---|---|---|
| 0.00 | 1.00 | 0.0160 |
| 0.25 | 1.00 | 0.0160 |
| 0.50 | 1.00 | 0.0160 |
| 0.75 | 0.50 | 0.0080 |
| 0.90 | 0.20 | 0.0032 |
| 1.00 | 0.00 | 0.0000 |

进度 $p$ 有两个来源。给定 `--num-iterations` 时 $p=\text{it}/\text{num\_iterations}$；默认 `-1` 时按数据量计算 $p=\text{consumed}/\text{dataset\_size}$，即一个 epoch 的比例。代码用 `progress = max(progress, approx_progress)` 保证单调：`approx_progress` 由数据生成器在预取下一批时更新，可能领先于当前实际应用的最后一步梯度，取最大值使进度只增不减，学习率乘子因此沿同一方向变化。

用进度而非步数，原因是 SFT 的步数由数据量与批大小共同决定，常被改动的量（`--device-batch-size`、epoch 数）都会改变总步数；用比例表示后，调度形状与数据规模解耦。

Muon 动量按步数线性升温：

```python
def get_muon_momentum(it):
    frac = min(it / 300, 1)
    momentum = (1 - frac) * 0.85 + frac * 0.95
    return momentum
```

第 0 步为 0.85，第 150 步为 0.90，第 300 步及以后固定为 0.95。这一形状与 `base_train.py` 相同，含义是早期用较小动量避免初始批次的方向偏差被放大，后期用较大动量平滑噪声。SFT 只跑数百步，因此动量几乎全程处在升温段；若把 SFT 的步数误认为与预训练同量级，会误判这一调度无足轻重。

优化器状态更新只在满足 `group['kind'] == 'muon'` 的参数组上写动量，AdamW 组的 betas 不受影响。

### 10. ChatCORE 与 centered baseline

ChatCORE 是 5 个任务的 centered accuracy 均值，定义与 CORE 同构。

$$
\text{centered}_i=\frac{\text{acc}_i-b_i}{1-b_i},\qquad
\text{ChatCORE}=\frac{1}{5}\sum_{i=1}^{5}\text{centered}_i,
$$

其中 $\text{acc}_i$ 是第 $i$ 个任务的准确率，$b_i$ 是该任务的随机基线。

| 任务 | 类型 | 基线 $b_i$ | 说明 |
|---|---|---|---|
| ARC-Easy | categorical | 0.25 | 四选一 |
| ARC-Challenge | categorical | 0.25 | 四选一 |
| MMLU | categorical | 0.25 | 四选一 |
| GSM8K | generative | 0.0 | 开放生成，无随机基线 |
| HumanEval | generative | 0.0 | 开放生成，无随机基线 |

centered 的作用是让不同随机基线的任务可比。categorical 任务的 25% 来自随机猜测，若直接平均，模型在三个多选题上各拿 30% 会贡献 0.30，而 GSM8K 拿 5% 只贡献 0.05，两者的「超出随机水平」程度被混淆。centered 后 30% 对应 $(0.30-0.25)/0.75=0.067$，5% 对应 $0.05$，量纲统一为「从随机到完美的相对位置」。

一个手算例子。设某检查点测得 ARC-Easy 0.40、ARC-Challenge 0.28、MMLU 0.32、GSM8K 0.02、HumanEval 0.05，则

$$
\text{ChatCORE}=\frac{0.200+0.040+0.093+0.020+0.050}{5}=0.0807,
$$

其中前三项分别是 $(0.40-0.25)/0.75=0.200$、$(0.28-0.25)/0.75=0.040$、$(0.32-0.25)/0.75=0.093$。`chat_sft.py` 还单独记录 `chatcore_cat`，只平均前三个 categorical 任务，本例为 $(0.200+0.040+0.093)/3=0.111$。两个数分开记录的理由是它们回答不同问题：`chatcore_cat` 衡量格式与知识，ChatCORE 还包含生成与算术能力，后者噪声更大。

评测频率由 `--chatcore-every=200` 控制，每个评测点跑 5 个任务。categorical 任务默认不限题数（`--chatcore-max-cat=-1`），generative 任务每个任务最多 24 道题（`--chatcore-max-sample=24`）；后者的限制是为了控制时间，因为 GSM8K 与 HumanEval 需要自回归生成。

> [!info] 版本说明
> `dev/LOG.md` 2026-02-16 条目写 ChatCORE「across all 6 tasks」，当前快照的 `chat_sft.py` 与 `chat_eval.py` 中 `all_tasks` 只有 5 项（ARC-Easy、ARC-Challenge、MMLU、GSM8K、HumanEval）。以代码为准：5 项，基线为 0.25/0.25/0.25/0/0。

### 在 nanochat 中的落地

| 语句 | 文件 | 为什么这样做 | 去掉会怎样 |
|---|---|---|---|
| `torch.compile(model, dynamic=False)` | `chat_sft.py` | 固定形状，编译收益最大 | 退回 eager 模式，吞吐下降 |
| `assert total_batch_size % world_tokens_per_fwdbwd == 0` | 同上 | 保证梯度累积整除 | 静默丢弃余数 token |
| `base_lrs = [...]; load_state_dict; 写回` | 同上 | 抵消 `param_groups` 覆盖 | 近零学习率起步 |
| `group["initial_lr"] = group["lr"]` | 同上 | 每步用基准值乘乘子 | 学习率逐级衰减 |
| `progress = max(progress, approx_progress)` | 同上 | 进度与已应用的步对齐 | 进度被预取提前推进 |
| `targets[mask_targets == 0] = -1` | 数据加载器 | 掩码右移一位后置忽略 | 提示词参与损失 |
| `targets[i, content_len-1:] = -1` | 同上 | padding 二次防线 | 掩码写错时 pad 进入损失 |
| `last_step` 的 `all_reduce(MAX)` | 训练循环 | 各 rank 同时退出 | 部分 rank 挂起或提前结束 |
| `Engine(orig_model, tokenizer)` | 评测分支 | 避免动态形状触发重编译 | 评测变慢或报错 |
| `gc.freeze(); gc.disable()` | 训练循环 | 避免周期性停顿 | 出现数百毫秒的停顿 |
| `save_checkpoint(..., rank=ddp_rank)` | 保存分支 | 各 rank 存优化器分片 | 优化器状态不完整 |
| `chatsft_checkpoints/{model_tag or d{depth}}` | 同上 | 与 base/rl 目录区分 | `load_model("sft")` 找不到 |

两处数据流细节值得单独记录。其一是精度类型：`inputs` 转成 `torch.int32`、`targets` 转成 `torch.int64`，前者用于 embedding 索引，后者用于交叉熵的目标；类型不一致是 PyTorch 的常见报错来源，这里提前显式转换。其二是 `pin_memory` 与 `non_blocking`：CUDA 下把批次固定到页锁定内存并异步拷贝，与下一步的前向重叠。两者都是吞吐优化，不影响正确性。

还有一处与元数据有关：`user_config = vars(args).copy()` 在继承之前执行，因此 SFT 检查点里保存的 `user_config` 中，未被显式传入的继承项仍是 `null`。若想从 SFT 检查点复原训练配置，必须同时读 `meta` 里的实际批大小与 `user_config` 里的显式覆盖，不能只看其一。

## 关键直觉

> [!tip] SFT 的三个机制各管一件事：掩码决定「哪些位置产生梯度」，打包决定「一行里放几条对话」，学习率重置决定「从哪里接上预训练」。三者互不替代，且都对损失曲线之外的指标负责：掩码错了，损失会下降而评测不涨；打包错了，验证损失虚低；学习率没重置，训练几乎不动。
>
> 与严格定义的关系：定义中的 $m_t$ 是掩码，$\mathbf{u}$ 的拼接方式是打包，$\eta_0\lambda(p)$ 是调度。目标函数只依赖 $m_t$ 与 $\mathbf{y}$，不依赖 $B$、$C$ 或 $\lambda$；因此改变批大小或调度不会改变最优解，只改变优化路径与步数。判断一次改动是否影响「模型能学到什么」看掩码与目标，判断它是否影响「多久学到」看批大小、打包与调度。

## 例子与代码

第一段手算掩码导致的损失稀释。设一条样本只有 2 个监督目标，正确 token 的概率分别为 0.25 与 0.9；若把 4 个提示词位置也计入，设其概率均为 0.5。

```python
"""掩码缺失对损失数值的影响。"""
import math

sup = [-math.log(0.25), -math.log(0.9)]                 # 两个监督目标
prompt = [-math.log(0.5)] * 4                             # 四个提示词位置
print(f"只监督回复: {sum(sup) / len(sup):.4f}")           # 分母 2
print(f"计入提示词: {sum(sup + prompt) / 6:.4f}")         # 分母 6
print(f"若按 token 求和: {sum(sup + prompt):.4f}")
```

预期输出如下。

```text
只监督回复: 0.7458
计入提示词: 0.7107
若按 token 求和: 4.2642
```

损失从 0.7458 降到 0.7107，但模型对回复的拟合没有任何改善：提示词位置的概率均为 0.5，其负对数似然 0.693 低于两个回复目标的平均值 0.7458，把四个这样的位置混进分母后，平均值被拉低。若直接观察损失曲线，会误判「加入提示词有助于训练」。第三行给出未归一化的和，说明分母的选择决定了不同配置之间能否比较；`F.cross_entropy` 的 `reduction="mean"` 在 `ignore_index` 下自动按有效目标数归一，与第一行一致。

第二段验证掩码与目标的右移对齐，纯 Python，可逐位核对。

```python
"""6 token 对话的掩码与目标对齐（与 chat_sft.py 的变换等价）。"""
BOS, US, UE, AS, AE = 0, 1, 2, 3, 4
row   = [BOS, US, 204, UE, AS, 205]          # 6 个 token，y=205
mask  = [0,   0,  0,   0,  0,  1]
capacity = 7                                  # 第 7 个位置留给 assistant_end

row.append(AE); mask.append(1)                # 补上结束符
row.extend([BOS] * (capacity - len(row)))     # 无剩余空间时补齐（此处为空）
mask.extend([0] * (capacity - len(row)))

inputs  = row[:-1]
targets = row[1:]
mask_targets = mask[1:]
targets = [-1 if m == 0 else t for t, m in zip(targets, mask_targets)]

print("inputs :", inputs)
print("targets:", targets)
print("监督目标数:", sum(t != -1 for t in targets))

# 手工核对：位置 4 的输入是 assistant_start，目标是 y；位置 5 的目标是结束符
assert inputs[4] == AS and targets[4] == 205
assert targets[5] == AE
```

预期输出如下。

```text
inputs : [0, 1, 204, 2, 3, 205]
targets: [-1, -1, -1, -1, 205, 4]
监督目标数: 2
```

`targets` 的前四项为 $-1$，对应位置 0 至 3 的预测目标是 user 侧 token；第五项是 $y=205$，第六项是结束符 $4$。若把 `mask_targets` 写成 `mask[:-1]`，第五项（本应是 $205$）会变成 $-1$，第一个 assistant 内容 token 因此失去监督；当一行内包含多条对话时，`<|assistant_end|>` 之后的第一个 BOS 还会被误监督。损失仍能算出，曲线也平滑，但监督集合整体错位了一位。

第三段引用 repo 的掩码与损失语句，便于对照。

```python
# chat_sft.py: 掩码右移一位后写入忽略值
mask_tensor = torch.tensor(mask_rows, dtype=torch.int8)
mask_targets = mask_tensor[:, 1:].to(device=device)
targets[mask_targets == 0] = -1

# gpt.py: GPT.forward 的损失，ignore_index=-1 跳过掩码位置
loss = F.cross_entropy(logits.view(-1, logits.size(-1)), targets.view(-1),
                       ignore_index=-1, reduction=loss_reduction)
```

两段合起来构成完整链路：加载器把掩码翻译成 $-1$，模型把 $-1$ 解释为「不计入分子也不计入分母」。中间没有别的约定，因此任何绕过加载器手工构造 `targets` 的代码都必须自己完成 $-1$ 的写入，不能指望模型推断掩码。

第四段是运行命令与预期日志。8 卡、d24、继承预训练批大小。

```bash
torchrun --standalone --nproc_per_node=8 -m scripts.chat_sft -- --run=sft-d24
```

启动日志的前五行由继承结果与批大小算术决定，最后一行是一次训练步的示意输出；`dt`、`tok/sec`、`mfu` 随硬件变化，此处标注为示例值而非某次运行记录。

```text
Inherited max_seq_len=2048 from pretrained checkpoint
Inherited device_batch_size=16 from pretrained checkpoint
Inherited total_batch_size=1048576 from pretrained checkpoint
Total batch size 1,048,576 => gradient accumulation steps: 4
Training mixture: 792,000 rows (MMLU x3, GSM8K x4)
step 00001 (0.05%) | loss: 1.874210 | lrm: 1.00 | dt: 412.35ms | tok/sec: 1,271,652 | mfu: 38.42 | epoch: 1 | total time: 0.01m
```

混合行数 792,000 是 repo 注释给出的三个量之和（$460\text{K}+3\times100\text{K}+4\times8\text{K}$），实际打印值随数据集版本略有差异。`grad_accum_steps=4` 来自 $1{,}048{,}576/(16\times2048\times8)=4$；若预训练元数据缺失而回退到 524,288，则对应 2。进度按已消费行数占数据规模的比例计算，与步数没有固定换算；`lrm: 1.00` 说明初始学习率乘子为 1，此时有效矩阵学习率为 $0.8\times0.02=0.016$。

## 易错点

> [!warning] 以下六条都能在日志、梯度检查或张量抽查中定位。
> 1. 掩码未右移一位。`mask_targets = mask[:, :-1]` 会让监督集合整体错位一位：第一个 assistant 内容 token 失去监督，紧随结束符的 token 被误监督；损失仍平滑下降，评测不涨。验证方法是本笔记第二段代码的断言。
> 2. 热启动后不重置学习率。`load_state_dict` 把预训练 warmdown 后的近零学习率带回 SFT，表现为损失几乎不动而梯度范数正常；必须按 `base_lrs` 写回，并在 `init_lr_frac` 之后记录 `initial_lr`。
> 3. 把 padding token 的掩码写成 1。补齐位置是 BOS，若被监督，模型会学到在对话中输出 BOS，推理时表现为生成突然中断；`content_len-1` 的二次防线只能挡住目标，挡不住 `attention` 分布被污染。
> 4. 认为补齐浪费了算力所以应当裁剪。裁剪会切掉 `<|assistant_end|>` 或半条回复，导致该行没有停止监督或标签不完整；两者相比，补齐的 5% 至 8% 浪费是更小的代价。
> 5. 用固定步数而非进度实现调度。改动批大小或 epoch 数后，warmdown 的起点随之漂移，两个实验的学习率曲线不可比；进度驱动让调度形状与数据规模解耦。
> 6. 把 `chatcore_cat` 与 ChatCORE 混用。前者只含 3 个 categorical 任务，后者含 5 个；在小模型上二者可能相差数倍，报告时必须写明口径。

## 关联笔记

- 前置 [[对话数据与SmolTalk]]：460K 行通用对话的来源、断言与 `HubDataset` 缓存机制，是本篇数据管线的输入。
- 前置 [[多选与工具使用数据]]：`render_mc` 与 GSM8K 分片协议决定了本篇掩码表中 python 与 output 两类的取值。
- 前置 [[交叉熵与困惑度]]：`ignore_index` 与按有效 token 平均的语义，是掩码能工作的数学前提。
- 后续 [[从生成式到对话式]]：解释 SFT 之后模型行为如何改变，以及推理时如何拼接对话 token。
- 后续 [[GRPO原理与实现]]：以本篇的检查点为策略初值，rollout 与奖励在 GSM8K 上定义。
- 跨库 [[指令微调SFT]]：通用目标函数、打包理论、LoRA 与灾难遗忘的完整讨论；本篇只讲 nanochat 的实现选择。

## 达标检测

- [ ] 默写 SFT 目标函数与 logits 梯度式，说明掩码位置梯度为零而提示词仍参与前向。
- [ ] 列出六项继承超参的来源与回退值，解释为什么批大小必须继承而不是重新调。
- [ ] 说明热启动后为什么必须重置学习率，以及 `initial_lr` 字段的作用。
- [ ] 手算 $p=0.75$、$p=0.9$ 时的学习率乘子与矩阵学习率，并说明 `progress = max(progress, approx_progress)` 的必要性。
- [ ] 用 6 token 例子画出掩码与目标的对齐表，指出 `mask[:, :-1]` 会错在哪一行。
- [ ] 解释 best-fit pad 的三个不变式，并估算一行 2049 容量的期望补齐比例。
- [ ] 给出四条不对 user token 计算损失的理由，并各指出一个可观察的后果。
- [ ] 用给定准确率手算 ChatCORE 与 `chatcore_cat`，说明二者为何分开记录。

## 参考来源

- Ouyang et al., "Training language models to follow instructions with human feedback", arXiv:2203.02155, 2022 —— 对应「为什么重要」中 SFT 在预训练与对齐之间的位置，以及第 8 节条件分布与联合分布的区别。
- Allal et al., "SmolLM2: When Smol Goes Big — Data-Centric Training of a Small Language Model", arXiv:2502.02737, 2025 —— 对应第 4 节中小模型的数据规模取舍与 epoch 过采样动机。
- Hendrycks et al., "Measuring Massive Multitask Language Understanding", arXiv:2009.03300, 2021；Cobbe et al., "Training Verifiers to Solve Math Word Problems", arXiv:2110.14168, 2021 —— 对应第 4 节混合中的 MMLU 与 GSM8K 两个任务及其划分。
- Karpathy, *nanochat*（commit 92d63d4），`scripts/chat_sft.py`、`nanochat/tokenizer.py`、`nanochat/gpt.py`、`scripts/chat_eval.py` —— 对应第 1 至 10 节与「在 nanochat 中的落地」一节的实现细节、示例代码与表格。
- Karpathy, *nanochat*（commit 92d63d4），`dev/LOG.md` 2026-02-16「SFT Script Upgrades」 —— 对应第 3 节的优化器热启动与 `--init-lr-frac` 从 1.0 改为 0.8、第 4 节的 epoch 数调整，以及第 10 节的版本说明。
