w wyl123ly 的博客
MD

MOC-中段训练与SFT

25 KB 2026.10.22 原文件

MOC · 中段训练与SFT

本阶段地图

05 阶段结束时的产物是一个会续写文档的基座模型;07 阶段的强化学习需要一个会对话、会调工具、会在正确位置停止的策略初值。两者之间的唯一训练环节就是本阶段:scripts/chat_sft.py 一个脚本,一轮数据,一个检查点。

四篇笔记按「输入—编码—训练—输出」组织。对话数据与SmolTalk 与 多选与工具使用数据 定义进入训练的两种数据形态(自然语言对话、分片工具协议);有监督微调SFT 把它们混合、打包、加掩码并训练;从生成式到对话式 解释训练后的模型在推理时如何被拼接与解读。四篇共同回答一个问题:基座模型的参数如何被重新加权为协议响应器。

本阶段不覆盖:RLHF 与偏好优化(07 阶段)、评测方法论与成绩单(08 阶段)、工具沙箱的隔离边界与 CLI/WebUI 的工程实现(09 阶段)。这些内容在各自阶段展开,本阶段只在必要处给出双链。

完成本阶段的判据不是「跑完脚本」,而是能用一组数字与一段对话证明迁移发生:scripts/chat_eval.py -i sft 输出的 3 个 categorical 任务 centered accuracy 明显为正;chat_cli 的多轮会话能在 <|assistant_end|> 处停止;对一条算术问题,模型会发起 <|python_start|> 调用而不是直接写出结果。

flowchart LR
    P["05 预训练<br/>base checkpoint + 分词器"] --> C["有监督微调SFT<br/>mask / packing / LR / ChatCORE"]
    A["对话数据与SmolTalk<br/>messages schema + HubDataset"] --> C
    B["多选与工具使用数据<br/>render_mc + python/output parts"] --> C
    C --> D["从生成式到对话式<br/>拼接 / 流式 / 行为变化"]
    C --> R["07 强化学习<br/>GRPO rollout 与奖励"]
    D --> E["09 推理 Engine<br/>chat_cli / 工具调用"]
    D --> M["08 评测<br/>ChatCORE 与人工检查"]

图中的实线是数据流,虚线关系体现为双链:render_conversation 同时被训练(掩码)与推理(拼接)使用,因此 06 阶段的知识在 09 阶段会被再次引用。四篇之间的依赖不是链式的:第三篇同时依赖前两篇,第四篇只依赖第三篇;因此第四篇可以在训练尚未跑通时先读讲解部分。

学习顺序与理由

第一步:对话数据与SmolTalk

先读数据,因为后续所有代码都以 messages 消息列表为输入。这一篇建立三个前置事实:一条对话的最小合法结构是什么(user 与 assistant 严格交替、可选 system、content 必须是字符串);数据如何落到本地(hub API 列 parquet 分片、FileLock 单进程下载、manifest 最后写入);样本顺序如何被固定(shuffle(seed=42) 与 TaskMixture 的确定性置换)。

对应小节是第 2 至 5 节与「在 nanochat 中的落地」。阅读时先看 tasks/smoltalk.py 的 45 行全文,再看 tasks/common.py 的 HubDataset 与 TaskMixture;后者的 index_map 结构值得在纸上画一遍,否则容易把逻辑下标与物理下标混淆。

跳过这一步的代价是具体的:不知道 render_conversation 会合并 system,就会以为模型见过独立的 system 槽位;不知道 HubDataset 用 manifest 判断完整性,就会在手工删除分片后反复重跑而找不到失败原因;不知道 TaskMixture 在构造时一次性打乱,就无法解释为什么修改一行数据会改变后续所有样本的位置。

先修自检:能否说出 Task.__len__ 的公式并解释为什么要用向上取整;能否解释 shuffle 之后 ds[0] 与 ds.ds[0] 的区别;能否写出缓存目录的完整路径。任一项答不上来,先回到第 3、4 节。

第二步:多选与工具使用数据

第二种数据形态是分片列表,它引入了两个新概念:单个标签 token 作为监督目标(MMLU、ARC),以及 python/python_output 两种分片(GSM8K)。这一篇的核心不是数据本身,而是 render_mc 的格式约定与 <<expr=result>> 的拆解规则,它们决定掩码的边界与评测的读取位置。

