训练脚本与 speedrun
定义
speedrun 是 runs/speedrun.sh 所描述的端到端流水线:在一台空白 8×H100 节点上,从安装依赖开始,依次完成数据下载、分词器训练、d24 基座模型预训练、基座评测、SFT 与对话评测,最终得到一个可用 chat_cli 对话的 GPT-2 级模型。
本篇出现的符号与术语:
--depth:Transformer 层数 ,唯一的规模旋钮。model_dim由depth * aspect_ratio向上取整到head_dim的倍数得到。- :参与缩放律统计的参数量,等于
transformer_matrices + lm_head,不含wte与 value embedding。 - :训练 token 数,由
--target-param-data-ratio乘以 得到。 - :一次优化器更新消费的 token 数,即总批大小;由缩放律自动计算或被
--total-batch-size覆盖。 - :单卡批大小,
--device-batch-size。 - :上下文长度,
--max-seq-len,默认 2048。 - :世界大小,即
torchrun --nproc_per_node,speedrun 为 8。 - :梯度累积步数,。
- 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 小时」指整条脚本的运行时间,且未随数据升级更新,属于过期表述。
版本说明
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 个阶段。顺序不是随意的,每一步都为下一步准备状态。
- 设置
PYTORCH_ALLOC_CONF=expandable_segments:True,打印 banner。前者减少显存碎片,后者只是日志。 - 解析 CLI。默认值本身就是一套配置:
--depth=20、--target-param-data-ratio=12、--device-batch-size=32、--warmup-steps=40、--warmdown-ratio=0.65。 compute_init(device_type):设置种子 42、CUDA 的 tf32、初始化 NCCL 进程组、选定device。返回ddp, rank, local_rank, world_size, device。get_tokenizer()、get_token_bytes()、vocab_size。分词器决定词表大小,进而决定lm_head与wte的形状,必须在建模型之前完成。build_model_meta(depth):在torch.device("meta")上下文中构造GPT,只得到形状与 dtype。model.to_empty(device=device):在目标设备上分配存储,内容为未初始化的垃圾值。model.init_weights():写入真实初始化值。这一步之前模型不可用。- 可选 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 中加载。 - 可选 fp8:
convert_to_float8_training把满足条件的nn.Linear换成Float8Linear。必须在torch.compile之前,否则编译图与模块类型不匹配。 orig_model = model,model = torch.compile(model, dynamic=False)。保留未编译模型用于保存与评测,因为评测输入形状会变化。- 缩放律推导:
num_scaling_params、estimate_flops、target_tokens、D_REF、B_total、batch_lr_scale、weight_decay_scaled。全部只依赖参数量与 ratio,不依赖数据。 setup_optimizer:按参数形状分组,Muon 组按(rows, cols)堆叠,AdamW 组按角色分组;随后可选加载优化器状态。- GradScaler:仅当
COMPUTE_DTYPE == torch.float16时创建,bf16 与 fp32 为None。 - 构建 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,源码在类定义处直接警告:
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.
"""
具体后果有三条:
__init__里写的torch.ones、torch.zeros、normal_都只会得到 meta 张量,没有存储。resid_lambdas = nn.Parameter(torch.ones(config.n_layer))在 meta 上下文中只是一个形状为(n_layer,)的空壳,真实值在init_weights中重新写入。to_empty之后参数是垃圾值。若跳过init_weights直接训练,前几步的损失会是 NaN 或远离 ;这个错误不会在形状检查中暴露。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,两者之差由梯度累积补足:
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:、、,故每次前向反向消费 token;,所以 。一步训练由 4 次前向反向与 1 次优化器更新组成。
三个实现细节:
- 损失在反传前除以
grad_accum_steps:loss = loss / grad_accum_steps。因为backward()累加梯度而不是求平均,不除会让梯度放大 倍。 - 数据预取在最后一次反传之后:
x, y, dataloader_state_dict = next(train_loader)位于 micro-step 循环内,下一批的 CPU 准备与 GPU 计算重叠。 assert要求整除。 是 2 的幂, 也是 2 的幂,只要 就成立。d24 的上限是 ,取 16 有 4 倍余量。
dev/LEADERBOARD.md 给出的经验值是 (8 卡时为 524,288 token,正是 d12 的参考批大小);d24 与 d26 因显存不足降到 16,脚本自动用累积补偿。
步骤 5 MFU、tok/s 与 ETA 的公式
训练循环末尾用四个量刻画吞吐:
其中 是每 token 的前向加反向 FLOPs,由 model.estimate_flops() 给出:
是所有 Linear 权重元素数之和, 为头数, 为每头维度, 为第 层的窗口大小。系数 6 来自每参数前向 2 FLOPs、反向 4 FLOPs。
对 d24 手算:, 与之相差极小,故 。按 _compute_window_sizes 的实际算式, 时短窗口为 (源码注释写作 768,与算式不一致,以代码为准),24 层中 18 层窗口 512、6 层窗口 2048,注意力项为
合计 。于是每步 FLOPs 为 。H100 的 bf16 峰值取 get_peak_flops 的 ,8 卡合计 ,故
这个式子说明 MFU 与每步耗时一一对应: s 时 MFU 上限 63.3%, s 时约 48.5%。leaderboard 记录 ClimbMix 配置为 2.02 小时、5568 步,反推平均 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 管理与显存
训练循环在第一步之后做三件事:
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 | 共 token |
--core-metric-every | -1 | 不跑 CORE |
按该配置,,训练 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,用于验证改动是否有效。完整命令:
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
推导其规模:,命令未传 --target-param-data-ratio,取默认值 12,故 ; 用同一默认值算得,与 相同,故 落在参考值 ;num_iterations = 1{,}321{,}210{,}944 // 524{,}288 = 2520。默认 时每次前向反向正好 524,288 token,,不需要累积。若显式加 --target-param-data-ratio=8,则 、1680 步,产物文件名也随之改变。
时间与显存:,每步 FLOPs,总计约 FLOPs。README 称该规模适合约 5 分钟的迭代,反推平均每步约 0.18 秒、吞吐约 2.9M token/s。显存的主要项是 logits: 个 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 训练循环的触发顺序
循环体每步的执行顺序固定,理解它才能读懂日志:
last_step = step == num_iterations。循环执行 次,最后一次只做评测与保存。flops_so_far = C_{\text{token}}\cdot B_{\text{total}}\cdot\text{step}。- 若
eval_every > 0且到达间隔或最后一步:切model.eval(),重建验证 loader,evaluate_bpb,记录val_bpb与min_val_bpb,切回train()。 - 若
core_metric_every > 0且到达间隔:用orig_model与disable_fp8跑 CORE,记录 22 项任务与均值。 - 若
sample_every > 0且是主进程:用Engine(orig_model)对 7 个固定提示做贪心采样,打印 16 个 token。提示包含「法国首都」「金的化学符号」等,用于肉眼判断模型是否退化。 - 若
save_every命中或最后一步:save_checkpoint写模型、优化器分片与 meta。 if last_step: break。- micro-step 循环:前向、除以累积步数、反传、预取下一批。
- 读取
lrm、muon_momentum、muon_weight_decay,写入各参数组。 - 若启用 GradScaler:
unscale_、跨 rank 同步found_inf、scaler.step、scaler.update;否则optimizer.step()。 model.zero_grad(set_to_none=True);同步并计时;计算 EMA 损失、tok/s、MFU、ETA;每 100 步写 wandb。- 更新
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 推导 、、LR 与 WD | 手工设错 --total-batch-size 会破坏整除断言或改变最优配置 |
base_train.py 的 grad_accum_steps | 用累积补足总批 | 损失不除以 会使梯度放大,等效学习率乘以 |
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 方差大 |
关键直觉
启动过程是一个状态机,每个状态转换都有代价: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 的公式。
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
预期输出:
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 一项是「百分比每秒」:把当步 代入即得百分比。d24 在 s 时为 48.5%,d12 在 s 时为 28.0%。该输出同时说明:d24 在 --target-param-data-ratio=8 下 自动落在 ,与 dev/LOG.md 2026-02-05 的表格一致;上面的 d12 命令使用默认 ratio 12,故为 2520 步。d12 的 只在 时成立,改成 16 则 ,总批不变。
下面的 d12 命令可直接复制,用于验证本机环境。它关闭 CORE 中途评测、采样与中间保存,只保留最后一次评测。
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;此时 ,总批不变,训练时间约翻倍。
下面是一行训练日志的字段说明,格式取自 base_train.py 的 print0:
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 为 秒约 120.8 分钟。前 10 步不计入,因为编译与 autotune 使其 dt 明显偏高。
易错点
以下六条都对应
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、世界大小与 ,能算出 、、
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」只统计训练步的定义,以及 的经验值与 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)—— 对应 的 FLOPs 估算与 MFU 指标,
estimate_flops的注释直接引用该文。 - Bergsma et al., Power Laws for Batch Size, Model Size, and Training Horizon(arXiv:2505.13738)—— 对应 的批大小推导,即步骤 4 的裁剪系数来源。