---
tags: [nanochat, 导航, 使用说明]
阶段: 全书
难度: ★☆☆
created: 2026-10-22
related: "[[00-MOC]], [[学习路线与前置要求]], [[本地环境搭建]]"
---

# 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 100B | ClimbMix-400B（`karpathy/climbmix-400b-shuffle`） |
| speedrun 模型 | d20，约 $100 | d24 + FP8，约 $48（8×H100 约 2 小时） |
| 梯度同步 | DDP | 优化器内部通信 + ZeRO-2 式状态分片 |
| 注意力 | 全上下文 | `SSSL` sliding window，最后层全上下文 |
| 架构特化 | 较少 | smear、value embedding、x0/resid 标量、backout、logit softcap |
| SFT / RL | 早期脚本 | ChatCORE、热启动优化器、简化 GRPO |
| 评测 | CORE / bpb | CORE / bpb / ChatCORE / infer_bench |

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

## 目录地图

```text
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. 规模与部署：[[缩放定律与模型深度]] 的 $B_{opt}\propto D^{0.383}$ 外推、[[部署与成本]] 的 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」解析规则。
