---
tags: [AI, sft, 微调]
阶段: 07-微调与对齐
难度: ★★★
created: 2026-10-18
related: "[[数据集质量控制]], [[LoRA与QLoRA]], [[对齐-RLHF]]"
---

# 指令微调SFT

## 定义

**监督指令微调**（supervised fine-tuning，SFT）指在已预训练的语言模型上，用「指令—回复」成对数据继续训练，使模型在给定指令与上下文的条件下提高人类撰写回复的似然。其目标函数为

$$
\mathcal{L}(\theta)=-\frac{1}{\sum_{b=1}^{B}\sum_{t=1}^{L}m_{b,t}}
\sum_{b=1}^{B}\sum_{t=1}^{L}m_{b,t}\log \pi_\theta\bigl(y_{b,t}\mid x_b,y_{b,<t}\bigr),
$$

其中 $\pi_\theta$ 是参数为 $\theta$ 的自回归语言模型给出的下一 token 分布，$x_b$ 是第 $b$ 条样本的指令部分（system 与 user 角色的 token 序列），$y_b=(y_{b,1},\dots,y_{b,T_b})$ 是 assistant 角色的回复，$L$ 是补齐后的序列长度，$m_{b,t}\in\{0,1\}$ 是**损失掩码**（loss mask），回复 token 取 1、其余取 0，$B$ 是批大小。

符号与术语逐项说明。

| 符号 | 含义 |
|---|---|
| $x_b$ | 第 $b$ 条样本的提示部分，包含模板特殊 token |
| $y_{b,t}$ | 第 $b$ 条样本回复的第 $t$ 个 token |
| $m_{b,t}$ | 损失掩码，只对回复 token 为 1 |
| $L$ | 打包或补齐后的固定序列长度 |
| $B$ | 每步的序列条数 |
| $z_{b,t}\in\mathbb{R}^{V}$ | 模型在位置 $(b,t)$ 输出的 logits，$V$ 为词表大小 |
| $\pi_\theta(\cdot\mid\cdot)$ | softmax 后的下一 token 分布 |
| $\mathrm{pad}$ | 补齐 token，其标签置为 $-100$ 后被忽略 |

**对话模板**（chat template）指把 role 与 content 映射为一段 token 序列的固定格式，包含角色标记、分隔符与结束符。**序列打包**（packing）指把多条短样本首尾相接填入同一长度为 $L$ 的窗口。**交叉污染**（cross-contamination）指打包后不同样本的 token 在同一注意力窗口内互相可见。**灾难遗忘**（catastrophic forgetting）指微调后模型在微调分布之外的能力显著下降。**全参数微调**（full fine-tuning）指更新全部权重；**参数高效微调**（parameter-efficient fine-tuning，PEFT）指只更新少量新增或选定参数。

## 为什么重要

预训练的目标是建模互联网文本的下一 token 分布，其中同时包含问答、代码、论坛争论与网页模板。模型因此学到的是「续写」而非「应答」：给定一个指令，它可能续写出更多类似指令的文本，而不是执行指令。SFT 通过把损失集中在回复 token 上，把「续写分布」改写为「条件于指令的回复分布」。

InstructGPT 的做法说明了这一阶段的位置：先收集约 1.3 万条人工示范做 SFT，再用人类偏好训练奖励模型并做强化学习；没有 SFT 时，强化学习阶段的策略在长序列上难以稳定探索。FLAN 在 60 余个任务上做指令微调，观察到模型对未见任务的零样本表现提升，说明 SFT 学到的不只是具体任务，还包括「按指令组织输出」这一行为模式。

SFT 同时决定后续对齐的上限。RLHF 与 DPO 都以 SFT 模型作为参考策略与初始化点，KL 约束把策略限制在 SFT 模型附近（见 [[对齐-RLHF]] 与 [[DPO与偏好优化]]）。SFT 模型若不会遵循格式、不会在合适位置停止，偏好优化只能在其附近做有限修正。

在本库中，本篇承接 [[数据集质量控制]] 产出的干净数据，把样本转换为对话格式并加上损失掩码；后续是 [[LoRA与QLoRA]]（在有限显存下执行同一目标函数）、[[继续预训练与领域适配]]（用回放抑制灾难遗忘）与 [[对齐-RLHF]]。前置知识包括 [[自回归生成与采样]] 中的下一 token 分解与 [[Tokenizer与BPE]] 中的子词边界，二者直接决定掩码能否对齐。

## 原理与推导

### 1 目标函数与掩码的梯度含义

自回归模型把序列的联合概率分解为

$$
\pi_\theta(y\mid x)=\prod_{t=1}^{T}\pi_\theta\bigl(y_t\mid x,y_{<t}\bigr).
$$

最大化该似然等价于最小化其负对数，即逐 token 交叉熵之和。SFT 在此之上乘掩码 $m_t$，只保留回复部分：

