---
tags: [nanochat, pretraining, speedrun]
阶段: 05-预训练Pretraining
难度: ★★★
created: 2026-10-22
related: "[[数据加载器dataloader]], [[学习率与warmup-warmdown]], [[检查点与恢复]], [[跑通speedrun脚本]]"
---

# 训练脚本与 speedrun

## 定义

**speedrun** 是 `runs/speedrun.sh` 所描述的端到端流水线：在一台空白 8×H100 节点上，从安装依赖开始，依次完成数据下载、分词器训练、d24 基座模型预训练、基座评测、SFT 与对话评测，最终得到一个可用 `chat_cli` 对话的 GPT-2 级模型。

本篇出现的符号与术语：

- `--depth`：Transformer 层数 $d$，唯一的规模旋钮。`model_dim` 由 `depth * aspect_ratio` 向上取整到 `head_dim` 的倍数得到。
- $N_{\text{scaling}}$：参与缩放律统计的参数量，等于 `transformer_matrices + lm_head`，不含 `wte` 与 value embedding。
- $D$：训练 token 数，由 `--target-param-data-ratio` 乘以 $N_{\text{scaling}}$ 得到。
- $B_{\text{total}}$：一次优化器更新消费的 token 数，即总批大小；由缩放律自动计算或被 `--total-batch-size` 覆盖。
- $B_{\text{dev}}$：单卡批大小，`--device-batch-size`。
- $T$：上下文长度，`--max-seq-len`，默认 2048。
- $W$：世界大小，即 `torchrun --nproc_per_node`，speedrun 为 8。
- $A$：梯度累积步数，$A=B_{\text{total}}/(B_{\text{dev}}\cdot T\cdot W)$。
- meta device：PyTorch 的虚拟设备，只保存形状与 dtype，不分配存储。用于在不知道参数值的前提下先确定模型结构。
- `total_training_time`：训练循环内累计的墙钟时间，只统计第 10 步之后的步；leaderboard 的「time to GPT-2」就是它，不含评测、日志与初始化。
- MFU（Model FLOPs Utilization）：实际吞吐与硬件峰值算力之比，代码中按百分比打印。

## 为什么重要

- 它是唯一被维护的官方复现路径。`runs/speedrun.sh` 的每一次改动都对应 leaderboard 上的一次提交，读这个脚本等于读当前状态的最佳配置。
- 它把「模型多大」压缩成一个整数。深度决定宽度、头数、批大小、学习率、权重衰减与训练 token 数，因此一次 `--depth` 改动会同时改变十几个超参数；不理解这条链就无法解释实验结果。
- 启动顺序决定能否跑起来。meta device 建模型、`to_empty` 分配显存、`init_weights` 写入真实值、fp8 转换、`torch.compile`，这五步的顺序错了会得到 NaN、编译失败或显存翻倍。
- 时间的定义决定指标可比性。leaderboard 只统计训练步，因此「2.02 小时」与「脚本跑了 2.5 小时」不矛盾；把两者混用会得出错误的加速比。
- 在全书中的位置：前置为 [[数据加载器dataloader]]（数据供给）与 [[缩放定律与模型深度]]（超参数如何从 depth 推导）；后续为 [[学习率与warmup-warmdown]]（循环内的调度）、[[检查点与恢复]]（保存格式）与 [[分布式训练与优化器分片]]（8 卡如何同步）。对应能力目标：懂原理对应「解释每一步的必要性」，能复现对应「在自有硬件上跑通并降级配置」，懂工程对应「定位 OOM、NaN 与吞吐异常」。

## 原理与推导

### 步骤 1 六个环节与九条命令

脚本按注释分为环境、分词器、基座模型、SFT 四段，加上开头的数据下载与结尾的对话，共六个环节：

| 环节 | 命令 | 产物（默认 `~/.cache/nanochat`） | 耗时量级（估计） |
|---|---|---|---|
| 1 环境 | `uv venv`、`uv sync --extra gpu`、`source .venv/bin/activate` | `.venv/` | 分钟级，取决于网络 |
| 2 数据 | `python -m nanochat.dataset -n 8`，随后 `-n 170 &` | `base_data_climbmix/shard_*.parquet`，171 个 | 分钟到十几分钟，与下一步重叠 |
| 3 分词器 | `python -m scripts.tok_train`、`tok_eval` | `tokenizer/tokenizer.pkl`、`tokenizer/token_bytes.pt` | 数十秒到数分钟 |
| 4 预训练 | `torchrun --nproc_per_node=8 -m scripts.base_train -- --depth=24 --target-param-data-ratio=8 --device-batch-size=16 --fp8` | `base_checkpoints/d24/model_005568.pt`、`optim_005568_rank*.pt`、`meta_005568.json` | 主体，约 1.5 至 2 小时 |
| 5 基座评测 | `torchrun --nproc_per_node=8 -m scripts.base_eval -- --device-batch-size=16` | `base_eval/base_model_005568.csv`，打印 CORE 与 bpb | 十几分钟 |
| 6 后训练与对话 | `chat_sft`、`chat_eval -i sft`、（注释）`chat_cli` | `chatsft_checkpoints/d24/model_*.pt`，打印 ChatCORE | 十几分钟 |

