MOC · 预训练
本阶段地图
05 阶段回答一个问题:如何用「下一个 token 预测」把一个随机初始化的 Transformer 训练到 GPT-2 级能力,并且让这件事在 8 卡上以可预测的时间与成本完成。九篇笔记沿一条因果链展开:数据从哪来(ClimbMix)、数据如何切成训练批(BOS-aligned best-fit)、训练循环如何组织(base_train)、学习率与权重衰减如何调度、状态如何落盘与恢复、8 卡如何同步与分片、模型该多大与训多久(缩放定律)、能力如何度量(CORE)、以及如何把度量换算成时间与金钱(time-to-GPT-2)。前置是 02 的 FLOPs 与 Muon、04 的
gpt.py;后续是 06 的 SFT 与 08 的评测。
flowchart LR
subgraph 数据
A1[训练数据与FineWeb<br/>ClimbMix-400B]
A2[数据加载器dataloader<br/>BOS对齐best-fit]
end
subgraph 训练
B1[训练脚本与speedrun<br/>base_train循环]
B2[学习率与warmup-warmdown<br/>调度器]
B3[检查点与恢复<br/>model/meta/optim]
B4[分布式训练与优化器分片<br/>MuonAdamW三段通信]
end
subgraph 规模与目标
C1[缩放定律与模型深度<br/>depth单旋钮]
D1[CORE指标<br/>22项ICL]
D2[对比GPT-2核心指标<br/>time-to-GPT-2]
end
A1 --> A2 --> B1
B1 --> B2
B1 --> B3
B1 --> B4
B1 --> C1
C1 --> B1
B4 --> B3
B4 --> D1
C1 --> D1 --> D2
D2 -.->|阈值未达则改配置| C1
B1 -.->|产物| E1[06 SFT]
D2 -.->|验收| E2[08 评测]
图中的双向关系是真实的迭代过程:base_train.py 先用缩放定律算出训练时长与批大小,训练结果又用来重新拟合缩放定律(runs/scaling_laws.sh);CORE 未达阈值时,调整的是深度、数据参数比与精度,而不是单个超参数。
阶段定位
预训练是 nanochat 中计算占比最高的一段。以当前 speedrun 为例,分词器训练只需几分钟,SFT 与 RL 各需数十分钟(按同一节点估算),而 d24 预训练需要约 1.65 小时(README leaderboard 第 6 行)。因此「优化 nanochat」在实践中几乎等价于「优化预训练」。
本阶段与相邻阶段的分工如下。
| 相邻阶段 | 交接物 | 本阶段不负责的内容 |
|---|---|---|
| 03 分词器 | 词表 32768、tokenizer 与 9 个特殊 token | BPE 训练算法本身 |
| 04 Transformer | GPT、GPTConfig、estimate_flops() | 注意力与残差的具体推导 |
| 06 中段训练与 SFT | base 检查点与 meta(batch、LR、token 数) | 对话数据与 mask 构造 |
| 07 强化学习 | SFT 检查点 | rollout 与奖励设计 |
| 08 评测 | CORE 分项 CSV、bpb | ChatCORE 与生成式评测 |
| 09 推理 Engine | base/chat 检查点 | KV Cache 与解码 |
| 10 复现与实验 | speedrun 命令与故障树 | 环境安装细节 |
三条能力主线
本阶段的九篇笔记不是并列的知识点,而是三条能力主线的交叉。
第一条,懂原理:从损失函数到能力度量。预训练的目标是下一个 token 的交叉熵,但「损失下降」不等于「能力提升」。这条主线的链条是:数据分布决定损失的下界(1),批构造决定每条样本被看到的方式(2),优化器决定参数沿什么方向移动(3、6),调度器决定移动的幅度(4),缩放定律决定模型容量与数据量的配比(7),CORE 决定如何把内部损失映射到外部任务(8),time-to-GPT-2 决定如何把能力映射到成本(9)。任一环缺失,结论都会变成「损失降了所以模型变好了」这种无法反驳也无法使用的判断。
第二条,能复现:从命令到产物。复现的判据是能解释每条命令的产物与失败模式,而不是脚本跑完。runs/speedrun.sh 产生五个目录(数据、分词器、检查点、评测 CSV、SFT 检查点);runs/scaling_laws.sh 产生一个可续跑的 CSV;runs/miniseries.sh 产生一条深度曲线。知道每个文件的来源,才能在结果异常时定位到具体阶段。
第三条,懂工程:显存、通信、成本。8 卡是默认配置,因此显存与通信是硬约束:优化器状态分片决定了 d24 能否装进 80 GB(6),梯度累积与总批整除关系决定了批大小能否改(3、6),精度选择(bf16、fp8)决定了吞吐与稳定性(3)。成本是最终约束:1.65 小时的 d24 训练约 40 美元,任何让时间翻倍的改动都需要明确收益。
关键概念速查
| 术语 | 一句话定义 | 出现笔记 |
|---|---|---|
| 缩放参数 | transformer_matrices + lm_head 的元素数,用于缩放定律 | 7、9 |
| 总参数 | 含 wte、value embeddings、lm_head 与逐层标量的全部参数 | 5、7 |
| FLOPs/token | 前向加反向每 token 的计算量, 加注意力项 | 3、7、9 |
| BOS-aligned best-fit | 每个训练行以 BOS 开头、按最优适配装填文档的批构造方式 | 2 |
| 梯度累积 | 一个优化器步内串联多个微批,使总批与显存解耦 | 3、6 |
| ZeRO-2 | 只分片优化器状态、不分片参数的数据并行变体 | 6 |
| reduce_scatter / all_gather | 规约后分片、分片后拼接的两个集合通信原语 | 6 |
| 中心化准确率 | ,扣掉随机猜测后的任务得分 | 8、9 |
| bpb | 每字节比特数, | 8、9 |
| time-to-GPT-2 | 在 8×H100 上把 CORE 训到超过 0.256525 的墙钟时间 | 9、本 MOC |
| 数据参数比 | 训练 token 数除以缩放参数,默认 12、speedrun 用 8 | 7、9 |
| MFU | 实测 FLOP/s 与硬件峰值的比值,训练脚本按步打印 | 3、6 |
学习顺序与理由
顺序遵循「先看数据、再看循环、再看调度、再看状态、最后看度量」,每一步只引入一个新变量。
- 训练数据与FineWeb:先确定训练分布。ClimbMix-400B 换了 FineWeb-EDU 之后,bpb 不再跨版本可比,这一条会贯穿到最后一篇。
- 数据加载器dataloader:确定一条训练样本如何从 parquet 变成
(x, y)。BOS-aligned best-fit 的裁剪率(约 34.6%)与 100% 利用率是后续所有 token 数计算的基准。 - 训练脚本与speedrun:把数据接进循环。这一篇给出从 meta device 建模型到
optimizer.step()的完整链路,是 05 的主干。 - 学习率与warmup-warmdown:循环确定后,再看每个 step 的学习率从哪来。warmup 40 步、warmdown 比例 0.65、终值 0.05 是三个必须记住的数。
- 检查点与恢复:训练可能中断,状态必须可重放。三类文件与 meta 字段在此引入。
- 分布式训练与优化器分片:把单卡循环扩到 8 卡。为什么不用 DDP、梯度在哪同步、状态如何分片,都在这一篇。
- 缩放定律与模型深度:从「怎么训」转向「训多大、训多久」。
--depth如何推出宽度、头数、批大小、学习率与权重衰减。 - CORE指标:训练完成后如何证明能力。22 项 ICL 任务、中心化公式、few-shot 采样与打分规则。
- 对比GPT-2核心指标:把 CORE 换算成时间与成本,对照 leaderboard 六次记录,理解 time-to-GPT-2 作为目标函数的含义与局限。
为什么不先读 CORE:CORE 的噪声(单次标准差约 0.005)与协议细节(max_per_task、few-shot 采样)只有在对训练流程有具体量感之后才有意义;先读会让「0.2626 与 0.256525」变成两个无上下文的数字。
为什么不把缩放定律放在最前:缩放定律的所有系数都锚定在 d12 的实测点上,而 d12 的批大小、学习率与权重衰减又来自前四篇的实现细节;脱离实现读公式会得到「」这样正确但无法落地的结论。
笔记索引
| # | 笔记 | 核心问题 | 关键数字 | 难度 | 前置 |
|---|---|---|---|---|---|
| 1 | [[训练数据与FineWeb]] | 预训练数据从哪来、如何分片与划分验证集 | ClimbMix-400B、训练 shard 最大编号 6542(实际 6543 个文件,含固定验证 shard)、约 150 个 shard 足够 GPT-2 级 | ★★☆ | 03 |
| 2 | [[数据加载器dataloader]] | 一条训练样本如何从 parquet 变成 (x,y) | 100% 利用率、约 34.6% token 被裁剪、T=2048 | ★★★ | 03 |
| 3 | [[训练脚本与speedrun]] | base_train.py 从建模型到训练循环的完整链路 | meta device 建模型、grad_accum_steps、MFU 打印 | ★★★ | 04 |
| 4 | [[学习率与warmup-warmdown]] | 学习率、动量与权重衰减如何随 step 变化 | warmup 40、warmdown 0.65、final 0.05、Muon 动量 0.85→0.97→0.90 | ★★☆ | 02 |
| 5 | [[检查点与恢复]] | 保存什么、如何恢复到同一训练状态 | model/meta/optim 三类文件、optim_{step}_rank{r}.pt | ★★☆ | 3 |
| 6 | [[分布式训练与优化器分片]] | 8 卡如何同步梯度、状态如何分片 | 3 阶段通信、AdamW 1024 元素阈值、Muon chunk | ★★★ | 02、3 |
| 7 | [[缩放定律与模型深度]] | 深度如何决定宽度、参数量、token 数与批大小 | d24:1536 维、12 头、729.8M 缩放参数、2^20 批 | ★★★ | 02、3 |
| 8 | [[CORE指标]] | 22 项 ICL 任务如何打分与聚合 | centered accuracy、baseline 百分数、GPT-2 阈值 0.256525 | ★★★ | 08 |
| 9 | [[对比GPT-2核心指标]] | 如何把 CORE 换算成时间与成本 | 2019 年约 \48、最快 1.65 h | ★★☆ | 8 |
九篇覆盖的能力:1–2 属于数据工程,3–6 属于训练工程,7 属于规模设计,8–9 属于评测与目标函数。三者缺一不可:只懂 3–6 会在换深度时失去依据,只懂 7 会在 8 卡上写出错误的同步逻辑,只懂 8–9 则无法解释分数为何波动。
符号约定与关键事实
以下数值均来自本地源码快照(commit 92d63d4),跨篇引用时以此表为准。
| 量 | 当前值 | 出处 |
|---|---|---|
| 词表大小 | 32768() | GPTConfig.vocab_size、tokenizer |
| 上下文长度 | 2048 | GPTConfig.sequence_len、--max-seq-len |
| 滑动窗口模式 | SSSL,短窗为 512 | base_train.py --window-pattern、_compute_window_sizes |
| speedrun 配置 | --depth=24 --target-param-data-ratio=8 --device-batch-size=16 --fp8 | runs/speedrun.sh |
| d24 宽度 / 头数 | 1536 / 12 | build_model_meta |
| d24 缩放参数 | 729,810,624 | GPT.num_scaling_params() |
| d24 总参数 | 1,384,122,122 | 同上,含 wte、value embeddings |
| d24 FLOPs/token | GPT.estimate_flops() | |
| d24 全局批 | auto batch 公式 | |
| d24 迭代数(ratio 8) | 5568 | |
| 默认数据参数比 | 12 | base_train.py 参数默认值 |
| CORE 阈值 | 0.256525 | dev/LEADERBOARD.md |
| CORE 任务数 | 22 | dev/estimate_gpt3_core.ipynb、dev/LEADERBOARD.md |
| 8×H100 单价 | 约 \$24/小时 | README |
| 最短 time-to-GPT-2 | 1.65 h(CORE 0.2626) | README leaderboard 第 6 行 |
三处版本差异必须记住,写作与实验时不得混用。第一,README 有一处写「GPT-2 约等于 depth 26」,当前 speedrun 用 d24(ClimbMix 之后模型缩小)。第二,dev/LEADERBOARD.md 与 dev/LOG.md 记「计算最优 ratio 约 10.5」,而当前 base_train.py 的默认值是 12;speedrun 显式用 8。第三,README 目录注释仍有一行 `speedrun.sh # Train the ~48。
成本与时间预算
阶段内的每一步都有可估算的时间与费用。下表以 8×H100、24 美元/小时为基准,数据来自 README 与 dev/LOG.md;标注「推算」的行为按单价换算所得,不是仓库直接给出的数字。
| 步骤 | 时间 | 费用 | 依据 |
|---|---|---|---|
| 下载约 150 个数据分片 | 取决于带宽 | 接近 0 | runs/speedrun.sh 的下载段 |
| 训练分词器(约 2B 字符) | 数分钟 | 约 1–2 美元(推算) | scripts/tok_train |
| d24 预训练(ratio 8、fp8) | 1.65 h | 约 40 美元 | README leaderboard 第 6 行 |
| base 评测(CORE + bpb + 采样) | 数十分钟 | 约 10 美元(推算) | scripts.base_eval |
| SFT | 数十分钟 | 约 10 美元(推算) | runs/speedrun.sh |
| 完整 speedrun | 约 1.5–2 h | 约 48 美元 | README |
| 完整 miniseries(d12–d26 共 8 个深度) | 数十小时 | 数百至一千美元(推算) | runs/miniseries.sh |
预算的分配原则是:预训练占绝大部分,评测与 SFT 各占很小一部分;因此优化应集中在预训练的时间上,而不是评测脚本的效率。
实验入口
阶段内的三条主要命令都来自仓库脚本,不另造参数。
# 1) 完整流程:分词器 -> d24 预训练 -> base 评测 -> SFT -> chat 评测
# 需要 8×H100,约 1.5-2 小时(不含数据下载)
bash runs/speedrun.sh
# 2) 只做预训练与 base 评测(已具备数据与分词器时)
OMP_NUM_THREADS=1 torchrun --standalone --nproc_per_node=8 -m scripts.base_train -- \
--depth=24 --target-param-data-ratio=8 --device-batch-size=16 --fp8
OMP_NUM_THREADS=1 torchrun --standalone --nproc_per_node=8 -m scripts.base_eval -- \
--device-batch-size=16
# 3) 小规模验证循环(单卡或 CPU,用于调试代码而非追指标)
python -m scripts.base_train --depth=4 --max-seq-len=512 --device-batch-size=1 \
--eval-tokens=512 --core-metric-every=-1 --total-batch-size=512 --num-iterations=20
产物目录固定,便于跨篇引用:
~/.cache/nanochat/
├── base_data_climbmix/ # 训练分片(每片约 250M 字符)
├── tokenizer/ # 词表与 token_bytes
├── base_checkpoints/d24/ # model_{step}.pt / meta_{step}.json / optim_{step}_rank{r}.pt
├── base_eval/base_model_{step}.csv # CORE 分项:Task, Accuracy, Centered
├── chatsft_checkpoints/ # SFT 检查点
├── chatrl_checkpoints/ # RL 检查点
└── eval_bundle/ # core.yaml / eval_data / eval_meta_data.csv
常见失败模式
- 数据未下齐就开跑:
base_train.py会在读取分片时阻塞或报错;runs/speedrun.sh先用wait $DATASET_DOWNLOAD_PID等下载完成。 - 词表不匹配:加载检查点时
build_model断言tokenizer.get_vocab_size() == vocab_size,换 tokenizer 后必须重训模型。 - 8 卡梯度被放大 倍:损失曲线比单卡陡;检查
loss / grad_accum_steps与ReduceOp.AVG是否同时存在。 - OOM:优先降
--device-batch-size(16 → 8 → 4),脚本会自动增大梯度累积步数保持总批不变。 - CORE 压线:单次结果与阈值差小于 0.005 时不可下结论,应按
dev/LOG.md的做法重复运行并同时看 bpb。 - 换数据集后比较 bpb:ClimbMix 与 FineWeb-EDU 的验证集不同,跨数据集的 bpb 不可比。
- FA3 不可用:
scripts/base_train.py会打印警告并回退到 SDPA,训练仍可进行但吞吐下降;此时SSSL的滑动窗口不被 SDPA 支持,脚本会建议改用--window-pattern=L。 - 在不支持 FP8 的 GPU 上给
--fp8:只有 CPU/MPS 会打印警告并忽略该参数;只要--device-type解析为cuda就会执行转换,A100 等不支持 FP8 的卡会在torch._scaled_mm处报错,而不是静默回退。
与《AI学习总纲》的分工
本库不重复通用教程,只写 nanochat 的落地位置。四组跨库衔接如下。
| 通用原理 | 本库只保留的结论 | 落地位置 |
|---|---|---|
| [[预训练-微调-对齐pipeline]] | 预训练产出 base 模型,SFT 与 RL 在其上继续 | 本阶段整体定位、阶段 06 与 07 的入口 |
| [[分布式训练与部署]] | 集合通信原语、ZeRO 三阶段、张量并行 | 第 6 篇的三段式通信与 ZeRO-2 分片 |
| [[模型评估矩阵]] | 基准的构造效度、统计不确定性、评分器分类 | 第 8 篇的 22 项 ICL 与第 9 篇的噪声分析 |
| [[成本-延迟-质量权衡]] | 质量阈值固定时成本与时间的换算 | 第 9 篇的 time-to-GPT-2 与预算档 |
阅读顺序上,跨库笔记不必先读完;遇到对应术语时再回查,比先读一遍通用教程更有效。
产物与验证点
每一步都应有可检查的产物;没有产物的步骤无法判断是否真正完成。
| 步骤 | 产物 | 验证方式 |
|---|---|---|
| 数据下载 | base_data_climbmix/*.parquet | 分片数不少于 150,且能读出一个 row group |
| 分词器训练 | tokenizer/ 下的词表与 token_bytes | python -m scripts.tok_eval 报告压缩率 |
| 预训练 | base_checkpoints/d24/model_*.pt 等三类文件 | 能加载并打印 meta 的 step |
| base 评测 | base_eval/base_model_{step}.csv | 末行 CORE 等于前 22 行 Centered 的均值 |
| SFT | chatsft_checkpoints/ | chat_eval 能输出 ChatCORE |
| 扫描实验 | scaling_laws_results_*/results.csv | 行数等于已完成的 (预算, 深度) 组合数 |
验证点按阶段递进:数据与分词器的错误会在预训练前暴露,检查点的错误会在恢复时暴露,评测的错误只在对比历史 CSV 时暴露。因此每次跑完应至少保存 CSV 与 meta,而不是只保存模型权重。
维护约定
本阶段的事实基准是 commit 92d63d4。若上游把 speedrun 深度、数据参数比或 CORE 阈值改掉,需要同步修改的篇目是:第 3 篇(命令)、第 7 篇(缩放律表与 d24 数值)、第 8 篇(阈值)、第 9 篇(成本与 leaderboard),以及本 MOC 的「符号约定与关键事实」表。只改其中一篇会造成跨篇数字冲突。
数字的书写约定:参数量写完整整数(如 729,810,624),比例与分数写小数(如 0.256525),时间写小时并附秒数(如 1.65 h、5940 s),金额写美元并注明单价基准。这样跨篇引用时不需要再换算。
达标清单
- [ ] 能画出从原始文本到 base 检查点的完整数据流,并标出每一步对应的脚本与产物目录。
- [ ] 能写出 d24 的宽度、头数、缩放参数、FLOPs/token、全局批与 ratio 8 下的迭代数,并说明每个量的出处。
- [ ] 能解释
--depth如何同时决定宽度、头数、批大小、学习率与权重衰减,以及为什么奇数深度的形状不整齐。 - [ ] 能说明检查点三类文件的分工,并指出哪一种必须每个 rank 各存一份。
- [ ] 能复述
MuonAdamW.step的三阶段通信,并说明 nanochat 为什么不用 DDP。 - [ ] 能写出 CORE 的中心化公式并手算一个任务;能说明 GPT-2 阈值 0.256525 的来源与噪声尺度。
- [ ] 能复算 2019 年 GPT-2 的约 \48,并解释 time-to-GPT-2 的排序逻辑。
- [ ] 能指出 05 阶段涉及的三处版本差异(d26 与 d24、10.5 与 12、\$100/d20 的旧注释)。
- [ ] 能在 8×H100 之外的硬件上给出至少一套降级配置(深度、批大小、精度)并说明预期后果。
阶段验收标准
完成本阶段的判据不是读完九篇,而是能独立完成一次端到端实验并解释结果:
- 用
--depth=12或--depth=16跑一次完整预训练与评测,记录训练时间、val bpb 与 CORE。 - 用本篇的缩放定律表核对实际批大小、迭代数与 token 数是否与预测一致,偏差超过 5% 时给出原因。
- 手动中断一次训练,用
--resume-from-step恢复,验证数据游标没有从头开始。 - 把 CORE 与 bpb 同时报告,并说明哪一个更适合作为该次实验的决策依据。
- 用成本换算公式给出该次实验的美元成本,并说明与 leaderboard 同配置记录的差异来源。
三种阅读路径
时间有限时按下表选一条路径,不必九篇全读。
| 目标 | 必读 | 可跳过 | 预计时间 |
|---|---|---|---|
| 只求跑通 speedrun | 1、3、5 | 6、7 的推导部分 | 2–3 小时 |
| 理解训练如何被设计 | 3、4、5、6、7 | 1、2 的细节 | 6–8 小时 |
| 关注指标与成本 | 8、9、7 的第 8 节 | 4、6 的实现细节 | 3–4 小时 |
| 做自己的实验 | 全部,重点 3、5、7 | 无 | 10–12 小时 |
只求跑通时仍建议读第 5 篇:没有检查点,任何中断都意味着重跑,这在按小时计费的节点上代价最高。
与全书的衔接
本阶段的产物是 base 检查点与 meta,它是 06(SFT)、07(RL)、08(评测)、09(推理)四个阶段的共同输入。03 训练出的词表与 04 定义的模型结构,在这里第一次被联合使用;10 则重复本阶段的命令并整理故障树。
若把全书看作一条流水线,05 是唯一把「算力」换算成「能力」的阶段:02 给出 FLOPs 与优化器的数学,03、04 给出结构与词表,06 之后都在此基础上做行为改造。因此本阶段的数字(d24、729.8M 缩放参数、 批、1.65 小时、CORE 0.2626)是全书的公共坐标,后续任何一篇引用模型规模或成本时都应与本 MOC 的「符号约定与关键事实」表一致。
参考来源
- Karpathy, nanochat(commit 92d63d4),README、
runs/speedrun.sh、dev/LEADERBOARD.md、dev/LOG.md—— 对应本篇全部配置、数字与版本差异。 - DCLM 团队, DataComp-LM(2406.11794)—— 对应 CORE 指标与本阶段的能力度量。
- Hoffmann et al., Training Compute-Optimal Large Language Models(2203.15556,Chinchilla)—— 对应缩放定律与数据参数比的对照基线。
- Rajbhandari et al., ZeRO(1910.02054)—— 对应优化器状态分片的理论背景。
- Karpathy, nanoGPT 与 modded-nanogpt —— 对应训练循环与 Muon 优化器设计的来源。
- 跨库衔接:通用原理见 预训练-微调-对齐pipeline 与 分布式训练与部署,本阶段只讲 nanochat 的落地。