$$
\mathcal{L}(\theta)=-\frac{1}{M}\sum_{t=1}^{T}m_t\log \pi_\theta\bigl(y_t\mid x,y_{<t}\bigr),\qquad M=\sum_{t=1}^{T}m_t .
$$

对 logits 求梯度。设 $p_t=\mathrm{softmax}(z_t)$，则

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

该式给出两条结论。第一，被掩码的位置梯度严格为零，提示词 token 不通过损失函数获得学习信号。第二，提示词仍然参与前向计算：位置 $t$ 的隐状态依赖 $x$ 的全部 token，因此掩码改变的是「哪些位置产生学习信号」，不是「模型是否看到提示」。把两者混为一谈，会得出「掩码后模型学不到指令」的错误推论。

归一化分母 $M$ 的选择影响优化。按 token 平均时，长回复贡献更多梯度，等效于给长样本更高权重；按序列平均时，

$$
\mathcal{L}_{\text{seq}}=\frac{1}{B}\sum_{b=1}^{B}\Bigl(-\frac{1}{M_b}\sum_{t}m_{b,t}\log \pi_\theta(y_{b,t}\mid\cdot)\Bigr),
$$

每条样本权重相同。实测差异可参见本篇代码：同一批数据上，token 平均为 1.2724，序列平均为 1.3063，相差 0.034。回复长度分布越偏，两者差距越大。

梯度累积会引入第三层偏差。框架默认对每个微批计算平均损失再跨微批求平均，若各微批的有效 token 数不同，全局等效于按「微批」而非按「token」加权。修正方式是累计 $\sum m\log p$ 与 $\sum m$ 后在步末相除，或固定每步 token 数。

### 2 数据格式与对话模板

一条 SFT 样本由角色化的消息序列构成。最小结构为 `system`、`user`、`assistant` 三个角色，多轮对话在 `user` 与 `assistant` 之间交替。JSONL 中的一行如下。

```json
{"id": "sft-000123", "messages": [{"role": "system", "content": "你是严谨的技术编辑。"}, {"role": "user", "content": "把这句话改成被动语态：团队完成了测试。"}, {"role": "assistant", "content": "测试被团队完成了。"}], "meta": {"source_id": "edit-01", "license": "apache-2.0"}}
```

模板负责把消息序列渲染为 token 序列。不同模型的模板不可互换：

| 模型族 | 模板要点 | 常见问题 |
|---|---|---|
| Llama-2 | `[INST]` 包裹用户轮次，system 内容并入首条 `[INST]` | 无独立 system 槽位，强行传入会被拼接到首条指令 |
| ChatML 系 | `<\|im_start\|>role` 与 `<\|im_end\|>` 分隔每轮 | 需要为 assistant 段补 `<\|im_end\|>` 作为结束符 |
| Llama-3 系 | 特殊 header token 标记角色，`<\|eot_id\|>` 结束 | 手工拼接易漏掉 header 的特殊 token |
| Qwen 系 | ChatML 风格，`<\|im_end\|>` 结束 | system 与 user 之间需要换行，模板已内置 |

训练与推理必须使用同一模板，且同一模板版本。模板中的空格、换行与特殊 token 都属于输入分布的一部分；训练时用自定义字符串拼接、推理时用 `apply_chat_template`，会让模型在推理时见到训练中从未出现的边界 token 组合。

模板还决定回复的边界。多数模板在 assistant 内容后追加结束符（EOS 或 `<|im_end|>`），该 token 是模型学会「停止」的唯一监督信号。若训练样本的回复没有终止符，模型只学到「继续生成」，不会学到「在何处停止」。

### 3 掩码的构造

标准做法分三步：用模板渲染完整对话得到 `input_ids`；确定 assistant 段在序列中的 token 区间；把区间外的标签置为 $-100$。

以长度为 6 的窗口为例，两条样本的字段如下。

| 位置 $t$ | 0 | 1 | 2 | 3 | 4 | 5 |
|---|---|---|---|---|---|---|
| 样本 A `input_ids` | 5 | 6 | 7 | 8 | 9 | 10 |
| 样本 A `labels` | -100 | -100 | -100 | 8 | 9 | 10 |
| 样本 B `input_ids` | 5 | 11 | 12 | 13 | 0 | 0 |
| 样本 B `labels` | -100 | -100 | 12 | 13 | -100 | -100 |
| 样本 B `attention_mask` | 1 | 1 | 1 | 1 | 0 | 0 |

样本 A 的提示为 3 个 token，回复为 3 个 token；样本 B 的提示为 2 个 token，回复为 2 个 token，后两个位置是补齐。因果语言模型的损失在右移一位后计算：位置 $t$ 的 logits 预测位置 $t+1$ 的标签。因此在 `labels` 中，提示词对应的位置写 $-100$，回复 token 写在自身位置，移位由损失函数内部完成。若手工构造时先移位再掩码，掩码会覆盖错误的区间，这是最常见的错位来源。