对应小节是第 1 至 6 节。第 1 节的两条设计理由需要与第三篇的掩码表对照阅读:格式之所以重要,是因为它决定了监督位置上有哪些 token,而不是因为排版美观。第 5、6 节的正则可以逐条在解释器里跑一遍,把 re.split 的捕获组行为看清楚。

跳过这一步的代价是:无法解释 chat_eval.py 为什么只比较候选标签的 logits;无法判断 python_output 的掩码为何是 0;在改动多选 prompt(例如给 = 后加空格)时看不出问题,只能观察到分数下降。

先修自检:能否说出 SPLIT_PATTERN 中哪一段导致 " A" 与 "A" 不同;能否手算一条 GSM8K 样本分成几个片段;能否解释 10.0 与 10 为什么判错。

第三步:有监督微调SFT

这一篇是本阶段的主体,也是全库中代码密度最高的一篇。它把前两篇的数据接入训练循环,并解释五个机制:六项超参继承、优化器热启动与学习率重置、best-fit pad 打包、掩码与目标的右移对齐、进度驱动的调度与 ChatCORE 评测。阅读时需要对照 scripts/chat_sft.py 与 nanochat/tokenizer.py 两个文件,边读边在纸上画出一条 batch 的 inputs/targets 布局。

对应小节是第 1 至 10 节,其中第 7 节(对齐)必须手算。读法建议:先读第 1 节的全链路表,建立八个步骤的骨架;再读第 3、4 节,理解参数从哪里来、数据由什么组成;然后读第 5、6、7 节,这是「一行 token 如何变成损失」的完整链条;最后读第 9、10 节,理解训练节奏与度量。

跳过这一步的代价最重:没有掩码对齐的概念,任何自建的 SFT 代码都可能出现「损失下降但评测不涨」的静默错误;不理解热启动后的学习率重置,会在别人的代码上重复同样的坑;不理解 ChatCORE 的 centered 口径,会把不同基线的任务直接平均。

先修自检:能否写出 get_lr_multiplier 在 处的返回值;能否说明 targets[i, content_len-1:] = -1 与掩码置 的重复关系;能否解释 Muon 动量为什么只作用于 kind == 'muon' 的参数组。

第四步:从生成式到对话式

最后读输出侧。这一篇把训练时学到的协议在推理时重新拼接出来,解释 chat_cli 的五个不变量、render_for_completion 的两步外科手术、流式解码的字节边界,以及 SFT 之后的行为变化与遗忘边界。它同时是 07 与 09 的入口:GRPO 的 rollout 用 render_for_completion,Engine 的工具状态机消费 SFT 学到的 python 协议。

对应小节是第 1 至 9 节与「在 nanochat 中的落地」。第 2 节的九个特殊 token 表格是全书唯一的协议清单,值得抄写一遍;第 3 节的拼接顺序必须与 chat_cli.py 逐行对照;第 7 节的遗忘讨论要结合 07 阶段的重读。

跳过这一步的代价是:把「训练好了」等同于「可以用了」,在拼接漏掉 <|bos|> 或忘记补 <|assistant_end|> 时无法定位原因;也可能把 ChatCORE 当作通用能力的度量,误判模型是否退化。

先修自检:能否写出一次单轮会话的 token 序列;能否解释 answer_time_positions 为什么是 len(ids) - 1;能否说出 SFT 后哪类行为变化无法用 ChatCORE 观测。

顺序的灵活性

若只有半天,优先读第三步的第 3、5、7 节(继承与热启动、打包、对齐)与第四步的第 3 节(拼接),其余按需回查。前三篇之间存在一处循环依赖:render_mc 的格式细节只有在读过掩码规则后才能完全理解,因此第一次读第二篇时可以跳过「监督信号的分布」一节,等读完第三篇再回来。

若目标是复现而非理解,顺序可以改为「跑通 speedrun 的 SFT 段,再读第三篇的落地表」:先看到 Training mixture: 792,000 rows 与 ChatCORE 的日志,再回头解释每一行的来源。这种做法省时间,但会在出现异常日志时缺少定位手段。

学习节奏

四篇的阅读与动手建议分四段进行,每段以该篇的「达标检测」自评,未通过的项不要进入下一段。

