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)

PyTorch 2.xGPT-2 架构DDP 多卡 torch.compileFlash Attentionbfloat16

CH.1项目概览

什么是 nanoGPT

nanoGPT 是 Andrej Karpathy 编写的 GPT 训练/微调仓库,自我定位是「训练中等规模 GPT 的最简单、最快的代码库」。它把一个完整可用的 GPT 压缩到极致:

它能做到的事情包括:

  1. 从零训练一个字符级的迷你 GPT(笔记本 CPU 上 3 分钟跑完);
  2. 在 OpenWebText 上复现 GPT-2 124M(8×A100 约 4 天,验证 loss ≈ 2.85);
  3. 微调预训练 GPT-2 到你自己的数据集(单卡几分钟);
  4. 直接加载 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

minGPTnanoGPT
定位教学,配合课程讲解实用,真的能训练出好模型
性能优化基本没有torch.compile、Flash Attention、bfloat16、DDP
规模上限玩具级可复现 GPT-2 124M(8×A100 · 4 天)
加载 GPT-2 权重有有(from_pretrained)
代码量较分散model.py + train.py 各约 300 行

项目现状与定位

⚠️ 注意:已有继任者
README 在 2025 年 11 月更新中说明:Karpathy 已发布新项目 nanochat(从零训练一个可对话的 ChatGPT 风格模型),nanoGPT 本身「very old and deprecated」,仓库保留供学习参考。但正因为它小而完整,至今仍是理解 GPT / Transformer / LLM 训练工程的最佳入门材料之一,社区依然活跃(Discord #nanoGPT 频道、大量 issue 讨论)。

为什么值得学习

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定义 GPTLayerNorm / 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环境准备与安装

依赖清单

包用途必需?
torchPyTorch ≥ 2.0(torch.compile 需要 2.0+)必需
numpymemmap 读取 .bin 数据必需
transformers加载 OpenAI GPT-2 checkpoint(仅 from_pretrained 时)用预训练权重时需要
datasets下载预处理 OpenWebText训练 GPT-2 复现时需要
tiktokenOpenAI 的 BPE 分词器BPE 数据 / gpt2 采样时需要
wandb训练日志可视化可选
tqdm进度条数据准备时需要
requests下载 tiny shakespeare数据准备时需要

安装步骤

bash一键安装全部依赖
pip install torch numpy transformers datasets tiktoken wandb tqdm

平台注意事项

CH.4快速开始:字符级莎士比亚

这是官方推荐的入门实验:在 tiny shakespeare 数据集上训练一个字符级 GPT,体量小到任何机器都能跑。

三步跑通

bash三条命令跑完入门实验
# 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 做了四件事:

  1. 从 GitHub(karpathy 的 char-rnn 仓库)下载 tinyshakespeare(约 1MB 的莎士比亚风格剧本);
  2. 把文本拆成字符集合,排序后得到 65 个字符的词表(大小写字母 + 标点 + 空格等);
  3. 构建 stoi(字符→整数)与 itos(整数→字符)映射,将全文编码为整数序列;
  4. 按 90% / 10% 切分为 train.bin(约 100 万 token)与 val.bin(约 11 万 token),以 uint16 二进制存储,并把词表信息存进 meta.pkl。
ℹ️ 为什么要存成 .bin?
训练时直接 np.memmap 内存映射二进制文件、随机采样片段,免去每次 decode 文本和运行 tokenizer 的开销——这就是 Karpathy 所谓的「穷人的数据加载器」,简单到极致但对中等数据集非常高效。

第二步:训练

配置文件 config/train_shakespeare_char.py 定义了一个小模型:

参数值说明
block_size256上下文窗口:一次看 256 个字符
n_embd384特征维度
n_layer66 层 Transformer Block
n_head66 个注意力头(每头 64 维)
显存需求数 GB 级消费级显卡轻松胜任

单张 A100 约 3 分钟训完,最佳验证 loss 约 1.4697。任何命令行参数都可以覆盖配置文件,例如:

bash覆盖配置文件中的参数
python train.py config/train_shakespeare_char.py --batch_size=32 --max_iters=5000

第三步:采样生成

bash生成 5 段、每段 500 字符的文本
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):

bashCPU 版训练命令
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.0

Apple 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。

文本→ 切分成 token(字符或 BPE 子词)→ 查表变成整数 id→ 模型对每个位置输出「下一个 token」的概率分布→ 训练目标:让真实下一个 token 概率最大(交叉熵)

训练就是在海量文本上反复做这件事;生成时把模型自己的输出拼回输入、循环往复(自回归)。

自注意力机制(Self-Attention)

注意力让每个位置去「查询」前文所有位置,聚合相关信息。每个 token 产生三个向量:

计算方式:每个位置的 Q 与所有位置的 K 做点积得到相关性分数,除以 √d(缩放防 softmax 饱和),softmax 归一化成权重,再对 V 加权求和:

math缩放点积注意力
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。这样一句话的所有位置可以并行训练,等价于逐词预测。

嵌入:词 + 位置

两者直接相加后进入 Transformer 主干。

残差流与 LayerNorm