PyTorch 的 `cross_entropy` 用 `ignore_index=-100` 跳过这些位置，掩码位置既不参与分子也不参与分母。等价的手工实现是：取 `shift_labels != -100` 的位置，对 `shift_logits` 做 log-softmax，按目标 token 取值后求平均。

按子词边界构造掩码还有一个陷阱。分别对提示与回复调用分词器，再把两个 id 序列拼接，与直接对拼接后的文本分词，结果可能不同：BPE 会在边界处合并字符，产生跨边界的 token。前一种做法得到的掩码会偏移一位或更多。可靠做法是用模板的 assistant 标记定位（需要模板支持 generation 标记），或用 `return_offsets_mapping=True` 取得字符区间，再按回复的字符起止位置映射到 token 位置。无论哪种做法，都应校验 `tokenizer.decode(input_ids)` 与模板渲染结果一致。

### 4 序列打包与交叉污染

SFT 数据的长度分布通常严重右偏：多数样本在 100 至 600 token，少数超过 2000。固定窗口 $L$ 下，不打包的利用率是

$$
U=\frac{\sum_{i=1}^{B}\ell_i}{B\cdot L},
$$

其中 $\ell_i$ 是第 $i$ 条样本的长度。若平均长度 300、$L=2048$，则 $U\approx0.146$，即 85% 的算力用于处理补齐 token。打包把多条样本首尾相接，$U$ 可升至 0.95 以上，相同步数下有效 token 数增加数倍。

打包引入两个问题。第一是注意力越界：因果掩码只保证位置 $t$ 看不到 $t$ 之后的位置，不保证它看不到「前一条样本」。打包后第二条样本的每个 token 会把注意力分配给第一条样本，造成信息泄漏，训练分布与推理分布不一致。修正方式是使用块对角注意力掩码：

```python
import numpy as np

seg = np.array([0, 0, 0, 1, 1])            # 打包后每个位置属于哪条样本
allowed = seg[:, None] == seg[None, :]      # True 表示允许注意
# allowed = [[1,1,1,0,0],[1,1,1,0,0],[1,1,1,0,0],[0,0,0,1,1],[0,0,0,1,1]]
```

不加块对角掩码时只有因果掩码，段 B 的第一个 token 在 4 个可见位置中能看到段 A 的 3 个，第二个 token 在 5 个可见位置中能看到段 A 的 3 个；块对角掩码把这两个比例都置零。实现上，FlashAttention 的变长接口用 `cu_seqlens` 描述各段边界，等价于块对角；若用普通注意力，则需显式构造形状为 $(B,1,L,L)$ 的加性掩码。

第二是位置编码。每条样本的位置编号应从 0 开始，不能沿用拼接后的全局位置，否则模型见到训练中不存在的长距离位置。实现时按段重置 `position_ids`，或使用支持变长序列的注意力实现。

打包还与损失归一化交互。打包后一个窗口内有多条样本，若仍按窗口求平均，长样本占的 token 多、权重自然更大；若要按序列平均，需记录每段的 token 数并分段归一化。多数框架提供的是窗口级 token 平均，报告指标时应说明。

### 5 训练配置

| 超参数 | 全参数微调 | LoRA/QLoRA | 说明 |
|---|---|---|---|
| 学习率 | $1\times10^{-5}$ 至 $2\times10^{-5}$ | $1\times10^{-4}$ 至 $2\times10^{-4}$ | 全参数更新全部权重，学习率过大会破坏预训练能力 |
| epoch | 2 至 3 | 2 至 3 | 超过 3 轮在数千条数据上通常过拟合 |
| 有效批大小 | 32 至 128 条序列 | 同左 | 按序列计；按 token 计更稳定 |
| 梯度累积 | 使有效批达到上述范围 | 同左 | 与批大小、显存共同决定 |
| warmup | 总步数的 3% | 3% | 线性升温，避免初期梯度破坏 |
| 调度器 | cosine | cosine | 末段学习率趋近 0 |
| weight decay | 0.0 至 0.1 | 0.0 | SFT 上常用 0 |
| 梯度裁剪 | 1.0 | 1.0 | 抑制个别长样本的梯度尖峰 |
| 精度 | bf16 | bf16 | 混合精度需保留 fp32 主权重 |

有效批大小与每步 token 数的关系为

$$
B_{\text{eff}}=B_{\text{device}}\times A\times N_{\text{gpu}},\qquad
T_{\text{step}}=B_{\text{eff}}\times \bar\ell,
$$

