nanochat 完全教程
“The best ChatGPT that $100 can buy.”
Andrej Karpathy 2025 年的力作:在单个 GPU 节点上、约 100 美元预算内,从分词器、预训练、SFT 到推理 CLI,端到端训练一个能对话的 ChatGPT 风格模型。本教程覆盖:项目解读 → 架构原理 → 逐文件精讲 → 实战命令 → 评测与排行榜 → 故障排除。
仓库地址:github.com/karpathy/nanochat(MIT 协议 · 58k+ Stars)
CH.1项目概览
什么是 nanochat
nanochat 是一个极简的 LLM 全流程实验框架:从分词器训练、预训练、SFT 微调、评测到推理部署,覆盖构建一个对话助手的全部阶段,且整套流程跑在单个 GPU 节点上。它的口号是「100 美元能买到的最好的 ChatGPT」——在 8×H100 上约 1.5 小时跑完全流程(节点约 $24/小时,README 按 2 小时预算估约 $48,spot 实例可低至 ~$15),产出的模型质量超过 GPT-2。
它能做到的事情:
- 从零预训练一个现代架构的 base 模型(FineWeb 数据);
- SFT 教会它对话、工具调用与数学(SmolTalk + MMLU + GSM8K);
- 评测:CORE 指标、bpb、ChatCORE(MMLU/GSM8K/HumanEval/ARC);
- 推理:自带 KV cache 推理引擎与 CLI,训练完立刻能聊天。
设计哲学:一个旋钮
nanochat 刻意避免「配置繁重的框架」,定位是最小化、可 hack、可 fork 的强基线代码。最鲜明的体现是:整个系统只有一个复杂度旋钮 --depth(Transformer 层数),其余一切超参数——宽度、头数、学习率、训练时长、weight decay 等——全部按 compute-optimal(算力最优)规则自动推导。想跑大一点的模型?只改一个数字。
硬件与成本
| 平台 | 可行性 | 说明 |
|---|---|---|
| 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 |
与 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 政策
- 求助渠道:GitHub Discussions(如 2026-02-01 的《<$100 打败 GPT-2 之旅》帖)、Discord #nanochat 频道、DeepWiki;
- AI 政策:提交 PR 需明确声明哪些部分由 LLM 大幅参与编写、或自己不完全理解——保持「人类理解每一行」的社区底线;
- 当前主攻方向:压缩预训练时间(从 3h 压到 ~1.5h 并继续),所有改动须在各 depth 下都成立。
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.py | SFT | SmolTalk+MMLU+GSM8K 混合、best-fit 打包、ChatCORE 评测(见第 8 章) |
speedrun.sh 感受全流程 → 读 gpt.py(现代架构浓缩版)→ 读 chat_sft.py(对话怎么教)→ 读 engine.py(推理与工具调用)→ 最后精读 speedrun.sh 把流程串起来。
CH.3环境准备与安装
用 uv 安装
nanochat 用 uv 管理依赖(比 pip 更快、锁定版本):
# 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 的精度策略与常见做法不同,值得专门理解:
- 不用
torch.amp.autocast:通过全局COMPUTE_DTYPE显式管理精度; - 权重以 fp32 存储,forward 时由自定义
Linear层 cast 到计算精度; - embedding 直接以 COMPUTE_DTYPE 存储(省内存;fp16 除外——GradScaler 无法 unscale fp16 梯度);
- fp16 训练时自动启用
GradScaler(注意:RL 阶段尚不支持 fp16); - 默认选择:SM80+(Ampere 及以上)用 bf16;旧 CUDA 卡用 fp32(可选 fp16);CPU/MPS 用 fp32。
--fp8(H100 原生支持);排行榜上「d26 + fp8」正是靠它从 3.04h 压到 2.91h 的关键一步。
CH.4快速开始:speedrun 一键全流程
一条命令全流程
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 覆盖):
阶段一:数据下载
脚本先用前台快速下载 8 个分片(约 20 亿字符、磁盘约 800MB),让后续步骤尽早开工;同时在后台继续拉取约 170 个分片供预训练消费(数据集全量最多 6542 个分片):
python -m nanochat.dataset -n 8阶段二:分词器训练
# 在已下载数据上训练 GPT-4 风格 BPE 分词器
python -m scripts.tok_train
# 评估:报告压缩率等指标
python -m scripts.tok_eval阶段三:预训练
# 等后台数据下载完成
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两个值得注意的参数:
--depth=24:24 层主模型(宽度等超参自动推导);--target-param-data-ratio=8:训练 token 数 = 参数量 × 8。Chinchilla 最优约是 10.5,这里刻意略欠训练——用更少数据换取墙钟时间,恰好够击败 GPT-2,这是 speedrun 竞赛的成本权衡。
阶段四:基础评测
torchrun --standalone --nproc_per_node=8 -m scripts.base_eval -- --device-batch-size=16阶段五:SFT 对话微调
# 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产物、时长与对话
- 总时长:8×H100 约 1.5 小时;
- SFT checkpoint 保存在
chatsft_checkpoints/<tag 或 dN>/,含模型、优化器状态、配置与 val bpb; - 训练完即可对话(详见第 9.4 节):
python -m scripts.chat_cliscripts/chat_rl.py(强化学习,见 8.4),但 speedrun.sh 主线不含 RL:tokenizer → 预训练 → 评测 → SFT → 评测五段已足够产出「$100 ChatGPT」。
CH.5低成本实验路径
d12 快速迭代
日常实验不必上 d24:d12(GPT-1 规模)约 5 分钟就能完成一次预训练迭代,适合快速验证改动:
torchrun --standalone --nproc_per_node=<卡数> -m scripts.base_train -- --depth=12 ...用 wandb 监控 val_bpb、core_metric、MFU 与吞吐——改动是否有效,五个分钟级实验就能看清。
单卡 / 显存不足
- 单张 GPU:直接跑
base_train,框架自动梯度累积等效 8 卡 batch(约慢 8 倍); - 显存 < 80GB:调小
--device-batch-size(框架会自动增加累积步数补偿); - fp8 只在 H100 等支持硬件上开启。
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 |
| 激活 | GELU | relu² |
| 注意力 | MHA + 因果掩码 | GQA + QK-norm + 滑动窗口 + FA3 |
| MLP | 4× 升维 GELU | 4× 升维 relu² |
| 输出头 | 与输入嵌入共享权重 | untied(不共享) |
| 残差 | 纯相加 | resid/x0 λ 缩放 + smear + backout |
| 优化器 | AdamW | Muon(矩阵)+ 分组 AdamW |
| 数值 | fp32/bf16 | 显式 COMPUTE_DTYPE + fp8 + logit softcap |
RoPE 旋转位置编码
把每个位置的 query/key 向量按角度 θ 旋转,两个位置的相对角度差编码了相对距离——注意力点积天然只依赖相对角度,因此外推性和参数效率都优于可学习的绝对位置嵌入。nanochat 中 base=100000,cos/sin 预计算为 buffer(按 sequence_len × 10 超额预计算),实现按 −θ 方向旋转(与教科书约定相反,仅相对旋转有意义,为 checkpoint 兼容保留)。
GQA 与 QK-norm
- GQA(分组查询注意力):多个 query 头共享一组 KV 头(
n_head=6、n_kv_head=6,留好接口可改为共享)。收益是 KV cache 与注意力计算大幅减小——推理便宜。 - QK-norm:RoPE 之后对 q、k 分别做 RMSNorm,再各乘 1.2(「更锐利的注意力」,把缩放分摊到 Q 和 K)。这是稳定深层训练的现代标配,能有效防止注意力 logits 爆炸。
滑动窗口注意力
默认窗口模式 "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)做了四项精细手术:
- resid_lambdas:每层一个可学习标量缩放残差贡献,按
1.15 − 0.10·i/(n_layer−1)从 1.15 线性衰减到 1.05——深层贡献递减; - x0_lambdas:把初始嵌入持续混回残差流(初始化 0.20 衰减到 0.05),防止信息在深层被冲淡;
- smear:
smear_lambda · sigmoid(smear_gate(x[..., :24]))把前一个 token 的嵌入混入当前 token——给注意力提供廉价的 bigram 先验(推理时由 KV cache 的prev_embedding支持); - backout:缓存中层(
n_layer // 2)的残差,最后减去0.2 × x_backout——抵消中途注入的偏置。
softcap 与 untied
- logit softcap 15:
15 · tanh(logits / 15)把 logits 限制在 ±15 内再算交叉熵(转 fp32 计算),防极端 logits 破坏训练稳定; - untied 输出头:token embedding 与 lm_head 不共享权重(nanoGPT/GPT-2 是共享的),配合分层初始化(lm_head std=0.001)各司其职;
- 词表填充:32768 本就是 64 的倍数(DDP/tensor core 效率),forward 中按实际 vocab 裁剪。
CH.7gpt.py 逐段精讲
GPTConfig 配置
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
# 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():
| 参数 | 初始化 | 意图 |
|---|---|---|
wte | normal std=0.8 | 嵌入大尺度初始化 |
lm_head | normal std=0.001 | 输出头接近零起步 |
| 注意力矩阵 | uniform,std=1/√n_embd | 方差控制 |
attn.c_proj / mlp.c_proj | 置零 | 每块初始为零贡献(配合 λ 缩放) |
mlp.c_fc | 0.4× 缩放 | 压低 MLP 初期幅度 |
| ve_gate / smear_gate | uniform [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
- Muon(MuonAdamW,按形状分组、stacking)用于 transformer 矩阵参数,lr=0.02——Muon 是 modded-nanoGPT 速度竞赛的最大赢家之一;
- AdamW 分组:lm_head(unembedding_lr=0.004)、wte(embedding_lr=0.2)、value_embeds(0.5×)、resid/x0/smear 标量——各配不同 betas 与 weight decay;
- AdamW 学习率按 ∝ 1/√(d_model/768) 缩放,宽度变化时自动适配。
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 旋钮
- 唯一复杂度旋钮
--depth:宽度、头数、学习率、训练时长、weight decay 全部按 compute-optimal 推导; - 数据:FineWeb token 流(dataloader.py 内存映射加载);
--target-param-data-ratio控制训练量(speedrun 用 8,略低于 Chinchilla 最优 ~10.5);--fp8开启 H100 fp8 训练;--device-batch-size按显存调整。
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:训练细节
- 打包:best-fit 装箱,每行容量 max_seq_len+1(2049),放不下的对话用 BOS 填充而非截断;
- 损失 mask:只有 assistant 回复计损失(mask=1);user 输入、BOS、特殊 token、工具输出一律 mask=0,target 置 -1(ignore_index);
- 学习率:默认继承预训练 checkpoint 的优化器配置(可热启动优化器状态),初始 LR 乘 0.8;调度 warmup=0、warmdown 后半程线性降至 0(warmdown_ratio=0.5,按 progress 而非绝对步数);
- batch:total_batch_size=524288 token,device_batch_size=32,梯度累积自动推导;迭代数默认 -1 = 跑满一个 epoch;
- 优化器:Muon(矩阵,momentum 0.85→0.95 线性升 300 步)+ AdamW,weight_decay=0;
- 评测:每 200 步估 val bpb(4M token),结束输出 ChatCORE;checkpoint 存
chatsft_checkpoints/<tag 或 dN>/。
chat_rl 强化学习
仓库提供 scripts/chat_rl.py 做 RL 阶段,但注意两点:不在 speedrun 主线(见 4.7 的提示);且 RL 尚不支持 fp16(GradScaler 限制)。对 $100 目标而言,SFT 后的模型已可用,RL 属于进阶加分项。
评测脚本一览
| 脚本 | 用途 |
|---|---|
base_eval.py | CORE 指标、train/val bpb、抽样生成 |
chat_eval.py | ChatCORE(-i sft 指定 SFT checkpoint) |
tok_eval.py | 分词器压缩率评估 |
infer_bench.py | 推理引擎性能基准 |
CH.9推理引擎 engine.py
engine.py 是一份「纯 token id 级别」的推理引擎——引擎对分词一无所知(工具调用除外,需借助 tokenizer),只接收/返回 token id。文件注释目标:尽可能高效。
KV Cache 架构
- 自定义
KVCache为 Flash Attention 3 量身定制:张量布局 (B, T, H, D)(FA2 是 B,H,T,D),由flash_attn_with_kvcache原地更新; - 用 int32 的
cache_seqlens逐 batch 元素追踪序列位置; - prefill + 克隆:先把 batch=1 的提示词预填充进缓存,再把缓存复制到 batch=N 的采样缓存——一次 prefill,多路并行采样;
- 无 fp8/int8 量化:KV cache 与前向统一 COMPUTE_DTYPE。
采样与流式生成
sample_next_token:temperature=0 直接 argmax;否则 top-k 截断 + softmax + multinomial,可指定 seed 的torch.Generator保证可复现;generate是生成器:逐 token 列产出token_column, token_masks(mask 标记该 token 是采样所得还是强制注入);- 停止条件:达到 max_tokens,或所有行完成(采样到
<|assistant_end|>或 BOS); - 自测:
__main__会逐 token 校验「朴素的 model.generate」与「高速的 Engine.generate」输出一致,并打印两者耗时对比。
内置计算器工具
引擎内置一个带超时保护(SIGALRM)的受限 eval 计算器:支持纯数学表达式和 .count() 字符串操作,封禁 **、dunder、import/exec 等。工作流:
RowState 状态机跟踪 python 块、强制 token 队列与行完成状态——这就是 GSM8K「数学 + 工具使用」在推理期的兑现。
chat_cli 对话
# 交互式对话
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:
- BOS 对齐:每行以 BOS 开头,padding 也用 BOS 填充;
- 存在结构化的对话标记(im_start/im_end 风格)与工具标记(
<|python_start|>等,见 9.3); - mask=1 仅对 assistant 回复计损失;user 提示、BOS、特殊 token、工具输出全部 mask=0(target=-1)——模型只学「怎么答」,不学「怎么问」。
CH.11Speedrun 排行榜
规则:墙钟时间击败 GPT-2
排行榜的指标干净利落:以「墙钟时间」计,训练出一个 DCLM CORE 分数超过 GPT-2(1.6B 参数,CORE 0.256525)的模型要多久。计时覆盖完整流程。
战绩演进表
| # | 墙钟时间 | 关键改动 |
|---|---|---|
| 0 | 168h | OpenAI 原始 GPT-2(2019 年,约 $43,000) |
| 1 | 3.04h | d24 基线(Karpathy 初始版本) |
| 2 | 2.91h | d26 + fp8 |
| 3 | 2.76h | 批量增大至 1M tokens |
| 4 | 2.02h | 换用 NVIDIA ClimbMix 数据集 |
| 5 | 1.80h | autoresearch round 1 |
| 6 | 1.65h | autoresearch round 2 |
游戏化的意义
这套「排行榜 + 单一清晰指标」的玩法继承自 modded-nanoGPT 速度竞赛:它把分布式训练、数据、优化器、数值精度等所有工程创新压缩进一个可比的数字,任何人拿出更快的一步就能上榜——nanochat 主线当前的 1.5 小时,正是这场持续竞赛的成果。「autoresearch」条目甚至开始由自动化研究流程贡献改进。
CH.12评测体系
CORE 指标与 bpb
- bpb(bits per byte):按字节计的交叉熵损失——跨分词器可比的标准语言建模指标(train/val 都报告);
- CORE:DCLM 的下游基准聚合分数,speedrun 排行榜的通关标准(GPT-2 XL 为 0.256525);
- 实现分布在
core_eval.py与loss_eval.py,由base_eval.py调用。
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进阶路径
学习路线建议
- 前置:先读 nanoGPT(GPT-2 原味实现,几百行读懂注意力与训练循环);
- 跑通:clone nanochat,跑
speedrun.sh(或先runcpu.sh小模型),用chat_cli和自己训的模型聊天; - 对照:按第 6 章的对照表逐项看 gpt.py 如何把 GPT-2 现代化(RoPE/GQA/Muon/残差流手术);
- 实验:d12 快速迭代 + wandb 监控 val_bpb/CORE,做自己的 scaling 曲线;
- 贡献:fork 并尝试压缩预训练时间——所有改动须在各 depth 下成立,遵守 AI 政策(声明 LLM 大幅参与的代码)。
仓库实验脚本
| 脚本 | 用途 |
|---|---|
runs/miniseries.sh | 小规模系列实验 |
runs/scaling_laws.sh | 缩放定律实验(配合 num_scaling_params 的 Kaplan/Chinchilla 口径) |
runs/runcpu.sh | CPU / MPS 小模型全流程 |
tests/ | attention 回退、engine 一致性、execution、optim、tokenizer 单元测试 |
Fork 方向建议
- 压时间:当前主攻方向(1.5h → ?),从数据、调度、优化器、精度入手;
- 换数据:中文语料 / 自己领域的语料重跑 tokenizer 与预训练(参考
dev/的数据重打包脚本); - 加能力:扩 SFT 配方(tasks/ 加任务)、上 RL(chat_rl.py,注意 fp16 限制);
- 做研究:残差流技巧、value embedding、Muon 的消融实验——gpt.py 结构干净,改起来顺手。
引用与社区
@misc{nanochat,
author = {Andrej Karpathy},
year = {2025}
}- 社区:Discord #nanochat 频道、GitHub Discussions(推荐 2026-02-01 的《<$100 打败 GPT-2 之旅》帖)、DeepWiki;
- 相关项目:nanoGPT(前身)、modded-nanoGPT(speedrun 传统与多数训练技巧的源头)。
从 nanoGPT 的「读懂 GPT」到 nanochat 的「100 美元拥有自己的 ChatGPT」——Karpathy 用两个仓库把 LLM 的过去与现在都留给了学习者。