nanochat 完全教程

“The best ChatGPT that $100 can buy.”

Andrej Karpathy 2025 年的力作:在单个 GPU 节点上、约 100 美元预算内,从分词器、预训练、SFT 到推理 CLI,端到端训练一个能对话的 ChatGPT 风格模型。本教程覆盖:项目解读 → 架构原理 → 逐文件精讲 → 实战命令 → 评测与排行榜 → 故障排除。

仓库地址:github.com/karpathy/nanochat(MIT 协议 · 58k+ Stars)

PyTorchRoPE / GQA / QK-normMuon 优化器 Flash Attention 3fp8 训练KV Cache 推理$100 Speedrun

CH.1项目概览

什么是 nanochat

nanochat 是一个极简的 LLM 全流程实验框架:从分词器训练、预训练、SFT 微调、评测到推理部署,覆盖构建一个对话助手的全部阶段,且整套流程跑在单个 GPU 节点上。它的口号是「100 美元能买到的最好的 ChatGPT」——在 8×H100 上约 1.5 小时跑完全流程(节点约 $24/小时,README 按 2 小时预算估约 $48,spot 实例可低至 ~$15),产出的模型质量超过 GPT-2。

它能做到的事情:

  1. 从零预训练一个现代架构的 base 模型(FineWeb 数据);
  2. SFT 教会它对话、工具调用与数学(SmolTalk + MMLU + GSM8K);
  3. 评测:CORE 指标、bpb、ChatCORE(MMLU/GSM8K/HumanEval/ARC);
  4. 推理:自带 KV cache 推理引擎与 CLI,训练完立刻能聊天。

设计哲学:一个旋钮

nanochat 刻意避免「配置繁重的框架」,定位是最小化、可 hack、可 fork 的强基线代码。最鲜明的体现是:整个系统只有一个复杂度旋钮 --depth(Transformer 层数),其余一切超参数——宽度、头数、学习率、训练时长、weight decay 等——全部按 compute-optimal(算力最优)规则自动推导。想跑大一点的模型?只改一个数字。

💡 为什么要这样设计?
任何提交到主线的改动都要求「在各 depth 下都成立」,单一旋钮让 scaling 实验和社区对比变得极其干净——这是从 modded-nanoGPT 速度竞赛里继承的工程纪律。

硬件与成本

平台可行性说明
8×H100 节点★ 目标平台约 $24/小时;speedrun 约 1.5h(README 按 2 小时预算估约 $48);spot 实例可低至 ~$15
8×A100 (Ampere)✅ 可跑更慢,但完整流程可运行
单张 GPU✅ 可跑自动梯度累积模拟 8 卡,约慢 8 倍
显存 < 80GB✅ 可跑调小 --device-batch-size 即可
CPU / Apple MPS✅ 小模型float32(macOS MPS 也支持 bf16,省约 25% 内存),见 runs/runcpu.sh
ℹ️ 成本对比
2019 年 OpenAI 训练 GPT-2 花费约 $43,000;nanochat 用不到 $50 超过它——六年五个数量级的进步缩影。项目贡献目标:让 <$1000 预算的端到端可对话模型成为人人可复现的事。

与 nanoGPT 的关系

nanoGPT (2022)nanochat (2025)
覆盖范围仅预训练 + 采样分词器 → 预训练 → SFT → 评测 → 推理全流程
目标复现 GPT-2$100 训练可对话模型(Speedrun 竞赛)
架构GPT-2 原味(LayerNorm/GELU/可学习位置嵌入)现代架构(RoPE/GQA/QK-norm/relu²/Muon 等)
推理朴素 generate(无 KV cache)专用引擎:KV cache + 批量采样 + 工具调用
代码组织两个 ~300 行脚本核心库 + scripts + runs 的模块化布局

名字直接源自 nanoGPT;预训练实现大量借鉴 modded-nanoGPT(含其游戏化传统:排行榜 + 清晰指标)。致谢 HuggingFace(FineWeb、SmolTalk 数据)、Lambda(算力)与 Alec Radford。

社区与 AI 政策

CH.2项目结构