其中 $B_{\text{device}}$ 是单卡批大小，$A$ 是梯度累积步数，$N_{\text{gpu}}$ 是卡数，$\bar\ell$ 是平均序列长度（打包后接近 $L$）。例如 $B_{\text{device}}=2$、$A=8$、$N_{\text{gpu}}=8$，则 $B_{\text{eff}}=128$；打包后 $\bar\ell\approx2048$，每步约 26 万 token。学习率需要与 $T_{\text{step}}$ 一同调整：每步 token 数扩大到 $m$ 倍时，常按 $\sqrt{m}$ 放大学习率并相应减少步数，使总更新量相近；跨实验比较时必须同时报告 $B_{\text{eff}}$ 与 $T_{\text{step}}$，否则学习率的差异不可比。

### 6 全参数微调与 LoRA 的选择

全参数微调更新全部 $P$ 个参数，优化器状态使显存需求约为

$$
\text{显存}\approx \underbrace{2P}_{\text{bf16 权重}}+\underbrace{2P}_{\text{bf16 梯度}}+\underbrace{8P}_{\text{fp32 一阶与二阶矩}}+\text{激活},
$$

以 $P=7\times10^{9}$ 计，仅前三项约 84 GB，尚未计入激活。LoRA 冻结基座，只训练低秩增量，可训练参数占比通常在 0.1% 至 1%，优化器状态随之下降两个数量级，详见 [[LoRA与QLoRA]]。

选择依据不是「效果上限」而是「数据量与目标」。数据量在数千条、目标是格式与风格时，LoRA 与全参数微调的差距通常在评测噪声内；数据量在十万条以上、目标是注入新领域的写作方式时，全参数微调的收益更明显。全参数微调还有一个副作用：对基座能力的破坏更大，需要更谨慎的数据混合。

### 7 灾难遗忘与数据混合

SFT 只在目标分布上最大化似然，没有项约束模型保留原有能力。目标数据越窄、学习率越大、轮数越多，遗忘越明显。三种控制手段配合使用。第一是数据混合：在训练集中保留 10% 至 30% 的通用指令数据，与目标任务同时训练，比例由通用能力回归测试确定。第二是降低更新幅度：更小的学习率、1 至 2 轮、LoRA 的低秩约束。第三是回放：把通用语料按固定比例混入每个批次，而不是只放在训练开头。具体配比与继续预训练阶段的遗忘控制见 [[继续预训练与领域适配]]。

遗忘的度量必须在微调前确定：通用能力用固定子集的前后对比，目标任务用留出集，两者同时报告。只报告目标任务提升，无法区分「能力增强」与「分布收窄」。

### 8 评测

SFT 的评测需要覆盖四个层面。

**留出集损失与任务指标**。留出集应与训练集同分布、无重叠，并按 [[数据集质量控制]] 的流程做过污染检查。任务指标取决于任务：抽取式问答用 exact match 与 token F1，代码用 pass@k，结构化输出用 JSON 解析成功率与字段级准确率，工具调用用调用名与参数的精确匹配率。

**LLM-as-judge**。用更强的模型对回复打分或做成对比较。成对比较需交换两条回复的位置各评一次，以抵消位置偏差；评分细则要写明维度（正确性、完整性、格式），并对每条细则给出可判定的标准。judge 的输出需要与人工评分在 100 至 300 条样本上对齐，报告一致率；未对齐的 judge 分数不能作为唯一依据。已知偏差包括位置偏好、长度偏好、对自身生成内容的偏好。

**人工评分**。成对偏好（A 更好、B 更好、相当）比 1 至 5 分李克特量表更稳定，后者需要事先定义每一档的判定标准。多人标注需报告一致性系数（见 [[数据集质量控制]] 的 $\alpha$ 与 $\kappa$），并保留分歧样本用于分析。

**回归检查**。固定一组通用能力题（学科问答、数学、代码）与一组安全拒答题，比较微调前后的正确率与拒答率。回归下降超过预设阈值时，应调整数据混合或降低学习率，而不是继续训练。

### 9 过拟合与早停

SFT 的过拟合有明确的外部表现，不只是留出集损失上升。

| 现象 | 度量 | 处理 |
|---|---|---|
| 留出集损失在 1 至 2 轮后回升 | 每 100 步评估 | 早停，取最优检查点 |
| 输出长度持续增长 | 平均回复 token 数 | 检查训练数据长度分布，降低轮数 |
| 复读模板开头 | 回复前缀重复率 | 检查模板一致性，增加数据多样性 |
| 对未见指令退化为固定格式 | 留出集格式合法率与内容正确率 | 混入通用指令数据 |
| 通用能力下降 | 回归子集准确率 | 降低学习率，增加回放比例 |

早停的实现要求评估与保存策略一致：`eval_strategy` 与 `save_strategy` 同为按步，且 `save_steps` 等于 `eval_steps`，否则 `load_best_model_at_end` 无法定位最优检查点。耐心值通常设为 2 至 3 次评估；触发早停后停止训练并回读最优检查点，不再继续更新参数。

