---
tags: [nanochat, MOC, repro]
阶段: 10-复现与实验
难度: ★★☆
created: 2026-10-22
related: "[[本地环境搭建]], [[跑通speedrun脚本]], [[常见问题踩坑]], [[MOC-预训练]]"
---

# MOC · 复现与实验

> [!summary] 本阶段地图
> 10 阶段回答一个问题：如何在自己的硬件上，把 nanochat 从一份源码变成一次可解释、可比较、可复现的实验。五篇笔记沿一条操作链展开：先把环境装到可验证的状态（依赖、CUDA、精度、基准目录、数据与分词器），再逐段跑通端到端流水线并核对每一步产物，然后用 `--depth` 把模型规模与算力预算对上，接着用统一的记录格式把结果变成可比数据，最后用故障树把失败收敛到具体代码位置。前置是 05 的 [[训练脚本与speedrun]] 与 [[缩放定律与模型深度]]，后续不再有新的原理，只把全书落到一次真实运行上。

```mermaid
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 缓存 | 解码循环与工具状态机 |

本阶段只保留三样东西：可执行的命令、可核对的产物、可复用的判定规则。

## 学习顺序与理由

顺序遵循「先可运行、再可解释、最后可比较」，每一步只增加一种能力。

1. [[本地环境搭建]]：先让 `import torch`、`torch.cuda.is_available()`、`COMPUTE_DTYPE`、`tokenizer.pkl` 四条检查全部通过。先读它的理由是环境错误会伪装成训练错误：`CUDA_VISIBLE_DEVICES` 指错时 `autodetect_device_type()` 会返回 `cpu`，训练不报错只是慢 100 倍。
2. [[跑通speedrun脚本]]：在环境正确的前提下逐段执行九个环节，并记录每一步的产物。这一篇是 10 阶段的主干，其余四篇分别是它的前置、放大、记录与排障。
3. [[用--depth调参]]：跑通一次之后，第二个问题必然是「我的卡能跑多大的模型」。这一篇把深度展开为宽度、参数、显存与时间，并给出 d12 与 d24 两套配置。
4. [[实验记录模板]]：有了可运行的配置，才能开始做实验。这一篇定义九个字段、五个指标的口径与判定阈值，使两次运行可比。
5. [[常见问题踩坑]]：放在最后不是因为它不重要，而是因为它的 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 为 $2^{19}$，d24 为 $2^{20}$ | 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 的落地命令、产物与判定规则。