目录树总览

  • nanochat/仓库根目录
    • nanochat/核心库(import nanochat.*)
      • gpt.py★ Transformer 模型定义
      • engine.py★ KV cache 推理引擎 + 工具调用
      • optim.pyAdamW + Muon 优化器
      • tokenizer.pyGPT-4 风格 BPE 分词器 + 对话模板
      • dataloader.pyFineWeb token 流数据加载
      • core_eval.pyCORE 指标评测
      • loss_eval.pybpb(bits per byte)评测
      • checkpoint_manager.pycheckpoint 存取管理
      • execution.pyPython 工具的安全执行
      • common.py公共工具
    • scripts/可执行训练 / 评测脚本
      • base_train.py★ 预训练(--depth 旋钮)
      • base_eval.pyCORE 分数 + bpb 评测
      • chat_sft.py★ SFT 对话微调
      • chat_rl.py强化学习(可选,不在 speedrun 主线)
      • chat_eval.pyChatCORE 评测
      • chat_cli.py★ 终端对话
      • infer_bench.py推理性能基准
      • tok_train.py分词器训练
      • tok_eval.py分词器评估(压缩率等)
    • runs/一键流程脚本
      • speedrun.sh★ $100 全流程(8×H100 约 1.5h)
      • miniseries.sh小规模系列实验
      • scaling_laws.sh缩放定律实验
      • runcpu.shCPU / MPS 小模型示例
    • tasks/mmlu / gsm8k / humaneval / arc / smoltalk
    • tests/attention 回退、engine、execution、optim、tokenizer 测试
    • dev/数据重打包参考脚本与图片

核心文件职责

文件职责关键点
nanochat/gpt.py模型定义RoPE、GQA、QK-norm、滑动窗口、Value Embedding、relu² MLP、残差流 λ 缩放、Muon+AdamW 分组优化器(见第 7 章)
nanochat/engine.py推理引擎FA3 原生 KV cache 布局、prefill + 克隆批量采样、计算器工具状态机(见第 9 章)
nanochat/tokenizer.py分词器 + 对话模板GPT-4 风格 BPE,词表 32768;render_conversation 渲染对话并生成损失 mask
nanochat/optim.py优化器Muon(矩阵专用)与 AdamW 实现
runs/speedrun.sh全流程编排数据 → 分词器 → 预训练 → 评测 → SFT → 评测(见第 4 章)
scripts/chat_sft.pySFTSmolTalk+MMLU+GSM8K 混合、best-fit 打包、ChatCORE 评测(见第 8 章)
💡 阅读顺序建议
先跑通 speedrun.sh 感受全流程 → 读 gpt.py(现代架构浓缩版)→ 读 chat_sft.py(对话怎么教)→ 读 engine.py(推理与工具调用)→ 最后精读 speedrun.sh 把流程串起来。

CH.3环境准备与安装

用 uv 安装

nanochat 用 uv 管理依赖(比 pip 更快、锁定版本):

bash安装依赖
# CUDA(A100 / H100 等)
uv sync --extra gpu

# 仅 CPU / Apple MPS
uv sync --extra cpu

# 激活虚拟环境
source .venv/bin/activate

# 开发环境(含测试等 dev 依赖组)
uv sync --extra gpu --group dev

硬件要求矩阵

见第 1.3 节的表格。要点重述:目标平台 8×H100(80GB);8×A100 可跑但更慢;单卡自动梯度累积(慢约 8 倍);显存不足调小 --device-batch-size;CPU/MPS 走 runs/runcpu.sh 的小模型路径。

精度管理 COMPUTE_DTYPE

nanochat 的精度策略与常见做法不同,值得专门理解:

⚠️ speedrun 用 fp8
主线 speedrun 的预训练命令带 --fp8(H100 原生支持);排行榜上「d26 + fp8」正是靠它从 3.04h 压到 2.91h 的关键一步。

CH.4快速开始:speedrun 一键全流程

一条命令全流程

bash8×H100 · 约 1.5 小时
git clone https://github.com/karpathy/nanochat
cd nanochat
uv sync --extra gpu
source .venv/bin/activate

bash runs/speedrun.sh

这一个脚本串起五个阶段,产物统一放在 ~/.cache/nanochat(可用 NANOCHAT_BASE_DIR 覆盖):

① 数据下载→ ② 分词器训练→ ③ 预训练 d24→ ④ 基础评测→ ⑤ SFT + 对话评测