### 10 与 RLHF、DPO 的关系

三者优化的是同一族目标的不同近似。RLHF 的目标为

$$
\max_{\pi_\theta}\ \mathbb{E}_{x\sim\mathcal{D},\,y\sim\pi_\theta}\bigl[r_\phi(x,y)\bigr]-\beta\,\mathrm{KL}\bigl(\pi_\theta\,\|\,\pi_{\text{ref}}\bigr),
$$

其中 $r_\phi$ 是由成对偏好训练的奖励模型，$\pi_{\text{ref}}$ 是参考策略，$\beta$ 控制偏离参考策略的惩罚。SFT 模型就是 $\pi_{\text{ref}}$ 的默认取值，也是策略的初始化点。DPO 把同一目标的闭式最优解代入，得到只依赖偏好对与策略比值的损失，见 [[DPO与偏好优化]]。

三者的数据与信号不同：SFT 用「正确回复」做行为克隆，信号是逐 token 的监督；RLHF 与 DPO 用「哪条回复更好」做偏好学习，信号是序列级的比较。因此 SFT 决定模型「会不会做」，偏好优化决定模型「偏向哪一种做法」。实践中 SFT 之后仍需偏好优化，因为示范数据无法覆盖「同样正确但更符合人类偏好」的取舍。

## 关键直觉

> [!tip] SFT 是在固定上下文的前提下，对回复 token 做逐位置的分类：每个位置的梯度只取决于该位置的预测分布与金标 token，提示词只作为条件进入前向计算，不产生学习信号。
>
> 与严格定义的关系：定义中的 $m_{b,t}$ 把这个区分写成乘性因子，梯度式 $\partial\mathcal{L}/\partial z_{t,v}=(m_t/M)(p_{t,v}-\mathbf{1}[v=y_t])$ 说明掩码位置梯度为零而上下文仍被使用；归一化分母 $M$ 决定了长回复与短回复的相对权重，对应 token 平均与序列平均的 1.2724 与 1.3063 之差；打包一节的块对角掩码则是在批维度上追加约束，防止条件项 $x_b$ 混入其他样本。

## 例子与代码

先用一个可手算的例子说明掩码的作用。设某条回复有 3 个 token，模型给出的正确 token 概率为 0.9、0.5、0.2，则

$$
\mathcal{L}=-\frac{1}{3}\bigl(\ln0.9+\ln0.5+\ln0.2\bigr)
=\frac{0.1054+0.6931+1.6094}{3}=0.8026 .
$$

若提示词有 4 个 token，模型对其下一 token 的概率均为 0.95（提示词高度可预测），把这些位置计入损失后

$$
\mathcal{L}_{\text{全}}=\frac{4\times0.0513+2.4079}{7}=0.3733 .
$$

损失从 0.803 降到 0.373，但模型对回复的拟合没有任何变化。这是掩码缺失最直接的后果：损失数值被提示词的可预测性稀释，训练动态与指标都随之失真。

以下代码构造带掩码的批次，并验证损失只计入回复 token。环境为 PyTorch 2.x，CPU 即可运行；为保证数值可逐位核对，验证块使用 float64。

```python
"""SFT 损失掩码的最小验证（PyTorch 2.x，CPU，float64）。"""
import torch
import torch.nn.functional as F

V, L = 16, 6
ids = torch.tensor([[5, 6, 7, 8, 9, 10], [5, 11, 12, 13, 0, 0]])
labels = torch.tensor([[-100, -100, -100, 8, 9, 10], [-100, -100, 12, 13, -100, -100]])
attn = torch.tensor([[1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 0, 0]])

b = torch.arange(2)[:, None, None]
t = torch.arange(L)[None, :, None]
v = torch.arange(V)[None, None, :]
logits = (((b * L + t) * V + v) % 17 - 8).to(torch.float64) * 0.37

# 抬高"金标下一 token"的 logit，模拟"已学会回复、但预测提示词较差"的模型
for i in range(2):
    for pos in range(L - 1):
        gold = int(labels[i, pos + 1])
        if gold != -100:
            logits[i, pos, gold] += 4.0


def lm_loss(logits, labels):
    """因果语言模型损失：右移一位后按 ignore_index 求平均。"""
    return F.cross_entropy(logits[:, :-1, :].reshape(-1, V),
                           labels[:, 1:].reshape(-1), ignore_index=-100)


loss = lm_loss(logits, labels)
print(f"掩码后 loss={loss.item():.4f}")

# 手工复核：只取有效位置，逐 token 求负对数似然后平均
shift_logits = logits[:, :-1, :].reshape(-1, V)
shift_labels = labels[:, 1:].reshape(-1)
keep = shift_labels != -100
targets = shift_labels[keep]
manual = -shift_logits[keep].log_softmax(-1).gather(1, targets[:, None]).mean()
print(f"手工复核={manual.item():.4f} 有效 token={int(keep.sum())}")

# 变体一：提示词不掩码，只掩码 padding
labels_full = ids.clone()
labels_full[attn == 0] = -100
print(f"未掩码提示词 loss={lm_loss(logits, labels_full).item():.4f}")

# 变体二：padding 位置写成类别 0，而不是 -100
labels_pad = labels.clone()
labels_pad[1, 5] = 0
print(f"padding 计入 loss={lm_loss(logits, labels_pad).item():.4f}")

# 变体三：不右移，位置 t 预测位置 t 的标签
loss_off = F.cross_entropy(logits.reshape(-1, V), labels.reshape(-1), ignore_index=-100)
print(f"未右移（错位） loss={loss_off.item():.4f}")

# 逐样本平均与逐 token 平均的差别
means = []
for i in range(2):
    sel = (labels[i, 1:] != -100).nonzero().squeeze(1)
    lp = logits[i, sel].log_softmax(-1).gather(1, labels[i, sel + 1][:, None]).squeeze(1)
    means.append((-lp.mean()).item())
    print(f"样本{i} token={len(sel)} 平均NLL={-lp.mean():.4f} 总NLL={-lp.sum():.4f}")
print(f"token 平均={loss.item():.4f} 序列平均={sum(means) / 2:.4f}")

# 梯度检查：只有回复 token 对应的位置获得梯度
w = logits.clone().requires_grad_(True)
lm_loss(w, labels).backward()
print("梯度非零位置:", (w.grad.abs().sum(-1) > 0).int().tolist())
```