段落阅读动手通过标志
第一段第一篇全部python -m tasks.common 观察切片能手算渲染后的 sum(mask)
第二段第二篇第 1 至 6 节在解释器里复现 render_mc 与 GSM8K 拆分能手算四种补全的奖励
第三段第三篇全部手算两张表,再跑一次短 SFT能解释每条日志字段的来源
第四段第四篇全部跑通 chat_cli 的单轮与多轮能指出拼接与停止的每个 token

第三段的「短 SFT」指 --num-iterations 设为数步的调试运行,用于验证数据管线与日志,不用于得到可用模型。全量训练需要 8 卡与数小时,放在第三段通过之后。

与其他阶段的分工

问题本阶段回答其他阶段回答
特殊 token 如何进入词表只说明它们被保留、各对应一个 id03 阶段:BPE 训练与 rustbpe + tiktoken 分工
因果注意力如何工作只说明打包后行内可互相注意04 阶段:注意力推导与 sliding window
批大小与学习率如何得出只说明继承自检查点05 阶段:--depth 推导与 warmup-warmdown
奖励如何定义只说明 GSM8K 的 #### 判分07 阶段:GRPO 的 rollout 与 advantage
ChatCORE 如何解读只给出 centered 公式与基线08 阶段:评测方法论与统计不确定性
工具调用如何执行只说明 python 分片的掩码09 阶段:use_calculator 与 execution.py 的边界

笔记索引

笔记核心问题关键实现前置读完应能
[[对话数据与SmolTalk]]一条 SFT 样本从 hub 到 (ids, mask) 经过哪些变换tasks/smoltalk.py、tasks/common.py 的 HubDataset/Task/TaskMixture[[词表与特殊token]]写出 schema 断言、目录布局与混合比例
[[多选与工具使用数据]]多选格式与工具协议如何被编码成监督信号render_mc、MMLU、ARC、GSM8K.get_example、extract_answer第一篇手拆 <<>>、算出奖励、解释标签 logits 聚焦
[[有监督微调SFT]]掩码、打包、学习率与评测如何协同scripts/chat_sft.py 全链路、render_conversation、GPT.forward 的 ignore_index=-1前两篇、[[检查点与恢复]]、[[学习率与warmup-warmdown]]画出 batch 布局、手算学习率乘子、解释 ChatCORE
[[从生成式到对话式]]训练后的模型如何被推理代码正确使用scripts/chat_cli.py、Engine.generate、render_for_completion、chat_eval.py第三篇复述拼接不变量、判断行为变化与遗忘

四篇各自的位置如下。

对话数据与SmolTalk 是数据篇,重点在「格式假设」与「可复现性」。它刻意不讨论掩码的数学含义,那属于第三篇;也不讨论模板化风险的缓解方案,只给出可检验的观察方法。九个二级标题中,第 3 节(HubDataset)与第 5 节(TaskMixture)最容易在第二次阅读时被跳过,但它们是复现性的来源。

多选与工具使用数据 是编码篇,重点在两个格式约定:render_mc 的三行结构与 <<expr=result>> 的分片规则。它把评测侧的读取逻辑(标签 logits 聚焦)提前讲清,因为格式的正确性只有在评测视角下才能被判定。第 4 节的 MMLU 与 ARC 对照表建议背下来,它是 08 阶段 categorical 评测的前置。

有监督微调SFT 是训练篇,重点在五个机制与一个度量。它是唯一需要对照三份源码阅读的一篇(chat_sft.py、tokenizer.py、gpt.py),也是唯一包含完整手算表的篇目。第 7 节的 6 token 表与第 9 节的学习率表可以互相独立地验证,两处都算对才算读懂。

从生成式到对话式 是输出篇,重点在「训练分布与推理分布必须逐 token 一致」。它把前三篇的结论汇总为一个可执行的检查清单,并指出 nanochat 默认流程没有覆盖的度量缺口(SFT 后的 base CORE)。第 9 节的上下文增长表把多轮对话的成本写成可计算的量,与 09 阶段的 KV Cache 显存公式相接。

各篇的关键手算点

四篇之间有一条共同的方法:把一个机制压缩成一个可以手算或可以逐位核对的量。下表列出每篇必须能独立完成的检查,通过标准是「不看笔记能写出结果」。

