w wyl123ly 的博客
MD

MOC-复现

16 KB 2026.10.22 原文件

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_bytesBPE 训练算法与合并过程
04 TransformerGPT、GPTConfig、精度开关注意力、RoPE、FP8 的数值推导
05 预训练base_train.py 的启动顺序、缩放律、检查点格式循环内部机制与分布式通信
06 中段训练与 SFTSFT 的数据混合与掩码render_conversation 的构造
07 强化学习chatrl_checkpoints 的来源GRPO 的推导与奖励设计
08 评测CORE 与 ChatCORE 的口径22 项任务的构造与打分
09 推理 Enginechat_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 与 bpbbase_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 devpyproject.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/nanochatnanochat/common.py:get_base_dir
数据karpathy/climbmix-400b-shuffle,分片编号 0–6542,其中 6542 固定作验证集nanochat/dataset.py
数据量-n 8 约 20 亿字符;-n 170 约 17 GBruns/speedrun.sh 注释与分片大小
词表32768,bos_id 为 32759nanochat/tokenizer.py
speedrun 配置--depth=24 --target-param-data-ratio=8 --device-batch-size=16 --fp8runs/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.005dev/LEADERBOARD.md
FP8 门槛计算能力 8.9 以上nanochat/fp8.py 与 base_train.py
精度默认SM80+ 为 bf16,更早为 fp32,CPU/MPS 为 fp32nanochat/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 或 Mac1、4、52 的命令部分3–4 小时装出环境、跑通冒烟、建立记录与排障习惯
有一张 24 GB 级 GPU1、2、3、456–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.ptvocab_size 为 32768,bos_id 为 32759
预训练base_checkpoints/d24/ 三类文件model_005568.pt 与 meta_005568.json 同名同 step
基座评测base_eval/base_model_005568.csv末行 CORE 等于前 22 行 Centered 的均值
SFTchatsft_checkpoints/d24/model_*.ptchat_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 的落地命令、产物与判定规则。