表中只有第 4 环节的耗时在仓库中有记录：`dev/LOG.md` 的 2h01m 与 leaderboard 的 2.02h 都指 `total_training_time`。其余环节的耗时量级来自各脚本注释与单步吞吐的反推，不是实测值；`runs/speedrun.sh` 头部只给出整条约 1.5 小时的旧数字。

几个容易忽略的细节：

- 第 2 环节先同步下 8 个 shard，因为分词器只需要约 2B 字符；随后后台下载 170 个，与分词器训练、评测并行。`wait $DATASET_DOWNLOAD_PID` 放在 `base_train` 之前，保证预训练开始前数据齐全。
- 第 3 环节的 `tok_eval` 只做压缩率对比，不阻塞后续；它的输出用于确认新分词器与语料匹配，不写入 checkpoint。
- 第 4 环节的 `torchrun` 与脚本之间有一个 `--`，它把 `--depth` 等参数传给 `base_train.py` 而不是 `torchrun`。漏掉 `--` 会让 `torchrun` 报未知参数。
- 第 6 环节的 `chat_cli` 默认是注释掉的，脚本以非交互方式结束；需要对话时手动执行 `python -m scripts.chat_cli`。

leaderboard 的「time」只取第 4 环节的 `total_training_time`。`dev/LOG.md` 2026-03-04 记录 ClimbMix 把 speedrun 从 2h46m 降到 2h01m，leaderboard 第 4 名记录 2.02 小时，两者是同一指标；`README` 写「约 1.5 小时」指整条脚本的运行时间，且未随数据升级更新，属于过期表述。

> [!info] 版本说明
> `runs/speedrun.sh` 的注释仍写「d24 model (slightly undertrained to beat GPT-2 => decrease data:params ratio from compute optimal 10.5 (default) to 8)」，`README` 写 GPT-2 能力约在 depth 26；当前 `base_train.py` 的默认 ratio 是 12，leaderboard 的 ClimbMix 记录是 d24、2.02 小时。三处文本分属不同时间点，引用时以 `base_train.py` 的默认值与 `dev/LOG.md` 的数字为准。

### 步骤 2 `base_train.py` 的启动顺序

从进程启动到第一个训练步，`scripts/base_train.py` 依次执行 14 个阶段。顺序不是随意的，每一步都为下一步准备状态。

1. 设置 `PYTORCH_ALLOC_CONF=expandable_segments:True`，打印 banner。前者减少显存碎片，后者只是日志。
2. 解析 CLI。默认值本身就是一套配置：`--depth=20`、`--target-param-data-ratio=12`、`--device-batch-size=32`、`--warmup-steps=40`、`--warmdown-ratio=0.65`。
3. `compute_init(device_type)`：设置种子 42、CUDA 的 tf32、初始化 NCCL 进程组、选定 `device`。返回 `ddp, rank, local_rank, world_size, device`。
4. `get_tokenizer()`、`get_token_bytes()`、`vocab_size`。分词器决定词表大小，进而决定 `lm_head` 与 `wte` 的形状，必须在建模型之前完成。
5. `build_model_meta(depth)`：在 `torch.device("meta")` 上下文中构造 `GPT`，只得到形状与 dtype。
6. `model.to_empty(device=device)`：在目标设备上分配存储，内容为未初始化的垃圾值。
7. `model.init_weights()`：写入真实初始化值。这一步之前模型不可用。
8. 可选 resume：`load_checkpoint(checkpoint_dir, args.resume_from_step, device, load_optimizer=True, rank=ddp_rank)`，`model.load_state_dict(model_data, strict=True, assign=True)`，随即 `del model_data` 释放内存。优化器状态在步骤 12 中加载。
9. 可选 fp8：`convert_to_float8_training` 把满足条件的 `nn.Linear` 换成 `Float8Linear`。必须在 `torch.compile` 之前，否则编译图与模块类型不匹配。
10. `orig_model = model`，`model = torch.compile(model, dynamic=False)`。保留未编译模型用于保存与评测，因为评测输入形状会变化。
11. 缩放律推导：`num_scaling_params`、`estimate_flops`、`target_tokens`、`D_REF`、`B_total`、`batch_lr_scale`、`weight_decay_scaled`。全部只依赖参数量与 ratio，不依赖数据。
12. `setup_optimizer`：按参数形状分组，Muon 组按 `(rows, cols)` 堆叠，AdamW 组按角色分组；随后可选加载优化器状态。
13. GradScaler：仅当 `COMPUTE_DTYPE == torch.float16` 时创建，bf16 与 fp32 为 `None`。
14. 构建 dataloader 并 `next(train_loader)` 预取第一批；计算 `num_iterations` 与总 token 数；定义三个调度器；进入循环。

