---
tags: [nanochat, repro, speedrun]
阶段: 10-复现与实验
难度: ★★★
created: 2026-10-22
related: "[[本地环境搭建]], [[用--depth调参]], [[训练脚本与speedrun]], [[检查点与恢复]]"
---

# 跑通 speedrun 脚本

## 定义

**speedrun 脚本**（`runs/speedrun.sh`）是一条从空白 8×H100 节点开始、以可对话的 GPT-2 级模型结束的 shell 流水线。它由环境、分词器、基座预训练与评测、SFT 与对话评测四段组成，共九个实际执行的环节：环境准备、下载 8 个分片、后台补齐 170 个分片、训练分词器、评测分词器、预训练、基座评测、SFT、对话评测。脚本头部的注释给出过一次运行的预期时长。

本篇使用的符号与术语：

- `$B_{\text{dev}}$`：单卡批大小，脚本取 16。
- `$B_{\text{total}}$`：一次优化器更新消费的 token 数，由缩放律自动推出，d24 下为 $2^{20}=1{,}048{,}576$。
- `$T$`：上下文长度，默认 2048。
- `$W$`：世界大小，脚本为 8。
- `$A$`：梯度累积步数，$A=B_{\text{total}}/(B_{\text{dev}}\cdot T\cdot W)=4$。
- `$N$`：缩放参数，等于 `transformer_matrices + lm_head`，d24 下为 729,810,624。
- `$D$`：训练 token 数，$D=\text{ratio}\times N$，ratio 取 8，得 5,838,484,992。
- **run name**：wandb 的运行名，由环境变量 `WANDB_RUN` 传入；取 `dummy` 时不写 wandb。
- **产物**（artifact）：脚本每一步写入磁盘的文件或目录，是判断该步是否真正完成的唯一依据。
- **检查点清单**：一次完整运行结束后应当存在的全部文件集合，用于验证没有漏跑阶段。

## 为什么重要

它是唯一被维护的官方复现路径。`runs/speedrun.sh` 的每次改动都对应 leaderboard 上的一次提交，因此读这个脚本等于读当前状态的最佳配置，而不是一份示例。README 说明该脚本「always reflects the reference way」，其它文档中的命令与数字都以它为准。

它把整本书的抽象约定落成一条可执行命令。05 阶段讲的缩放律、检查点格式、分布式优化器，06 阶段讲的 SFT 数据混合与热启动，08 阶段讲的 CORE 与 ChatCORE，在这条命令序列中各出现一次；不跑通它，前面所有推导都停留在纸面。

它定义了「完成」的判据。脚本的最后一行 `chat_cli` 是注释掉的，因此脚本本身以非交互方式结束；真正的完成判据是三个层次的检查：文件存在、数值正确、模型能回答。缺少任一层，都可能出现「脚本退出码为 0 但模型不可用」的情形。

在全书中的位置：前置为 [[本地环境搭建]]（依赖与目录）与 [[训练脚本与speedrun]]（训练循环内部机制）；后续为 [[用--depth调参]]（改变模型规模）与 [[常见问题踩坑]]（故障定位）。懂原理对应「解释每个参数为何是这个值」，能复现对应「在自有硬件上按比例缩减并跑通」，懂工程对应「预测每一步的时间与显存并验证」。

## 原理与推导

### 1 四段九个环节

脚本按注释分成四段，加上头部的环境准备，实际执行的命令如下。表中耗时是按 8×H100 与仓库记录推算的量级，显存列只对训练与评测阶段有意义。