GPT-2 采用预归一化(Pre-Norm)结构,每个 Block 是两次「归一化 → 子层 → 残差相加」:

pythonBlock 的骨架
x = x + attn( ln_1(x) )   # 注意力子层,残差连接
x = x + mlp( ln_2(x) )    # 前馈子层,残差连接

残差连接(x + …)让梯度可以直达浅层,是深层网络能训起来的关键;LayerNorm 稳定每层输入分布。MLP 则对每个位置独立地做 n_embd → 4·n_embd → n_embd 的非线性变换,存储大量「知识」。

自回归生成

模型最后一层输出每个位置的 logits(词表大小的未归一化分数)。生成时:

  1. 只取最后一个位置的 logits(前面位置的预测训练用,生成用不上);
  2. 除以 temperature,可选 top-k 截断;
  3. softmax 后按概率随机采样一个 token,拼到序列末尾;
  4. 重复,直到达到 max_new_tokens 或遇到终止符。

数据流全景图

shapeB=batch, T=序列长度, C=n_embd, V=词表大小
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 配置

pythondataclass 配置
@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)
💡 细节:50304 而不是 50257
GPT-2 词表是 50257,但 CUDA 的矩阵乘在维度是 64 的倍数时明显更快,所以训练时词表取 50304,多余的位只是浪费一点参数、不影响正确性。这类「工程洁癖」在 nanoGPT 里随处可见。

LayerNorm

自己实现而不是用 torch.nn.LayerNorm,唯一原因是 PyTorch 原生层不支持 bias=False。weight 初始化为全 1、bias 全 0、eps=1e-5,行为与标准 LayerNorm 一致。

CausalSelfAttention(因果自注意力)

python核心逻辑(节选)
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))

MLP

python两层线性 + GELU
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

python组装(节选)
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 tying

forward 流程:校验 t ≤ block_size → tok_emb + pos_emb → dropout → 逐层 Block → ln_f → lm_head。两个省算力的细节:

权重初始化

generate() 采样

python自回归生成(节选)
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 权重

bash四种规格
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 参数上(它们维度低、且衰减它们通常有害)。实现上按维度分组:

python分组逻辑(节选)
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/Oout_dir'out'checkpoint 输出目录
eval_interval2000每多少步评估一次
log_interval1每多少步打印日志
eval_iters200每次评估用多少个 batch 估 loss
eval_onlyFalseTrue 则只评估一次就退出
always_save_checkpointTrue每次评估都保存(False 则仅创新低时保存)
init_from'scratch''scratch' / 'resume' / 'gpt2*'
数据dataset'openwebtext'对应 data/ 下的目录名
gradient_accumulation_steps40 (=5×8)梯度累积步数,模拟更大 batch
batch_size / block_size12 / 1024micro-batch 与上下文长度
模型n_layer / n_head / n_embd12 / 12 / 768GPT-2 124M 规格
dropout0.0预训练 0;小数据微调建议 0.1+
biasFalseLayerNorm/Linear 是否带 bias(False 略优)
vocab_size50304按 meta.pkl 或默认
AdamWlearning_rate6e-4最大学习率(小模型可承受较大值)
max_iters600000总训练步数
weight_decay1e-1仅作用于矩阵参数
beta1 / beta20.9 / 0.95β₂=0.95(而非 0.999)是 LLM 惯例
grad_clip1.0梯度全局范数裁剪(0 = 禁用)
min_lr6e-5约为最大学习率的 1/10
调度warmup_iters2000线性预热步数
lr_decay_iters600000余弦衰减总步数(Chinchilla:≈ max_iters)
系统backend / device / dtypenccl / cuda / 自动bf16 可用则 bf16,否则 fp16
compileTruetorch.compile 加速
wandb_logFalse默认关闭,项目名 'owt'

configurator 配置系统

没有 argparse:configurator.py 在运行时解析 --key=value 或配置文件路径,直接覆盖调用方(train.py / sample.py)的全局变量。这就是为什么配置文件只是普通的 python 脚本、而命令行可以随意追加任意参数覆盖它。

DDP 分布式初始化

数据加载 get_batch

python穷人的数据加载器(节选)
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 做「模型手术」缩短上下文。

混合精度与编译

学习率调度

pythonget_lr(it)
# 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 主循环,每步依次做:

  1. 取当前学习率写入 optimizer param_groups;
  2. 定期评估/保存:每 eval_interval 步且是 master 进程时评估,val loss 创新低或 always_save_checkpoint 时保存;
  3. 前向反向 + 梯度累积:循环 micro_step 累积梯度,loss 除以累积步数;DDP 下用 model.require_backward_grad_sync = (micro_step == 最后一步)——只在最后一次 micro-batch 时同步梯度(作者不采用 no_sync() 上下文的写法,认为其导致代码重复);前向时异步预取下一 batch;
  4. 梯度裁剪(grad_clip≠0 时先 scaler.unscale_ 再 clip);
  5. optimizer.step() / scaler.update() / zero_grad(set_to_none=True);
  6. 计时与日志:计算并指数滑动平均 MFU,打印 step、loss 区间估计、耗时、mfu;
  7. 终止:iter_num > max_iters 退出,DDP 时 destroy_process_group()。