`num_iterations` 的优先级写在代码里：`--num-iterations` > `--target-flops` > `--target-param-data-ratio`。三者都未给出时 `assert args.num_iterations > 0 or args.target_param_data_ratio > 0 or args.target_flops > 0` 失败。

### 步骤 3 meta device 的 footgun

`GPT.__init__` 的运行上下文是 meta device，源码在类定义处直接警告：

```python
def __init__(self, config, pad_vocab_size_to=64):
    """
    NOTE a major footgun: this __init__ function runs in meta device context (!!)
    Therefore, any calculations inside here are shapes and dtypes only, no actual data.
    => We actually initialize all data (parameters, buffers, etc.) in init_weights() instead.
    """
```

具体后果有三条：

1. `__init__` 里写的 `torch.ones`、`torch.zeros`、`normal_` 都只会得到 meta 张量，没有存储。`resid_lambdas = nn.Parameter(torch.ones(config.n_layer))` 在 meta 上下文中只是一个形状为 `(n_layer,)` 的空壳，真实值在 `init_weights` 中重新写入。
2. `to_empty` 之后参数是垃圾值。若跳过 `init_weights` 直接训练，前几步的损失会是 NaN 或远离 $\ln V$；这个错误不会在形状检查中暴露。
3. `checkpoint_manager.build_model` 也重复同一套流程：meta 建模型、`to_empty`、`init_weights`、再 `load_state_dict`。先 init 再 load 看似多余，实际是为了让 rotary embedding 等非持久 buffer 有真实值，因为 `persistent=False` 的 buffer 不在 checkpoint 中。

`dev/LOG.md` 2026-01-11 把这条记为「Meta Device Footgun」，并说明当时新增的 per-layer 标量参数正是踩到了这一点。

另一个相关细节是 `torch.compile` 的位置：编译发生在 `init_weights` 与 fp8 转换之后。若在编译后再把线性层替换为 `Float8Linear`，已编译的图仍指向旧的 `nn.Linear`，会触发重编译或直接报错。

### 步骤 4 梯度累积的计算

总批大小由缩放律给出，单卡显存只能容纳较小的 `device_batch_size`，两者之差由梯度累积补足：

```python
tokens_per_fwdbwd = args.device_batch_size * args.max_seq_len
world_tokens_per_fwdbwd = tokens_per_fwdbwd * ddp_world_size
assert total_batch_size % world_tokens_per_fwdbwd == 0
grad_accum_steps = total_batch_size // world_tokens_per_fwdbwd
```

对 speedrun 的 d24：$B_{\text{dev}}=16$、$T=2048$、$W=8$，故每次前向反向消费 $16\times2048\times8=262{,}144$ token；$B_{\text{total}}=1{,}048{,}576$，所以 $A=4$。一步训练由 4 次前向反向与 1 次优化器更新组成。

三个实现细节：

- 损失在反传前除以 `grad_accum_steps`：`loss = loss / grad_accum_steps`。因为 `backward()` 累加梯度而不是求平均，不除会让梯度放大 $A$ 倍。
- 数据预取在最后一次反传之后：`x, y, dataloader_state_dict = next(train_loader)` 位于 micro-step 循环内，下一批的 CPU 准备与 GPU 计算重叠。
- `assert` 要求整除。$B_{\text{total}}$ 是 2 的幂，$B_{\text{dev}}\cdot T\cdot W$ 也是 2 的幂，只要 $B_{\text{dev}}\le B_{\text{total}}/(T\cdot W)$ 就成立。d24 的上限是 $1{,}048{,}576/16{,}384=64$，取 16 有 4 倍余量。