| # | 段 | 命令 | 产物（默认 `~/.cache/nanochat`） | 耗时量级 | 显存峰值 |
|---|---|---|---|---|---|
| 1 | 环境 | `uv venv`、`uv sync --extra gpu`、`source .venv/bin/activate` | `.venv/` | 2–10 分钟 | 无 |
| 2 | 数据 | `python -m nanochat.dataset -n 8` | `base_data_climbmix/shard_0000*.parquet`，9 个 | 1–5 分钟 | 无 |
| 3 | 数据 | `python -m nanochat.dataset -n 170 &` | 追加到 171 个分片 | 10–40 分钟，与下两步重叠 | 无 |
| 4 | 分词器 | `python -m scripts.tok_train` | `tokenizer/tokenizer.pkl`、`tokenizer/token_bytes.pt` | 1–5 分钟 | 数 GB |
| 5 | 分词器 | `python -m scripts.tok_eval` | 终端输出压缩率对比，无文件 | 1–2 分钟 | 数 GB |
| 6 | 预训练 | `torchrun --standalone --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`、`meta_005568.json`、`optim_005568_rank{0..7}.pt` | 1.65–2.02 小时 | 45–65 GB |
| 7 | 评测 | `torchrun --standalone --nproc_per_node=8 -m scripts.base_eval -- --device-batch-size=16` | `base_eval/base_model_005568.csv`、`eval_bundle/` | 10–30 分钟 | 30–50 GB |
| 8 | SFT | `torchrun --standalone --nproc_per_node=8 -m scripts.chat_sft -- --run=$WANDB_RUN` | `chatsft_checkpoints/d24/model_*.pt` | 30–60 分钟 | 40–60 GB |
| 9 | 对话评测 | `torchrun --standalone --nproc_per_node=8 -m scripts.chat_eval -- -i sft` | 终端输出 ChatCORE | 10–30 分钟 | 30–50 GB |

只有第 6 步的 1.65 小时与 2.02 小时来自仓库记录（README leaderboard 第 6 行与 `dev/LOG.md` 2026-03-04），其余耗时是按脚本注释与吞吐反推的量级。脚本头部写「approximately 1.5 hours」，指的是整条流水线在理想网络与空闲节点上的运行时间；后续数据升级与评测项变化会使其偏长。

> [!info] 版本说明
> 当前 `runs/speedrun.sh` 的第 6 步是 `--depth=24 --target-param-data-ratio=8 --device-batch-size=16 --fp8`。2025 年 10 月的版本用 d20、FineWeb-EDU、ratio 10.5，README 目录树里仍留着 `speedrun.sh # Train the ~$100 nanochat d20` 这一行旧注释；README 正文另有一处写「GPT-2 capability 约等于 depth 26」。三处文本属于不同时间点，以脚本与 `base_train.py` 的实际取值为准。

### 2 环境段逐行

```bash
export OMP_NUM_THREADS=1
export NANOCHAT_BASE_DIR="$HOME/.cache/nanochat"
mkdir -p $NANOCHAT_BASE_DIR
```

`OMP_NUM_THREADS=1` 的作用是限制每个进程的 OpenMP 线程数。8 个训练进程若各自再开满 CPU 线程，分词与数据准备会互相抢占，实际吞吐下降；设为 1 后每个 rank 只用一个线程，把 CPU 留给数据加载的并行度控制。

`NANOCHAT_BASE_DIR` 显式导出而不是依赖默认值，使脚本在任何用户下都把产物写到固定位置，也让后续命令无需重复传参。`mkdir -p` 与 `get_base_dir()` 内部的 `makedirs` 重复，属于防御性写法。

```bash
command -v uv &> /dev/null || curl -LsSf https://astral.sh/uv/install.sh | sh
[ -d ".venv" ] || uv venv
uv sync --extra gpu
source .venv/bin/activate
```

四行分别对应「装工具」「建环境」「装依赖」「激活」。第三行没有 `--group dev`，因此这条流水线装出的环境里没有 pytest；要跑测试必须手工补 `--group dev`。第四行不可省略：`torchrun` 用 PATH 中的 python 启动子进程，未激活时会用系统 python 并报 `No module named nanochat`。

### 3 wandb 段

```bash
if [ -z "$WANDB_RUN" ]; then
    WANDB_RUN=dummy
fi
```

`dummy` 是 `base_train.py` 与 `chat_sft.py` 共同识别的特殊值：`use_dummy_wandb = args.run == "dummy" or not master_process`，为真时使用 `DummyWandb`，其 `log` 与 `finish` 都是空实现。因此不设该变量时脚本不联网、不需要账号。

启用 wandb 需要两步：先 `wandb login`（或设置 `WANDB_API_KEY`），再用 `WANDB_RUN=<名字>` 启动脚本。三个训练脚本写入不同的项目名：

| 脚本 | 项目名 | 触发条件 |
|---|---|---|
| `scripts/base_train.py` | `nanochat` | `--run` 不是 dummy 且是主进程 |
| `scripts/chat_sft.py` | `nanochat-sft` | 同上 |
| `scripts/chat_rl.py` | `nanochat-rl` | 同上 |
| `scripts/base_eval.py` | 无 | 该脚本没有 `--run` 参数，不写 wandb |