笔记必须能独立完成可执行校验对应小节
[[对话数据与SmolTalk]]给定一条两轮对话,写出渲染后的 token 序列与掩码和用字符级复现代码打印 ids 与 sum(mask),与手算一致第 2 节、例子第一段
[[多选与工具使用数据]]把一条 GSM8K 答案拆成分片,标出每段掩码,判断四种补全的奖励跑拆分脚本,核对分片数与监督片段数第 5、6 节、例子第二段
[[有监督微调SFT]]画出 6 token 对话的掩码与目标对齐表;手算 的学习率跑对齐脚本,核对 targets 与监督目标数第 7、9 节
[[从生成式到对话式]]写出一次单轮会话的拼接顺序与 render_for_completion 的差异跑状态机脚本,核对第 1、2 轮的 token 列表第 3、5 节

手算点不是练习题,而是排错工具。训练日志出现异常时,第一步是回到对应的手算点,用最小例子确认自己理解的机制与代码一致;机制理解正确而结果异常,问题一定在数据或配置,而不在概念。

符号约定与关键事实

事实值出处
SmolTalk 训练/测试行数460K / 24Ktasks/smoltalk.py 类注释
MMLU 辅助训练集约 100K 行,3 个 epochchat_sft.py 混合与 --mmlu-epochs=3
GSM8K 训练集约 8K 行,4 个 epochchat_sft.py 混合与 --gsm8k-epochs=4
训练混合总行数约 792K(460K + 300K + 32K)由前两行相加
验证混合行数约 29.6K(24K + 5.2K + 0.42K)chat_sft.py 的 val_dataset
每行容量max_seq_len + 1 = 2049row_capacity
渲染截断2048 tokenrender_conversation(max_tokens=2048)
特殊 token9 个tokenizer.SPECIAL_TOKENS
初始学习率比例0.8--init-lr-frac=0.8
warmdown 比例0.5--warmdown-ratio=0.5
最终学习率比例0--final-lr-frac=0.0
Muon 动量0.85 到 0.95,300 步线性get_muon_momentum
ChatCORE 任务数5chat_sft.py、chat_eval.py 的 all_tasks
ChatCORE 基线0.25/0.25/0.25/0/0baseline_accuracies
ChatCORE 评测间隔200 步--chatcore-every=200
检查点目录chatsft_checkpoints/d{depth}save_checkpoint 调用处

一张掩码表

token 类掩码由谁产生
`<bos>`0数据加载器
`<user_start>、<user_end>`0拼接代码
user 内容0用户
`<assistant_start>`0拼接代码
assistant 文本内容1模型
`<python_start>、python 表达式、<python_end>`1模型
`<output_start>、输出内容、<output_end>`0解释器与运行时
`<assistant_end>`1模型

掩码的取值可以压缩成一句:只有模型需要自己生成的内容才计损失。<|assistant_start|> 由代码注入,掩码 0;<|assistant_end|> 由模型输出,掩码 1;python 分片的三段由模型输出,掩码 1;python_output 分片的三段由解释器产生,掩码 0。

术语与记号

术语含义首次出现
渲染把消息序列映射为 (ids, mask)第一篇
打包多条完整对话填入一行 2049 的容量第三篇
best-fit选择能完整放入剩余空间的最长对话第三篇
热启动加载预训练动量缓冲但重置学习率第三篇
centered accuracy,把随机基线映射到 0第三篇
协议由 9 个特殊 token 定义的轮次结构第四篇
强制注入掩码为 0、由运行时写入的 token第四篇
遗忘SFT 后原分布上的能力下降第四篇

按「是否计入损失」可以把全部 token 分成两类,这个二分比逐项记忆掩码表更快。

类别包含的 token用途
仅作输入、不计损失`<bos>、user 段、<assistant_start>、python_output` 段训练时的条件项
需要模型生成、计损失assistant 文本、python 段、`<assistant_end>`训练目标与评测对象

一个训练批次的数据流