`dev/LEADERBOARD.md` 给出的经验值是 $B_{\text{dev}}=32$（8 卡时为 524,288 token，正是 d12 的参考批大小）；d24 与 d26 因显存不足降到 16，脚本自动用累积补偿。

### 步骤 5 MFU、tok/s 与 ETA 的公式

训练循环末尾用四个量刻画吞吐：

$$
\text{tok/s}=\frac{B_{\text{total}}}{\Delta t},\qquad
\text{FLOPs/s}=\frac{C_{\text{token}}\cdot B_{\text{total}}}{\Delta t},\qquad
\text{MFU}=100\cdot\frac{\text{FLOPs/s}}{P_{\text{peak}}\cdot W},\qquad
\text{ETA}=\frac{N-\text{step}}{\text{total\_time}/(\text{step}-10)}.
$$

其中 $C_{\text{token}}$ 是每 token 的前向加反向 FLOPs，由 `model.estimate_flops()` 给出：

$$
C_{\text{token}}=6\cdot N_{\text{matmul}}+12\sum_{\ell} h\cdot q\cdot \min(w_\ell,T),
$$

$N_{\text{matmul}}$ 是所有 `Linear` 权重元素数之和，$h$ 为头数，$q$ 为每头维度，$w_\ell$ 为第 $\ell$ 层的窗口大小。系数 6 来自每参数前向 2 FLOPs、反向 4 FLOPs。

对 d24 手算：$N_{\text{scaling}}=729{,}810{,}624$，$N_{\text{matmul}}$ 与之相差极小，故 $6N\approx4.379\times10^{9}$。按 `_compute_window_sizes` 的实际算式，$T=2048$ 时短窗口为 $512$（源码注释写作 768，与算式不一致，以代码为准），24 层中 18 层窗口 512、6 层窗口 2048，注意力项为

$$
12\cdot12\cdot128\cdot(18\cdot512+6\cdot2048)\approx3.96\times10^{8},
$$

合计 $C_{\text{token}}\approx4.78\times10^{9}$。于是每步 FLOPs 为 $4.78\times10^{9}\times1{,}048{,}576\approx5.01\times10^{15}$。H100 的 bf16 峰值取 `get_peak_flops` 的 $989\times10^{12}$，8 卡合计 $7.912\times10^{15}$，故

$$
\text{MFU}=\frac{5.01\times10^{15}/\Delta t}{7.912\times10^{15}}\cdot100\%=\frac{63.3\%}{\Delta t\ [\text{s}]}.
$$

这个式子说明 MFU 与每步耗时一一对应：$\Delta t=1.0$ s 时 MFU 上限 63.3%，$\Delta t=1.306$ s 时约 48.5%。leaderboard 记录 ClimbMix 配置为 2.02 小时、5568 步，反推平均 $\Delta t\approx1.306$ s、吞吐约 803k token/s、MFU 约 48.5%。这是反推值，不是脚本打印值；实际运行会因 `--fp8`、FA3 与硬件差异而偏离。

`total_training_time` 只累计 `step > 10` 的步，ETA 也以 `step - 10` 为分母。原因是前 10 步包含 `torch.compile` 编译、cuBLAS autotune 与显存分配，耗时远高于稳态；把它们计入会让 ETA 严重偏高。日志中的 `dt` 由 `torch.cuda.synchronize()` 前后夹住，因而是真实墙钟而非异步排队时间。

### 步骤 6 GC 管理与显存

训练循环在第一步之后做三件事：

```python
if first_step_of_run:
    gc.collect()   # 清理初始化阶段产生的大量垃圾
    gc.freeze()    # 把当前存活对象移出 GC 扫描范围
    gc.disable()   # 关闭自动 GC
elif step % 5000 == 0:
    gc.collect()   # 每 5000 步手动回收一次
```

动机写在注释里：Python 的循环垃圾回收会周期性地扫描容器对象，单次约 500 ms，而清理出的对象很少。训练循环本身几乎不产生循环引用，因此把 GC 关闭、只保留每 5000 步一次手动回收，可以消除这些停顿。

`gc.freeze()` 是这一步的关键：它把当下所有对象移到「永久代」，之后的 `gc.collect()` 不再扫描它们。若只 `disable()` 不 `freeze()`，每 5000 步的 `collect()` 仍会扫描初始化阶段创建的全部对象，停顿依旧。