只有主进程（`RANK=0`）初始化 wandb，其余 rank 用 `DummyWandb`，因此一次 8 卡运行只产生一个 run。离线环境可以设 `WANDB_MODE=offline` 把记录写到本地 `wandb/` 目录，之后再 `wandb sync`。

### 4 分词器段逐行

```bash
python -m nanochat.dataset -n 8
python -m nanochat.dataset -n 170 &
DATASET_DOWNLOAD_PID=$!
python -m scripts.tok_train
python -m scripts.tok_eval
```

第一行同步下载 8 个分片。每个分片约 2.5 亿字符，8 个约 20 亿字符，正好覆盖 `tok_train.py` 默认的 `--max-chars=2000000000`。分词器训练只需要这些，因此不必等全部数据。

第二行在后台继续下载到 170 个分片，`&` 使其与分词器训练并行，`$!` 记录进程号供后面 `wait` 使用。为什么要 170 而不是 150：脚本注释写明 GPT-2 级预训练约需 150 个分片，多下 20 个作为余量，避免最后一个 epoch 数据不足而提前重复。数据集总共 6542 个训练分片，170 只是其中很小一部分。

第四行训练词表。默认词表 32768，训练语料截断到 20 亿字符，单文档截断到 10000 字符，这些默认值与 `base_train.py` 的 `GPTConfig.vocab_size` 必须一致。第五行做压缩率对比，会额外加载 gpt2 与 cl100k_base 两个编码，首次运行需要联网下载 tiktoken 的编码文件；它不写任何产物，失败也不影响已训练好的词表。

第 6 步之前有一行容易被忽略的同步：

```bash
echo "Waiting for dataset download to complete..."
wait $DATASET_DOWNLOAD_PID
```

去掉它，预训练可能在分片未下齐时启动。`list_parquet_files` 在 dataloader 构造时一次性列出所有已存在的文件，之后不再重新扫描；若此时只有 40 个分片，整个训练会在这 40 个分片上循环，等效于把数据重复看了四遍，损失曲线看起来正常但能力偏低。

### 5 预训练段逐行

```bash
torchrun --standalone --nproc_per_node=8 -m scripts.base_train -- \
    --depth=24 --target-param-data-ratio=8 --device-batch-size=16 --fp8 --run=$WANDB_RUN
```

`torchrun` 的三个参数：`--standalone` 表示单机，自己拉起 rendezvous 而不需要 `--rdzv_endpoint`；`--nproc_per_node=8` 表示每台机器 8 个进程；`-m scripts.base_train` 表示以模块方式启动，因此工作目录必须是仓库根目录。

`--` 是 shell 与 argparse 之间的分界。`torchrun` 会把 `--` 之后的参数原样传给被启动的脚本；漏掉它，`--depth` 会被 `torchrun` 当作自己的参数并报未知选项。

五个训练参数各自的含义与后果：

- `--depth=24` 决定宽度 1536、头数 12、缩放参数 729,810,624。
- `--target-param-data-ratio=8` 把训练 token 数定为 $8N=5{,}838{,}484{,}992$，比计算最优的低，注释称之为「slightly undertrained to beat GPT-2」。
- `--device-batch-size=16` 是 80 GB 卡上 d24 能容纳的单卡批；累积步数由 $B_{\text{total}}/(16\times2048\times8)=4$ 自动得到。
- `--fp8` 把满足条件的线性层换成 `Float8Linear`，需要计算能力 8.9 以上；在 sm80 的 A100 上会在第一次 FP8 矩阵乘处报错。
- `--run` 决定 wandb 是否启用与运行名。

由前两个参数推导出的量可以直接核对：$B_{\text{total}}$ 由 d12 参考点外推，落在 $2^{20}$；步数为 $5{,}838{,}484{,}992/1{,}048{,}576=5568$；每步 FLOPs 为 $C_{\text{token}}\cdot B_{\text{total}}=4.7752\times10^{9}\times2^{20}\approx5.007\times10^{15}$。

### 6 评测段逐行

```bash
torchrun --standalone --nproc_per_node=8 -m scripts.base_eval -- --device-batch-size=16
```

这里没有 `--model-tag`，`load_model` 会调用 `find_largest_model`，在 `base_checkpoints/` 下按目录名的 `d<数字>` 取最大深度。目录里同时有 d12 与 d24 时它会选 d24；这正是它不传 model-tag 的原因，也埋下了一个易错点：若你只想评 d12，必须显式传 `--model-tag=d12`。

