nanoGPT 完全教程
The simplest, fastest repository for training/finetuning medium-sized GPTs.
一个用约 300 行 model.py + 约 300 行 train.py 就能从零训练、微调、推理 GPT 的极简仓库。本教程覆盖:项目解读 → 原理 → 逐文件精讲 → 各平台实战命令 → 性能优化 → 故障排除。
仓库地址:github.com/karpathy/nanoGPT(MIT 协议 · 63k+ Stars)
CH.1项目概览
什么是 nanoGPT
nanoGPT 是 Andrej Karpathy 编写的 GPT 训练/微调仓库,自我定位是「训练中等规模 GPT 的最简单、最快的代码库」。它把一个完整可用的 GPT 压缩到极致:
model.py(约 300 行):完整的 GPT 模型定义 —— 嵌入、因果自注意力、MLP、Transformer Block、生成采样、加载 OpenAI GPT-2 预训练权重、优化器配置,全在一个文件里。train.py(约 300 行):完整的训练循环 —— 数据加载、混合精度、梯度累积、DDP 多卡分布式、学习率调度、checkpoint 保存、wandb 日志,同样一个文件搞定。
它能做到的事情包括:
- 从零训练一个字符级的迷你 GPT(笔记本 CPU 上 3 分钟跑完);
- 在 OpenWebText 上复现 GPT-2 124M(8×A100 约 4 天,验证 loss ≈ 2.85);
- 微调预训练 GPT-2 到你自己的数据集(单卡几分钟);
- 直接加载 gpt2 / medium / large / xl 权重做文本生成。
作者 Andrej Karpathy
OpenAI 创始成员、前 Tesla AI 总监,也是著名课程 「Neural Networks: Zero To Hero」的作者。他一贯的风格是:用最少、最直白的代码把复杂系统讲透(代表作还有 micrograd、minGPT、nanoGrad、"Let's build GPT" 视频等)。nanoGPT 正是这种哲学的产物——删掉一切非必要抽象,让每一行代码都能被读完、读懂、改对。
nanoGPT vs minGPT
| minGPT | nanoGPT | |
|---|---|---|
| 定位 | 教学,配合课程讲解 | 实用,真的能训练出好模型 |
| 性能优化 | 基本没有 | torch.compile、Flash Attention、bfloat16、DDP |
| 规模上限 | 玩具级 | 可复现 GPT-2 124M(8×A100 · 4 天) |
| 加载 GPT-2 权重 | 有 | 有(from_pretrained) |
| 代码量 | 较分散 | model.py + train.py 各约 300 行 |
项目现状与定位
为什么值得学习
- 完整性:tokenizer 之外的一切(模型、训练、分布式、采样)都在两个文件里,没有框架魔法。
- 工业级技巧集:Flash Attention、混合精度、梯度累积、DDP 梯度同步控制、weight decay 分组、Chinchilla 思路的学习率调度……这些正是真实 LLM 训练的缩影。
- 可改可玩:改一个超参数就能做 scaling 实验;仓库还带
scaling_laws.ipynb和transformer_sizing.ipynb两个实验笔记本。 - 面试硬通货:能把 nanoGPT 讲清楚 = 把 GPT 讲清楚。
CH.2项目结构
目录树总览
- nanoGPT/仓库根目录
- assets/README 图片资源
- config/训练 / 微调 / 评估配置脚本
- train_shakespeare_char.py字符级莎士比亚训练配置
- train_gpt2.pyGPT-2 124M 复现配置
- finetune_shakespeare.py微调配置
- eval_gpt2*.py各规格 GPT-2 评估配置
- data/数据准备脚本(每个子目录一个数据集)
- shakespeare_char/prepare.py字符级莎士比亚(入门)
- shakespeare/prepare.pyBPE 编码莎士比亚(微调用)
- openwebtext/prepare.pyOpenWebText(复现 GPT-2)
- model.py★ GPT 模型定义(约 300 行)
- train.py★ 训练脚本(约 300 行)
- sample.py★ 采样 / 推理脚本
- bench.py基准测试 & 性能分析
- configurator.py命令行 / 配置文件覆盖全局变量
- scaling_laws.ipynb缩放定律实验
- transformer_sizing.ipynb模型尺寸估算实验
核心文件职责
| 文件 | 职责 | 关键点 |
|---|---|---|
model.py | 定义 GPT | LayerNorm / CausalSelfAttention / MLP / Block / GPT 五个类;generate() 自回归采样;from_pretrained() 加载 OpenAI 权重;configure_optimizers() 分组 weight decay |
train.py | 训练循环 | 「穷人的数据加载器」直接 memmap 读 .bin;DDP + 梯度累积;余弦学习率 + warmup;bf16 + torch.compile |
sample.py | 推理生成 | 加载 checkpoint 或 gpt2 系列权重,支持 temperature / top_k / 文件提示词 |
configurator.py | 配置覆盖 | 让 --key=value 直接覆盖 train.py / sample.py 里的全局变量,无需 argparse |
bench.py | 性能基准 | 只保留训练循环内核,配合 profiler 分析耗时 |
data/shakespeare_char/prepare.py(看数据长什么样)→ model.py(看模型)→ train.py(看训练)→ sample.py(看生成)。四个文件读完全部加起来不到 1000 行。
CH.3环境准备与安装
依赖清单
| 包 | 用途 | 必需? |
|---|---|---|
torch | PyTorch ≥ 2.0(torch.compile 需要 2.0+) | 必需 |
numpy | memmap 读取 .bin 数据 | 必需 |
transformers | 加载 OpenAI GPT-2 checkpoint(仅 from_pretrained 时) | 用预训练权重时需要 |
datasets | 下载预处理 OpenWebText | 训练 GPT-2 复现时需要 |
tiktoken | OpenAI 的 BPE 分词器 | BPE 数据 / gpt2 采样时需要 |
wandb | 训练日志可视化 | 可选 |
tqdm | 进度条 | 数据准备时需要 |
requests | 下载 tiny shakespeare | 数据准备时需要 |
安装步骤
pip install torch numpy transformers datasets tiktoken wandb tqdm平台注意事项
- NVIDIA GPU:先按官网命令装好 CUDA 版 PyTorch,其余依赖直接 pip。
- Windows:
torch.compile在 Windows 上不可用,训练时务必加--compile=False(会慢一些,功能不受影响)。 - Apple Silicon (M1/M2/M3):用
--device=mps走 Metal 加速,相比 CPU 约快 2~3 倍(详见仓库 Issue #28)。 - 纯 CPU:完全可以跑通字符级莎士比亚示例(见第 4 章),约 3 分钟。
CH.4快速开始:字符级莎士比亚
这是官方推荐的入门实验:在 tiny shakespeare 数据集上训练一个字符级 GPT,体量小到任何机器都能跑。
三步跑通
# 1. 下载并预处理数据 → 生成 train.bin / val.bin / meta.pkl
python data/shakespeare_char/prepare.py
# 2. 训练(按 config/train_shakespeare_char.py 中的配置)
python train.py config/train_shakespeare_char.py
# 3. 用训好的模型生成文本
python sample.py --out_dir=out-shakespeare-char第一步:准备数据
prepare.py 做了四件事:
- 从 GitHub(karpathy 的 char-rnn 仓库)下载
tinyshakespeare(约 1MB 的莎士比亚风格剧本); - 把文本拆成字符集合,排序后得到 65 个字符的词表(大小写字母 + 标点 + 空格等);
- 构建
stoi(字符→整数)与itos(整数→字符)映射,将全文编码为整数序列; - 按 90% / 10% 切分为
train.bin(约 100 万 token)与val.bin(约 11 万 token),以uint16二进制存储,并把词表信息存进meta.pkl。
np.memmap 内存映射二进制文件、随机采样片段,免去每次 decode 文本和运行 tokenizer 的开销——这就是 Karpathy 所谓的「穷人的数据加载器」,简单到极致但对中等数据集非常高效。
第二步:训练
配置文件 config/train_shakespeare_char.py 定义了一个小模型:
| 参数 | 值 | 说明 |
|---|---|---|
block_size | 256 | 上下文窗口:一次看 256 个字符 |
n_embd | 384 | 特征维度 |
n_layer | 6 | 6 层 Transformer Block |
n_head | 6 | 6 个注意力头(每头 64 维) |
| 显存需求 | 数 GB 级 | 消费级显卡轻松胜任 |
单张 A100 约 3 分钟训完,最佳验证 loss 约 1.4697。任何命令行参数都可以覆盖配置文件,例如:
python train.py config/train_shakespeare_char.py --batch_size=32 --max_iters=5000第三步:采样生成
python sample.py --out_dir=out-shakespeare-char \
--num_samples=5 --max_new_tokens=500训练约 3 分钟后,模型就能产出相当像样的「莎士比亚风格」剧本:人名、台词格式、舞台指示(如 Enter KING LEAR)都有模有样——虽然语义上仍是胡言乱语,这正是字符级小模型的表现预期。
CPU / Apple Silicon 配置
没有 GPU?缩小模型 + 缩短上下文即可。官方 CPU 命令(MacBook 约 3 分钟,loss ≈ 1.88):
python train.py config/train_shakespeare_char.py --device=cpu --compile=False \
--eval_iters=20 --log_interval=1 --block_size=64 --batch_size=12 \
--n_layer=4 --n_head=4 --n_embd=128 --max_iters=2000 \
--lr_decay_iters=2000 --dropout=0.0Apple Silicon 把 --device=cpu 换成 --device=mps 即可。
调参速查
| 想…… | 改什么 |
|---|---|
| 训得更好 | 增大 n_layer / n_embd / max_iters,保持 lr_decay_iters ≈ max_iters |
| 显存不够 | 减小 batch_size,用 gradient_accumulation_steps 补偿有效 batch |
| 训得更快 | 保持 compile=True(Windows 除外)、用 bf16、缩短 block_size |
| 防过拟合 | 如出现过拟合,可把 dropout 提到 0.1 左右 |
CH.5GPT 核心原理
读懂 nanoGPT 的前提是读懂 GPT。本章用最少的概念把架构讲清,下一章再对照代码。
GPT 在做什么
GPT(Generative Pre-trained Transformer)的目标极其简单:给定前文,预测下一个 token。
训练就是在海量文本上反复做这件事;生成时把模型自己的输出拼回输入、循环往复(自回归)。
自注意力机制(Self-Attention)
注意力让每个位置去「查询」前文所有位置,聚合相关信息。每个 token 产生三个向量:
- Query(Q):我想找什么信息?
- Key(K):我能提供什么信息?
- Value(V):我实际携带的内容。
计算方式:每个位置的 Q 与所有位置的 K 做点积得到相关性分数,除以 √d(缩放防 softmax 饱和),softmax 归一化成权重,再对 V 加权求和:
Attention(Q, K, V) = softmax( Q · Kᵀ / √d_k ) · V多头(Multi-Head):把 n_embd 维切成 n_head 份(如 768 维 ÷ 12 头 = 每头 64 维),各头独立做注意力再拼接——不同的头可以关注不同类型的关系(语法、位置、指代……)。
因果掩码(Causal Mask)
语言模型预测第 t 个 token 时只能看见前 t-1 个,不能偷看未来——否则训练目标就泄漏了。做法:给注意力分数矩阵(T×T)盖一个下三角掩码,上三角(未来位置)置为 −∞,softmax 后权重即为 0。这样一句话的所有位置可以并行训练,等价于逐词预测。
嵌入:词 + 位置
- 词嵌入 wte:vocab_size × n_embd 的查找表,把 token id 变成向量。语义相近的词在向量空间中靠近。
- 位置嵌入 wpe:注意力本身对顺序无感,必须额外把「这是第几个 token」加进去。GPT-2 用可学习的绝对位置嵌入(后续模型流行 RoPE / ALiBi,见第 14 章 TODO)。
两者直接相加后进入 Transformer 主干。
残差流与 LayerNorm
GPT-2 采用预归一化(Pre-Norm)结构,每个 Block 是两次「归一化 → 子层 → 残差相加」:
x = x + attn( ln_1(x) ) # 注意力子层,残差连接
x = x + mlp( ln_2(x) ) # 前馈子层,残差连接残差连接(x + …)让梯度可以直达浅层,是深层网络能训起来的关键;LayerNorm 稳定每层输入分布。MLP 则对每个位置独立地做 n_embd → 4·n_embd → n_embd 的非线性变换,存储大量「知识」。
自回归生成
模型最后一层输出每个位置的 logits(词表大小的未归一化分数)。生成时:
- 只取最后一个位置的 logits(前面位置的预测训练用,生成用不上);
- 除以 temperature,可选 top-k 截断;
- softmax 后按概率随机采样一个 token,拼到序列末尾;
- 重复,直到达到
max_new_tokens或遇到终止符。
数据流全景图
token ids (B,T)
│ wte 查表 + wpe 位置嵌入
▼
(B,T,C) ──▶ [ Block × n_layer ]
│ ├─ ln_1 → CausalSelfAttention(多头, 因果掩码)→ 残差+
│ └─ ln_2 → MLP(C → 4C → C, GELU) → 残差+
▼
ln_f 最终归一化 (B,T,C)
│ lm_head(与 wte 权重共享)
▼
logits (B,T,V)
│ 训练: 与目标对齐算交叉熵 生成: 取最后一位 → temperature → top-k → 采样
▼CH.6model.py 逐行精讲
模型文件一共五个类,自底向上读:LayerNorm → CausalSelfAttention → MLP → Block → GPT。
GPTConfig 配置
@dataclass
class GPTConfig:
block_size: int = 1024 # 最大序列长度(上下文窗口)
vocab_size: int = 50304 # 50257 向上取整到 64 的倍数,GPU 上更高效
n_layer: int = 12 # Transformer 层数
n_head: int = 12 # 注意力头数
n_embd: int = 768 # 特征维度
dropout: float = 0.0 # 预训练 0.0;小数据微调建议 0.1+
bias: bool = True # False 时略快更好(但为兼容 GPT-2 默认 True)LayerNorm
自己实现而不是用 torch.nn.LayerNorm,唯一原因是 PyTorch 原生层不支持 bias=False。weight 初始化为全 1、bias 全 0、eps=1e-5,行为与标准 LayerNorm 一致。
CausalSelfAttention(因果自注意力)
class CausalSelfAttention(nn.Module):
def __init__(self, config):
# 一个线性层同时生成 Q、K、V(输出 3*n_embd),再 split 成三份 —— GPT-2 风格
self.c_attn = nn.Linear(n_embd, 3 * n_embd, bias=config.bias)
self.c_proj = nn.Linear(n_embd, n_embd, bias=config.bias) # 输出投影
self.attn_dropout = nn.Dropout(config.dropout)
self.resid_dropout = nn.Dropout(config.dropout)
def forward(self, x):
B, T, C = x.size()
q, k, v = self.c_attn(x).split(n_embd, dim=2)
# (B,T,C) → 拆头 → (B, n_head, T, head_size):把 head 维提到前面,便于并行
q = q.view(B, T, n_head, C // n_head).transpose(1, 2)
k = k.view(B, T, n_head, C // n_head).transpose(1, 2)
v = v.view(B, T, n_head, C // n_head).transpose(1, 2)
y = F.scaled_dot_product_attention(q, k, v, is_causal=True) # Flash Attention!
y = y.transpose(1, 2).contiguous().view(B, T, C) # 拼回 (B,T,C)
return self.resid_dropout(self.c_proj(y))- Flash Attention 路径:PyTorch ≥ 2.0 时直接调
F.scaled_dot_product_attention(..., is_causal=True), fused kernel 又快又省显存。 - 手动回退路径:老版本 PyTorch 走经典实现
att = (q @ k.transpose(-2,-1)) / √d,用一个注册为 buffer 的下三角掩码把未来位置填 −inf,softmax+dropout 后乘 v。
MLP
class MLP(nn.Module):
def __init__(self, config):
self.c_fc = nn.Linear(n_embd, 4 * n_embd) # 升维 4 倍
self.gelu = nn.GELU() # GPT-2 用 GELU 激活
self.c_proj = nn.Linear(4 * n_embd, n_embd) # 降回原维度
self.dropout = nn.Dropout(config.dropout)Block
标准 GPT-2 预归一化结构(见第 5 章 5.5 节),包含 ln_1 / attn / ln_2 / mlp 四个成员,forward 就是两行残差加法。
GPT 主模型与 forward
self.transformer = nn.ModuleDict(dict(
wte = nn.Embedding(config.vocab_size, config.n_embd), # token 嵌入
wpe = nn.Embedding(config.block_size, config.n_embd), # 位置嵌入
drop = nn.Dropout(config.dropout),
h = nn.ModuleList([Block(config) for _ in range(config.n_layer)]),
ln_f = LayerNorm(config.n_embd), # 最终归一化
))
self.lm_head = nn.Linear(config.n_embd, config.vocab_size, bias=False)
self.transformer.wte.weight = self.lm_head.weight # ★ 权重共享 weight tyingforward 流程:校验 t ≤ block_size → tok_emb + pos_emb → dropout → 逐层 Block → ln_f → lm_head。两个省算力的细节:
- 权重共享:输入嵌入 wte 与输出投影 lm_head 用同一矩阵。GPT-2 论文做法,省掉一整个 (n_embd × vocab_size) 的大参数矩阵,且通常提升小模型效果。
- 推理只算最后一位:训练时对全部 T 个位置算 logits 并算交叉熵(
ignore_index=-1);推理时只对最后一个位置x[:, [-1], :]过 lm_head——下一步只需要它。
权重初始化
- 所有 Linear / Embedding 权重:
normal(0, 0.02),bias 置零(GPT-2 传统)。 - 残差路径投影特殊处理:每个 Block 里 attn.c_proj 与 mlp.c_proj 的 std 除以
√(2·n_layer)。层数越深初始化越小,避免残差流方差随层数线性膨胀——同样来自 GPT-2 论文。
generate() 采样
def generate(self, idx, max_new_tokens, temperature=1.0, top_k=None):
for _ in range(max_new_tokens):
idx_cond = idx if idx.size(1) <= self.block_size else idx[:, -block_size:] # 超长截断
logits, _ = self(idx_cond)
logits = logits[:, -1, :] / temperature # 只要最后一位 + 温度
if top_k is not None: # top-k 截断
v, _ = torch.topk(logits, top_k)
logits[logits < v[:, [-1]]] = -float('inf')
probs = F.softmax(logits, dim=-1)
idx_next = torch.multinomial(probs, num_samples=1) # 按概率采样
idx = torch.cat((idx, idx_next), dim=1) # 拼回序列
return idx注意逐 token 生成会反复前向整个上下文,复杂度 O(T²)。生产系统会用 KV 缓存,nanoGPT 为了代码简洁没有实现——这是「教学优先」的取舍。
from_pretrained:加载 OpenAI GPT-2 权重
gpt2 → 12 层 · 12 头 · 768 维 · 124M 参数
gpt2-medium → 24 层 · 16 头 · 1024 维 · 350M 参数
gpt2-large → 36 层 · 20 头 · 1280 维 · 774M 参数
gpt2-xl → 48 层 · 25 头 · 1600 维 · 1558M 参数实现要点:用 HuggingFace 的 GPT2LMHeadModel.from_pretrained 取权重再逐个拷贝;强制 vocab=50257、block=1024、bias=True(OpenAI 权重如此);由于 OpenAI 原实现用 Conv1D,四个权重矩阵(attn.c_attn、attn.c_proj、mlp.c_fc、mlp.c_proj)需要转置后复制;过滤掉 mask 类 buffer。加载后即可采样或微调。
configure_optimizers:weight decay 分组
一个常被忽略的细节:weight decay 不应该作用在 bias 和 LayerNorm 参数上(它们维度低、且衰减它们通常有害)。实现上按维度分组:
decay_params = [p for p in params if p.dim() >= 2] # 矩阵、嵌入 → 衰减
nodecay_params = [p for p in params if p.dim() < 2] # bias、LayerNorm → 不衰减
optim_groups = [
{'params': decay_params, 'weight_decay': weight_decay},
{'params': nodecay_params, 'weight_decay': 0.0},
]优化器用 AdamW;CUDA 且 PyTorch 版本支持时自动启用 fused 版本(更快)。
crop_block_size:上下文手术
把训好的 1024 上下文模型「裁」成更短上下文(如微调时用 block_size=256 省显存):直接截断位置嵌入 wpe 的前 block_size 行,并同步截断旧式注意力掩码 buffer。位置嵌入是逐位置查表,截断即生效,无需重训。
estimate_mfu:估算算力利用率
按 PaLM 论文附录 B 的公式估算模型前向+反向的 FLOPs(每 token 约 6N,N 为参数量;注意力项再加 12·L·H·Q·T),与 A100 bfloat16 峰值 312 TFLOPS 对比得到 MFU(Model FLOPs Utilization)。训练日志里打印的 mfu% 就是它,是判断「GPU 是否喂饱」的核心指标(大型训练一般落在 35%~50%)。
CH.7train.py 逐行精讲
全部默认超参数
train.py 顶部直接写全局变量作为默认配置(GPT-2 124M 规格),可被配置文件或命令行覆盖:
| 分组 | 参数 | 默认值 | 说明 |
|---|---|---|---|
| I/O | out_dir | 'out' | checkpoint 输出目录 |
eval_interval | 2000 | 每多少步评估一次 | |
log_interval | 1 | 每多少步打印日志 | |
eval_iters | 200 | 每次评估用多少个 batch 估 loss | |
eval_only | False | True 则只评估一次就退出 | |
always_save_checkpoint | True | 每次评估都保存(False 则仅创新低时保存) | |
init_from | 'scratch' | 'scratch' / 'resume' / 'gpt2*' | |
| 数据 | dataset | 'openwebtext' | 对应 data/ 下的目录名 |
gradient_accumulation_steps | 40 (=5×8) | 梯度累积步数,模拟更大 batch | |
batch_size / block_size | 12 / 1024 | micro-batch 与上下文长度 | |
| 模型 | n_layer / n_head / n_embd | 12 / 12 / 768 | GPT-2 124M 规格 |
dropout | 0.0 | 预训练 0;小数据微调建议 0.1+ | |
bias | False | LayerNorm/Linear 是否带 bias(False 略优) | |
vocab_size | 50304 | 按 meta.pkl 或默认 | |
| AdamW | learning_rate | 6e-4 | 最大学习率(小模型可承受较大值) |
max_iters | 600000 | 总训练步数 | |
weight_decay | 1e-1 | 仅作用于矩阵参数 | |
beta1 / beta2 | 0.9 / 0.95 | β₂=0.95(而非 0.999)是 LLM 惯例 | |
grad_clip | 1.0 | 梯度全局范数裁剪(0 = 禁用) | |
min_lr | 6e-5 | 约为最大学习率的 1/10 | |
| 调度 | warmup_iters | 2000 | 线性预热步数 |
lr_decay_iters | 600000 | 余弦衰减总步数(Chinchilla:≈ max_iters) | |
| 系统 | backend / device / dtype | nccl / cuda / 自动 | bf16 可用则 bf16,否则 fp16 |
compile | True | torch.compile 加速 | |
wandb_log | False | 默认关闭,项目名 'owt' |
configurator 配置系统
没有 argparse:configurator.py 在运行时解析 --key=value 或配置文件路径,直接覆盖调用方(train.py / sample.py)的全局变量。这就是为什么配置文件只是普通的 python 脚本、而命令行可以随意追加任意参数覆盖它。
DDP 分布式初始化
- 通过环境变量
RANK是否存在判断是否处于 torchrun 启动的 DDP 环境;是则init_process_group('nccl'),每个进程绑定cuda:LOCAL_RANK。 master_process = (rank == 0):只有 0 号进程负责打印日志与保存 checkpoint,避免多进程重复写文件。- 每个进程用不同随机种子偏移,保证数据增强/初始化的多样性。
- 关键断言:梯度累积步数必须能被 world_size 整除,并按 world_size 缩小——保证「全局有效 batch = batch_size × 梯度累积 × world_size」在改卡数时不漂移。每步 token 数也会打印:
grad_accum × world_size × batch_size × block_size。
数据加载 get_batch
def get_batch(split):
data = np.memmap('train.bin' if split=='train' else 'val.bin', dtype=np.uint16, mode='r')
ix = torch.randint(len(data) - block_size, (batch_size,))
x = torch.stack([torch.from_numpy(data[i : i+block_size] .astype(np.int64)) for i in ix])
y = torch.stack([torch.from_numpy(data[i+1 : i+1+block_size].astype(np.int64)) for i in ix])
return x.pin_memory().to(device, non_blocking=True), y.pin_memory().to(device, non_blocking=True)要点:y 就是 x 错开一位——位置 t 的预测目标就是 t+1 处的 token,语言模型的训练信号由此而来。每次重新 memmap 是刻意为之(长期驻留会内存泄漏);pin_memory + non_blocking 实现 CPU→GPU 异步搬运,并在前向传播时预取下一个 batch,把数据搬运藏进计算时间。
三种初始化模式
| init_from | 行为 |
|---|---|
'scratch' | 从零初始化。词表优先取数据集 meta.pkl 中的 vocab_size,否则用 50304 |
'resume' | 加载 out_dir/ckpt.pt,强制继承 checkpoint 里的结构参数(n_layer 等),处理 _orig_mod. 前缀(torch.compile 产物),并恢复 iter_num 与 best_val_loss 续训 |
'gpt2*' | GPT.from_pretrained 加载 OpenAI 预训练权重(微调用) |
另有一处妙招:若命令行 block_size 小于模型原有 block_size,自动调用 crop_block_size 做「模型手术」缩短上下文。
混合精度与编译
torch.autocast包裹前向,dtype 自动选 bfloat16(不支持则 float16);fp16 时启用GradScaler梯度缩放防下溢,bf16 则 scaler 为空操作。- 开启 TF32(matmul 与 cudnn)——Ampere 及以上显卡的免费提速。
torch.compile(model):首次编译约 1 分钟,之后每步显著加速。
学习率调度
# 1) 线性 warmup:0 → learning_rate
if it < warmup_iters:
return learning_rate * it / warmup_iters
# 2) 超过 lr_decay_iters:维持 min_lr
if it > lr_decay_iters:
return min_lr
# 3) 中间:余弦衰减 learning_rate → min_lr
coeff = 0.5 * (1.0 + math.cos(pi * (it - warmup_iters) / (lr_decay_iters - warmup_iters)))
return min_lr + coeff * (learning_rate - min_lr)warmup 防止初期大学习率把随机初始化的模型推崩;注释明确指出 lr_decay_iters 应约等于 max_iters(Chinchilla 论文的可训练性结论)。
训练主循环
while True 主循环,每步依次做:
- 取当前学习率写入 optimizer param_groups;
- 定期评估/保存:每 eval_interval 步且是 master 进程时评估,val loss 创新低或 always_save_checkpoint 时保存;
- 前向反向 + 梯度累积:循环 micro_step 累积梯度,loss 除以累积步数;DDP 下用
model.require_backward_grad_sync = (micro_step == 最后一步)——只在最后一次 micro-batch 时同步梯度(作者不采用no_sync()上下文的写法,认为其导致代码重复);前向时异步预取下一 batch; - 梯度裁剪(grad_clip≠0 时先
scaler.unscale_再 clip); - optimizer.step() / scaler.update() / zero_grad(set_to_none=True);
- 计时与日志:计算并指数滑动平均 MFU,打印 step、loss 区间估计、耗时、mfu;
- 终止:iter_num > max_iters 退出,DDP 时 destroy_process_group()。
评估与 checkpoint
estimate_loss:在@torch.no_grad()+model.eval()下对 train/val 各跑 200 个 batch 取平均——用「多个随机 batch 的均值」估计 loss,比单批更平稳。评估后记得切回model.train()。- checkpoint 保存到
out_dir/ckpt.pt,内容:模型 state_dict(保存解包 DDP 后的 raw_model)、优化器 state_dict、model_args、iter_num、best_val_loss、完整 config。第 0 步不保存。 - wandb 开启时记录 iter、train/val loss、lr、mfu。
CH.8数据集准备
三个数据集脚本,对应三种典型玩法:
shakespeare_char(字符级 · 入门)
详见第 4 章:下载 1MB 文本 → 65 字符词表 → 90/10 切分 → train.bin / val.bin(uint16) + meta.pkl(存 vocab_size、stoi、itos)。字符级意味着词表极小、任何文本都能编码,代价是同样内容需要更多 token。
shakespeare(BPE 级 · 微调用)
同样下载 tiny shakespeare,但改用 tiktoken 的 GPT-2 BPE 分词器编码成子词 token 序列——因为预训练 GPT-2 的词表就是这套 BPE,微调时必须对齐。这是「微调 GPT-2 到莎士比亚」实验的数据准备步骤。
openwebtext(复现 GPT-2)
- 用 HuggingFace
datasets下载 OpenWebText(WebText 的开源复刻版,数百万网页); - 全部文档拼成一条长流,用 GPT-2 BPE 编码;
- 切分后存成
train.bin(约 90 亿 token、17GB)与val.bin(约 440 万 token,占 0.05%);每条文档末尾追加<|endoftext|>(id 50256)作为分隔; - 下载与分词需要较长时间(视网速与 CPU 而定),产物供 train_gpt2.py 使用。
--dataset=你的目录名 传给 train.py。CH.9复现 GPT-2 (124M)
训练命令
# 1. 准备 OpenWebText(下载 + BPE 分词,产物 train.bin/val.bin)
python data/openwebtext/prepare.py
# 2. DDP 训练 GPT-2 124M
torchrun --standalone --nproc_per_node=8 train.py config/train_gpt2.py训练结束后验证 loss 约 2.85。默认配置即 GPT-2 124M(12 层/12 头/768 维)+ block_size 1024 + 梯度累积 40:有效 batch 为 12 × 40 × 8 = 3840 条 × 1024 token ≈ 393 万 token/步;60 万步合计处理约 2.4 万亿 token——相当于对约 90 亿 token 的 OpenWebText 反复训练了两百多个 epoch。
多节点 DDP
# 主节点(node_rank=0,IP 换成你的):
torchrun --nproc_per_node=8 --nnodes=2 --node_rank=0 \
--master_addr=123.456.123.456 --master_port=1234 train.py config/train_gpt2.py
# 工作节点(node_rank=1):
torchrun --nproc_per_node=8 --nnodes=2 --node_rank=1 \
--master_addr=123.456.123.456 --master_port=1234 train.py config/train_gpt2.py- 没有 Infiniband 的普通以太网集群,需要加环境变量
NCCL_IB_DISABLE=1,否则多机训练仍能运行但会「爬行」般极慢(README 原话:most likely crawl); - 建议用
iperf3先测节点间带宽,带宽不足会成为训练瓶颈; - 单卡直接
python train.py config/train_gpt2.py(无需 torchrun),调小 batch_size/梯度累积即可。
基线结果对照
OpenAI 原版 GPT-2 各规格在 OpenWebText 上的(训练/验证)loss,作为复现目标:
| 模型 | 参数量 | 训练 loss | 验证 loss |
|---|---|---|---|
| gpt2 | 124M | 3.11 | 3.12 |
| gpt2-medium | 350M | 2.85 | 2.84 |
| gpt2-large | 774M | 2.66 | 2.67 |
| gpt2-xl | 1558M | 2.56 | 2.54 |
config/eval_gpt2*.py 系列配置直接在 OWT 上评估官方权重复现出来。
CH.10微调实战
把预训练 GPT-2 微调到莎士比亚风格,是最经典的 nanoGPT 用法:
微调三步
# 1. 用 BPE 编码莎士比亚数据
python data/shakespeare/prepare.py
# 2. 微调(init_from='gpt2-xl':加载最大规格预训练权重)
python train.py config/finetune_shakespeare.py
# 3. 采样
python sample.py --out_dir=out-shakespeare关键超参差异
| 参数 | 预训练 (train_gpt2) | 微调 (finetune_shakespeare) | 为什么 |
|---|---|---|---|
init_from | 'scratch' | 'gpt2-xl'(最大规格) | 起点是预训练权重 |
max_iters | 600000 | 仅 20 步 | 数据极小,几步就够 |
learning_rate | 6e-4(衰减) | 3e-5(恒定) | 大步长会破坏预训练知识 |
decay_lr | True(warmup+余弦) | False | 总共 20 步,没有衰减的必要 |
batch_size / 梯度累积 | 12 / 40 | 1 / 32 | 每步 32,768 token;gpt2-xl 显存所限 |
always_save_checkpoint | True | False | 只在验证 loss 改善时保存 |
显存不足怎么办
- 往小换模型:
--init_from=gpt2-large→gpt2-medium→gpt2(124M 最省显存,默认的 gpt2-xl 需要约 20GB 显存); - 缩短上下文:
--block_size=256(会自动做 crop_block_size 手术,无需重训); - 减小
batch_size,加大gradient_accumulation_steps保持有效 batch 不变; - 确保混合精度开启(bf16/fp16 自动)。
CH.11采样与推理
sample.py 参数全表
| 参数 | 默认值 | 说明 |
|---|---|---|
init_from | 'resume' | 'resume' 从 out_dir 读自己的 checkpoint;或 'gpt2' / 'gpt2-medium' / 'gpt2-large' / 'gpt2-xl' 直接用 OpenAI 权重 |
out_dir | 'out' | checkpoint 目录(仅 resume 时生效) |
start | "\n" | 提示词;支持 "FILE:prompt.txt" 从文件读取 |
num_samples | 10 | 生成几个样本 |
max_new_tokens | 500 | 每个样本生成多少个 token |
temperature | 0.8 | 温度:<1 更保守,>1 更奔放,1.0 原始分布 |
top_k | 200 | 只在概率最高的 k 个 token 中采样,其余置零 |
seed | 1337 | 随机种子(可复现) |
device / dtype | cuda / 自动 | bf16 可用则 bf16,否则 fp16 |
compile | False | 推理也可编译加速(首次编译慢) |
编解码器自动选择:若 checkpoint 记录的 dataset 有 meta.pkl(字符级)就用其中的 stoi/itos;否则默认 tiktoken GPT-2 BPE 编码。
temperature 与 top_k
- temperature:logits 除以 T。T→0 时退化为贪心(总选最大概率),T=1 保持原分布,T 大时分布变平、更随机有创造性(也更容易胡说)。
- top_k:硬截断长尾——概率极低的 token(错别字、乱码)即便温度高也不该被选中。两个参数通常配合使用,例如 0.8/200。
实用示例
python sample.py --init_from=gpt2-xl \
--start="What is the answer to life, the universe, and everything?" \
--num_samples=5 --max_new_tokens=100python sample.py --out_dir=out-shakespeare --start=FILE:prompt.txt \
--temperature=0.7 --top_k=100 --num_samples=3CH.12性能优化
torch.compile
PyTorch 2.0 的编译器把 Python 模型 JIT 编译成优化 kernel。Karpathy 实测在 nanoGPT 上一行代码让迭代时间从 ~250ms 降到 ~135ms(约 1.86×)。代价:首次编译约 1 分钟;与部分环境不兼容(尤其 Windows),出问题时加 --compile=False(仅变慢,不影响结果)。
Flash Attention
PyTorch ≥ 2.0 时,model.py 自动走 F.scaled_dot_product_attention fused kernel:把注意力的 softmax 分块做在 SRAM 里,不显式构造 T×T 注意力矩阵——长上下文下既省显存又省时间,还不需要改任何模型逻辑。老版本 PyTorch 自动回退到手动实现。
TF32 与混合精度
- TF32:Ampere+ 显卡上把 float32 矩阵乘用 19 位 TF32 格式执行,精度几乎无损、速度可观提升。代码里对 matmul 和 cudnn 都打开。
- bfloat16 混合精度:动态范围与 fp32 相同(指数位相同),训练无需 GradScaler;不支持 bf16 的旧卡退回 fp16+GradScaler。
MFU 是什么
MFU(Model FLOPs Utilization)= 模型理论 FLOPs ÷(耗时 × GPU 峰值 FLOPs)。它剥离了「你的模型算多少」与「GPU 干了多少活」的耦合,是跨模型比较训练效率的标准指标。nanoGPT 按 PaLM 附录 B 公式估算(每 token ≈ 6N + 注意力项),日志里持续打印,配合 bench.py 找瓶颈。
bench.py
剥离了数据/日志/评估的「纯训练循环」基准脚本,支持配合 profiler 输出,用于回答:这个配置在我的卡上每秒多少 token?MFU 多少?换 batch / block_size / 精度各提升多少?做 scaling 实验前先用它摸底。
CH.13常见问题排查
FAQ 清单
| 症状 | 原因与解法 |
|---|---|
| torch.compile 报错 / Windows 上崩溃 | Windows 不支持 torch.compile。加 --compile=False(变慢但可用) |
提示找不到 train.bin / val.bin | 先运行对应 data/<dataset>/prepare.py 生成数据 |
| CUDA out of memory | 减小 batch_size(用梯度累积补)、缩短 block_size、换小模型;确认混合精度开启 |
| 多机训练极慢(爬行) | 无 Infiniband 时加 NCCL_IB_DISABLE=1;检查防火墙放行 master_port;用 iperf3 验证带宽是否成为瓶颈 |
| loss 很早就不降 / NaN | 学习率过大,检查 warmup;确认 grad_clip 生效;fp16 下确认 GradScaler 在用 |
| 生成的文本是乱码 | 编解码器不匹配:字符级模型必须让 sample.py 找到对应的 meta.pkl(dataset 名一致);BPE 模型默认 tiktoken |
| 训练极慢 | 确认 compile=True、bf16、TF32 可用;查看日志 mfu% 是否异常低;用 bench.py 定位 |
| 想续训但结构对不上 | 用 --init_from='resume',结构参数(n_layer 等)会强制继承 checkpoint,不要手动改 |
| 微调效果差 | 学习率是否太大(应比预训练小一个量级)?dropout 是否加了?max_iters 是否过长导致过拟合? |
CH.14进阶学习路径
Zero To Hero 课程
nanoGPT 与 Karpathy 的免费课程 Neural Networks: Zero To Hero 深度互补:从 micrograd 手写反向传播,到 makemore、注意力,一路手写到 「Let's build GPT: from scratch, in code, spelled out」(YouTube 视频链接)——那节课一步步手写出来的产物正是 nanoGPT 的前身。看完课程再来读这两个 300 行的文件,每一行都有出处。
官方 TODO 改进方向
README 里列出的未竟事项,本身是一份绝佳的「进阶练习清单」:
- 用 FSDP 替代 DDP(更大模型的分片并行);
- 在标准评测集上测 zero-shot 困惑度(LAMBADA、HELM);
- 改进微调超参数;
- 线性增长的 batch size 调度;
- 引入 RoPE / ALiBi 位置编码;
- checkpoint 中分离优化器状态与模型参数;
- 更多网络健康日志(梯度裁剪触发等);
- 更好的初始化方案探索。
相关项目
| 项目 | 关系 |
|---|---|
| minGPT | 前身,教学向的 GPT 实现 |
| nanochat | 2025 年的继任者:从零训练可对话的 ChatGPT 风格模型(含聊天模板、RLHF 后训练等) |
| micrograd | 同作者的手写自动微分引擎,Zero To Hero 第一课 |
| llm.c(同作者) | 纯 CUDA/C++ 实现的 GPT-2 训练,性能极致化方向的下一站 |
| modded-nanogpt | 社区著名的「nanoGPT 速度竞赛」仓库:全球开发者持续用最新优化技巧刷新复现 GPT-2 的时间与成本下限,是跟踪 LLM 训练优化前沿的最佳窗口 |
学习路线建议
- 跑通:第 4 章三条命令,在 Shakespeare 上训练并采样;
- 读懂:对照第 5/6/7 章精读 model.py 与 train.py,随手改超参观察 loss 变化;
- 实验:换自己的数据集(第 8 章)、做微调(第 10 章)、玩 temperature/top_k(第 11 章);
- 深挖:用 bench.py 做 scaling 实验,试着实现 TODO 里的 RoPE 或 FSDP;
- 延伸:转向 nanochat 或 llm.c,看现代对话模型与极致性能工程长什么样。
「Famous last words: this repository is very old and deprecated… but it remains a great way to learn.」—— 读完这不到 1000 行代码,你就拥有了看懂任何 LLM 训练代码的地基。