显存方面，脚本在结束时打印 `torch.cuda.max_memory_allocated()`。它统计的是分配器峰值，不含 CUDA 上下文与碎片；排查 OOM 时应同时看 `nvidia-smi` 与 `PYTORCH_ALLOC_CONF=expandable_segments:True` 是否生效。

### 步骤 7 `runcpu.sh` 的最小配置与为什么结果很弱

`runs/runcpu.sh` 把模型缩到能在 CPU 上几十分钟跑完：

| 参数 | 取值 | 作用 |
|---|---|---|
| `--depth` | 6 | 6 层，`model_dim=384` |
| `--head-dim` | 64 | 6 头，与默认 128 不同 |
| `--window-pattern` | L | SDPA 不支持滑动窗口，只能用全上下文 |
| `--max-seq-len` | 512 | 上下文降到 512 |
| `--device-batch-size` | 32 | 单进程，无累积 |
| `--total-batch-size` | 16384 | 手工指定，非自动推导 |
| `--num-iterations` | 5000 | 共 $5000\times16384=8.19\times10^{7}$ token |
| `--core-metric-every` | -1 | 不跑 CORE |

按该配置，$N_{\text{scaling}}\approx2.32\times10^{7}$，训练 token 与缩放参数之比约 3.5，远低于 d12 的 8；上下文只有 512，且 `--core-metric-every=-1` 表示训练中完全不做能力评测。`base_eval` 也只跑 `--split-tokens=16384`、`--max-per-task=16` 的抽样。因此它验证的是代码路径：分词器、dataloader、`MuonAdamW` 优化器、SFT、CLI 都能跑通，但模型能力没有参考价值。脚本注释本身写明「You will not get far on your Macbook」。

它仍然有用：在无 GPU 的环境中，它是唯一能在半小时量级验证整条流水线的方式；`tok_train --max-chars=2000000000` 在该脚本中约 34 秒（M3 Max 注释），说明分词器不是瓶颈。

### 步骤 8 d12 短跑的命令与量级

`README` 推荐的快速实验规模是 d12，用于验证改动是否有效。完整命令：

```bash
export NANOCHAT_BASE_DIR="$HOME/.cache/nanochat"
export OMP_NUM_THREADS=1
source .venv/bin/activate

torchrun --standalone --nproc_per_node=8 -m scripts.base_train -- \
    --depth=12 \
    --run="d12" \
    --model-tag="d12" \
    --core-metric-every=999999 \
    --sample-every=-1 \
    --save-every=-1
```

推导其规模：$N_{\text{scaling}}=110{,}100{,}912$，命令未传 `--target-param-data-ratio`，取默认值 12，故 $D=12\times N=1{,}321{,}210{,}944$；$D_{\text{REF}}$ 用同一默认值算得，与 $D$ 相同，故 $B_{\text{total}}$ 落在参考值 $2^{19}=524{,}288$；`num_iterations = 1{,}321{,}210{,}944 // 524{,}288 = 2520`。默认 $B_{\text{dev}}=32$ 时每次前向反向正好 524,288 token，$A=1$，不需要累积。若显式加 `--target-param-data-ratio=8`，则 $D=880{,}807{,}296$、1680 步，产物文件名也随之改变。

时间与显存：$C_{\text{token}}\approx7.60\times10^{8}$，每步 $3.98\times10^{14}$ FLOPs，总计约 $1.0\times10^{18}$ FLOPs。README 称该规模适合约 5 分钟的迭代，反推平均每步约 0.18 秒、吞吐约 2.9M token/s。显存的主要项是 logits：$32\times2048\times32768$ 个 bf16 元素约 4.0 GiB，但 `logits.float()` 与 softcap 会产生同尺寸 fp32 中间量，峰值高于 4 GiB；其余为激活、fp32 主权重与优化器状态；80 GB 卡无需降低 `--device-batch-size`，显存更小的卡按 README 从 32 降到 16、8、4。

`--core-metric-every=999999` 是一个技巧：CORE 只在 `last_step` 时触发，而 `999999` 保证中途不触发。`--sample-every=-1` 与 `--save-every=-1` 关闭采样与中间保存，缩短迭代周期。这三项只影响评测与 I/O，不改变训练结果。

### 步骤 9 训练循环的触发顺序

循环体每步的执行顺序固定，理解它才能读懂日志：