预期输出如下。

```text
掩码后 loss=1.2724
手工复核=1.2724 有效 token=5
未掩码提示词 loss=2.5876
padding 计入 loss=1.8093
未右移（错位） loss=5.5372
样本0 token=3 平均NLL=1.1367 总NLL=3.4100
样本1 token=2 平均NLL=1.4759 总NLL=2.9519
token 平均=1.2724 序列平均=1.3063
梯度非零位置: [[0, 0, 1, 1, 1, 0], [0, 1, 1, 0, 0, 0]]
```

这段代码在做什么：`ids` 与 `labels` 是上表的张量形式，补齐位置在 `labels` 中写 $-100$；`lm_loss` 先右移一位再调用带 `ignore_index` 的交叉熵，与框架内部的实现一致；手工复核取有效位置，用 `log_softmax` 与 `gather` 直接算负对数似然；三个变体分别去掉掩码、把 padding 写成类别 0、去掉右移；最后用反向传播检查梯度分布。

为什么这样验证：掩码的正确性有两个可判定的条件。其一，掩码后的损失必须等于逐回复 token 负对数似然的平均，代码用 `manual` 与 `loss` 对齐验证，两者都是 1.2724。其二，非回复位置的梯度必须为零，梯度矩阵显示位置 0、1、5 的行为全零，只有右移后目标位置的 logits 获得梯度。两个条件同时成立，才能排除「标签写错位置但仍能算出相近数值」的情形。

去掉会怎样：未掩码提示词时损失变成 2.5876，比掩码后高 1.3152，因为提示词 token 的可预测性低；若这些位置参与训练，模型会把容量分配给复述用户输入。padding 计入时损失为 1.8093，且补齐位置会被学成高频输出，推理时表现为生成重复的填充内容。未右移时损失为 5.5372，模型在学习「复制当前位置」而不是「预测下一位置」，训练损失可以下降但生成完全失效。

`token 平均` 与 `序列平均` 的 0.034 之差说明归一化的影响：样本 0 有 3 个回复 token、平均 1.1367，样本 1 有 2 个、平均 1.4759，按 token 平均时前者权重为 3/5，按序列平均时两者各占一半。

第二段代码从对话消息构造带掩码的训练样本，并检查提示词与回复的拼接是否与整体分词一致。`return_assistant_tokens_mask` 依赖 `transformers` 4.45 以上版本。

```python
"""由 messages 构造 input_ids 与 labels，并检查子词边界（transformers 4.45+）。"""
from transformers import AutoTokenizer

tok = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-1.5B-Instruct")
msgs = [
    {"role": "system", "content": "你是严谨的技术编辑。"},
    {"role": "user", "content": "把这句话改成被动语态：团队完成了测试。"},
    {"role": "assistant", "content": "测试被团队完成了。"},
]

# 路径一：模板支持 generation 标记时直接取 assistant 掩码
enc = tok.apply_chat_template(msgs, tokenize=True, return_dict=True,
                              return_assistant_tokens_mask=True)
print("路径一 token 数:", len(enc["input_ids"]), "assistant 掩码和:", sum(enc["assistant_masks"]))

# 路径二：分别编码提示与回复，再拼接并显式构造掩码
prompt = tok.apply_chat_template(msgs[:-1], tokenize=False, add_generation_prompt=True)
answer = msgs[-1]["content"] + tok.eos_token
p_ids = tok(prompt, add_special_tokens=False)["input_ids"]
a_ids = tok(answer, add_special_tokens=False)["input_ids"]
input_ids = p_ids + a_ids
labels = [-100] * len(p_ids) + a_ids
print("提示 token:", len(p_ids), "回复 token:", len(a_ids), "总长:", len(input_ids))

# 边界检查：分别编码再拼接，必须与整体编码一致，否则掩码会偏移
joint = tok(prompt + answer, add_special_tokens=False)["input_ids"]
print("边界一致:", joint == input_ids)
if joint != input_ids:
    print("不一致：BPE 在边界处合并，需改用 offset mapping 定位")
```