`base_eval.py` 默认执行三项：`core`、`bpb`、`sample`。CORE 首次运行会从 S3 下载评测包并解压到 `eval_bundle/`；bpb 在 train 与 val 两个 split 上各评 `--split-tokens` 个 token，默认 $40\times524288\approx2.1\times10^{7}$；sample 用 7 个固定提示做贪心采样并额外生成 8 条无条件样本。CSV 只由 CORE 产生，路径为 `base_eval/base_model_{step:06d}.csv`，最后一行的第三列是 CORE 值。

### 7 SFT 与对话段

```bash
torchrun --standalone --nproc_per_node=8 -m scripts.chat_sft -- --run=$WANDB_RUN
torchrun --standalone --nproc_per_node=8 -m scripts.chat_eval -- -i sft
# python -m scripts.chat_cli -p "Why is the sky blue?"
```

`chat_sft.py` 不传深度、批大小与学习率，而是从 base 检查点的 meta 继承。继承的六项是 `max_seq_len`、`device_batch_size`、`total_batch_size`、`embedding_lr`、`unembedding_lr`、`matrix_lr`，都有 fallback 值；显式传参会打印 `NOTE: --... overrides pretrained value`。

SFT 的三个关键默认值：`--init-lr-frac=0.8` 把初始学习率设为继承值的 80%；`--warmdown-ratio=0.5` 在最后一半步数线性降到 `--final-lr-frac=0.0`；`--load-optimizer=1` 从 base 检查点加载优化器状态，但只保留动量缓冲，学习率在加载后被重置为 SFT 的新值，代码注释明确说明了原因：预训练的 warmdown 已把学习率降到接近零。

数据混合是 SmolTalk 训练集 460K 条、MMLU 辅助训练集 3 个 epoch 各 100K 条、GSM8K 训练集 4 个 epoch 各 8K 条，合计 792K 条对话。步数不预先固定，`--num-iterations=-1` 表示跑完一个 epoch 即停；每步仍消费 $B_{\text{total}}=1{,}048{,}576$ token，因此实际步数取决于对话的平均长度与打包效率。

`chat_eval -i sft` 的 `-i` 是必填的模型来源，取值 `sft` 或 `rl`；默认跑全部任务，输出 ChatCORE 与各任务分数。`chat_cli` 默认也从 `sft` 加载，带 `-p` 时单轮问答后退出，不带时进入交互模式；`-t` 默认温度 0.6，`-k` 默认 top-k 50。

RL 段不在脚本内：`chatrl_checkpoints/d24` 由 `python -m scripts.chat_rl` 产生，它加载的是 SFT 检查点（`load_model("sft", ...)`），默认 `--num-epochs=1`、每步 16 个样本、每个问题采样 16 次。要得到该目录必须单独跑这一步，`runs/speedrun.sh` 不包含它。

### 8 时间与显存的账

显存可以按五项拆开估算。下表以 d24、$B_{\text{dev}}=16$、$T=2048$、8 卡为条件，单位是 $10^{9}$ 字节；优化器状态已按 ZeRO-2 分片到各 rank。

| 项 | 计算依据 | 量级 |
|---|---|---|
| 参数 | 矩阵与 `lm_head` 为 fp32，`wte` 与 value embeddings 为 bf16 | 4.2 |
| 梯度 | dtype 与参数相同，每个 rank 都是完整副本 | 4.2 |
| 优化器状态 | AdamW 两个矩加 Muon 动量合计约 5.7，按 rank 分 8 份 | 0.7 |
| logits 与其梯度 | $16\times2048\times32768\times2$ 字节，两份 | 4.3 |
| 激活 | 每层注意力的 q/k/v 与投影输出，加 MLP 的 $4d$ 中间量 | 20–30 |
| 合计 | | 33–43 |

这个估算给出两个可检验的结论。第一，单卡批翻到 32 时合计约 76 GB，因此在 80 GB 卡上必须降到 16；第二，FP8 的收益主要在矩阵乘吞吐与临时显存，`dev/LOG.md` 2026-02-02 在 d26 上测得吞吐从 630K tok/s 升到 740K tok/s、显存减少约 9 GB，d24 上的比例相近。实测值通常比上表高 5 至 15 GB，差额来自 CUDA 上下文、cuBLAS 工作区、碎片与激活项估计的偏差。

真实峰值以训练结束时打印的三行为准，其格式如下（数值按同量级运行的典型值给出，实际以本机日志为准）：

```text
Peak memory usage: 48123.45MiB
Total training time: 121.35m
Minimum validation bpb: 0.718043
```

