跑通 speedrun 脚本
定义
speedrun 脚本(runs/speedrun.sh)是一条从空白 8×H100 节点开始、以可对话的 GPT-2 级模型结束的 shell 流水线。它由环境、分词器、基座预训练与评测、SFT 与对话评测四段组成,共九个实际执行的环节:环境准备、下载 8 个分片、后台补齐 170 个分片、训练分词器、评测分词器、预训练、基座评测、SFT、对话评测。脚本头部的注释给出过一次运行的预期时长。
本篇使用的符号与术语:
$B_{\text{dev}}$:单卡批大小,脚本取 16。$B_{\text{total}}$:一次优化器更新消费的 token 数,由缩放律自动推出,d24 下为 。$T$:上下文长度,默认 2048。$W$:世界大小,脚本为 8。$A$:梯度累积步数,。$N$:缩放参数,等于transformer_matrices + lm_head,d24 下为 729,810,624。$D$:训练 token 数,,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」,指的是整条流水线在理想网络与空闲节点上的运行时间;后续数据升级与评测项变化会使其偏长。
版本说明
当前
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 环境段逐行
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 重复,属于防御性写法。
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 段
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 分词器段逐行
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 步之前有一行容易被忽略的同步:
echo "Waiting for dataset download to complete..."
wait $DATASET_DOWNLOAD_PID
去掉它,预训练可能在分片未下齐时启动。list_parquet_files 在 dataloader 构造时一次性列出所有已存在的文件,之后不再重新扫描;若此时只有 40 个分片,整个训练会在这 40 个分片上循环,等效于把数据重复看了四遍,损失曲线看起来正常但能力偏低。
5 预训练段逐行
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 数定为 ,比计算最优的低,注释称之为「slightly undertrained to beat GPT-2」。--device-batch-size=16是 80 GB 卡上 d24 能容纳的单卡批;累积步数由 自动得到。--fp8把满足条件的线性层换成Float8Linear,需要计算能力 8.9 以上;在 sm80 的 A100 上会在第一次 FP8 矩阵乘处报错。--run决定 wandb 是否启用与运行名。
由前两个参数推导出的量可以直接核对: 由 d12 参考点外推,落在 ;步数为 ;每步 FLOPs 为 。
6 评测段逐行
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,默认 ;sample 用 7 个固定提示做贪心采样并额外生成 8 条无条件样本。CSV 只由 CORE 产生,路径为 base_eval/base_model_{step:06d}.csv,最后一行的第三列是 CORE 值。
7 SFT 与对话段
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 即停;每步仍消费 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、、、8 卡为条件,单位是 字节;优化器状态已按 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 与其梯度 | 字节,两份 | 4.3 |
| 激活 | 每层注意力的 q/k/v 与投影输出,加 MLP 的 中间量 | 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 工作区、碎片与激活项估计的偏差。
真实峰值以训练结束时打印的三行为准,其格式如下(数值按同量级运行的典型值给出,实际以本机日志为准):
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 记录日志
脚本头部给出三种启动方式,第二种是标准做法:
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 能被 整除:d24 的 1,048,576 除以 得 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 从零到对话的完整序列
把上述各段拼成一条可直接复制的序列,并列出每步应检查的产物。
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 | 指定模型来源 | 缺该参数直接报错 |
关键直觉
speedrun 的时间由两件事决定:5568 步与每步 1.3 秒
训练时长不是「脚本跑多久」这一个数,而是 ,其中 由深度与 ratio 决定, 由 MFU 决定。d24 在 ratio 8 下给出 5568 步,在 8×H100 上 秒即约 2 小时;把 ratio 改成 12 会把步数推到约 8352,把 fp8 去掉会把 抬高约 15%。这条乘积关系与第 5 节的推导、第 8 节的显存表共同构成「换硬件或换配置后时间是多少」的唯一算法。
例子与代码
例 1:校验 CORE CSV 与 meta 的一致性
# 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 项任务。
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:只跑预训练与评测
# 前提:环境已装、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 会话与分段日志
# 启动一个带日志的会话
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 确认进程状态。
易错点
以下六条都能在日志或产物中直接核对
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推出 、步数与总 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.md2026-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 节的会话与日志用法。