阶段一:数据下载

脚本先用前台快速下载 8 个分片(约 20 亿字符、磁盘约 800MB),让后续步骤尽早开工;同时在后台继续拉取约 170 个分片供预训练消费(数据集全量最多 6542 个分片):

bash前台先下 8 片,后台继续补
python -m nanochat.dataset -n 8

阶段二:分词器训练

bash词表大小 2^15 = 32768
# 在已下载数据上训练 GPT-4 风格 BPE 分词器
python -m scripts.tok_train

# 评估:报告压缩率等指标
python -m scripts.tok_eval

阶段三:预训练

bash8 卡 DDP · d24 · fp8
# 等后台数据下载完成
wait

torchrun --standalone --nproc_per_node=8 -m scripts.base_train -- \
    --depth=24 \
    --target-param-data-ratio=8 \
    --device-batch-size=16 \
    --fp8 \
    --run=$WANDB_RUN

两个值得注意的参数:

阶段四:基础评测

bashCORE 指标 + bpb + 抽样生成
torchrun --standalone --nproc_per_node=8 -m scripts.base_eval -- --device-batch-size=16

阶段五:SFT 对话微调

bash教会对话 / 工具 / 多选题
# SFT:对话特殊 token、工具使用、多选题
torchrun --standalone --nproc_per_node=8 -m scripts.chat_sft -- --run=$WANDB_RUN

# 对话评测
torchrun --standalone --nproc_per_node=8 -m scripts.chat_eval -- -i sft

产物、时长与对话

bash与你的模型聊天
python -m scripts.chat_cli
ℹ️ speedrun 主线没有 RL 阶段
仓库提供 scripts/chat_rl.py(强化学习,见 8.4),但 speedrun.sh 主线不含 RL:tokenizer → 预训练 → 评测 → SFT → 评测五段已足够产出「$100 ChatGPT」。

CH.5低成本实验路径

d12 快速迭代

日常实验不必上 d24:d12(GPT-1 规模)约 5 分钟就能完成一次预训练迭代,适合快速验证改动:

bashd12 快速实验
torchrun --standalone --nproc_per_node=<卡数> -m scripts.base_train -- --depth=12 ...

用 wandb 监控 val_bpb、core_metric、MFU 与吞吐——改动是否有效,五个分钟级实验就能看清。

单卡 / 显存不足

CPU 与 Apple Silicon

参考 runs/runcpu.sh:小 depth 模型 + float32 即可在笔记本 CPU / MPS 上跑通全流程。macOS 的 MPS 后端还支持 bf16,可省约 25% 内存。

CH.6现代 GPT 架构速览

nanochat 的 gpt.py 是一份「2025 年主流做法浓缩版」。本章把每个组件讲清,下一章对照代码。

从 GPT-2 到 2025

组件nanoGPT(GPT-2 风格)nanochat(现代风格)
位置编码可学习绝对位置嵌入RoPE(旋转位置编码,无嵌入参数)
归一化LayerNorm(带参数)无参数 RMSNorm
激活GELUrelu²
注意力MHA + 因果掩码GQA + QK-norm + 滑动窗口 + FA3
MLP4× 升维 GELU4× 升维 relu²
输出头与输入嵌入共享权重untied(不共享)
残差纯相加resid/x0 λ 缩放 + smear + backout
优化器AdamWMuon(矩阵)+ 分组 AdamW
数值fp32/bf16显式 COMPUTE_DTYPE + fp8 + logit softcap

RoPE 旋转位置编码

把每个位置的 query/key 向量按角度 θ 旋转,两个位置的相对角度差编码了相对距离——注意力点积天然只依赖相对角度,因此外推性和参数效率都优于可学习的绝对位置嵌入。nanochat 中 base=100000,cos/sin 预计算为 buffer(按 sequence_len × 10 超额预计算),实现按 −θ 方向旋转(与教科书约定相反,仅相对旋转有意义,为 checkpoint 兼容保留)。

GQA 与 QK-norm

滑动窗口注意力