这三个数分别对应 `torch.cuda.max_memory_allocated()`、只统计第 10 步之后的累计墙钟、以及最优验证损失。它们与 `nvidia-smi` 显示的总占用不同：后者包含 CUDA 上下文、cuBLAS 工作区与碎片，通常高出数 GB。

### 9 用 screen 记录日志

脚本头部给出三种启动方式，第二种是标准做法：

```bash
screen -L -Logfile runs/speedrun.log -S speedrun bash runs/speedrun.sh
```

四个参数的作用：`-L` 开启日志，`-Logfile` 指定日志路径（需要 screen 4.06 以上，旧版本只能用默认的 `screenlog.0`），`-S` 给会话命名以便 `screen -r speedrun` 回到会话，最后的命令是会话内执行的进程。

操作序列是固定的：启动后用 `Ctrl-a` 再按 `d` 脱离，此时进程继续运行；`screen -ls` 列出会话与状态；`screen -r speedrun` 重新附着；`tail -f runs/speedrun.log` 在另一个终端跟随日志。日志会包含 ANSI 颜色码，因为它直接复刻终端输出；需要干净文本时应在命令中加 `2>&1 | tee` 而不是依赖 screen。

两个替代方案：`tmux new -s speedrun` 配合 `tmux pipe-pane -o 'cat >> runs/speedrun.log'`；或在无 screen 的镜像里用 `nohup bash runs/speedrun.sh > runs/speedrun.log 2>&1 &`，代价是无法中途交互。

日志的作用不只是留档。每一步的起始与结束都要能在日志中定位：分词器打印训练时间与压缩率，预训练打印参数分组、自动批大小、迭代数与每 100 步的吞吐，评测打印每个任务的 accuracy 与 centered。缺少某一段输出，就说明该段没有真正执行。

### 10 只跑部分阶段

按已有产物决定从哪一段开始，是节省节点时间的常规做法。

| 已有 | 可跳过 | 从哪开始 |
|---|---|---|
| 环境已装好 | 第 1 步 | `source .venv/bin/activate` |
| 数据已下齐 | 第 2、3 步 | `python -m scripts.tok_train` |
| 分词器已训练且词表一致 | 第 4、5 步 | `torchrun ... base_train` |
| base 检查点已存在 | 第 6 步 | `torchrun ... base_eval` |
| base 评测已完成 | 第 7 步 | `torchrun ... chat_sft` |
| SFT 检查点已存在 | 第 8 步 | `torchrun ... chat_eval -i sft` |

三条与「部分运行」相关的参数：

- `--model-tag` 改变检查点目录名。用它给不同实验分目录，避免互相覆盖；评测与 SFT 时用同一个 tag 指回。
- `--step` 指定加载哪一步的检查点，缺省取目录中最大的 step。
- `--eval=core,bpb` 关闭抽样，`--max-per-task=100 --split-tokens=524288` 把评测缩到分钟级，用于快速回归而不是正式报告。

单卡运行只需去掉 `torchrun`，直接 `python -m scripts.base_train -- --depth=24 ...`。此时 `ddp_world_size=1`，累积步数自动变为 32，总批不变，结果按 README 说明「approximately identical」，时间约为 8 倍。这一点的前提是 `total_batch_size` 能被 $B_{\text{dev}}\cdot T\cdot W$ 整除：d24 的 1,048,576 除以 $16\times2048=32{,}768$ 得 32，成立。

### 11 验证结果

验证分三层，逐层排除不同的失败模式。

第一层是文件存在。九个产物缺一即说明对应阶段未完成。第二层是数值自洽。`base_eval` 的 CSV 中，`CORE` 行的值必须等于全部任务行 `Centered` 列的算术平均，这是 `core_metric = sum(centered_results.values()) / len(centered_results)` 的直接后果；`meta_005568.json` 中的 `step` 与文件名一致，`val_bpb` 与日志最后一行一致，`user_config` 中的 `depth` 与目录名一致。第三层是行为正确。CORE 高于 GPT-2 门槛 0.256525 说明基座达到目标；`chat_cli` 能对「法国的首都是」答出 Paris、对「天空为什么是蓝的」给出连贯回答，说明 SFT 生效。

三个层次的判据强度不同。文件存在只证明脚本跑完，数值自洽证明评测没有被跳过或截断，行为正确才证明模型可用。README 记录的当前最好成绩是 1.65 小时、CORE 0.2626，ClimbMix 那次是 2.02 小时、CORE 0.2571；单次 CORE 的标准差约 0.005，因此 0.2571 与阈值 0.256525 的差距在噪声范围内，不能凭一次运行断言「超过 GPT-2」。

