w wyl123ly 的博客
MD

README

10 KB 2026.10.22 原文件

README · 使用说明

本库是一部以 Obsidian 为载体的 nanochat 教材,书名可定为《从零训练一个 ChatGPT:nanochat 原理与实践》。它以 karpathy/nanochat 源码为唯一事实基准,覆盖分词器、预训练、中段训练、SFT、GRPO、评测、推理引擎、工具沙箱与复现实验八个环节,目标是让读者同时获得三种能力:解释每个设计的原因,读通仓库的每一段关键代码,独立复现并在预算内做实验。

本库不是零散便签。全部笔记共用一套符号约定与术语,按阶段递进,每篇包含严格定义、第一性推导、repo 代码对照、可运行例子、易错点与达标检测。阶段之间以 MOC(Map of Content)组织阅读顺序,新概念回指前置、预告后续,形成「分词 → 预训练 → 对齐 → 推理」的因果链。

与《AI学习总纲》的分工

同 vault 内的 线性代数、反向传播详解、注意力机制与QKV、指令微调SFT、对齐-RLHF、KV缓存、模型推理优化 等笔记属于《AI学习总纲》,负责通用原理通识。本库只承担两件事:

  1. 用双链指向总纲的对应阶段,写出该原理的关键结论,不重复展开教程;
  2. 展开总纲没有深入、或 nanochat 独有的内容:Rust 分词器、从零预训练管线、BOS-aligned dataloader、Muon、smear/value embedding/x0/backout 等架构特化、GRPO 的简化实现、CORE 与 ChatCORE、KV Cache 与 prefill/decode、Python 工具沙箱、--depth 调参、训练成本。

一句话:总纲管通用原理,本库管端到端复现、工程细节与本仓库特有实现。

版本基准(必须先读)

全库以仓库 master 提交 92d63d4(2026-07-03)为基准,源码快照保存在 C:\Users\Wuyanlin\AppData\Local\Temp\nanochat-src\nanochat-master\。任何与代码有关的结论都可以回到该目录核对。

本库写作时,仓库已相对 2025 年 10 月的首发版本发生多项变化;涉及这些主题的笔记会用 > [!info] 版本说明 标注旧版与当前版的差异,避免混淆:

主题2025 年 10 月版本当前 master(本库基准)
预训练数据FineWeb-EDU 100BClimbMix-400B(karpathy/climbmix-400b-shuffle)
speedrun 模型d20,约 48(8×H100 约 2 小时)
梯度同步DDP优化器内部通信 + ZeRO-2 式状态分片
注意力全上下文SSSL sliding window,最后层全上下文
架构特化较少smear、value embedding、x0/resid 标量、backout、logit softcap
SFT / RL早期脚本ChatCORE、热启动优化器、简化 GRPO
评测CORE / bpbCORE / bpb / ChatCORE / infer_bench

历史数字仍然保留在教学叙述中(例如 GPT-2 在 2019 年约 $43,000),但会明确标注出处与年份。

目录地图

nanochat学习知识库/
├── 00-MOC.md                 总索引与学习路线
├── README.md                 本文件
├── 01-背景与定位/            作者、项目定位、与 nanoGPT 的边界、学习路线
├── 02-数学与工程基础/        矩阵、softmax、交叉熵、AdamW、Muon、FLOPs 与成本
├── 03-分词器Tokenizer/       BPE 原理、词表与特殊 token、Rust 实现
├── 04-Transformer架构/       注意力、RoPE、RMSNorm、ReLU²、gpt.py 逐段拆解、架构特化、FA3、FP8
├── 05-预训练Pretraining/     数据、dataloader、训练脚本、调度器、checkpoint、CORE、分布式、缩放律
├── 06-中段训练与SFT/         对话数据、MMLU/GSM8K 数据、SFT 损失掩码、行为转变
├── 07-强化学习对齐RL/        RLHF 脉络、GRPO 推导与实现、GSM8K、影响与风险
├── 08-评测Eval/              方法论、ARC/MMLU、GSM8K/HumanEval、report 成绩单、指标解读
├── 09-推理Engine与工具/      自回归解码、KV Cache、Python 沙箱、CLI、部署与成本
├── 10-复现与实验/            环境、speedrun、--depth 调参、实验记录、故障排查
├── 模板/                     新建笔记与 MOC 时复制
└── 学习追踪/                 学习记录与实验日志

建议阅读顺序

完整路线见 00-MOC。若时间有限,优先读以下六篇,它们覆盖了 nanochat 的核心机制:

  1. 从第一性看nanochat的gpt.py:模型全部结构决策的集中说明;
  2. 数据加载器dataloader:训练数据的组织方式如何影响 loss 与吞吐;
  3. Muon优化器:与 AdamW 并列的第二类参数更新规则;
  4. CORE指标:整个项目优化的目标函数;
  5. GRPO原理与实现:对齐阶段最容易被口号化的一环;
  6. KV Cache原理:推理成本的第一性来源。

其余笔记可按阶段顺序推进;每篇末尾的达标检测用于判断是否可以进入下一阶段。

可后深挖的部分