默认窗口模式 "SSSL":S = 1/4 上下文的局部窗口,L = 全上下文;即每 4 层里 3 层看局部,第 4 层看全局,最后一层强制全局。S 窗口按源码公式 ceil(long_window / 4 / 128) × 128 向上取整到 FA3 tile 128 的倍数——2048 上下文即 2048/4=512(恰为 128 倍数),S 窗口 = 512。局部注意力省算力,穿插的全局层保证远距离信息仍然流通。

Value Embedding(ResFormer 风格)

在交替层(与最后一层同奇偶的层)给 value 注入一个「绝对位置嵌入」,通过逐头门控 3 × sigmoid(gate)(范围 0~3)混入 v。RoPE 只编码相对位置,value embedding 补回了绝对位置信息——两条路径互补。

relu² MLP

MLP 不是 swiGLU:c_fc(768→3072)→ relu(x)² → c_proj(3072→768),无 bias。relu² 的平滑平方在 modded-nanoGPT 系实验中表现优于 GELU,且计算更便宜。

残差流技巧四件套

nanochat 对残差流(residual stream)做了四项精细手术:

  1. resid_lambdas:每层一个可学习标量缩放残差贡献,按 1.15 − 0.10·i/(n_layer−1) 从 1.15 线性衰减到 1.05——深层贡献递减;
  2. x0_lambdas:把初始嵌入持续混回残差流(初始化 0.20 衰减到 0.05),防止信息在深层被冲淡;
  3. smear:smear_lambda · sigmoid(smear_gate(x[..., :24])) 把前一个 token 的嵌入混入当前 token——给注意力提供廉价的 bigram 先验(推理时由 KV cache 的 prev_embedding 支持);
  4. backout:缓存中层(n_layer // 2)的残差,最后减去 0.2 × x_backout——抵消中途注入的偏置。

softcap 与 untied

CH.7gpt.py 逐段精讲

GPTConfig 配置

pythondataclass 默认值(d12 规模)
sequence_len = 2048      # 上下文长度
vocab_size   = 32768      # 分词器词表 2^15
n_layer      = 12         # 深度(--depth 旋钮就是它)
n_head       = 6          # query 头数
n_kv_head    = 6          # KV 头数(GQA 接口,可改为共享)
n_embd       = 768        # 宽度 → head_dim = 768/6 = 128
window_pattern = "SSSL"  # 滑动窗口模式,最后一层强制全局

注意 head_dim=128 是 FA3 友好的维度;q/k 张量直接以 (B, T, H, D) 布局(FA3 原生),省去转置。

CausalSelfAttention

python核心流程(节选)
# 1) 无 bias 投影出 q/k/v(GQA:kv 头数可少于 q 头数)
q = self.c_q(x); k = self.c_k(x); v = self.c_v(x)

# 2) RoPE 旋转 → QK-norm → 乘 1.2 锐化
q, k = apply_rotary_emb(q, k, cos, sin)
q = F.rms_norm(q) * 1.2
k = F.rms_norm(k) * 1.2

# 3) Value Embedding:交替层把绝对位置嵌入以 3*sigmoid 门控混入 v
if has_ve(self.layer_idx):
    v = v + 3 * torch.sigmoid(self.ve_gate) * value_embedding

# 4) Flash Attention:训练 flash_attn_func(FA3 优先,SDPA 回退)
#    推理 flash_attn_with_kvcache,处理完后 kv_cache.advance(T)

Block 与残差流

Pre-norm 结构(RMSNorm 无参数):x = λ_resid·x + attn(norm(x))、x = λ_resid·x + mlp(norm(x)),外加 x0 回混、smear 与中层 backout 的管理(详见 6.7)。骨干里的 norm 同样无可学习参数——整份模型里「标量可学习参数」只剩各种 λ 和门控。

分层初始化

__init__ 在 meta device 上只确定形状与 dtype(不占显存),真正赋值在 init_weights():

参数初始化意图
wtenormal std=0.8嵌入大尺度初始化
lm_headnormal std=0.001输出头接近零起步
注意力矩阵uniform,std=1/√n_embd方差控制
attn.c_proj / mlp.c_proj置零每块初始为零贡献(配合 λ 缩放)
mlp.c_fc0.4× 缩放压低 MLP 初期幅度
ve_gate / smear_gateuniform [0, 0.02]门初始略偏正

参数量与 FLOPs 估算

gpt.py 自带一组成本估算工具:num_matmul_params(矩阵参数量)、estimate_flops(6×参数 + 按窗口调整的注意力项 12·h·q·有效序列长)、estimate_decode_flops / estimate_prefill_flops / kv_bytes_per_token / kv_read_bytes(推理成本)。num_scaling_params 还按 Kaplan(排除嵌入)与 Chinchilla(全部)两种口径分组统计——做 scaling law 实验时直接可用。

setup_optimizer:Muon + 分组 AdamW

forward 与 generate

forward(idx, targets, kv_cache):截取 RoPE cos/sin(有 kv_cache 时用 get_pos() 偏移)→ 嵌入 → norm → smear(训练用切片,推理用缓存)→ 逐层 Block(λ 管理 + value embed 注入 + 中层 backout 缓存)→ 减 backout → norm → lm_head → 裁剪 → fp32 → softcap → 交叉熵。

generate 是 @torch.inference_mode() 的流式生成器(yield),支持 temperature/top-k,temperature>0 时用带 seed 的 Generator 采样,否则 argmax。注意它是朴素实现(无 KV cache),正确性参考;高速路径在第 9 章的 engine.py(测试会逐 token 校验两者一致)。

CH.8训练脚本精讲

base_train 与 depth 旋钮

chat_sft:数据配方

数据集规模epoch教什么
SmolTalk(train)约 46 万条对话1(跑满)通用对话能力
MMLU auxiliary_train每 epoch 约 10 万条3多选题 / 知识问答
GSM8K train每 epoch 约 8 千条4数学 + 工具调用
验证集SmolTalk test 24K + MMLU test 5.2K + GSM8K test 420—val bpb / ChatCORE

chat_sft:训练细节

chat_rl 强化学习

仓库提供 scripts/chat_rl.py 做 RL 阶段,但注意两点:不在 speedrun 主线(见 4.7 的提示);且 RL 尚不支持 fp16(GradScaler 限制)。对 $100 目标而言,SFT 后的模型已可用,RL 属于进阶加分项。

评测脚本一览

脚本用途
base_eval.pyCORE 指标、train/val bpb、抽样生成
chat_eval.pyChatCORE(-i sft 指定 SFT checkpoint)
tok_eval.py分词器压缩率评估
infer_bench.py推理引擎性能基准

CH.9推理引擎 engine.py

engine.py 是一份「纯 token id 级别」的推理引擎——引擎对分词一无所知(工具调用除外,需借助 tokenizer),只接收/返回 token id。文件注释目标:尽可能高效。

KV Cache 架构

采样与流式生成

内置计算器工具

引擎内置一个带超时保护(SIGALRM)的受限 eval 计算器:支持纯数学表达式和 .count() 字符串操作,封禁 **、dunder、import/exec 等。工作流:

模型输出 <|python_start|>表达式<|python_end|>→ 引擎执行表达式→ <|output_start|>结果<|output_end|> 作为强制 token 注入→ 模型基于结果继续作答

RowState 状态机跟踪 python 块、强制 token 队列与行完成状态——这就是 GSM8K「数学 + 工具使用」在推理期的兑现。

chat_cli 对话

bash交互式聊天 / 单次提问
# 交互式对话
python -m scripts.chat_cli

# 单次提问(-p)
python -m scripts.chat_cli -p "hello"

# 用环境变量控制精度
NANOCHAT_DTYPE=float32 python -m scripts.chat_cli -p "1+1等于几?"

CH.10分词器与对话模板

GPT-4 风格 BPE

nanochat/tokenizer.py 实现 GPT-4 风格 BPE,词表 32768(2^15)——由 tok_train.py 在下载的 FineWeb 样本上从零训练,tok_eval.py 评估压缩率。相比 nanoGPT 直接借用 GPT-2 的 50257 词表,从零训练小词表让 embedding 参数更省、与模型规模更匹配。

对话模板与损失 mask

对话渲染集中在 tokenizer.render_conversation(conversation),返回 ids, mask:

CH.11Speedrun 排行榜

规则:墙钟时间击败 GPT-2

排行榜的指标干净利落:以「墙钟时间」计,训练出一个 DCLM CORE 分数超过 GPT-2(1.6B 参数,CORE 0.256525)的模型要多久。计时覆盖完整流程。

战绩演进表

#墙钟时间关键改动
0168hOpenAI 原始 GPT-2(2019 年,约 $43,000)
13.04hd24 基线(Karpathy 初始版本)
22.91hd26 + fp8
32.76h批量增大至 1M tokens
42.02h换用 NVIDIA ClimbMix 数据集
51.80hautoresearch round 1
61.65hautoresearch round 2

游戏化的意义

这套「排行榜 + 单一清晰指标」的玩法继承自 modded-nanoGPT 速度竞赛:它把分布式训练、数据、优化器、数值精度等所有工程创新压缩进一个可比的数字,任何人拿出更快的一步就能上榜——nanochat 主线当前的 1.5 小时,正是这场持续竞赛的成果。「autoresearch」条目甚至开始由自动化研究流程贡献改进。

CH.12评测体系

CORE 指标与 bpb

ChatCORE

SFT 后的对话评测指标:对 ARC-Easy / ARC-Challenge / MMLU / GSM8K / HumanEval 取中心化平均准确率(减去随机基线再平均),由 chat_eval.py -i sft 输出,训练过程中也会周期性计算。任务实现在 tasks/ 目录(mmlu、gsm8k、humaneval、arc、smoltalk)。

infer_bench

scripts/infer_bench.py 基准化推理引擎的吞吐(结合 gpt.py 的 decode/prefill FLOPs 与 KV 字节估算工具,可精确分析推理瓶颈)。

CH.13常见问题排查

FAQ 清单

症状 / 问题原因与解法
显存不足(OOM)调小 --device-batch-size;框架自动用梯度累积补偿;MPS 可用 bf16 省约 25% 内存
只有一张 GPU直接跑,自动梯度累积等效 8 卡(约慢 8 倍);不必改代码
fp8 报错或不生效fp8 需要 H100 级硬件支持;A100/Ampere 用 bf16 路径
RL 阶段崩溃RL 尚不支持 fp16;确认没有强制 fp16 精度
数据下载太慢speedrun 前台先下 8 片(~800MB)就开工、后台补量;全量最多 6542 片,检查磁盘与网络
找不到 checkpoint统一在 NANOCHAT_BASE_DIR(默认 ~/.cache/nanochat);SFT 在 chatsft_checkpoints/<tag 或 dN>/
wandb 一直没记录默认 WANDB_RUN=dummy 跳过日志;需要监控时自行设置 run 名
想小成本试改动用 --depth=12 做 5 分钟级迭代实验,再上 d24/d26 验证「各 depth 都成立」
对话效果差确认 SFT 跑完且用 chat_eval -i sft 检查 ChatCORE;CLI 指定对 checkpoint
Windows 上能跑吗面向 Linux 训练节点设计;建议 WSL2 + uv;CPU 小模型路径(runcpu.sh)最稳妥

CH.14进阶路径

学习路线建议

  1. 前置:先读 nanoGPT(GPT-2 原味实现,几百行读懂注意力与训练循环);
  2. 跑通:clone nanochat,跑 speedrun.sh(或先 runcpu.sh 小模型),用 chat_cli 和自己训的模型聊天;
  3. 对照:按第 6 章的对照表逐项看 gpt.py 如何把 GPT-2 现代化(RoPE/GQA/Muon/残差流手术);
  4. 实验:d12 快速迭代 + wandb 监控 val_bpb/CORE,做自己的 scaling 曲线;
  5. 贡献:fork 并尝试压缩预训练时间——所有改动须在各 depth 下成立,遵守 AI 政策(声明 LLM 大幅参与的代码)。

仓库实验脚本

脚本用途
runs/miniseries.sh小规模系列实验
runs/scaling_laws.sh缩放定律实验(配合 num_scaling_params 的 Kaplan/Chinchilla 口径)
runs/runcpu.shCPU / MPS 小模型全流程
tests/attention 回退、engine 一致性、execution、optim、tokenizer 单元测试

Fork 方向建议

引用与社区

bibtex官方引用格式
@misc{nanochat,
  author = {Andrej Karpathy},
  year   = {2025}
}
从 nanoGPT 的「读懂 GPT」到 nanochat 的「100 美元拥有自己的 ChatGPT」——Karpathy 用两个仓库把 LLM 的过去与现在都留给了学习者。