---
tags: [nanochat, MOC, pretraining]
阶段: 05-预训练Pretraining
难度: ★★☆
created: 2026-10-22
related: "[[MOC-Transformer]], [[MOC-中段训练与SFT]], [[MOC-评测]], [[MOC-复现]]"
---

# MOC · 预训练

> [!summary] 本阶段地图
> 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 的评测。

```mermaid
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 的计算量，$6N$ 加注意力项 | 3、7、9 |
| BOS-aligned best-fit | 每个训练行以 BOS 开头、按最优适配装填文档的批构造方式 | 2 |
| 梯度累积 | 一个优化器步内串联多个微批，使总批与显存解耦 | 3、6 |
| ZeRO-2 | 只分片优化器状态、不分片参数的数据并行变体 | 6 |
| reduce_scatter / all_gather | 规约后分片、分片后拼接的两个集合通信原语 | 6 |
| 中心化准确率 | $(a-b/100)/(1-b/100)$，扣掉随机猜测后的任务得分 | 8、9 |
| bpb | 每字节比特数，$\sum\text{nats}/(\ln2\cdot\sum\text{bytes})$ | 8、9 |
| time-to-GPT-2 | 在 8×H100 上把 CORE 训到超过 0.256525 的墙钟时间 | 9、本 MOC |
| 数据参数比 | 训练 token 数除以缩放参数，默认 12、speedrun 用 8 | 7、9 |
| MFU | 实测 FLOP/s 与硬件峰值的比值，训练脚本按步打印 | 3、6 |

## 学习顺序与理由

顺序遵循「先看数据、再看循环、再看调度、再看状态、最后看度量」，每一步只引入一个新变量。

1. [[训练数据与FineWeb]]：先确定训练分布。ClimbMix-400B 换了 FineWeb-EDU 之后，bpb 不再跨版本可比，这一条会贯穿到最后一篇。
2. [[数据加载器dataloader]]：确定一条训练样本如何从 parquet 变成 `(x, y)`。BOS-aligned best-fit 的裁剪率（约 34.6%）与 100% 利用率是后续所有 token 数计算的基准。
3. [[训练脚本与speedrun]]：把数据接进循环。这一篇给出从 meta device 建模型到 `optimizer.step()` 的完整链路，是 05 的主干。
4. [[学习率与warmup-warmdown]]：循环确定后，再看每个 step 的学习率从哪来。warmup 40 步、warmdown 比例 0.65、终值 0.05 是三个必须记住的数。
5. [[检查点与恢复]]：训练可能中断，状态必须可重放。三类文件与 meta 字段在此引入。
6. [[分布式训练与优化器分片]]：把单卡循环扩到 8 卡。为什么不用 DDP、梯度在哪同步、状态如何分片，都在这一篇。
7. [[缩放定律与模型深度]]：从「怎么训」转向「训多大、训多久」。`--depth` 如何推出宽度、头数、批大小、学习率与权重衰减。
8. [[CORE指标]]：训练完成后如何证明能力。22 项 ICL 任务、中心化公式、few-shot 采样与打分规则。
9. [[对比GPT-2核心指标]]：把 CORE 换算成时间与成本，对照 leaderboard 六次记录，理解 time-to-GPT-2 作为目标函数的含义与局限。

为什么不先读 CORE：CORE 的噪声（单次标准差约 0.005）与协议细节（`max_per_task`、few-shot 采样）只有在对训练流程有具体量感之后才有意义；先读会让「0.2626 与 0.256525」变成两个无上下文的数字。

为什么不把缩放定律放在最前：缩放定律的所有系数都锚定在 d12 的实测点上，而 d12 的批大小、学习率与权重衰减又来自前四篇的实现细节；脱离实现读公式会得到「$N\propto C^{0.5}$」这样正确但无法落地的结论。

## 笔记索引

| # | 笔记 | 核心问题 | 关键数字 | 难度 | 前置 |
|---|---|---|---|---|---|
| 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 年约 \$43K、当前约 \$48、最快 1.65 h | ★★☆ | 8 |

九篇覆盖的能力：1–2 属于数据工程，3–6 属于训练工程，7 属于规模设计，8–9 属于评测与目标函数。三者缺一不可：只懂 3–6 会在换深度时失去依据，只懂 7 会在 8 卡上写出错误的同步逻辑，只懂 8–9 则无法解释分数为何波动。

## 符号约定与关键事实

以下数值均来自本地源码快照（commit `92d63d4`），跨篇引用时以此表为准。

| 量 | 当前值 | 出处 |
|---|---|---|
| 词表大小 | 32768（$2^{15}$） | `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 | $4.7752\times10^{9}$ | `GPT.estimate_flops()` |
| d24 全局批 | $2^{20}=1{,}048{,}576$ | auto batch 公式 |
| d24 迭代数（ratio 8） | 5568 | $8\times729{,}810{,}624/2^{20}$ |
| 默认数据参数比 | 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 ~$100 nanochat d20`，属于旧版叙述，当前为 d24、约 \$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 各占很小一部分；因此优化应集中在预训练的时间上，而不是评测脚本的效率。

## 实验入口

阶段内的三条主要命令都来自仓库脚本，不另造参数。

```bash
# 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
```

产物目录固定，便于跨篇引用：

```text
~/.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 卡梯度被放大 $N$ 倍：损失曲线比单卡陡；检查 `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 的约 \$43K 与当前 speedrun 的约 \$48，并解释 time-to-GPT-2 的排序逻辑。
- [ ] 能指出 05 阶段涉及的三处版本差异（d26 与 d24、10.5 与 12、\$100/d20 的旧注释）。
- [ ] 能在 8×H100 之外的硬件上给出至少一套降级配置（深度、批大小、精度）并说明预期后果。

## 阶段验收标准

完成本阶段的判据不是读完九篇，而是能独立完成一次端到端实验并解释结果：

1. 用 `--depth=12` 或 `--depth=16` 跑一次完整预训练与评测，记录训练时间、val bpb 与 CORE。
2. 用本篇的缩放定律表核对实际批大小、迭代数与 token 数是否与预测一致，偏差超过 5% 时给出原因。
3. 手动中断一次训练，用 `--resume-from-step` 恢复，验证数据游标没有从头开始。
4. 把 CORE 与 bpb 同时报告，并说明哪一个更适合作为该次实验的决策依据。
5. 用成本换算公式给出该次实验的美元成本，并说明与 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 缩放参数、$2^{20}$ 批、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 的落地。