主线读完后,以下五组内容值得单独展开;它们不是理解全流程的前置,而是决定「能不能把实验做成」的细节。

  1. 数值与内核层:FP8混合精度训练 的缩放粒度与转换过滤、FlashAttention与高效注意力 的 FA3/SDPA 回退与窗口映射。
  2. 分布式与内存:分布式训练与优化器分片 的三阶段通信、ZeRO-2 式状态分片与 8 卡通信量估算。
  3. 优化器理论:Muon优化器 的 Polar Express 迭代、NorMuon 方差缩放与 cautious weight decay 的推导。
  4. 评测统计:CORE指标 的 centered accuracy 与 如何解读指标 的二项标准误、CORE 噪声与压线判断。
  5. 规模与部署:缩放定律与模型深度 的 外推、部署与成本 的 MBU 与每百万 token 成本,以及 CLI与WebUI 的 FastAPI + SSE 扩展。

笔记约定

  • frontmatter 字段:tags、阶段、难度、created、related。related 中只放本库或总纲已有的笔记名。
  • 九个固定二级标题:定义、为什么重要、原理与推导、关键直觉、例子与代码、易错点、关联笔记、达标检测、参考来源。MOC 使用「学习顺序与理由 / 笔记索引 / 达标清单」三段式。
  • > [!tip] 为机制性直觉,不替代定义与推导;> [!warning] 为可检验的错误模式;> [!info] 为版本说明;> [!summary] 仅用于 MOC。
  • 代码块全部标注语言,并给出形状、数值或预期输出。公式行内用 $...$,独立公式用 $$...$$。
  • 双链不带路径与扩展名。跨库链接统一加「通用原理见 笔记名」的说明,避免读者误以为本库重复讲解。

Obsidian 设置建议

  • 本库位于既有 vault D:\Note\wyl123ly 的 笔记\nanochat学习知识库 下,直接打开该 vault 即可看到;双链与总纲互通。
  • 需要启用核心插件「Backlinks」「Graph view」「Outlines」,并安装社区插件 Dataview(已有)、Excalidraw(已有)、LaTeX Suite(已有)。
  • MOC 中的 mermaid 图依赖核心插件 Mermaid;公式渲染依赖 Obsidian 内置 MathJax。

完整文件清单

根目录:00-MOC.md、README.md。

01-背景与定位(5):MOC-背景与定位、Karpathy与nanochat、nanochat与nanoGPT的区别、LLM101n课程、学习路线与前置要求。

02-数学与工程基础(7):MOC-数学与工程基础、矩阵与线性代数速查、softmax与softmax温度、交叉熵与困惑度、梯度下降与AdamW、Muon优化器、FLOPs与训练成本估算。

03-分词器Tokenizer(5):MOC-分词器、为什么需要分词、字节对编码BPE原理、词表与特殊token、nanochat的Rust分词器实现。

04-Transformer架构(11):MOC-Transformer、自注意力机制、多头注意力、位置编码与RoPE、残差连接与LayerNorm、前馈层与激活函数、GPT模型类与config、从第一性看nanochat的gpt.py、nanochat架构特化技巧、FlashAttention与高效注意力、FP8混合精度训练。

05-预训练Pretraining(10):MOC-预训练、训练数据与FineWeb、数据加载器dataloader、训练脚本与speedrun、学习率与warmup-warmdown、检查点与恢复、CORE指标、对比GPT-2核心指标、分布式训练与优化器分片、缩放定律与模型深度。

06-中段训练与SFT(5):MOC-中段训练与SFT、对话数据与SmolTalk、多选与工具使用数据、有监督微调SFT、从生成式到对话式。

07-强化学习对齐RL(5):MOC-强化学习、RLHF与GRPO概览、GRPO原理与实现、GSM8K数学任务、RL对模型的影响。

08-评测Eval(6):MOC-评测、评测方法论、ARC与MMLU、GSM8K与HumanEval、生成report成绩单、如何解读指标。

09-推理Engine与工具(6):MOC-推理Engine、自回归解码与prefill-decode、KV Cache原理、工具调用与Python沙箱、CLI与WebUI、部署与成本。

10-复现与实验(6):MOC-复现、本地环境搭建、跑通speedrun脚本、用--depth调参、实验记录模板、常见问题踩坑。

模板与追踪(4):nanochat概念笔记模板、nanochat阶段MOC模板、nanochat学习记录模板、实验日志。

合计 72 个 Markdown 文件。

维护与扩展

  1. 新增笔记:复制 nanochat概念笔记模板,放入对应阶段目录,frontmatter 的 阶段 与目录一致;在该阶段 MOC 的「笔记索引」中补一行。
  2. 修改事实:先更新 C:\Users\Wuyanlin\AppData\Local\Temp\nanochat-src\nanochat-master\ 的源码快照,再同步所有引用该结论的笔记;README 的「版本基准」表同步更新提交号。
  3. 校验:运行 python .dsh-build/check.py,要求 errors=0;警告中的行数不足、占位符需要逐条确认。
  4. 导入为独立 vault:若把本目录单独作为 vault 打开,跨库双链会变为未解析链接(显示为灰色);此时以「添加到既有 vault」的方式使用,或安装 Obsidian 的「Same name」解析规则。