w wyl123ly 的博客
MD

跑通speedrun脚本

30 KB 2026.10.22 原文件

跑通 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 8base_data_climbmix/shard_0000*.parquet,9 个1–5 分钟无
3数据python -m nanochat.dataset -n 170 &追加到 171 个分片10–40 分钟,与下两步重叠无
4分词器python -m scripts.tok_traintokenizer/tokenizer.pkl、tokenizer/token_bytes.pt1–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 --fp8base_checkpoints/d24/model_005568.pt、meta_005568.json、optim_005568_rank{0..7}.pt1.65–2.02 小时45–65 GB
7评测torchrun --standalone --nproc_per_node=8 -m scripts.base_eval -- --device-batch-size=16base_eval/base_model_005568.csv、eval_bundle/10–30 分钟30–50 GB
8SFTtorchrun --standalone --nproc_per_node=8 -m scripts.chat_sft -- --run=$WANDB_RUNchatsft_checkpoints/d24/model_*.pt30–60 分钟40–60 GB
9对话评测torchrun --standalone --nproc_per_node=8 -m scripts.chat_eval -- -i sft终端输出 ChatCORE10–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.pynanochat--run 不是 dummy 且是主进程
scripts/chat_sft.pynanochat-sft同上
scripts/chat_rl.pynanochat-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 为 bf164.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.csvCORE 已评测,末行为总分
chatsft_checkpoints/d24/model_*.ptSFT 完成
终端 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.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 节的会话与日志用法。