### 12 从零到对话的完整序列

把上述各段拼成一条可直接复制的序列，并列出每步应检查的产物。

```bash
export NANOCHAT_BASE_DIR="$HOME/.cache/nanochat"
export OMP_NUM_THREADS=1
export WANDB_RUN=dummy          # 需要曲线时改为具体名字，并先 wandb login

cd ~/nanochat
command -v uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv && uv sync --extra gpu && source .venv/bin/activate

python -m nanochat.dataset -n 8
python -m nanochat.dataset -n 170 &
DATASET_PID=$!
python -m scripts.tok_train
python -m scripts.tok_eval
wait $DATASET_PID

torchrun --standalone --nproc_per_node=8 -m scripts.base_train -- \
    --depth=24 --target-param-data-ratio=8 --device-batch-size=16 --fp8 --run=$WANDB_RUN
torchrun --standalone --nproc_per_node=8 -m scripts.base_eval -- --device-batch-size=16
torchrun --standalone --nproc_per_node=8 -m scripts.chat_sft -- --run=$WANDB_RUN
torchrun --standalone --nproc_per_node=8 -m scripts.chat_eval -- -i sft
python -m scripts.chat_cli -p "Why is the sky blue?"
```

检查点清单如下。左列是产物，右列是它证明的阶段成功。

| 产物 | 证明 |
|---|---|
| `.venv/lib/python3.10/site-packages/torch/` | 依赖安装完成 |
| `base_data_climbmix/shard_00000.parquet` 到 `shard_06542.parquet`，共 171 个 | 数据齐全，含验证分片 |
| `tokenizer/tokenizer.pkl`、`tokenizer/token_bytes.pt` | 分词器训练完成且可算 bpb |
| `base_checkpoints/d24/model_005568.pt` | 预训练到 5568 步 |
| `base_checkpoints/d24/meta_005568.json` | 训练配置与数据游标已落盘 |
| `base_checkpoints/d24/optim_005568_rank0.pt` 到 `rank7.pt`，共 8 个 | 优化器分片齐全，可续训 |
| `base_eval/base_model_005568.csv` | CORE 已评测，末行为总分 |
| `chatsft_checkpoints/d24/model_*.pt` | SFT 完成 |
| 终端 ChatCORE 输出 | 对话能力已评测 |

### 在 nanochat 中的落地

| 位置 | 作用 | 去掉或写错会怎样 |
|---|---|---|
| `runs/speedrun.sh` 的环境段 | 固定 `NANOCHAT_BASE_DIR`、装依赖、激活 | 产物散落或 `torchrun` 找不到模块 |
| `runs/speedrun.sh` 的 `-n 8` 与 `-n 170 &` | 分词器与预训练的数据分工 | 只下 8 个则预训练重复数据 |
| `runs/speedrun.sh` 的 `wait $DATASET_DOWNLOAD_PID` | 预训练前汇合后台下载 | 训练在不足的分片上循环 |
| `runs/speedrun.sh` 的 `--` | 分隔 torchrun 与脚本参数 | `torchrun` 报未知参数 |
| `base_train.py --target-param-data-ratio=8` | 用欠训练换时间 | 用默认 12 则约多 50% 步数 |
| `base_train.py --fp8` | 启用 FP8 线性层 | 无 fp8 时时间增加约 15%，显存增加约 9 GB |
| `base_eval.py` 的 `find_largest_model` | 未给 tag 时按深度取最大 | 同目录多模型时评错对象 |
| `chat_sft.py` 的继承逻辑 | 从 base meta 取批与学习率 | 手工传错批大小破坏整除断言 |
| `chat_sft.py` 的优化器热启动 | 只继承动量，重置学习率 | 不重置则从接近零的学习率开始 |
| `chat_eval.py -i sft` | 指定模型来源 | 缺该参数直接报错 |

## 关键直觉