1. `last_step = step == num_iterations`。循环执行 $N+1$ 次，最后一次只做评测与保存。
2. `flops_so_far = C_{\text{token}}\cdot B_{\text{total}}\cdot\text{step}`。
3. 若 `eval_every > 0` 且到达间隔或最后一步：切 `model.eval()`，重建验证 loader，`evaluate_bpb`，记录 `val_bpb` 与 `min_val_bpb`，切回 `train()`。
4. 若 `core_metric_every > 0` 且到达间隔：用 `orig_model` 与 `disable_fp8` 跑 CORE，记录 22 项任务与均值。
5. 若 `sample_every > 0` 且是主进程：用 `Engine(orig_model)` 对 7 个固定提示做贪心采样，打印 16 个 token。提示包含「法国首都」「金的化学符号」等，用于肉眼判断模型是否退化。
6. 若 `save_every` 命中或最后一步：`save_checkpoint` 写模型、优化器分片与 meta。
7. `if last_step: break`。
8. micro-step 循环：前向、除以累积步数、反传、预取下一批。
9. 读取 `lrm`、`muon_momentum`、`muon_weight_decay`，写入各参数组。
10. 若启用 GradScaler：`unscale_`、跨 rank 同步 `found_inf`、`scaler.step`、`scaler.update`；否则 `optimizer.step()`。
11. `model.zero_grad(set_to_none=True)`；同步并计时；计算 EMA 损失、tok/s、MFU、ETA；每 100 步写 wandb。
12. 更新 `step`，执行 GC 管理。

评测与采样使用 `orig_model` 而不是编译后的 `model`，原因是第 3 步的注释：评测输入的形状会变化，编译模型会反复重编译。`disable_fp8` 上下文在评测期间把 `Float8Linear` 换回自定义 `Linear` 并共享权重，避免 FP8 的量化误差影响指标。

### 在 nanochat 中的落地

| 位置 | 作用 | 去掉或写错会怎样 |
|---|---|---|
| `runs/speedrun.sh` | 端到端流水线，唯一的官方复现入口 | 缺少 `wait` 会让预训练在数据未下完时启动 |
| `scripts/base_train.py:build_model_meta` | meta device 建模型，`model_dim` 向上取整到 `head_dim` | 不取整会使 `n_embd % n_head != 0`，注意力断言失败 |
| `base_train.py` 的 `to_empty` + `init_weights` | 分配存储并写入真实初始化 | 跳过 `init_weights` 得到垃圾权重，损失为 NaN |
| `base_train.py` 的 fp8 转换与 `disable_fp8` | 训练用 FP8，评测用 BF16 | 评测仍用 FP8 会让 CORE 与 bpb 偏低且不可复现 |
| `base_train.py` 的 `torch.compile(dynamic=False)` | 固定形状编译，最大化吞吐 | `dynamic=True` 会保留动态分支，吞吐下降 |
| `base_train.py` 的缩放律段 | 从 depth 推导 $D$、$B_{\text{total}}$、LR 与 WD | 手工设错 `--total-batch-size` 会破坏整除断言或改变最优配置 |
| `base_train.py` 的 `grad_accum_steps` | 用累积补足总批 | 损失不除以 $A$ 会使梯度放大，等效学习率乘以 $A$ |
| `base_train.py` 的 GC 段 | 消除约 500 ms 的 GC 停顿 | 不 `freeze` 则每 5000 步的回收仍会扫描全部对象 |
| `runs/runcpu.sh` | 无 GPU 环境的冒烟路径 | 把它当作能力评测会得到无意义的 CORE |
| `scripts/base_eval.py` | CORE、bpb、采样三项评测，写 CSV | 抽样过小（`--max-per-task=16`）时 CORE 方差大 |

## 关键直觉

> [!tip] 启动过程是一个状态机，每个状态转换都有代价：meta 到真实存储需要 `to_empty` 与 `init_weights`，bf16 到 FP8 需要模块替换，eager 到 compiled 需要固定形状。顺序错误的代价不是报错而是静默错误或显存翻倍，因此这五步的次序应当作为整体记忆，而不是当作可调参数。同样，speedrun 的时间只统计训练步，所以「脚本 2.5 小时」与「leaderboard 2.02 小时」的差额是环境、评测与 SFT，不是测量误差。该表述与步骤 2 的启动顺序、步骤 5 的 `total_training_time` 定义一一对应。

## 例子与代码

下面的脚本复算 d12 与 d24 的关键量，不依赖 torch，可直接运行。它按 `num_scaling_params` 的定义逐项计数，再套用 `base_train.py` 的公式。