这段代码在做什么：路径一调用模板的 assistant 掩码接口，由模板中的 generation 标记确定回复区间；路径二先渲染提示（带生成提示符），单独编码回复并追加 EOS，再把标签前段填 $-100$；最后把「分别编码再拼接」与「整体编码」的结果比较。

为什么这样做：路径一依赖于模板是否包含 `{% generation %}` 标记，部分模型的模板没有该标记，返回的掩码可能全为 0，因此需要保留路径二作为通用方案。路径二的正确性依赖子词边界不被合并；`joint == input_ids` 就是这一条件的可执行检查。若不一致，说明边界处出现了跨段 token，必须用 `return_offsets_mapping=True` 取得字符区间，再按回复的字符起止位置映射回 token 位置。

去掉会怎样：不做边界检查，掩码可能偏移一个 token，造成「第一个回复 token 未被监督、最后一个提示 token 被当作回复」的静默错误，损失数值变化很小，难以从曲线上发现。不追加 EOS，模型学不会停止，推理时生成到 `max_new_tokens` 才被截断。

第三段是 TRL 的训练配置。字段名在版本间有改动，以下以 TRL 0.20 的 `SFTConfig` 为准；升级前需核对 `max_seq_length` 已更名为 `max_length`、`tokenizer` 已更名为 `processing_class`。

```python
"""TRL SFTTrainer 配置片段（TRL 0.20+，transformers 4.45+）。"""
from datasets import load_dataset
from transformers import AutoModelForCausalLM, AutoTokenizer
from trl import SFTConfig, SFTTrainer

model_id = "Qwen/Qwen2.5-1.5B-Instruct"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype="bfloat16",
    attn_implementation="flash_attention_2",   # 未安装 flash-attn 时删除该参数
)

ds = load_dataset("json", data_files={"train": "data/train.jsonl",
                                      "validation": "data/val.jsonl"})

args = SFTConfig(
    output_dir="runs/sft-qwen25-1.5b",
    max_length=2048,                  # 0.20 起由 max_seq_length 更名
    packing=True,                     # 多条样本拼进同一窗口，需块对角注意力
    per_device_train_batch_size=2,
    gradient_accumulation_steps=8,    # 有效批 = 2 × 8 × 卡数
    learning_rate=1e-4,               # 全参数 1e-5~2e-5；LoRA 1e-4~2e-4
    num_train_epochs=2,
    lr_scheduler_type="cosine",
    warmup_ratio=0.03,
    weight_decay=0.0,
    max_grad_norm=1.0,
    bf16=True,
    gradient_checkpointing=True,
    logging_steps=10,
    eval_strategy="steps",            # 旧版字段名为 evaluation_strategy
    eval_steps=100,
    save_strategy="steps",
    save_steps=100,
    save_total_limit=2,
    load_best_model_at_end=True,      # 需 eval_steps == save_steps
    metric_for_best_model="eval_loss",
    assistant_only_loss=True,         # 只对 assistant 段计损失，要求模板含 {% generation %}；与 packing 同开需确认版本支持
)

trainer = SFTTrainer(
    model=model,
    args=args,
    train_dataset=ds["train"],
    eval_dataset=ds["validation"],
    processing_class=tokenizer,       # 旧版字段名为 tokenizer
)
trainer.train()
trainer.save_model("runs/sft-qwen25-1.5b/final")
```

这段配置在做什么：`packing=True` 把多条样本拼进 2048 的窗口以提升利用率；`assistant_only_loss=True` 让框架按模板的 generation 标记生成掩码，等价于本篇第一段代码的手工构造；`eval_strategy` 与 `save_strategy` 同步，使最优检查点可被回读；`gradient_accumulation_steps=8` 在单卡批大小为 2 时把有效批提升到 16 乘以卡数。

为什么这样设：学习率 1e-4 对应 LoRA 量级；若改为全参数微调，应降到 $1\times10^{-5}$ 至 $2\times10^{-5}$，并相应增大梯度累积以维持有效批。`warmup_ratio=0.03` 在 2000 步的训练中对应前 60 步线性升温。`assistant_only_loss=True` 若报错提示模板缺少 generation 标记，需要在 `tokenizer_config.json` 的模板中为 assistant 段添加 `{% generation %}` 与 `{% endgeneration %}`，或退回第一段代码的手工掩码。

