MOC · 复现与实验
本阶段地图
10 阶段回答一个问题:如何在自己的硬件上,把 nanochat 从一份源码变成一次可解释、可比较、可复现的实验。五篇笔记沿一条操作链展开:先把环境装到可验证的状态(依赖、CUDA、精度、基准目录、数据与分词器),再逐段跑通端到端流水线并核对每一步产物,然后用
--depth把模型规模与算力预算对上,接着用统一的记录格式把结果变成可比数据,最后用故障树把失败收敛到具体代码位置。前置是 05 的 训练脚本与speedrun 与 缩放定律与模型深度,后续不再有新的原理,只把全书落到一次真实运行上。
flowchart LR
subgraph 准备
A1[本地环境搭建<br/>uv 与 CUDA 匹配]
A2[数据与分词器<br/>climbmix 与 token_bytes]
end
subgraph 执行
B1[跑通speedrun脚本<br/>四段九个环节]
B2[调参 depth<br/>规模与显存]
end
subgraph 沉淀
C1[实验记录模板<br/>九字段与阈值]
C2[常见问题踩坑<br/>故障树]
C3[实验日志<br/>按周累积]
end
A1 --> A2 --> B1
B1 --> B2
B2 --> C1
B1 --> C2
C1 --> C3
C2 --> C3
C3 -.->|下一轮假设| B2
图中唯一的回边是「日志到调参」:一次实验的结论会变成下一次的假设,这是 10 阶段与其它阶段的结构差别。其它阶段的知识是单向累积的,本阶段的知识来自运行结果的反馈。
阶段定位
前九个阶段回答「为什么这样设计」,本阶段回答「怎样证明它在我的机器上成立」。两者共用同一套数字,但判据不同:05 阶段的判据是能推导出 d24 的 729,810,624 个缩放参数,本阶段的判据是能在日志里找到这个数。
本阶段与相邻阶段的分工如下。
| 相邻阶段 | 交接物 | 本阶段不重复的内容 |
|---|---|---|
| 03 分词器 | 词表 32768、9 个特殊 token、token_bytes | BPE 训练算法与合并过程 |
| 04 Transformer | GPT、GPTConfig、精度开关 | 注意力、RoPE、FP8 的数值推导 |
| 05 预训练 | base_train.py 的启动顺序、缩放律、检查点格式 | 循环内部机制与分布式通信 |
| 06 中段训练与 SFT | SFT 的数据混合与掩码 | render_conversation 的构造 |
| 07 强化学习 | chatrl_checkpoints 的来源 | GRPO 的推导与奖励设计 |
| 08 评测 | CORE 与 ChatCORE 的口径 | 22 项任务的构造与打分 |
| 09 推理 Engine | chat_cli 与 KV 缓存 | 解码循环与工具状态机 |
本阶段只保留三样东西:可执行的命令、可核对的产物、可复用的判定规则。
学习顺序与理由
顺序遵循「先可运行、再可解释、最后可比较」,每一步只增加一种能力。
- 本地环境搭建:先让
import torch、torch.cuda.is_available()、COMPUTE_DTYPE、tokenizer.pkl四条检查全部通过。先读它的理由是环境错误会伪装成训练错误:CUDA_VISIBLE_DEVICES指错时autodetect_device_type()会返回cpu,训练不报错只是慢 100 倍。 - 跑通speedrun脚本:在环境正确的前提下逐段执行九个环节,并记录每一步的产物。这一篇是 10 阶段的主干,其余四篇分别是它的前置、放大、记录与排障。
- 用--depth调参:跑通一次之后,第二个问题必然是「我的卡能跑多大的模型」。这一篇把深度展开为宽度、参数、显存与时间,并给出 d12 与 d24 两套配置。
- 实验记录模板:有了可运行的配置,才能开始做实验。这一篇定义九个字段、五个指标的口径与判定阈值,使两次运行可比。
- 常见问题踩坑:放在最后不是因为它不重要,而是因为它的 11 条症状只有在前四篇建立具体量感之后才能被准确识别。例如显存不足的两种成因(单卡批过大与分配器碎片)表现都是 OOM,区分它们需要知道 d24 的显存在
dev=16与dev=8下分别是多少。
不建议先读第五篇:故障树是一张查找表,脱离具体配置读它,会把每条症状记成一堆互不相关的命令。也不建议跳过第四篇直接做实验:没有阈值与口径的约束,「感觉更好」会成为唯一的判据。
笔记索引
| # | 笔记 | 核心问题 | 读完应能 | 关键产物或命令 | 难度 |
|---|---|---|---|---|---|
| 1 | [[本地环境搭建]] | 怎样装出可验证的环境 | 在 Linux 与 WSL2 上装出可训练环境并自检 | .venv/、base_data_climbmix/、tokenizer/ | ★★☆ |
| 2 | [[跑通speedrun脚本]] | 端到端流水线每一步做什么 | 复述九个环节、核对九个产物、验证 CORE 与 bpb | base_checkpoints/d24/、base_eval/*.csv | ★★★ |
| 3 | [[用--depth调参]] | 深度如何决定规模、显存与时间 | 由深度手算参数与步数,按顺序降级 OOM | --depth、--device-batch-size、--fp8 | ★★★ |
| 4 | [[实验记录模板]] | 怎样把一次运行变成可比数据 | 写出九字段记录,设计 A/B,判定采纳与否 | meta_*.json、user_config、train/mfu | ★★☆ |
| 5 | [[常见问题踩坑]] | 失败如何收敛到一行代码 | 按症状定位根因并给出修复 | triage.sh、HAS_FA3、find_last_step | ★★★ |
五篇覆盖的能力:1 属于环境工程,2 属于流程编排,3 属于规模设计,4 属于实验方法,5 属于故障定位。缺 1 无法开始,缺 2 无法完成,缺 3 无法换硬件,缺 4 无法累积,缺 5 无法在中断后恢复。
关键事实与配置
以下数值来自 commit 92d63d4 的本地快照,跨篇引用时以本表为准。
| 事实 | 取值 | 可核对位置 |
|---|---|---|
| Python 版本 | 3.10 | .python-version、requires-python |
| 依赖安装 | uv sync --extra gpu 或 --extra cpu,开发另加 --group dev | pyproject.toml、README |
| torch 版本 | 2.9.1,CUDA 12.8 或 CPU 两个显式索引 | pyproject.toml 的 [tool.uv.sources] |
| 默认组 | default-groups = [],dev 组不默认安装 | pyproject.toml 的 [tool.uv] |
| 基准目录 | NANOCHAT_BASE_DIR,默认 ~/.cache/nanochat | nanochat/common.py:get_base_dir |
| 数据 | karpathy/climbmix-400b-shuffle,分片编号 0–6542,其中 6542 固定作验证集 | nanochat/dataset.py |
| 数据量 | -n 8 约 20 亿字符;-n 170 约 17 GB | runs/speedrun.sh 注释与分片大小 |
| 词表 | 32768,bos_id 为 32759 | nanochat/tokenizer.py |
| speedrun 配置 | --depth=24 --target-param-data-ratio=8 --device-batch-size=16 --fp8 | runs/speedrun.sh |
| d24 规模 | 1536 维、12 头、729,810,624 缩放参数、5,838,484,992 token、5568 步 | base_train.py 推导 |
| d12 规模 | 768 维、6 头、110,100,912 缩放参数、880,807,296 token、1680 步 | 同上 |
| 全局批 | d12 为 ,d24 为 | auto batch 公式 |
| 时间 | d12 约 5 分钟,d24 约 1.65–2.0 小时(8×H100) | README leaderboard、dev/LOG.md |
| CORE 阈值 | 0.256525,单次标准差约 0.005 | dev/LEADERBOARD.md |
| FP8 门槛 | 计算能力 8.9 以上 | nanochat/fp8.py 与 base_train.py |
| 精度默认 | SM80+ 为 bf16,更早为 fp32,CPU/MPS 为 fp32 | nanochat/common.py |
两处版本差异必须记住。第一,README 目录树仍写 speedrun.sh # Train the ~$100 nanochat d20,当前脚本是 d24 加 fp8。第二,README 正文说 GPT-2 能力约等于 depth 26,而 ClimbMix 之后 speedrun 用 d24,d26 只作为对照。引用旧数字时必须标注版本。
一处容易被忽略的产品事实:runs/speedrun.sh 不包含强化学习段,chatrl_checkpoints/ 由单独的 scripts.chat_rl.py 产生,且它加载的是 SFT 检查点。把 speedrun 的产物清单当成四类检查点齐全,会导致「RL 检查点找不到」的误判。
三条能力主线
懂原理在本阶段的落点是「能解释每个默认值的来源」。为什么 --device-batch-size 默认 32 而 speedrun 用 16,为什么 ratio 默认 12 而脚本用 8,为什么 fp16 需要 GradScaler 而 bf16 不需要,这些问题的答案都在 04 与 05 阶段,本阶段只负责在日志里认出它们。
能复现的落点是「产物清单」。复现的判据不是脚本退出码为 0,而是九个产物齐全且数值自洽:CSV 的 CORE 行等于 22 项任务均值,meta 的 step 与文件名一致,optim 分片数等于进程数。缺一项就说明某一步被跳过或截断。
懂工程的落点是「在约束内做选择」。8×H100 是最优配置,但多数人只有一张 24 GB 卡或一台 Mac。本阶段给出的选择顺序是:先降单卡批(不改语义),再开 FP8(改数值),再降上下文(改设定),最后降深度(改模型);每一步都要在记录中标注,否则后续无法比较。
常见失败模式
- 装了 GPU 版 torch 但驱动不支持 CUDA 12.8:
torch.cuda.is_available()为 False,训练自动跑在 CPU 上。 - 只下 8 个分片就开始预训练:dataloader 在 8 个分片上循环,损失正常但能力偏低。
- 重训分词器后继续用旧检查点:
vocab_size相同使断言通过,token 语义已错位。 - 在 A100(sm80)上加
--fp8:代码只检查 CUDA,第一次torch._scaled_mm才报错。 - 用不同卡数恢复训练:优化器状态按 rank 分片,形状不匹配。
- 把
total_training_time当作脚本墙钟:两者相差数据下载、评测与 SFT。 - 用单次 CORE 的 0.003 差异下结论:落在 0.005 的噪声内。
- 在 FA3 回退后仍用
SSSL窗口:SDPA 的显式掩码比全上下文更慢。
以上八条都能在 常见问题踩坑 中找到对应的验证命令与修复。
与学习追踪的接口
本阶段的两份追踪文件承担不同职责。
- nanochat学习记录模板 是表头与周计划的骨架:每周填一行进度,按阶段勾选达标项,回答固定的复盘问题。
- 实验日志 是实际的运行记录:每条按 实验记录模板 的九字段填写,失败实验标注
(negative)并写明条件。
两者的关系是「计划」与「证据」。周计划说本周要跑 d12,实验日志记录这次 d12 的命令、指标与结论;没有后者,前者无法验证;没有前者,后者会退化成流水账。
与全书的衔接
若把全书看作一条流水线,05 阶段把算力换成能力,10 阶段把能力换成可验证的证据。它消费 03 的词表、04 的结构、05 的训练配置、06 的 SFT 产物与 08 的评测口径,产出的是三样可复用的东西:一套环境、一份产物清单、一套记录格式。
本阶段也是全书唯一要求「动手」的阶段。其它阶段的达标检测是推导与复述,本阶段的达标检测是「跑过一次并解释结果」。因此它的笔记比其他阶段更依赖机器:没有 GPU 时只能完成第 1 篇的 CPU 路径与第 4、5 篇的纸面练习,第 2、3 篇的训练部分无法验证。这一点应当在 nanochat学习记录模板 的周计划中显式标注。
三条阅读路径
时间与硬件条件不同,路径不同。三条路径共用同一套事实,区别只在读到哪里为止。
| 条件 | 必读 | 可选 | 预计时间 | 能完成的事 |
|---|---|---|---|---|
| 只有 CPU 或 Mac | 1、4、5 | 2 的命令部分 | 3–4 小时 | 装出环境、跑通冒烟、建立记录与排障习惯 |
| 有一张 24 GB 级 GPU | 1、2、3、4 | 5 | 6–8 小时 | 跑到 d16、完成一次 A/B |
| 有 8 卡节点 | 全部 | 无 | 10–12 小时 | 跑通 speedrun、复现 CORE、做深度扫描 |
第一行的限制是真实的:runs/runcpu.sh 的模型只有 2320 万参数,CORE 没有参考价值,因此 CPU 路径只能验证代码,不能验证能力。若目标是「理解全书」,CPU 路径足够;若目标是「复现 GPT-2 级」,必须具备 8 卡或租用节点。
产物与验证点
每一步都应有可检查的产物,没有产物的步骤无法判断是否完成。
| 步骤 | 产物 | 验证方式 |
|---|---|---|
| 环境 | .venv/ | python -c "import torch; print(torch.version.cuda)" |
| 数据 | base_data_climbmix/*.parquet | 分片数 171,末片为 shard_06542.parquet |
| 分词器 | tokenizer/tokenizer.pkl、token_bytes.pt | vocab_size 为 32768,bos_id 为 32759 |
| 预训练 | base_checkpoints/d24/ 三类文件 | model_005568.pt 与 meta_005568.json 同名同 step |
| 基座评测 | base_eval/base_model_005568.csv | 末行 CORE 等于前 22 行 Centered 的均值 |
| SFT | chatsft_checkpoints/d24/model_*.pt | chat_eval -i sft 能输出 ChatCORE |
| 对话 | 终端回答 | chat_cli -p 能答出法国的首都 |
验证点按阶段递进:环境与数据的错误在预训练前暴露,检查点的错误在恢复或评测时暴露,词表的错误只在对比历史结果时暴露。因此每次跑完至少保存 CSV 与 meta,而不是只保存权重。
维护约定
本阶段的事实基准是 commit 92d63d4。若上游改动 speedrun 的深度、ratio 或精度开关,需要同步修改的篇目是:本地环境搭建(依赖与精度)、跑通speedrun脚本(命令与产物)、用--depth调参(两套配置表)、本 MOC 的「关键事实与配置」表。只改其中一处会造成跨篇数字冲突。
数字书写沿用全库约定:参数量写完整整数(729,810,624),比例写小数(0.256525),时间写小时并附量级范围(1.65–2.0 小时),金额写美元并注明单价基准(8×H100 约 24 美元/小时)。显存与耗时凡属估算,均在原处标注「量级」或以实测打印项为准。
达标清单
- [ ] 能在 Linux 或 WSL2 上从零装出可训练环境,并给出三条自检输出。
- [ ] 能按顺序复述 speedrun 的四段九个环节,并列出九个产物及其证明的阶段。
- [ ] 能由
--depth手算宽度、头数、缩放参数、全局批、步数与总 token 数。 - [ ] 能按代价从小到大给出显存不足时的五步调整顺序,并说明哪一步改变实验含义。
- [ ] 能写出实验记录的九个字段与五个指标的 wandb key,并给出判定阈值。
- [ ] 能设计一次 A/B:说明运行次数、阈值与 A/A 自检方法。
- [ ] 能按「现象、原因、验证、修复」四段处理至少三条故障。
- [ ] 能指出当前 speedrun 与旧版 d20 叙述的三处差异,以及 RL 检查点的真实来源。
- [ ] 能解释为什么「脚本退出码为 0」不构成复现成功的判据。
参考来源
- Karpathy, nanochat(commit
92d63d4),README.md、runs/speedrun.sh、runs/runcpu.sh、dev/LOG.md、dev/LEADERBOARD.md—— 对应本阶段的全部配置、命令、产物与时间数字。 - Karpathy, nanochat(commit
92d63d4),nanochat/common.py、dataset.py、tokenizer.py、checkpoint_manager.py、flash_attention.py—— 对应环境、数据、词表、检查点与注意力后端的事实。 - Astral, uv documentation 与 PyTorch documentation(CUDA semantics、torchrun、memory management) —— 对应环境安装与显存、分布式两节。
- NVIDIA, CUDA C++ Programming Guide 与 CUDA on WSL User Guide —— 对应计算能力表、FP8 门槛与 WSL2 的驱动前提。
- Hoffmann et al., Training Compute-Optimal Large Language Models(2203.15556)与 Bergsma et al., Power Laws for Batch Size, Model Size, and Training Horizon(2505.13738) —— 对应 ratio 与批大小的选择依据。
- 跨库衔接:通用原理见 分布式训练与部署 与 成本-延迟-质量权衡,本阶段只写 nanochat 的落地命令、产物与判定规则。