评估与 checkpoint

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)

ℹ️ 换成自己的数据集
仿照任意 prepare.py 写一个:把你的文本编码成 token id 序列,存成 uint16 的 train.bin/val.bin,字符级就在 meta.pkl 里放 stoi/itos,BPE 级则什么都不用存(sample.py 会默认用 tiktoken gpt2 编码)。然后把 --dataset=你的目录名 传给 train.py。

CH.9复现 GPT-2 (124M)

训练命令

bash单机 8 卡 A100 · 约 4 天
# 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

bash双机 16 卡示例
# 主节点(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

基线结果对照

OpenAI 原版 GPT-2 各规格在 OpenWebText 上的(训练/验证)loss,作为复现目标:

模型参数量训练 loss验证 loss
gpt2124M3.113.12
gpt2-medium350M2.852.84
gpt2-large774M2.662.67
gpt2-xl1558M2.562.54
⚠️ 关于 2.85 这个数
OpenAI 的 GPT-2 原始训练数据是未公开的 WebText,与开源 OpenWebText 存在域差异,所以 nanoGPT 从零训到 2.85 并不等于「超过 OpenAI」。更公平的复现基线是:加载官方 gpt2 权重在 OWT 上微调,同样能得到 ~2.85。表中基线数字可以用 config/eval_gpt2*.py 系列配置直接在 OWT 上评估官方权重复现出来。

CH.10微调实战

把预训练 GPT-2 微调到莎士比亚风格,是最经典的 nanoGPT 用法:

微调三步

bash单卡几分钟完成
# 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_iters600000仅 20 步数据极小,几步就够
learning_rate6e-4(衰减)3e-5(恒定)大步长会破坏预训练知识
decay_lrTrue(warmup+余弦)False总共 20 步,没有衰减的必要
batch_size / 梯度累积12 / 401 / 32每步 32,768 token;gpt2-xl 显存所限
always_save_checkpointTrueFalse只在验证 loss 改善时保存
💡 为什么 20 步就够?
莎士比亚 BPE 语料总共只有约 301,966 个 token,微调配置每步处理 1 × 32 × 1024 = 32,768 个 token,即约 9.2 步过完一遍数据——20 步约等于只训练了 2 个 epoch。预训练模型早已掌握语言能力,微调只是「教它换个口音」,因此不需要多步、不需要 dropout、也不需要学习率衰减。这是迁移学习威力的直观展示。

显存不足怎么办

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_samples10生成几个样本
max_new_tokens500每个样本生成多少个 token
temperature0.8温度:<1 更保守,>1 更奔放,1.0 原始分布
top_k200只在概率最高的 k 个 token 中采样,其余置零
seed1337随机种子(可复现)
device / dtypecuda / 自动bf16 可用则 bf16,否则 fp16
compileFalse推理也可编译加速(首次编译慢)

编解码器自动选择:若 checkpoint 记录的 dataset 有 meta.pkl(字符级)就用其中的 stoi/itos;否则默认 tiktoken GPT-2 BPE 编码。

temperature 与 top_k

实用示例

bash用官方 gpt2-xl 回答「终极问题」
python sample.py --init_from=gpt2-xl \
    --start="What is the answer to life, the universe, and everything?" \
    --num_samples=5 --max_new_tokens=100
bash从文件读长提示词 + 低温保守生成
python sample.py --out_dir=out-shakespeare --start=FILE:prompt.txt \
    --temperature=0.7 --top_k=100 --num_samples=3

CH.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 与混合精度

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 里列出的未竟事项,本身是一份绝佳的「进阶练习清单」:

相关项目

项目关系
minGPT前身,教学向的 GPT 实现
nanochat2025 年的继任者:从零训练可对话的 ChatGPT 风格模型(含聊天模板、RLHF 后训练等)
micrograd同作者的手写自动微分引擎,Zero To Hero 第一课
llm.c(同作者)纯 CUDA/C++ 实现的 GPT-2 训练,性能极致化方向的下一站
modded-nanogpt社区著名的「nanoGPT 速度竞赛」仓库:全球开发者持续用最新优化技巧刷新复现 GPT-2 的时间与成本下限,是跟踪 LLM 训练优化前沿的最佳窗口

学习路线建议

  1. 跑通:第 4 章三条命令,在 Shakespeare 上训练并采样;
  2. 读懂:对照第 5/6/7 章精读 model.py 与 train.py,随手改超参观察 loss 变化;
  3. 实验:换自己的数据集(第 8 章)、做微调(第 10 章)、玩 temperature/top_k(第 11 章);
  4. 深挖:用 bench.py 做 scaling 实验,试着实现 TODO 里的 RoPE 或 FSDP;
  5. 延伸:转向 nanochat 或 llm.c,看现代对话模型与极致性能工程长什么样。
「Famous last words: this repository is very old and deprecated… but it remains a great way to learn.」—— 读完这不到 1000 行代码,你就拥有了看懂任何 LLM 训练代码的地基。