> [!tip] speedrun 的时间由两件事决定：5568 步与每步 1.3 秒
> 训练时长不是「脚本跑多久」这一个数，而是 $T_{\text{train}}=N_{\text{iter}}\cdot\Delta t$，其中 $N_{\text{iter}}=D/B_{\text{total}}$ 由深度与 ratio 决定，$\Delta t$ 由 MFU 决定。d24 在 ratio 8 下给出 5568 步，在 8×H100 上 $\Delta t\approx1.3$ 秒即约 2 小时；把 ratio 改成 12 会把步数推到约 8352，把 fp8 去掉会把 $\Delta t$ 抬高约 15%。这条乘积关系与第 5 节的推导、第 8 节的显存表共同构成「换硬件或换配置后时间是多少」的唯一算法。

## 例子与代码

### 例 1：校验 CORE CSV 与 meta 的一致性

```python
# verify_run.py —— 只依赖标准库；有真实 CSV 时校验真实文件，否则构造一个同格式的示例
import os
import tempfile

base = os.environ.get("NANOCHAT_BASE_DIR", os.path.expanduser("~/.cache/nanochat"))
path = os.path.join(base, "base_eval", "base_model_005568.csv")
source = "real"

if not os.path.exists(path):
    source = "demo"
    demo = "\n".join([
        "Task, Accuracy, Centered",
        "arc_easy, 0.610000, 0.210000",
        "arc_challenge, 0.340000, 0.320000",
        "mmlu, 0.260000, 0.239575",
        "CORE, , 0.256525",
        "",
    ])
    fd, path = tempfile.mkstemp(suffix=".csv")
    with os.fdopen(fd, "w", encoding="utf-8") as f:
        f.write(demo)

# 仓库写入的表头带空格（f"{'Task':<35}, ..."），因此按逗号切分后必须 strip
rows = []
with open(path, encoding="utf-8") as f:
    for line in f:
        parts = [p.strip() for p in line.split(",")]
        if len(parts) != 3 or parts[0] in ("", "Task"):
            continue
        rows.append((parts[0], parts[2]))

tasks = [float(v) for name, v in rows if name != "CORE"]
core = float(dict(rows)["CORE"])
mean = sum(tasks) / len(tasks)

print(f"source: {source}")
print(f"tasks: {len(tasks)}")
print(f"CORE row: {core:.6f}")
print(f"mean(Centered): {mean:.6f}")
print(f"match: {abs(mean - core) < 1e-6}")
```

示例模式下输出固定为下面四行，可直接对照。任务数 3 只用于演示公式，真实评测包有 22 项任务。

```text
source: demo
tasks: 3
CORE row: 0.256525
mean(Centered): 0.256525
match: True
```

在真实运行上把 `source` 变为 `real`，`tasks` 应为 22，`match` 应为 `True`。若 `match` 为 `False`，说明 CSV 被手工改过或评测在中途被截断：CORE 行是 `base_eval.py` 在全部任务跑完后一次性写入的，二者不可能不一致。

### 例 2：只跑预训练与评测

```bash
# 前提：环境已装、171 个分片已下齐、分词器已训练
export NANOCHAT_BASE_DIR="$HOME/.cache/nanochat"
export OMP_NUM_THREADS=1
cd ~/nanochat && source .venv/bin/activate

# 预训练，产物写入 base_checkpoints/d24
torchrun --standalone --nproc_per_node=8 -m scripts.base_train -- \
    --depth=24 --target-param-data-ratio=8 --device-batch-size=16 --fp8 --run=dummy

# 只评 CORE 与 bpb，跳过 8 条无条件采样
torchrun --standalone --nproc_per_node=8 -m scripts.base_eval -- \
    --model-tag=d24 --device-batch-size=16 --eval=core,bpb
```

预期在终端看到 `Calculated number of iterations from target data:param ratio: 5,568`、`Total batch size 1,048,576 => gradient accumulation steps: 4`，以及结束时 `CORE metric` 一行；CORE 的绝对值取决于权重与采样规模，应同时抄录到实验记录。第二行显式传 `--model-tag`，避免 `find_largest_model` 在存在多个深度时选错。

### 例 3：screen 会话与分段日志

```bash
# 启动一个带日志的会话
screen -L -Logfile runs/speedrun.log -S speedrun bash runs/speedrun.sh
# 脱离：Ctrl-a 然后按 d
# 查看会话
screen -ls
# 回到会话
screen -r speedrun
# 另一个终端跟随日志，定位当前阶段
tail -f runs/speedrun.log | grep --line-buffered -E "Downloading|Training time|parameter|iterations|Validation bpb|CORE metric"
```

过滤后的四类关键字分别对应数据、分词器、预训练配置与评测结果。若日志停在三十分钟以上没有任何 `step` 行，通常是数据下载未完成或 torchrun 在等待 rendezvous，应先用 `nvidia-smi` 与 `ps aux | grep torchrun` 确认进程状态。