flowchart TD
    H["HubDataset 的一行<br/>messages"] --> R["render_conversation<br/>返回 (ids, mask)"]
    R --> B["conv_buffer<br/>最多 100 条"]
    B --> F["best-fit 取整条对话<br/>填入 2049 容量"]
    F --> T["rows / mask_rows<br/>形状 (B, 2049)"]
    T --> S["inputs = rows[:, :-1]<br/>targets = rows[:, 1:]"]
    S --> M["mask_targets = mask[:, 1:]<br/>targets[mask == 0] = -1"]
    M --> L["GPT.forward<br/>cross_entropy(ignore_index=-1)"]

这张图与开头的阶段图不同:阶段图给出模块之间的数据流,这张图给出一条样本在训练批次内的六次变换。若在排错时需要定位「哪一步把信息丢了」,按图从右往左走即可。

阶段自检脚本

下面这段脚本检查协议掩码,需要已训练的分词器与 ~/.cache/nanochat。

"""阶段自检:带工具调用的对话渲染后,python 段被监督、output 段不被监督。"""
from nanochat.tokenizer import get_tokenizer

tok = get_tokenizer()
conversation = {"messages": [
    {"role": "user", "content": "What is 23*47?"},
    {"role": "assistant", "content": [
        {"type": "text", "text": "23*47 = "},
        {"type": "python", "text": "23*47"},
        {"type": "python_output", "text": "1081"},
        {"type": "text", "text": "1081"},
    ]},
]}
ids, mask = tok.render_conversation(conversation)
python_start = tok.encode_special("<|python_start|>")
output_start = tok.encode_special("<|output_start|>")
print("长度", len(ids), "监督 token 数", sum(mask))
print(tok.visualize_tokenization(ids, mask))
assert mask[ids.index(python_start)] == 1      # 工具调用由模型发起
assert mask[ids.index(output_start)] == 0      # 返回值由运行时注入
print("协议掩码自检通过")

脚本只验证两件事:工具调用的起始符被监督,返回值的起始符不被监督。这两条同时成立,说明渲染器的分片分支与掩码表一致;若第一条失败,模型学不会发起调用;若第二条失败,模型会学到伪造计算结果。

阶段产物与命令

命令产物说明
torchrun --standalone --nproc_per_node=8 -m scripts.chat_sft -- --run=sftchatsft_checkpoints/d{depth}训练入口,--run=dummy 关闭 wandb
torchrun --nproc_per_node=8 -m scripts.chat_eval -- -i sft5 个任务的准确率与 ChatCORE评测入口,-a 限定单任务
python -m scripts.chat_cli -p "What is 2+2?"一段回复单轮,-p 存在时生成一次即退出
python -m scripts.chat_cli多轮会话输入 quit/exit 退出,clear 重置
python -m tasks.common切片自测输出验证 Task.__getitem__ 与物理下标一致

版本说明

dev/LOG.md 2026-02-16 条目记录了本阶段的四项调整:优化器热启动默认开启(--load-optimizer=1)、学习率调度改为与预训练同构的 warmup/constant/warmdown、--init-lr-frac 从 1.0 降到 0.8、MMLU epoch 从 1 提到 3 而 GSM8K 从 2 提到 4。同一条目写 ChatCORE 覆盖「all 6 tasks」,当前快照的代码只有 5 个;以代码为准。

常见失败模式

现象可能原因检查位置
损失下降但 ChatCORE 不涨掩码未右移一位,或 targets 未写 -1mask_targets = mask_tensor[:, 1:]
训练几乎不动热启动加载了预训练的近零学习率base_lrs 写回与 init_lr_frac
验证损失虚低行内多条对话互相可见,或验证集与训练集重叠打包边界、TaskMixture 的划分
模型不停止渲染截断切掉了 `<assistant_end>`render_conversation 的 max_tokens
推理时输出字面量 `<user_start>`用字符串拼接代替 id 拼接chat_cli 的 encode_special
多选分数接近随机标签 token 前有空格,或读取位置少减 1render_mc、answer_time_positions
首步损失异常高特殊 token 嵌入在预训练中未被训练第 2 篇与第 4 篇的特殊 token 讨论
中文回复质量明显差SFT 数据全为英文第 4 篇第 6 节