去掉会怎样：关闭 `packing` 时吞吐下降到约 15%，训练时间成倍增加；关闭 `assistant_only_loss` 且框架默认使用全序列损失时，提示词参与训练，与第一段代码中 2.5876 的情形一致；`eval_strategy` 与 `save_strategy` 不一致时，`load_best_model_at_end` 会在训练结束时抛出异常。

## 易错点

> [!warning] 以下六条均可在训练日志、梯度检查或样本抽查中直接验证。
> 1. 掩码错位：在右移之后再做掩码，或把 $-100$ 写到了错一位的位置。验证方法是手工取有效位置计算负对数似然并与框架损失比较，本篇数据为 1.2724 对 5.5372；两者不等说明对齐有误。
> 2. padding 计入损失：补齐位置未写 $-100$，或未向模型传 `attention_mask`。表现为损失被稀释或被抬高（示例中 1.2724 变为 1.8093），模型还会把补齐 token 学成高频输出。
> 3. 对话模板不一致：训练用自定义字符串拼接，推理用 `apply_chat_template`，特殊 token 与空格不同。检查方法是对同一条样本比较训练张量解码结果与推理 prompt 的字节内容。
> 4. EOS 未被学习：回复未追加结束符，模型不会停止。抽查训练集，以模板结束符结尾的样本比例应为 100%；推理时若总是生成到上限，先检查这一项。
> 5. 打包未做块对角掩码：后一条样本能看到前一条的内容，隐式泄漏使留出集损失虚低。检查打包后的 `position_ids` 是否每条样本从 0 开始，以及注意力实现是否传入变长边界。
> 6. 只监控训练损失：SFT 的训练损失在过拟合与能力退化时都可能继续下降。必须同时记录留出集损失、平均输出长度、格式合法率与通用能力回归子集。

## 关联笔记

- 前置 [[数据集质量控制]]：去重、过滤与污染检测决定 SFT 数据的上限，本篇的掩码与打包建立在其输出的干净样本上。
- 前置 [[Tokenizer与BPE]]：子词边界决定掩码能否与回复区间对齐，边界合并会使掩码偏移。
- 后续 [[LoRA与QLoRA]]：在显存受限时执行同一目标函数，可训练参数与学习率量级不同。
- 后续 [[对齐-RLHF]]：以 SFT 模型为参考策略与初始化点，用偏好信号继续优化。
- 对照 [[继续预训练与领域适配]]：需要注入新知识而非新行为时先做继续预训练，SFT 与它的数据混合策略互为补充。

## 达标检测

- [ ] 写出 SFT 的目标函数与 logits 梯度式，说明掩码位置梯度为零而提示词仍参与前向计算的原因。
- [ ] 用 3 个回复 token、概率 0.9、0.5、0.2 手算负对数似然；再加入 4 个概率为 0.95 的提示词 token，比较两种归一化结果。
- [ ] 给定 $B_{\text{device}}=4$、$A=16$、$N_{\text{gpu}}=4$、$\bar\ell=1536$，计算有效批大小与每步 token 数，并说明学习率应如何随之调整。
- [ ] 运行第一段代码，把 `labels[1, 3]` 改为 $-100$，观察损失、有效 token 数与梯度矩阵的变化，解释结果。
- [ ] 解释序列打包的利用率公式，算出平均长度 300、$L=2048$ 时的利用率，并说明块对角掩码与 `cu_seqlens` 的等价性。
- [ ] 列出 SFT 过拟合的四个外部表现及对应度量，说明为什么不能只看训练损失。
- [ ] 写出一段脚本，检查训练集中以模板结束符结尾的样本比例，并给出修复缺失结束符的处理步骤。

## 参考来源

- Ouyang et al., "Training language models to follow instructions with human feedback", arXiv:2203.02155, 2022 —— 对应「为什么重要」中的人工示范规模、第 1 节的目标函数，以及第 10 节 RLHF 目标与 SFT 作为参考策略的位置。
- Wei et al., "Finetuned Language Models Are Zero-Shot Learners", arXiv:2109.01652, 2021 —— 对应「为什么重要」中指令微调提升未见任务零样本表现的实证结论，以及任务混合的动机。
- Hugging Face TRL 官方文档（`SFTTrainer`、`SFTConfig`、packing 与 assistant-only loss 的配置说明） —— 对应第 4 节的打包、第 5 节的训练配置与第三段代码。
- Raschka, *Build a Large Language Model (From Scratch)*, 2024, 第 7 章「Fine-tuning to follow instructions」 —— 对应第 2 节的对话数据组织、第 3 节的掩码构造与第 5 节的训练循环设置。