## 易错点

> [!warning] 以下六条都能在日志或产物中直接核对
> 1. 漏写 `--`。`torchrun` 把 `--depth` 当作自己的参数并报 `unrecognized arguments`。核对：日志第一行是否为 `usage: torchrun`。
> 2. 漏写 `wait`。预训练在不足 171 个分片上启动，`epoch` 计数增长异常快。核对：日志中的 `epoch: N pq: M rg: K` 三元组。
> 3. 把 `total_training_time` 当成脚本墙钟。前者只统计第 10 步之后且不含下载、评测与 SFT，因此 2.02 小时与「脚本跑了 3 小时」不矛盾。核对：日志末行 `Total training time`。
> 4. 重训分词器后继续用旧检查点。`build_model` 断言 `tokenizer.get_vocab_size() == model_config["vocab_size"]`，词表大小相同但内容不同时断言不会失败，模型输出会退化为乱码。核对：检查点目录名与 `tokenizer.pkl` 的修改时间。
> 5. 在 A100 上加 `--fp8`。代码只在非 CUDA 时忽略该参数，sm80 上会完成模块替换并在 `torch._scaled_mm` 处失败。核对：`torch.cuda.get_device_capability()` 是否 ≥ (8, 9)。
> 6. 认为 speedrun 包含 RL。脚本只有 SFT 与 chat 评测，`chatrl_checkpoints/` 不会出现。核对：`ls $NANOCHAT_BASE_DIR` 中是否有该目录。

## 关联笔记

- 前置 [[本地环境搭建]]：提供 `.venv`、数据、分词器与 `COMPUTE_DTYPE`，本篇假定这些已通过三条自检。
- 前置 [[训练脚本与speedrun]]：解释第 6 步内部从 meta device 到训练循环的 14 个阶段，本篇只讲脚本层的编排。
- 后续 [[用--depth调参]]：把第 6 步的五个参数展开为可替换的调参维度。
- 对照 [[检查点与恢复]]：本篇列出产物，该篇解释三类文件的内容与 resume 语义。
- 跨库 [[分布式训练与部署]]：通用原理见该篇，本篇只写 8 卡在 speedrun 中的具体参数与整除约束。

## 达标检测

- [ ] 能按顺序复述 speedrun 的四段与九个环节，并说出每个环节的产物。
- [ ] 能解释 `-n 8`、`-n 170 &` 与 `wait` 三者的配合，以及缺少 `wait` 的后果。
- [ ] 能由 `--depth=24 --target-param-data-ratio=8` 推出 $B_{\text{total}}$、步数与总 token 数。
- [ ] 能说明 `--` 在 `torchrun` 命令行中的作用，并解释漏写后的报错。
- [ ] 能列出 SFT 从 base 检查点继承的六项配置，以及 `load_optimizer` 为何要重置学习率。
- [ ] 能写出 screen 启动、脱离、恢复与跟随日志的四条命令。
- [ ] 能用 CSV 与 meta 做数值自洽校验，并说明 `CORE` 行为何等于任务均值。
- [ ] 能指出当前 speedrun 与旧版 d20 叙述的三处差异。

## 参考来源

- Karpathy, *nanochat*（commit `92d63d4`），`runs/speedrun.sh` —— 对应本篇的九个环节、`wait` 同步、`--` 分隔与四段结构。
- Karpathy, *nanochat*（commit `92d63d4`），`scripts/base_train.py`、`scripts/base_eval.py`、`scripts/chat_sft.py`、`scripts/chat_eval.py`、`scripts/chat_cli.py` —— 对应参数语义、继承逻辑、CSV 格式与命令行选项。
- Karpathy, *nanochat*（commit `92d63d4`），`README.md` 的 Getting started 与 Time-to-GPT-2 Leaderboard、`dev/LOG.md` 2026-02-02 与 2026-03-04 —— 对应耗时、CORE 记录与 FP8 的吞吐与显存收益。
- Karpathy, *nanochat* `dev/LEADERBOARD.md` —— 对应「time to GPT-2」只统计训练步的口径。
- PyTorch documentation, *torchrun* 与 *Distributed overview* —— 对应 `--standalone`、`--nproc_per_node` 与环境变量注入方式。
- GNU Screen 手册（`-L`、`-Logfile`、`-S` 选项） —— 对应第 9 节的会话与日志用法。