常见误读

  • 把「掩码为 0」理解为「模型看不到该 token」。掩码只作用于损失,提示词仍然进入注意力。
  • 把「补齐」理解为浪费算力、应当改为裁剪。裁剪会切掉 <|assistant_end|> 或半条回复,代价高于补齐。
  • 把「ChatCORE 高」理解为「模型更聪明」。ChatCORE 只覆盖 5 个对话任务,不含多轮连贯性与事实性。
  • 把「热启动」理解为「接着预训练的步数继续训练」。SFT 的步数从 0 开始,只有优化器状态被复用。
  • 把「MMLU 与 ARC 都是多选」理解为格式相同。ARC 的标签集合与选项数由数据给出,可能不是四项,评测的候选集也随之变化。
  • 把「工具调用」理解为模型被执行器取代。模型仍需生成表达式与消费结果,工具只承担求值。

达标清单

  • [ ] 画出从 hub 到 (inputs, targets) 的完整数据流,标出 shuffle(42)、render_conversation、best-fit 打包、掩码右移四个变换点。
  • [ ] 写出 SmolTalk 的三层断言,并各给出一种会触发它的坏样本。
  • [ ] 说明 render_mc 为什么要求 = 与标签之间没有空格,用 tokenizer 的切分规则解释。
  • [ ] 把一条 GSM8K 样本拆成分片列表,标出每个分片的掩码,并算出奖励。
  • [ ] 默写 SFT 的六项继承超参及其来源,说明热启动后为什么必须重置学习率。
  • [ ] 用 6 token 例子画出掩码与目标的对齐表,指出 mask[:, :-1] 错在哪一行。
  • [ ] 解释 best-fit pad 与预训练 best-fit crop 的取舍差异,并估算补齐比例。
  • [ ] 手算 时的学习率乘子与矩阵学习率,说明进度驱动相对步数驱动的优势。
  • [ ] 用给定准确率手算 ChatCORE 与 chatcore_cat,说明两者为何分开报告。
  • [ ] 复述 chat_cli 的五个拼接不变量,指出漏掉任意一个的后果。
  • [ ] 列出 SFT 后的三类行为变化,并说明哪一类无法用 ChatCORE 观测。
  • [ ] 设计一个测量 SFT 造成 base 能力退化的实验,写明脚本、数据与对照口径。
  • [ ] 说明 render_for_completion 与 render_conversation 的返回值差异,以及各自被哪些脚本调用。
  • [ ] 解释 9 个特殊 token 中哪几个在预训练中从未出现,以及这对 SFT 的学习率设置意味着什么。
  • [ ] 给定一条新数据(例如中文对话),判断它能否直接用于 nanochat 的 SFT,并列出需要改动的位置。
  • [ ] 说出本阶段与 07、08、09 三个阶段的交界点各是什么,以及交界处由哪个函数或指标承担。
  • [ ] 用阶段自检脚本验证协议掩码,并解释两条断言各自失败时的后果。
  • [ ] 说明 HubDataset.shuffle(42) 与 TaskMixture 的 random.Random(42) 两个「42」分别固定了什么。
  • [ ] 解释为什么 SFT 只跑一个 epoch,而 MMLU 在同一份数据上被看三次。
  • [ ] 画出 ChatCORE 的 centered 公式,说明 GSM8K 与 HumanEval 的基线为何取 0。

参考来源

  • Karpathy, nanochat(commit 92d63d4),scripts/chat_sft.py、tasks/、nanochat/tokenizer.py、nanochat/engine.py —— 本阶段全部事实、代码与数字的基准。
  • Karpathy, nanochat(commit 92d63d4),dev/LOG.md 2026-02-16「SFT Script Upgrades」 —— 本阶段的调参记录与版本差异来源。
  • Allal et al., "SmolLM2: When Smol Goes Big — Data-Centric Training of a Small Language Model", arXiv:2502.02737, 2025 —— smol-smoltalk 的来源、规模与面向小模型的取舍。
  • Ouyang et al., "Training language models to follow instructions with human feedback", arXiv:2203.02155, 2022 —— SFT 在「预训练—对齐」链路中的位置,以及条件分布与联合分布的区别。
  • Hendrycks et al., "Measuring Massive Multitask Language Understanding", arXiv:2009.03300, 2021;Clark et al., "Think you have Solved Question Answering? Try ARC", arXiv:1803.05457, 2018;Cobbe et al., "Training Verifiers to Solve Math Word Problems", arXiv:2110.14168, 2021 —— 多选与数学任务的原始定义、标签结构与答案约定。