```python
import math

V = 32768

def scaling_params(depth, aspect=64, head_dim=128):
    base = depth * aspect
    d = ((base + head_dim - 1) // head_dim) * head_dim
    h = d // head_dim
    n_ve = sum(1 for i in range(depth) if i % 2 == (depth - 1) % 2)
    matrices = depth * (4 * d * d + 2 * d * 4 * d) + n_ve * 12 * h
    return matrices + d * V, d, h

def plan(depth, ratio=8, bb=16, T=2048, world=8):
    N, d, h = scaling_params(depth)
    D = int(ratio * N)
    N_ref, _, _ = scaling_params(12)
    D_ref = ratio * N_ref
    B = 2 ** round(math.log2(2**19 * (D / D_ref) ** 0.383))   # Power Lines 0.383
    lr_scale = (B / 2**19) ** 0.5
    wd = 0.28 * lr_scale * (D_ref / D)
    iters = D // B
    A = B // (bb * T * world)
    short_w = -(-T // 4 // 128) * 128
    attn = sum(12 * h * (d // h) * min(T if "SSSL"[i % 4] == "L" else short_w, T)
               for i in range(depth))
    c_tok = 6 * N + attn
    print(f"d{depth:2d} N={N:>12,} D={D:>13,} B={B:>9,} A={A} iters={iters:>5,} "
          f"lr_scale={lr_scale:.4f} wd={wd:.4f} C_tok={c_tok/1e9:.3f}e9 "
          f"MFU={100*c_tok*B/(989e12*world):.4f}/dt")

plan(12, bb=32)   # d12 短跑，README 未指定 device batch，取默认 32
plan(24, bb=16)   # speedrun
```

预期输出：

```text
d12 N= 110,100,912 D=1,321,210,944 B=  524,288 A=1 iters=2,520 lr_scale=1.0000 wd=0.2800 C_tok=0.760e9 MFU=5.0341/dt
d24 N= 729,810,624 D=5,838,484,992 B=1,048,576 A=4 iters=5,568 lr_scale=1.4142 wd=0.0597 C_tok=4.775e9 MFU=63.2860/dt
```

打印的 `MFU` 一项是「百分比每秒」：把当步 $\Delta t$ 代入即得百分比。d24 在 $\Delta t=1.306$ s 时为 48.5%，d12 在 $\Delta t\approx0.18$ s 时为 28.0%。该输出同时说明：d24 在 `--target-param-data-ratio=8` 下 $B_{\text{total}}$ 自动落在 $2^{20}$，与 `dev/LOG.md` 2026-02-05 的表格一致；上面的 d12 命令使用默认 ratio 12，故为 2520 步。d12 的 $A=1$ 只在 $B_{\text{dev}}=32$ 时成立，改成 16 则 $A=2$，总批不变。

下面的 d12 命令可直接复制，用于验证本机环境。它关闭 CORE 中途评测、采样与中间保存，只保留最后一次评测。

```bash
export NANOCHAT_BASE_DIR="$HOME/.cache/nanochat"
export OMP_NUM_THREADS=1
cd /path/to/nanochat && source .venv/bin/activate

torchrun --standalone --nproc_per_node=8 -m scripts.base_train -- \
    --depth=12 --run=d12 --model-tag=d12 \
    --core-metric-every=999999 --sample-every=-1 --save-every=-1

torchrun --standalone --nproc_per_node=8 -m scripts.base_eval -- \
    --model-tag=d12 --device-batch-size=32 --eval=core,bpb
```

预期产物为 `base_checkpoints/d12/model_002520.pt` 与 `base_eval/base_model_002520.csv`，日志末行打印 `Minimum validation bpb` 与 `Total training time`。若加 `--target-param-data-ratio=8`，则步数与文件名分别变为 1680 与 `model_001680.pt`。若显存不足，先把 `--device-batch-size` 降到 16；此时 $A=2$，总批不变，训练时间约翻倍。

下面是一行训练日志的字段说明，格式取自 `base_train.py` 的 `print0`：

```text
step 00020/05568 (0.36%) | loss: 10.123456 | lrm: 0.53 | dt: 1306.00ms |
tok/sec: 802,900 | bf16_mfu: 48.50 | epoch: 1 pq: 0 rg: 240 | total time: 0.22m | eta: 120.8m
```

`loss` 是去偏 EMA，`lrm` 是学习率乘子，`dt` 是单步墙钟，`tok/sec` 与 `bf16_mfu` 由步骤 5 的公式得到，`epoch: 1 pq: 0 rg: 240` 是 dataloader 状态，`eta` 由剩余步数乘平均步时得到。该例取第 20 步：`total time` 只累计第 11 至 20 步，共 10 步约 13.06 秒，即 0.22 分钟；ETA 为 $(5568-20)\times1.306$ 秒约 120.8 分钟。前 10 步不计入，因为编译与 autotune 使其 `dt` 明显偏高。

## 易错点

> [!warning] 以下六条都对应 `base_train.py` 中可核对的行为。
>
> 1. 在 meta device 上直接给参数赋值。`model.resid_lambdas.data.fill_(1.0)` 在 meta 张量上无效，必须在 `init_weights()` 内写真实值。
> 2. 先 `torch.compile` 再转换 FP8。模块类型变化会让已编译图失效，表现为重编译或 `Float8Linear` 未被调用。
> 3. 把 `--device-batch-size` 当成总批。它只影响单卡显存与累积步数；总批由 ratio 推导，改它不改变优化目标。
> 4. 只给 `--num-iterations` 而不给 `--total-batch-size`，然后手工调 LR。此时 LR 仍按缩放律计算，与实际步数不匹配。
> 5. 把 speedrun 的总墙钟当作 leaderboard 时间。后者只统计训练步，且排除前 10 步；两者相差初始化、数据下载、评测与 SFT。
> 6. 相信脚本注释里的历史数字。`runs/speedrun.sh` 写「d24 model (slightly undertrained to beat GPT-2 => decrease data:params ratio from compute optimal 10.5 (default) to 8)」，而 `base_train.py` 当前默认是 12；`README` 又写 GPT-2 能力约在 d26。注释与代码不一致时以代码为准。

## 关联笔记

- 前置：[[数据加载器dataloader]] —— 训练循环消费的 `x, y, state_dict` 来自该 loader，续训状态随 checkpoint 保存。
- 前置：[[缩放定律与模型深度]] —— 步骤 2 的 11 号阶段全部由该篇的缩放律决定。
- 后续：[[学习率与warmup-warmdown]] —— 循环第 9 步写入的 `lrm`、动量与权重衰减来自三个调度函数。
- 后续：[[检查点与恢复]] —— `save_checkpoint` 的三个产物与 resume 的加载顺序。
- 跨库：[[从零实现小型GPT指南]] —— 通用训练循环见该篇，本篇只讲 nanochat 的启动顺序、缩放律与吞吐指标；两者的 warmup 与累积语义相同。

## 达标检测

- [ ] 能按顺序复述 `base_train.py` 的 14 个启动阶段，并指出 fp8 转换与 `torch.compile` 的先后约束。
- [ ] 能解释 meta device 上 `torch.ones` 为何不产生真实值，以及 `to_empty` 与 `init_weights` 各自的作用。
- [ ] 给定 depth、ratio、device batch、世界大小与 $T$，能算出 $B_{\text{total}}$、$A$、`num_iterations` 与总 token 数。
- [ ] 能写出 tok/s、FLOPs/s、MFU、ETA 四个公式，并说明 `total_training_time` 为何跳过前 10 步。
- [ ] 能说明 `runcpu.sh` 的配置为什么只能验证代码路径，并给出至少两个定量理由。
- [ ] 能写出 d12 短跑命令，并预测其产物文件名与大约的训练步数。
- [ ] 能解释评测与采样为何使用 `orig_model` 与 `disable_fp8`。
- [ ] 能指出 `speedrun.sh` 注释中至少一处与当前代码不一致的数字。

## 参考来源

- Karpathy, *nanochat*（commit `92d63d4`），`scripts/base_train.py` 与 `runs/speedrun.sh` —— 对应本篇的启动顺序、梯度累积、吞吐指标与六个环节。
- Karpathy, *nanochat* `dev/LEADERBOARD.md` —— 对应「time to GPT-2」只统计训练步的定义，以及 $B_{\text{dev}}=32$ 的经验值与 2.02 小时的记录。
- Karpathy, *nanochat* `dev/LOG.md`（2026-02-05、2026-01-11）—— 对应自动批大小与 d12 参考点，以及 meta device footgun。
- Chowdhery et al., *PaLM: Scaling Language Modeling with Pathways*（arXiv:2204.02311）—— 对应 $6N+12hqT$ 的 FLOPs 估算与 MFU 指标，`estimate_flops` 的注释直接引用该文。
- Bergsma et al., *Power Laws for Batch Size, Model Size, and Training Horizon*（arXiv:2505.13738）—— 对应 $B_{\text{opt}}\propto D^{0.383}$ 的批大小推导，即步骤 4 的裁剪系数来源。
