---
tags: [AI, 大语言模型, 从零实现, 训练]
阶段: 05-Transformer与LLM原理
难度: ★★★
created: 2026-10-18
related: "[[Transformer架构详解]], [[注意力机制与QKV]], [[KV缓存]], [[自回归生成与采样]]"
---

# 从零实现小型GPT指南

## 定义

**字符级小型 GPT**（character-level small GPT）是以单个字符为最小建模单位、采用 decoder-only Transformer、以最大化下一个字符条件概率为训练目标的语言模型。本篇给出它的一份完整可运行实现：6 层、6 头、384 维、上下文 256、参数量约 10.75M，训练语料为字符级莎士比亚剧本，训练后可生成具备说话人标签与换行结构的文本。

本篇使用的符号与术语：

- 字符级语言模型（character-level language model）：把文本视为字符序列 $c_1c_2\cdots c_N$，模型对每个位置输出下一个字符在词表上的分布，而不是对子词 token 建模。
- 词表（vocabulary）：语料中出现的全部不同字符的集合，大小记为 $V$；莎士比亚语料的 $V=65$。
- 词表映射（stoi）与逆映射（itos）：$\mathrm{stoi}:\mathcal{C}\to\{0,\dots,V-1\}$ 把字符映射为整数下标，$\mathrm{itos}$ 为其逆映射。
- 上下文长度（block size）：单次前向允许的最大序列长度，记为 $T_{\max}=256$；模型只为不超过该长度的位置提供位置嵌入。
- 批（batch）：一次前向并行处理的序列条数，记为 $B$；输入张量形状为 $[B,T]$。
- logits：模型末端线性层输出、尚未归一化的分数，形状 $[B,T,V]$。
- 交叉熵（cross entropy）：负对数似然在批与时间步上的平均，是本篇唯一的训练损失。
- 教师强制（teacher forcing）：训练时把真实前缀 $x_{\le t}$ 作为输入、要求位置 $t$ 预测 $x_{t+1}$，所有位置并行计算损失。
- Pre-LN：把 LayerNorm 放在每个子层之前、残差相加之前的结构，即 $x+\mathrm{Sub}(\mathrm{LN}(x))$。
- 权重绑定（weight tying）：输入嵌入矩阵与输出投影矩阵共享同一参数，即 $W_{\text{head}}=E_{\text{tok}}$。
- 梯度累积（gradient accumulation）：在多次前向上分别反传、累加梯度后再更新一次参数，用显存换取更大的等效批。
- 学习率调度（learning rate schedule）：随迭代步数改变学习率的函数，本篇为线性预热加余弦衰减。
- checkpoint：包含模型参数、优化器状态与配置的持久化文件，用于恢复训练或独立采样。
- KV Cache：自回归解码时缓存历史键与值、避免重复计算前缀的机制，见 [[KV缓存]]。
- 参数量（parameter count）：全部可训练标量的个数，本篇为 10,745,088，约 10.75M。

## 为什么重要

- 前面各篇分别推导了注意力、掩码、位置编码与优化器，但公式正确不等于实现正确。只有把数据、模型、损失、优化器与采样连成一个可运行的整体，才能暴露形状、掩码、标签移位与数值稳定性上的错误；这些错误中的大多数不会抛出异常，只会让损失曲线或生成文本异常。
- 小型 GPT 与 GPT-2、Llama 在结构上同源，差别集中在规模、归一化位置、位置编码与注意力变体。掌握这份 10.75M 参数的实现后，[[Llama-2架构复盘]] 中的 RMSNorm、SwiGLU、RoPE 与 GQA 都可以看作对同一结构的局部替换。
- 训练流程的每个组件都有明确的工程后果：优化器参数分组决定正则化是否作用于归一化参数，梯度累积决定等效批大小，warmup 与余弦衰减决定早期稳定性与后期收敛，梯度裁剪决定是否出现 NaN。这些组件在 [[预训练-微调-对齐pipeline]] 所描述的大规模训练中被放大到多卡与万亿 token 规模，但语义不变。
- 小模型提供短反馈回路。单卡数十分钟即可完成一次从数据到生成的完整流程，使超参数与结构改动可以被快速证伪；这种迭代速度在大模型上无法承担。
- 在全书中的位置：前置为 [[Transformer架构详解]]（层结构）、[[注意力机制与QKV]]（缩放点积注意力）、[[因果注意力与多头注意力]]（掩码与多头拆分）、[[位置编码-正弦与RoPE]]（位置信息注入）、[[Tokenizer与BPE]]（字符级与子词级的取舍）、[[自回归生成与采样]]（解码策略）、[[PyTorch实战入门]]（训练循环与 `state_dict`）；后续为 [[KV缓存]]、[[GPT系列架构]]、[[预训练-微调-对齐pipeline]]。
- 对应能力目标：懂原理对应「说明每个张量的形状与每个超参数的作用」；能复现对应「从空文件写出并完成训练与采样」；会评估对应「用损失曲线、参数量、生成样例与显存占用判断实现是否正确」。

## 原理与推导

### 步骤 1 目标与验收标准

本步骤把目标固定为一张可核对的配置表，后续所有代码与数值都以它为准。

| 项目 | 符号 | 取值 |
|---|---|---|
| 层数 | $L$ | 6 |
| 注意力头数 | $H$ | 6 |
| 残差流维度 | $d$ | 384 |
| 每头维度 | $d_h=d/H$ | 64 |
| 上下文长度 | $T_{\max}$ | 256 |
| 词表大小 | $V$ | 65 |
| 前馈隐藏维度 | $d_{ff}$ | 1536 |
| dropout 概率 | $p$ | 0.2 |
| 线性层偏置 | — | 不使用 |
| 批大小 | $B$ | 12 |
| 梯度累积步数 | $A$ | 4 |
| 总迭代步数 | $T_{\text{iter}}$ | 5000 |

参数量由各组件求和得到。不使用偏置时，单个 Block 包含注意力 $4d^2$、前馈网络 $2dd_{ff}$ 与两个 LayerNorm 的缩放参数 $2d$；词嵌入与输出投影绑定，只计一份；位置嵌入与末端 LayerNorm 各计一份：

$$
N=Vd+T_{\max}d+L\left(4d^{2}+2dd_{ff}+2d\right)+d.
$$

代入 $d=384$、$d_{ff}=4d=1536$、$V=65$、$T_{\max}=256$、$L=6$：

$$
N=65\cdot384+256\cdot384+6\left(12\cdot384^{2}+2\cdot384\right)+384=10{,}745{,}088.
$$

逐项核算如下表。$12d^{2}=12\cdot147{,}456=1{,}769{,}472$ 是单层注意力的 $4d^{2}$ 与前馈网络的 $8d^{2}$ 之和。

| 组件 | 计算式 | 参数量 |
|---|---|---|
| token 嵌入 `wte` | $65\times384$ | 24,960 |
| 位置嵌入 `wpe` | $256\times384$ | 98,304 |
| 单层注意力 | $4\times384^{2}$ | 589,824 |
| 单层前馈网络 | $2\times384\times1536$ | 1,179,648 |
| 单层 LayerNorm 两个 | $2\times384$ | 768 |
| 单层合计 | $12d^{2}+2d$ | 1,770,240 |
| 六层合计 | $6\times1{,}770{,}240$ | 10,621,440 |
| 末端 LayerNorm | $384$ | 384 |
| 输出投影（绑定） | $0$ | 0 |
| 合计 | — | 10,745,088 |

训练目标不是「损失下降」这一模糊描述，而是下表列出的可检验条件。初始损失由词表大小决定：若模型对所有字符输出均匀分布，交叉熵为 $\ln V=\ln65=4.174$，因此第 0 步的损失应在 4.17 至 4.25 之间；显著高于该区间说明初始化尺度过大或 logits 存在整体偏移，显著低于该区间说明优化器状态或评估数据异常。标签移位错误不会改变第 0 步损失，而是让损失在训练几十步内降到 0.1 以下。

| 验收项 | 目标值 | 检验方式 |
|---|---|---|
| 参数量 | 10.745M，误差不超过 1% | 打印 `sum(p.numel())` |
| 第 0 步损失 | 4.17 至 4.25 | 训练日志 |
| 第 5000 步验证损失 | 低于 1.70，典型值 1.50 附近 | 训练日志 |
| 生成文本 | 含 `名字:` 形式的说话人标签、换行、常见英文词 | 目视检查样例 |
| 单步显存 | 4 GB 显卡可运行（$B=12$） | `nvidia-smi` |
| checkpoint | 可被 `torch.load` 读取并独立生成 | 重新加载脚本 |

训练预算可以直接算出。每步处理的 token 数为 $B\cdot T\cdot A=12\cdot256\cdot4=12{,}288$，5000 步共 $6.14\times10^{7}$ 个 token。训练集约 100 万个字符，因此 5000 步相当于把语料重复约 60 遍；这个倍数解释了为什么必须使用 dropout 0.2，也解释了为什么验证损失在 1.5 附近停止下降后，继续训练只会扩大训练集与验证集的差距。

选择该规模的依据是可运行性而非最优性：10.75M 参数在 fp32 下参数、梯度与 AdamW 两个动量共约 172 MB，单张 4 GB 显卡即可容纳全部状态与激活；同时 6 层、6 头的结构保留了多头拆分、残差、Pre-LN 与权重绑定的全部关键路径，改动任一组件都会在损失或生成文本上产生可观察的差异。

### 步骤 2 数据准备：语料、词表与批采样

（1）语料。使用 Karpathy 的 tinyshakespeare 数据集，文件为纯文本，约 1.1 MB、1,115,394 个字符、65 个不同字符，内容为莎士比亚若干剧本的拼接。选择它有三个原因：体积小，可完整读入内存并按字符索引；字符集小，$V=65$ 使 token 嵌入、输出投影与位置嵌入合计约 12 万参数，模型容量集中在 Transformer 本体；文本具有稳定的局部结构（人名、冒号、换行、诗句），训练后这些结构会直接出现在生成结果中，便于判断模型是否学到东西。

脚本先检查 `data/input.txt` 是否存在；不存在时尝试用 `urllib.request.urlretrieve` 下载，失败则写入内置回退语料。回退语料只包含三行对白、重复 300 次，词表约 38 个字符，仅用于验证代码路径，不能用于复现第 7 节的损失数值。删除下载逻辑会使脚本在离线环境中直接失败；删除回退逻辑则使脚本在无法访问数据源时无法完成冒烟测试。

（2）词表与编码。把语料中出现的字符排序去重得到 `chars`，再构造两个字典：

$$
\mathrm{stoi}(c)=i\iff \mathrm{itos}(i)=c,\qquad \mathcal{C}=\{c_1<c_2<\cdots<c_V\}.
$$

排序保证同一语料在任意机器上得到相同的下标，从而保证 checkpoint 可跨进程复用。编码把字符串映射为整型序列：

$$
\mathbf{d}=\left(\mathrm{stoi}(c_1),\dots,\mathrm{stoi}(c_N)\right)\in\{0,\dots,V-1\}^{N}.
$$

下标类型必须是 `torch.long`（int64），因为 `nn.Embedding` 要求整型索引；用 `torch.tensor(list_of_ints)` 时 PyTorch 默认推断为 int64，但若从 NumPy 传入 `int32` 数组则会在嵌入层抛出类型错误。

（3）训练集与验证集划分。取前 90% 为训练集、后 10% 为验证集：

$$
N_{\text{train}}=\lfloor0.9N\rfloor,\qquad \mathbf{d}_{\text{train}}=\mathbf{d}_{0:N_{\text{train}}},\qquad \mathbf{d}_{\text{val}}=\mathbf{d}_{N_{\text{train}}:N}.
$$

划分必须按位置连续切分，不能随机抽取字符。随机划分会让验证集中的每个字符在训练集中都有相邻字符作为上下文，而语言模型的输入是长度 256 的窗口，相邻窗口高度重叠，验证损失会被系统性低估。连续切分保留了「验证集是未见过的连续文本块」这一条件，代价是验证集与训练集在文体上可能略有差异。

（4）批采样。训练不按固定顺序遍历语料，而是在每个可起始位置中均匀抽取：

$$
i\sim\mathcal{U}\{0,1,\dots,N-T-1\},\qquad
\mathbf{x}=\mathbf{d}_{i:i+T},\qquad
\mathbf{y}=\mathbf{d}_{i+1:i+T+1}.
$$

其中 $\mathbf{x},\mathbf{y}\in\mathbb{Z}^{B\times T}$，$B$ 条序列的起始位置独立抽取。$\mathbf{y}$ 相对 $\mathbf{x}$ 右移一位，因此在位置 $t$ 上，输入是 $d_{i+t}$，目标是 $d_{i+t+1}$；最后一位目标 $d_{i+T}$ 是窗口之后紧接着的字符，它不在 $\mathbf{x}$ 中。这正是教师强制的实现形式：一次前向同时得到 $T$ 个预测，每个预测只使用其左侧的真实字符。

用一个长度为 6 的玩具序列说明移位与边界。设 $\mathbf{d}=[7,4,11,11,14,15]$、$T=4$、$i=0$，则 $\mathbf{x}=[7,4,11,11]$、$\mathbf{y}=[4,11,11,14]$；若 $i=1$，则 $\mathbf{x}=[4,11,11,14]$、$\mathbf{y}=[11,11,14,15]$。$i$ 的最大合法值为 $N-T-1=1$，此时 $\mathbf{y}$ 的最后一个元素恰好是序列最后一个字符。代码用 `torch.randint(len(data) - block_size, (batch_size,))` 采样，上界开区间为 $N-T$，因此最大取到 $N-T-1$，`y` 的切片 `data[i+1:i+T+1]` 末端不超过 $N$，不会越界。若把上界写成 $N-T+1$，$i$ 可以取到 $N-T$，`y` 的切片末端超过 $N$，实际长度变为 $T-1$，`torch.stack` 因形状不一致而报错；若写成 $N$，`x` 的切片长度同样不足 $T$，`stack` 同样失败。

随机偏移的替代方案是按固定步长顺序遍历。顺序遍历的相邻批高度相关，梯度噪声小且分布偏移明显，训练前期容易在局部文体上过拟合；随机偏移使每个批近似独立同分布，代价是同一 epoch 内某些位置被重复采样、某些位置未被采样。在 60 个 epoch 的预算下，这一代价可以忽略。

（5）张量形状与类型。整条数据链上的形状变化如下表，后续模型定义中的每个形状都可以在这张表上对齐。

| 对象 | 形状 | dtype | 说明 |
|---|---|---|---|
| `data` | $(N,)$ | int64 | 全语料字符索引 |
| `x` | $(B,T)$ | int64 | 输入字符 |
| `y` | $(B,T)$ | int64 | 右移一位的目标 |
| token 嵌入 | $(B,T,d)$ | float32 | 查表结果 |
| Block 输出 | $(B,T,d)$ | float32 | 形状保持不变 |
| logits | $(B,T,V)$ | float32 | 每个位置一个词表分布 |
| loss | $()$ | float32 | 标量 |

（6）字符级与子词级的取舍。字符级把 $V$ 压到 65，输出层与嵌入层参数极少，任意字符串都可编码，不存在未登录词；代价是同样长度的文本包含的语义更少，256 个字符大约相当于 60 至 80 个英文词，模型必须从更长的字符序列中学习词形与句法。子词级 BPE 把常见片段合并为一个 token，$V$ 通常为 3 万至 5 万，同样文本的 token 数约为字符数的四分之一，但嵌入与输出层参数量增加到 $Vd$ 量级。两种分词下的损失数值不可直接比较，跨分词比较应换算为每字符比特数：

$$
\mathrm{BPC}=\frac{\mathcal{L}_{\text{token}}\cdot n_{\text{tokens}}}{n_{\text{chars}}\ln2},
$$

其中 $\mathcal{L}_{\text{token}}$ 是每 token 的平均负对数似然，$n_{\text{tokens}}$ 与 $n_{\text{chars}}$ 分别是同一文本的 token 数与字符数。BPE 的算法与训练过程见 [[Tokenizer与BPE]]，token 与嵌入的关系见 [[预备知识-token与嵌入]]。

### 步骤 3 模型定义：注意力、MLP、Block 与 GPT

（1）整体数据流。模型由五个可独立检查的部分串联：token 嵌入、位置嵌入、$L$ 个 Pre-LN Block、末端 LayerNorm、与词嵌入绑定的输出投影。数据流如下。

```mermaid
flowchart LR
    A["token 索引 (B,T)"] --> B["token 嵌入 (B,T,d)"]
    C["位置 0..T-1"] --> D["位置嵌入 (T,d)"]
    B --> E["逐元素相加"]
    D --> E
    E --> F["dropout"]
    F --> G["Block × L"]
    G --> H["末端 LayerNorm"]
    H --> I["lm_head，权重与 wte 绑定"]
    I --> J["logits (B,T,V)"]
```

前向中序列维始终保持 $T$，唯一在序列维之间混合信息的算子是注意力；其余算子对每个位置独立作用。这一性质使形状检查可以简化为两条断言：每个 Block 的输入输出形状相同，logits 的最后一维等于 $V$。

（2）LayerNorm。对每个位置的特征向量独立归一化，统计量沿 $d$ 维计算：

$$
\mathrm{LN}(\mathbf{x})=\boldsymbol{\gamma}\odot\frac{\mathbf{x}-\mu}{\sqrt{\sigma^{2}+\epsilon}},\qquad
\mu=\frac{1}{d}\sum_{i=1}^{d}x_i,\qquad
\sigma^{2}=\frac{1}{d}\sum_{i=1}^{d}(x_i-\mu)^{2},
$$

其中 $\boldsymbol{\gamma}\in\mathbb{R}^{d}$ 是可学习的缩放向量，$\epsilon=10^{-5}$ 防止除零，$\odot$ 为逐元素乘。本篇不使用偏置，因此没有平移项 $\boldsymbol{\beta}$。LayerNorm 与批归一化的区别在于统计量的范围：前者只依赖单个位置的 $d$ 个特征，后者依赖整个批，因而 LayerNorm 在批大小变化与自回归推理时行为一致。归一化的作用维度必须是最后一维；若误对序列维归一化，不同位置的尺度被强行拉平，位置信息与内容信息同时受损。

（3）因果自注意力。输入 $X\in\mathbb{R}^{B\times T\times d}$ 先经过一次合并投影得到查询、键、值：

$$
[Q,K,V]=XW_{qkv},\qquad W_{qkv}\in\mathbb{R}^{d\times3d}.
$$

合并投影在数学上等价于三个独立的 $d\times d$ 投影按列拼接，但只需一次矩阵乘法与一次内核调用，且 `split` 得到的三块在内存中连续。拆分多头时，把最后一维 $d$ 解释为 $H\times d_h$，再交换头维与序列维：

$$
Q_h=XW_{Q,h}\in\mathbb{R}^{B\times T\times d_h}
\;\longrightarrow\;
\tilde{Q}_h\in\mathbb{R}^{B\times H\times T\times d_h}.
$$

每个头的注意力为

$$
A_h=\mathrm{softmax}\left(\frac{\tilde{Q}_h\tilde{K}_h^{\top}}{\sqrt{d_h}}+M\right),\qquad
O_h=A_h\tilde{V}_h,
$$

其中 $M\in\mathbb{R}^{T\times T}$ 是因果掩码：

$$
M_{ij}=\begin{cases}0, & j\le i,\\ -\infty, & j>i.\end{cases}
$$

$-\infty$ 在 softmax 之前加入，使被禁止位置的权重严格为 0，且每行仍归一化为 1。所有头的结果在特征维拼接后经过输出投影：

$$
O=\left[O_1;\dots;O_H\right]W_O,\qquad W_O\in\mathbb{R}^{d\times d}.
$$

缩放因子 $\sqrt{d_h}$ 的作用可以用方差说明。若 $q_i,k_i$ 独立且均值 0、方差 1，则点积 $q\cdot k=\sum_{i=1}^{d_h}q_ik_i$ 的方差为 $d_h$；不除 $\sqrt{d_h}$ 时，$d_h=64$ 使 logits 的标准差约为 8，softmax 进入饱和区，最大权重接近 1、其余接近 0，梯度接近 0。除以 $\sqrt{d_h}$ 后点积方差回到 1，softmax 处于可训练区间。完整推导与数值例子见 [[注意力机制与QKV]]。

实现上有两条路径。第一条调用 `F.scaled_dot_product_attention(q, k, v, is_causal=True, dropout_p=p)`，由底层根据硬件选择融合内核，不显式构造 $T\times T$ 矩阵；第二条在手写路径中显式构造分数矩阵并加上掩码。为了让两条路径都能工作，构造函数中注册一个形状为 $(1,1,T_{\max},T_{\max})$ 的布尔掩码缓冲区，内容为下三角全真矩阵。缓冲区不参与梯度，`persistent=False` 使它不进入 `state_dict`，避免固定尺寸的掩码与可变上下文长度冲突；注册为 buffer 而非普通属性，是为了让 `.to(device)` 自动把它搬到与输入相同的设备。

掩码若加在 softmax 之后再把上三角置零，每行之和不再为 1，输出尺度随位置变化；若把掩码转置，位置 $t$ 只能看到 $t$ 之后的内容，训练损失会异常低而生成完全无效；若忘记把掩码搬到 GPU，前向会直接抛出设备不一致错误。这三种错误在小模型上都可能训练若干步后才被发现，因此应在第一次前向时就用因果性检验确认：只修改最后一个位置的输入，前面所有位置的输出必须逐元素不变。

多头拆分的形状变换如下表，以 $B=12$、$T=256$、$d=384$、$H=6$ 为例。

| 步骤 | 形状 |
|---|---|
| 输入 $X$ | $(12,256,384)$ |
| 合并投影 $XW_{qkv}$ | $(12,256,1152)$ |
| 拆分后的 $Q,K,V$ | 各 $(12,256,384)$ |
| `view` 为四维 | $(12,256,6,64)$ |
| `transpose(1,2)` | $(12,6,256,64)$ |
| 分数 $\tilde{Q}\tilde{K}^{\top}/\sqrt{d_h}$ | $(12,6,256,256)$ |
| softmax 后权重 | $(12,6,256,256)$ |
| 加权和 $A\tilde{V}$ | $(12,6,256,64)$ |
| `transpose` 后合并头维 | $(12,256,384)$ |
| 输出投影 $W_O$ | $(12,256,384)$ |

`view` 与 `transpose` 的分工不能交换。若先 `view(B, H, T, d_h)` 再转置，得到的是把序列切成 $H$ 段、每段内部再分 $T\times d_h$ 的布局，头与位置的对应关系错误；这种错误不会报错，只会让每个头看到错位的内容。正确做法是先 `view(B, T, H, d_h)`，再 `transpose(1, 2)`。

（4）前馈网络。每个位置独立地经过两层线性变换与一次激活：

$$
\mathrm{MLP}(X)=W_2\,\mathrm{GELU}(W_1X),\qquad
W_1\in\mathbb{R}^{d\times d_{ff}},\quad W_2\in\mathbb{R}^{d_{ff}\times d}.
$$

隐藏维度取 $d_{ff}=4d=1536$。GELU 的定义为

$$
\mathrm{GELU}(x)=x\Phi(x),\qquad
\Phi(x)=\frac{1}{2}\left(1+\mathrm{erf}\left(\frac{x}{\sqrt{2}}\right)\right),
$$

其中 $\Phi$ 是标准正态分布的累积分布函数。工程上常用 tanh 近似：

$$
\mathrm{GELU}(x)\approx\frac{x}{2}\left(1+\tanh\left(\sqrt{\frac{2}{\pi}}\left(x+0.044715x^{3}\right)\right)\right).
$$

与 ReLU 相比，GELU 在 $x<0$ 的小区间内保留非零梯度，且在 0 附近平滑，使深层网络的损失曲面更连续。PyTorch 的 `F.gelu` 默认使用精确的 erf 形式。

$4\times$ 的扩展比例来自容量分配：单层注意力的参数量为 $4d^{2}$，前馈网络的参数量为 $2dd_{ff}=8d^{2}$，两者约为 $1:2$。若把 $d_{ff}$ 取为 $d$，前馈网络参数降到 $2d^{2}$，单层总参数从约 $12d^{2}$ 降到约 $6d^{2}$，减少接近一半，模型容量显著下降；若取 $8d$，单层总参数增到约 $20d^{2}$，而小数据集上的收益有限，因此 $4d$ 是常见折中。

（5）Block。每个 Block 由两个子层组成，均采用 Pre-LN 与残差连接：

$$
X\leftarrow X+\mathrm{Attn}\left(\mathrm{LN}_1(X)\right),\qquad
X\leftarrow X+\mathrm{MLP}\left(\mathrm{LN}_2(X)\right).
$$

残差路径上的恒等映射使梯度可以从最后一层直接回传到第一层：对 $X_{l+1}=X_l+F_l(\mathrm{LN}(X_l))$ 求导，$\partial X_{l+1}/\partial X_l=I+\partial F_l/\partial X_l$，其中 $I$ 保证即使子层梯度很小，梯度也不会按层数指数衰减。Post-LN 把归一化放在残差相加之后，即 $X_{l+1}=\mathrm{LN}(X_l+F_l(X_l))$，初始阶段每次相加后的尺度被归一化重新压缩，深层网络的梯度范数随层数下降，需要精细的 warmup 才能训练；Pre-LN 把归一化移到子层入口，残差流保持未归一化的累加状态，训练更稳定，代价是残差流的尺度随层数增长，因此在全部 Block 之后必须再加一次 LayerNorm。去掉末端 LayerNorm，最后一层的输出尺度直接进入输出投影，logits 量级随深度漂移，交叉熵在初始阶段即可能溢出。

（6）GPT 主体。token 嵌入矩阵 $E_{\text{tok}}\in\mathbb{R}^{V\times d}$ 与位置嵌入矩阵 $E_{\text{pos}}\in\mathbb{R}^{T_{\max}\times d}$ 相加后经过 dropout：

$$
X_0=\mathrm{Drop}\left(E_{\text{tok}}[\mathbf{x}]+E_{\text{pos}}[0{:}T]\right)\in\mathbb{R}^{B\times T\times d}.
$$

位置索引必须是 $0$ 到 $T-1$ 的连续整数，且与输入窗口的起点无关：模型学习的是相对位置模式在绝对位置上的投影，窗口在语料中滑动时位置编号始终从 0 开始。若把位置索引写成语料中的绝对位置，位置嵌入表会在超过 $T_{\max}$ 时越界；若忘记加位置嵌入，注意力无法区分不同位置的内容，只能依赖因果掩码提供的粗略顺序信息，损失会明显高于正常配置，通常停在 2.2 以上。

$L$ 个 Block 之后接末端 LayerNorm，再与绑定的词嵌入相乘得到 logits：

$$
Z=\mathrm{LN}_f(X_L)\,E_{\text{tok}}^{\top},\qquad Z\in\mathbb{R}^{B\times T\times V}.
$$

权重绑定使输出投影不再单独占用 $Vd$ 个参数。在本篇规模下这只节省 24,960 个参数，约占总量的 0.23%；当 $V=50{,}257$、$d=768$ 时节省约 3,860 万参数，与 GPT-2 的 1.24 亿总量相比不可忽略。绑定还有正则化效果：同一个矩阵既要把字符映射为向量，又要从向量还原为字符分布，两个方向的梯度相加，迫使嵌入空间同时满足两种约束。绑定的实现顺序必须是先创建 `lm_head`，再把 `wte.weight` 赋给它；若先初始化再绑定，`apply` 会对同一张量按两个模块各初始化一次，最终只保留后一次抽样，初始化分布与设计不符；若在绑定之外又为 `lm_head` 单独创建一份权重，绑定失效，参数量增加且两个矩阵各自更新。

初始化采用标准差 0.02 的正态分布。对残差投影（名字以 `c_proj.weight` 结尾的矩阵）额外除以 $\sqrt{2L}$：

$$
W_{\text{proj}}\sim\mathcal{N}\left(0,\frac{0.02^{2}}{2L}\right).
$$

推导依据是残差流的方差累积。每个 Block 有两次残差相加，$L$ 层共 $2L$ 次；若每次子层输出的方差与输入同阶，残差流方差会按 $2L$ 倍增长。把子层输出的方差缩小到 $1/(2L)$，相加后的方差保持在与输入同阶，深层网络的激活与梯度不会随深度漂移。去掉该缩放，12 层以上的模型在训练初期会出现损失尖峰；在本篇 6 层规模下影响较小，但保留它可以与更深的配置兼容。

前向返回 logits 与可选损失。损失在模型内部计算，是为了让训练循环只依赖 `(x, y)` 两个张量；若把损失计算移到外部，需要把 logits 从 $[B,T,V]$ 展平为 $[BT,V]$ 并与 `y.reshape(-1)` 对齐，这段逻辑在多个调用点重复，容易在评估与训练之间出现不一致。

`generate` 方法把前缀裁剪到最近 $T_{\max}$ 个字符，前向取最后一个位置的 logits，除以温度、可选地做 top-k 过滤，再经 softmax 与 `multinomial` 采样，最后沿序列维拼接。裁剪保证位置嵌入不越界；只取最后一个位置是因为前面的位置在训练时已经用真实前缀计算过，解码时它们的预测不再需要。采样细节与 KV Cache 版本见步骤 5。

### 步骤 4 训练循环：损失、优化器与调度

（1）损失函数。语言模型的训练目标是最大化真实下一个字符的条件概率，等价于最小化其负对数似然：

$$
\mathcal{L}(\theta)=-\frac{1}{BT}\sum_{b=1}^{B}\sum_{t=1}^{T}\log p_\theta\left(y_{b,t}\mid x_{b,\le t}\right),
$$

其中 $p_\theta(\cdot\mid x_{b,\le t})=\mathrm{softmax}(Z_{b,t})$ 是位置 $t$ 的词表分布。代码把 logits 从 $[B,T,V]$ 展平为 $[BT,V]$，把目标展平为 $[BT]$，再调用 `F.cross_entropy`，它在内部完成 log-softmax 与负号，数值上比先 softmax 再取对数稳定。除以 $BT$ 使损失与批大小、上下文长度无关；若改为求和，学习率需要随 $B\cdot T$ 反向缩放，换配置时容易遗忘。

初始损失由均匀分布给出：$\mathcal{L}_0\approx\ln V=\ln65=4.174$。实际第 0 步略高，因为初始化使 logits 有小幅波动，且评估只抽取有限批。若第 0 步接近 $\ln V$ 而在几十步内迅速降到 0.1 以下，说明目标与输入错位（模型看到了答案）；若一直停在 $\ln V$ 附近不下降，问题通常在优化器、学习率或掩码，而不在数据。

（2）AdamW 与参数分组。AdamW 维护梯度的一阶与二阶矩估计：

$$
\mathbf{m}_t=\beta_1\mathbf{m}_{t-1}+(1-\beta_1)\mathbf{g}_t,\qquad
\mathbf{v}_t=\beta_2\mathbf{v}_{t-1}+(1-\beta_2)\mathbf{g}_t^{2},
$$

$$
\hat{\mathbf{m}}_t=\frac{\mathbf{m}_t}{1-\beta_1^{t}},\qquad
\hat{\mathbf{v}}_t=\frac{\mathbf{v}_t}{1-\beta_2^{t}},
$$

$$
\theta_t=\theta_{t-1}-\eta\left(\frac{\hat{\mathbf{m}}_t}{\sqrt{\hat{\mathbf{v}}_t}+\epsilon}+\lambda\theta_{t-1}\right).
$$

与原始 Adam 不同，权重衰减项 $\eta\lambda\theta_{t-1}$ 不经过二阶矩的缩放，因此不会与自适应学习率耦合；这是 AdamW 名称中 decoupled 的含义。$\beta_1=0.9$、$\beta_2=0.95$，后者低于常用的 0.999，使二阶矩对近期梯度更敏感，适合梯度分布随训练阶段变化的语言模型。

参数按维度分组：二维及以上的参数（线性层权重、嵌入矩阵）施加 $\lambda=0.1$ 的权重衰减，一维参数（LayerNorm 的缩放向量）不施加。LayerNorm 的 $\gamma$ 控制归一化后的尺度，把它拉向 0 会直接削弱该子层的输出，与正则化的目标无关；偏置项同理。若对所有参数统一施加权重衰减，归一化层的学习会被持续压制，深层模型表现为损失下降变慢或验证损失变差。分组时按 `p.dim() >= 2` 判断，而不是按参数名匹配，可以覆盖自定义层而不依赖命名约定。

（3）梯度累积。一次参数更新使用 $A$ 个微批：

$$
\mathbf{g}=\frac{1}{A}\sum_{a=1}^{A}\nabla_\theta\mathcal{L}\left(\mathcal{B}_a\right),\qquad
\mathbf{g}\approx\nabla_\theta\mathcal{L}\left(\bigcup_{a=1}^{A}\mathcal{B}_a\right).
$$

等效批大小为 $B\cdot T\cdot A=12\cdot256\cdot4=12{,}288$ 个 token。实现要点有三条：每个微批的损失必须先除以 $A$ 再反传，否则梯度是正确值的 $A$ 倍；`zero_grad` 只能在一次参数更新之前调用一次，放在微批循环内部会不断清空已累积的梯度；`optimizer.step()` 在微批循环之后调用一次。三条中任意一条写错，训练仍会运行，但等效学习率与批大小偏离设定，损失曲线与预期不符。

梯度累积不改变显存峰值，因为每个微批的反向完成后其计算图即被释放；它改变的是梯度的方差与优化步数。等效批增大 $A$ 倍后，梯度噪声下降约 $\sqrt{A}$ 倍，通常可以相应提高学习率，但提高幅度需通过验证损失确认，不能直接按线性比例放大。

（4）梯度裁剪。每次参数更新之前计算全部参数梯度的全局 $L_2$ 范数，并按阈值 $c$ 缩放：

$$
\|\mathbf{g}\|_2=\sqrt{\sum_i g_i^{2}},\qquad
\mathbf{g}\leftarrow\mathbf{g}\cdot\min\left(1,\frac{c}{\|\mathbf{g}\|_2}\right).
$$

阈值取 1.0。裁剪只在范数超过阈值时生效，正常情况下不改变更新方向，只缩短步长。它的作用是限制偶发的尖峰：当某个批包含罕见字符组合或数值异常时，梯度范数可能比中位数高两个数量级，一次更新即可把参数推出可训练区域，表现为损失突然跳到 10 以上且不再恢复。裁剪必须在所有微批反传完成之后、`step()` 之前调用；若在每个微批后单独裁剪，累积的梯度不再是各微批梯度的平均。

（5）学习率调度。前 $T_w=100$ 步线性预热，之后余弦衰减到 $\eta_{\min}=10^{-4}$：

$$
\eta(t)=\begin{cases}
\eta_{\max}\dfrac{t+1}{T_w+1}, & t<T_w,\\[2mm]
\eta_{\min}+\left(\eta_{\max}-\eta_{\min}\right)\dfrac{1+\cos\left(\pi\dfrac{t-T_w}{T_{\max}-T_w}\right)}{2}, & T_w\le t\le T_{\max},
\end{cases}
$$

其中 $\eta_{\max}=10^{-3}$，$T_{\max}=5000$。第 0 步的学习率为 $10^{-3}/101\approx9.90\times10^{-6}$，第 100 步达到峰值，第 5000 步降到 $10^{-4}$。预热解决的是 Adam 二阶矩在最初几步估计不准的问题：$t=1$ 时 $\hat{\mathbf{v}}_1=\mathbf{g}_1^{2}$，更新量近似为 $\eta\cdot\mathrm{sign}(\mathbf{g}_1)$，与梯度大小无关，若此时学习率已是峰值，参数会在初始几步被大幅推离初始化。余弦衰减使后期步长平滑减小，降低最终阶段的梯度噪声，使验证损失更稳定地停在局部极小值附近。

（6）评估。每 250 步在训练集与验证集上各抽取 100 个批，计算平均损失。评估必须调用 `model.eval()` 关闭 dropout，并在 `torch.no_grad()` 下进行；否则 dropout 使每次评估的损失随机波动，且中间激活被保留，显存随评估批数增长。评估结束后调用 `model.train()` 恢复训练模式。训练损失与验证损失同时记录：两者同步下降说明模型仍在学习；训练损失下降而验证损失上升说明过拟合，应增大 dropout、减小模型或提前停止；两者都停滞说明容量或优化配置已到瓶颈。

（7）日志与 checkpoint。每次评估输出迭代步、训练损失、验证损失、当前学习率与每步毫秒数。checkpoint 保存四项内容：`model.state_dict()`、`optimizer.state_dict()`、配置字典与当前步数。保存优化器状态是为了恢复训练时 Adam 的一阶与二阶矩不丢失；只保存模型参数会使恢复后的前几百步出现损失反弹。保存配置是为了在独立采样时重建结构，否则必须手工保证 `n_layer`、`n_head`、`n_embd` 与训练时一致。恢复训练的标准流程是：重建同配置模型、加载模型与优化器状态、把循环起点设为保存的步数，并让学习率调度从该步继续。

（8）稳定性配置的相互作用。dropout 0.2 抑制 60 个 epoch 下的过拟合；梯度裁剪 1.0 限制尖峰；warmup 100 步避免初始大步长；残差投影缩放使深层残差流尺度稳定；学习率峰值 $10^{-3}$ 与批大小 12,288 匹配。五项中任意一项缺失，训练通常仍能完成，但损失曲线会出现可识别的异常：去掉 warmup 时前 50 步损失可能上升到 6 以上；去掉裁剪时偶发 NaN；去掉 dropout 时验证损失在 2000 步后回升；残差缩放缺失时 12 层以上配置出现损失尖峰。

### 步骤 5 采样：温度、top-k 与 KV Cache

（1）温度。模型输出 logits $\mathbf{z}\in\mathbb{R}^{V}$，温度为 $\tau>0$ 时采样分布为

$$
p_i^{(\tau)}=\frac{\exp\left(z_i/\tau\right)}{\sum_{j=1}^{V}\exp\left(z_j/\tau\right)}.
$$

$\tau<1$ 使分布更尖锐，$\tau>1$ 使分布更平坦，$\tau\to0$ 时退化为 argmax。以 logits $[2,1,0]$ 为例：

| 温度 $\tau$ | $p_0$ | $p_1$ | $p_2$ | 分布熵 |
|---|---|---|---|---|
| 0.5 | 0.8668 | 0.1173 | 0.0159 | 0.44 |
| 1.0 | 0.6652 | 0.2447 | 0.0900 | 0.94 |
| 2.0 | 0.5065 | 0.3072 | 0.1863 | 1.04 |

温度不改变 logits 的排序，只改变概率质量在候选间的分配。训练损失与温度无关；温度只影响解码。字符级模型在 $\tau=0.8$ 附近通常能兼顾拼写正确性与多样性；$\tau=1.2$ 以上时生成文本会出现更多拼写错误与随机标点。

（2）top-k。只保留 logits 最大的 $k$ 个候选，其余置为 $-\infty$ 后重新归一化：

$$
\mathcal{S}_k=\operatorname{topk}(\mathbf{z},k),\qquad
p_i=\frac{\exp(z_i)\cdot\mathbb{1}\left[i\in\mathcal{S}_k\right]}{\sum_{j\in\mathcal{S}_k}\exp(z_j)}.
$$

$k$ 必须被截断到 $[1,V]$；当 $k\ge V$ 时过滤不产生任何效果。字符级模型 $V=65$，$k=40$ 会去掉约 25 个低频字符，减少标点与大小写噪声；若沿用语言模型常见的 $k=200$，在本篇配置下等价于不过滤。top-k 与温度可以叠加：先按温度缩放，再取 top-k，最后 softmax；顺序不能颠倒，若先 softmax 再按概率截断，被截掉的质量不会重新分配，剩余概率之和小于 1。

（3）生成循环中的形状与索引。设前缀为 $\mathbf{idx}\in\mathbb{Z}^{B\times T_0}$，每步执行：

1. 取最近 $T_{\max}$ 个位置：$\mathbf{idx}[:, -T_{\max}:]$，保证位置嵌入不越界。
2. 前向得到 $[B,T,V]$ 的 logits，只取最后一个位置：$\mathbf{z}=\text{logits}[:, -1, :]\in\mathbb{R}^{B\times V}$。
3. 除以温度，按需做 top-k，softmax 得到 $[B,V]$ 的概率。
4. `torch.multinomial(probs, num_samples=1)` 采样，得到 $[B,1]$ 的下一个 token。
5. 沿第 1 维拼接：$\mathbf{idx}\leftarrow[\mathbf{idx};\mathbf{idx}_{\text{next}}]\in\mathbb{Z}^{B\times(T_0+1)}$。

五步中任何一步的维度写错都会立即报错，唯独第 1 步的裁剪容易被忽略：若不裁剪，生成长度超过 $T_{\max}$ 时 `wpe(pos)` 的索引越界，抛出 `IndexError`；若裁剪时误用 `idx[:, :T_max]` 保留最前面的字符，最近生成的内容被丢弃，模型始终基于旧前缀续写，输出与前文脱节但不报错。

（4）计算复杂度与缓存动机。不缓存时，第 $t$ 步需要为长度 $t$ 的前缀重新计算全部键与值，单步成本约为

$$
\mathcal{O}\left(L\left(td^{2}+t^{2}d\right)\right),
$$

生成长度为 $n$ 的序列、前缀长度为 $T_0$ 时总成本约为

$$
\mathcal{O}\left(Ld^{2}n(T_0+n)+Ld\,n(T_0+n)^{2}\right).
$$

缓存历史键值后，每步只为新 token 计算 $Q,K,V$，单步成本降为

$$
\mathcal{O}\left(Ld^{2}+Ltd\right),
$$

总成本降为 $\mathcal{O}(Ld^{2}n+Ld\,n(T_0+n))$。当 $T_0+n=256$、$d=384$ 时，注意力部分从每步约 $256^{2}\cdot384$ 次乘加降到约 $256\cdot384$ 次，投影部分从 $256d^{2}$ 降到 $d^{2}$。缓存占用的显存为

$$
M_{\text{KV}}=2\cdot L\cdot B\cdot T\cdot d\cdot s,
$$

其中因子 2 对应键与值，$s$ 是每个元素的字节数。$L=6$、$B=1$、$T=256$、$d=384$、fp32 时 $M_{\text{KV}}=4{,}718{,}592$ 字节，约 4.5 MiB；$B=12$ 时约 54 MiB。显存的详细分析与 prefill/decode 两阶段的差异见 [[KV缓存]]。

（5）KV Cache 版本。以下代码保存为 `kv_cache.py`，与 `train.py` 放在同一目录后可直接运行。它不改动训练路径，只把三个 `forward_cached` 方法与一个 `generate_cached` 方法挂到 `train` 模块的类上；末尾的对照检查验证缓存版本与完整前向的 logits 一致、采样序列一致。

```python
"""kv_cache.py：为 train.py 的 GPT 增加键值缓存解码。"""
import torch
import torch.nn.functional as F

import train


def attn_forward_cached(self, x, cache=None):
    B, T, C = x.shape
    q, k, v = self.c_attn(x).split(self.n_embd, dim=2)
    hs = C // self.n_head
    q, k, v = [t.view(B, T, self.n_head, hs).transpose(1, 2) for t in (q, k, v)]
    if cache is not None:
        k = torch.cat([cache[0], k], dim=2)      # 历史键在前，新键在后
        v = torch.cat([cache[1], v], dim=2)
    if self.flash:
        y = F.scaled_dot_product_attention(q, k, v, is_causal=(cache is None))
    else:
        att = (q @ k.transpose(-2, -1)) / (self.n_embd // self.n_head) ** 0.5
        if cache is None:
            att = att.masked_fill(~self.mask[:, :, :T, :T], float("-inf"))
        y = F.softmax(att, dim=-1) @ v
    y = y.transpose(1, 2).contiguous().view(B, T, C)
    return self.c_proj(y), (k, v)


def block_forward_cached(self, x, cache=None):
    a, new_cache = self.attn.forward_cached(self.ln_1(x), cache)
    x = x + a
    return x + self.mlp(self.ln_2(x)), new_cache


def gpt_forward_cached(self, idx, past=None):
    T = idx.size(1)
    offset = 0 if past is None else past[0][0].size(2)
    pos = torch.arange(offset, offset + T, device=idx.device)
    x = self.transformer.drop(self.transformer.wte(idx) + self.transformer.wpe(pos))
    new_past = []
    for i, block in enumerate(self.transformer.h):
        x, c = block.forward_cached(x, None if past is None else past[i])
        new_past.append(c)
    return self.lm_head(self.transformer.ln_f(x)), new_past


@torch.no_grad()
def generate_cached(self, idx, max_new_tokens, temperature=1.0, top_k=None):
    self.eval()
    idx = idx[:, -self.config.block_size:]
    past = None
    for _ in range(max_new_tokens):
        offset = 0 if past is None else past[0][0].size(2)
        step = idx if past is None else idx[:, -1:]
        if offset + step.size(1) > self.config.block_size:
            break
        logits, past = self.forward_cached(step, past)
        logits = logits[:, -1, :] / max(temperature, 1e-8)
        if top_k is not None:
            v, _ = torch.topk(logits, min(top_k, logits.size(-1)))
            logits[logits < v[:, [-1]]] = -float("inf")
        probs = F.softmax(logits, dim=-1)
        idx = torch.cat((idx, torch.multinomial(probs, 1)), dim=1)
    return idx


train.CausalSelfAttention.forward_cached = attn_forward_cached
train.Block.forward_cached = block_forward_cached
train.GPT.forward_cached = gpt_forward_cached
train.GPT.generate_cached = generate_cached

if __name__ == "__main__":
    cfg = train.GPTConfig(block_size=64, vocab_size=20, n_layer=2, n_head=2,
                          n_embd=32, dropout=0.0)
    torch.manual_seed(0)
    model = train.GPT(cfg).eval()
    prompt = torch.tensor([1, 5, 7, 3, 9]).unsqueeze(0)
    full, _ = model(prompt)
    cached, past = model.forward_cached(prompt)
    print("logits 一致:", torch.allclose(full, cached, atol=1e-6))
    print("缓存形状:", tuple(past[0][0].shape))
    torch.manual_seed(42)
    a = model.generate(prompt, 20, temperature=0.8, top_k=10)
    torch.manual_seed(42)
    b = model.generate_cached(prompt, 20, temperature=0.8, top_k=10)
    print("采样一致:", torch.equal(a, b))
```

预期输出为：

```text
logits 一致: True
缓存形状: (1, 2, 5, 16)
采样一致: True
```

缓存版本在总长度达到 `block_size` 时停止，因此最多返回 `block_size` 个 token；`generate` 通过裁剪前缀可以继续生成。若需要无限长度，应在缓存中丢弃最旧的键值并相应调整位置编号，这会改变位置语义，完整讨论见 [[KV缓存]]。

代码中的三个要点对应缓存实现的三类错误。第一，位置偏移必须由缓存长度给出：`offset = past[0][0].size(2)`，新 token 的位置编号接在历史之后；若每步都从 0 开始，每个新 token 都会被当作位置 0，位置嵌入与训练时的语义不一致。第二，`is_causal` 只在预填充阶段为真：预填充一次送入长度为 $T_0$ 的前缀，必须屏蔽未来位置；逐 token 解码时查询只有 1 个、键包含全部历史，所有历史都在过去，不需要也不能再用因果掩码，否则会错误地屏蔽部分缓存。第三，缓存与生成的停止条件必须同时检查：`offset + step.size(1) > block_size` 时停止，避免位置嵌入越界；若只检查生成长度而不检查缓存长度，前缀较长时会在中途越界。

## 关键直觉

> [!tip] 小型 GPT 的训练可以看作一条固定的五段映射上的梯度下降：字符索引经嵌入得到向量，经 $L$ 个「因果注意力 + 前馈网络」残差块变换，在末端投影回词表，交叉熵只惩罚真实字符位置上的概率。实现是否正确可由四个量定位：第 0 步损失是否等于 $\ln V$，损失是否在数百步内降到 2 附近，验证损失是否与训练损失同步下降，生成文本是否出现语料中的局部结构。四个量分别对应链路的不同环节：第 0 步偏离 $\ln V$ 对应词表、初始化或损失计算，几十步内降到 0.1 以下对应标签移位，数百步后仍停在 2 以上对应学习率、掩码或位置处理，后期验证损失回升对应正则化与数据量，生成异常对应解码与采样。该表述与步骤 1 的验收表、步骤 4 的损失公式、步骤 5 的采样公式逐项对应，不引入额外假设。

## 例子与代码

以下脚本在 PyTorch 2.0 及以上运行，CPU 与 GPU 均可，GPU 上自动启用融合注意力与 fused AdamW。本机以 PyTorch 2.14.1 CPU 版完成了 1 至 2 步的端到端冒烟运行：数据下载因网络限制失败后自动改用回退语料，词表 38，参数量 10.73M，前向、反向、优化器更新、checkpoint 保存与重新加载、采样全部执行成功。完整 5000 步的损失与耗时未在本机复现，第 7 节给出依据配置与算力推算的预期量级。

### 步骤 6 完整代码：train.py

将以下内容保存为 `train.py`，在空目录中直接运行。脚本只依赖标准库与 PyTorch，不依赖 NumPy、transformers 或 datasets。

```python
"""字符级小型 GPT：单文件训练与采样。运行: python train.py
依赖: Python 3.10+，PyTorch 2.0+"""
import math
import os
import time
import urllib.request
from dataclasses import dataclass

import torch
import torch.nn as nn
import torch.nn.functional as F

DATA_URL = ("https://raw.githubusercontent.com/karpathy/char-rnn/"
            "master/data/tinyshakespeare/input.txt")
FALLBACK_TEXT = (  # 离线回退语料：仅供冒烟测试
    "KING: What news from the northern road tonight?\n"
    "QUEEN: Then let the gates be closed and torches lit;\n"
    "MESSENGER: My lord, the army waits beyond the river.\n") * 300
CFG = dict(batch_size=12, grad_accum=4, max_iters=5000, eval_interval=250,
           eval_iters=100, lr=1e-3, min_lr=1e-4, warmup=100, weight_decay=0.1,
           grad_clip=1.0, dropout=0.2, seed=1337, block_size=256)


@dataclass
class GPTConfig:
    block_size: int = 256
    vocab_size: int = 65
    n_layer: int = 6
    n_head: int = 6
    n_embd: int = 384
    dropout: float = 0.2
    bias: bool = False


class CausalSelfAttention(nn.Module):
    def __init__(self, config):
        super().__init__()
        assert config.n_embd % config.n_head == 0
        self.n_head, self.n_embd = config.n_head, config.n_embd
        self.dropout = config.dropout
        self.c_attn = nn.Linear(config.n_embd, 3 * config.n_embd, bias=config.bias)
        self.c_proj = nn.Linear(config.n_embd, config.n_embd, bias=config.bias)
        self.resid_dropout = nn.Dropout(config.dropout)
        self.flash = hasattr(F, "scaled_dot_product_attention")
        mask = torch.tril(torch.ones(config.block_size, config.block_size,
                                     dtype=torch.bool))
        self.register_buffer("mask", mask[None, None], persistent=False)

    def forward(self, x):
        B, T, C = x.shape
        q, k, v = self.c_attn(x).split(self.n_embd, dim=2)
        hs = C // self.n_head
        q, k, v = [t.view(B, T, self.n_head, hs).transpose(1, 2)
                   for t in (q, k, v)]                       # (B, nh, T, hs)
        if self.flash:
            y = F.scaled_dot_product_attention(
                q, k, v, is_causal=True,
                dropout_p=self.dropout if self.training else 0.0)
        else:
            att = (q @ k.transpose(-2, -1)) / math.sqrt(hs)
            att = att.masked_fill(~self.mask[:, :, :T, :T], float("-inf"))
            att = F.dropout(F.softmax(att, dim=-1), self.dropout, self.training)
            y = att @ v
        y = y.transpose(1, 2).contiguous().view(B, T, C)
        return self.resid_dropout(self.c_proj(y))


class MLP(nn.Module):
    def __init__(self, config):
        super().__init__()
        self.c_fc = nn.Linear(config.n_embd, 4 * config.n_embd, bias=config.bias)
        self.c_proj = nn.Linear(4 * config.n_embd, config.n_embd, bias=config.bias)
        self.dropout = nn.Dropout(config.dropout)

    def forward(self, x):
        return self.dropout(self.c_proj(F.gelu(self.c_fc(x))))


class Block(nn.Module):
    def __init__(self, config):
        super().__init__()
        self.ln_1 = nn.LayerNorm(config.n_embd, bias=config.bias)
        self.attn = CausalSelfAttention(config)
        self.ln_2 = nn.LayerNorm(config.n_embd, bias=config.bias)
        self.mlp = MLP(config)

    def forward(self, x):
        x = x + self.attn(self.ln_1(x))
        return x + self.mlp(self.ln_2(x))


class GPT(nn.Module):
    def __init__(self, config):
        super().__init__()
        self.config = config
        self.transformer = nn.ModuleDict(dict(
            wte=nn.Embedding(config.vocab_size, config.n_embd),
            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=nn.LayerNorm(config.n_embd, bias=config.bias)))
        self.lm_head = nn.Linear(config.n_embd, config.vocab_size, bias=False)
        self.lm_head.weight = self.transformer.wte.weight      # 权重绑定
        self.apply(self._init_weights)
        for name, p in self.named_parameters():
            if name.endswith("c_proj.weight"):
                nn.init.normal_(p, 0.0, 0.02 / math.sqrt(2 * config.n_layer))

    def _init_weights(self, module):
        if isinstance(module, nn.Linear):
            nn.init.normal_(module.weight, 0.0, 0.02)
            if module.bias is not None:
                nn.init.zeros_(module.bias)
        elif isinstance(module, nn.Embedding):
            nn.init.normal_(module.weight, 0.0, 0.02)

    def forward(self, idx, targets=None):
        T = idx.size(1)
        assert T <= self.config.block_size, "序列长度超过 block_size"
        pos = torch.arange(T, dtype=torch.long, device=idx.device)
        x = self.transformer.wte(idx) + self.transformer.wpe(pos)
        x = self.transformer.drop(x)
        for block in self.transformer.h:
            x = block(x)
        logits = self.lm_head(self.transformer.ln_f(x))        # (B, T, V)
        loss = None
        if targets is not None:
            loss = F.cross_entropy(logits.view(-1, logits.size(-1)),
                                   targets.reshape(-1))
        return logits, loss

    @torch.no_grad()
    def generate(self, idx, max_new_tokens, temperature=1.0, top_k=None):
        self.eval()
        for _ in range(max_new_tokens):
            logits, _ = self(idx[:, -self.config.block_size:])
            logits = logits[:, -1, :] / max(temperature, 1e-8)
            if top_k is not None:
                v, _ = torch.topk(logits, min(top_k, logits.size(-1)))
                logits[logits < v[:, [-1]]] = -float("inf")
            probs = F.softmax(logits, dim=-1)
            idx = torch.cat((idx, torch.multinomial(probs, 1)), dim=1)
        return idx


def prepare_data():
    path = os.path.join("data", "input.txt")
    if not os.path.exists(path):
        os.makedirs("data", exist_ok=True)
        try:
            urllib.request.urlretrieve(DATA_URL, path)
        except Exception as exc:
            print(f"下载失败（{exc}），改用内置回退语料")
            with open(path, "w", encoding="utf-8") as f:
                f.write(FALLBACK_TEXT)
    text = open(path, encoding="utf-8").read()
    chars = sorted(set(text))
    stoi = {ch: i for i, ch in enumerate(chars)}
    itos = {i: ch for i, ch in enumerate(chars)}
    data = torch.tensor([stoi[c] for c in text], dtype=torch.long)
    n = int(0.9 * len(data))
    return data[:n], data[n:], stoi, itos


def get_batch(split, train_data, val_data, block_size, batch_size, device):
    data = train_data if split == "train" else val_data
    ix = torch.randint(len(data) - block_size, (batch_size,))
    x = torch.stack([data[i:i + block_size] for i in ix])
    y = torch.stack([data[i + 1:i + block_size + 1] for i in ix])
    return x.to(device), y.to(device)


@torch.no_grad()
def estimate_loss(model, train_data, val_data, config, batch_size, device,
                  eval_iters):
    out = {}
    model.eval()
    for split in ("train", "val"):
        losses = [model(*get_batch(split, train_data, val_data, config.block_size,
                                   batch_size, device))[1].item()
                  for _ in range(eval_iters)]
        out[split] = sum(losses) / len(losses)
    model.train()
    return out


def get_lr(it, max_iters):
    if it < CFG["warmup"]:
        return CFG["lr"] * (it + 1) / (CFG["warmup"] + 1)
    ratio = min(1.0, (it - CFG["warmup"]) / (max_iters - CFG["warmup"]))
    return CFG["min_lr"] + 0.5 * (1 + math.cos(math.pi * ratio)) * (
        CFG["lr"] - CFG["min_lr"])


def main():
    torch.manual_seed(CFG["seed"])
    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
    train_data, val_data, stoi, itos = prepare_data()
    config = GPTConfig(vocab_size=len(stoi), dropout=CFG["dropout"])
    model = GPT(config).to(device)
    print(f"词表 {config.vocab_size}，参数量 "
          f"{sum(p.numel() for p in model.parameters()) / 1e6:.2f}M")

    decay = [p for p in model.parameters() if p.dim() >= 2]
    no_decay = [p for p in model.parameters() if p.dim() < 2]
    optimizer = torch.optim.AdamW(
        [{"params": decay, "weight_decay": CFG["weight_decay"]},
         {"params": no_decay, "weight_decay": 0.0}],
        lr=CFG["lr"], betas=(0.9, 0.95))
    os.makedirs("out", exist_ok=True)
    ckpt_path = os.path.join("out", "ckpt.pt")
    t0 = time.time()

    for it in range(CFG["max_iters"] + 1):
        lr = get_lr(it, CFG["max_iters"])
        for group in optimizer.param_groups:
            group["lr"] = lr
        if it % CFG["eval_interval"] == 0:
            losses = estimate_loss(model, train_data, val_data, config,
                                   CFG["batch_size"], device, CFG["eval_iters"])
            ms = 1000 * (time.time() - t0) / max(it, 1)
            print(f"iter {it:5d} | train {losses['train']:.4f} | "
                  f"val {losses['val']:.4f} | lr {lr:.2e} | {ms:.0f} ms/iter")
            torch.save({"model": model.state_dict(),
                        "optimizer": optimizer.state_dict(),
                        "config": config.__dict__, "iter": it}, ckpt_path)
        if it == CFG["max_iters"]:
            break
        optimizer.zero_grad(set_to_none=True)
        for _ in range(CFG["grad_accum"]):
            x, y = get_batch("train", train_data, val_data, config.block_size,
                             CFG["batch_size"], device)
            _, loss = model(x, y)
            (loss / CFG["grad_accum"]).backward()
        torch.nn.utils.clip_grad_norm_(model.parameters(), CFG["grad_clip"])
        optimizer.step()

    model.load_state_dict(torch.load(ckpt_path, map_location=device)["model"])
    prompt = "KING: "
    idx = torch.tensor([stoi[c] for c in prompt]).unsqueeze(0).to(device)
    out = model.generate(idx, max_new_tokens=300, temperature=0.8, top_k=40)
    print("----- 生成样例 -----")
    print("".join(itos[i] for i in out[0].tolist()))


if __name__ == "__main__":
    main()
```

脚本共 247 行，其中非空行 214 行。以下按六个代码块解释关键行：每块说明它在做什么、为什么这样做、去掉或写错会怎样。块 1 是顶部常量与 `GPTConfig`。`CFG` 字典集中全部训练超参数，`GPTConfig` 只保留决定模型结构的字段。这样划分的原因是：结构参数必须写进 checkpoint 才能在独立采样时重建模型，训练参数则可以在恢复训练时被新的配置覆盖。`vocab_size` 的默认值 65 只是占位，`main` 用 `len(stoi)` 覆盖它。若把超参数散落在函数体内，改变批大小或学习率需要修改多处，且 checkpoint 无法记录当时的配置；若把 `block_size` 只写在 `CFG` 而不传入模型，位置嵌入表的行数与生成时的裁剪长度可能不一致，越界错误会在生成阶段才出现。

块 2 是 `CausalSelfAttention`。`c_attn` 把三个投影合并为一个 `Linear(d, 3d)`，`split(d, dim=2)` 沿最后一维切成三块，顺序必须是查询、键、值，与后续 `q, k, v = ...` 的拆包顺序一致。`view(B, T, H, d_h).transpose(1, 2)` 把头维放到序列维之前，得到 `(B, H, T, d_h)`；注意力在最后两维上计算，批维与头维只做广播。`mask` 是形状 `(1,1,T_max,T_max)` 的布尔下三角矩阵，注册为 `persistent=False` 的 buffer，因此会随 `.to(device)` 迁移、不进入 `state_dict`、不参与梯度。`flash` 分支调用融合注意力，`else` 分支手写分数、掩码、softmax、dropout 与加权和。两条路径的计算结果在浮点误差内一致，区别只在显存与速度：手写路径显式构造 `(B,H,T,T)` 的分数矩阵，`T=256`、`B=12`、`H=6` 时为 18.9 MB，融合路径不物化该矩阵。

这一块中去掉因果掩码，位置 $t$ 可以看到 $t$ 之后的字符，训练损失会在几百步内降到 1 以下，但生成时模型只能看到自己刚写出的前缀，分布与训练不一致，输出退化为重复或乱码；把掩码加在 softmax 之后，每行不再归一化，输出尺度随位置变化；把 `transpose` 写成 `view(B, H, T, d_h)`，每个头看到错位的内容，损失仍会下降但明显更慢；去掉输出投影 `c_proj`，多个头的结果只能直接拼接，头与头之间没有可学习的混合；去掉 `resid_dropout`，注意力输出以确定方式进入残差流，60 个 epoch 下验证损失更早回升。

块 3 是 `MLP` 与 `Block`。`c_fc` 把维度从 384 升到 1536，`F.gelu` 逐元素激活，`c_proj` 降回 384，最后接 dropout。`Block` 按 Pre-LN 组合：`ln_1` 的输出进入注意力，注意力输出与原始 `x` 相加；`ln_2` 的输出进入 MLP，MLP 输出再与更新后的 `x` 相加。两次相加的顺序不能交换，第二次相加的输入必须是第一次相加的结果，否则 MLP 看到的是未融合注意力信息的旧残差流。`nn.LayerNorm(d, bias=False)` 只保留缩放向量，与全模型不使用偏置的设定一致。

去掉残差相加，6 层网络仍可训练，但梯度必须逐层穿过归一化与两个线性层，收敛速度显著下降，且第 0 步之后的损失曲线更容易出现平台；去掉两个 LayerNorm，残差流的尺度随层数增长，学习率 $10^{-3}$ 下前几十步就可能出现损失尖峰；把 Pre-LN 改成 Post-LN 而保留 `x + sub(ln(x))` 的写法，归一化位置与残差顺序不一致，深层配置需要重新调 warmup；把 $4\times$ 改成 $1\times$，单层参数从 177 万降到约 89 万，模型容量不足以在 5000 步内把验证损失压到 1.6 以下。

块 4 是 `GPT`。`nn.ModuleDict` 让 `wte`、`wpe`、`drop`、`h`、`ln_f` 以固定名字注册，`state_dict` 的键因此稳定，checkpoint 可跨版本加载。`lm_head` 创建后立即把 `wte.weight` 赋给它，完成权重绑定；`apply(self._init_weights)` 对线性层与嵌入层做正态初始化；随后的循环只对名字以 `c_proj.weight` 结尾的矩阵重新缩放，涵盖注意力的输出投影与 MLP 的第二层，不涵盖 `c_fc`。`forward` 中位置索引由 `torch.arange(T)` 生成，与输入内容无关；`logits.view(-1, V)` 与 `targets.reshape(-1)` 把批与时间维合并，交给交叉熵。

`generate` 先把前缀裁剪到最近 256 个字符，再前向取最后一个位置。裁剪是为了位置嵌入不越界；只取最后一个位置是因为前缀中其他位置的预测在训练时已经出现过，解码时不需要。温度除法与 top-k 过滤都在 softmax 之前完成，`multinomial` 按归一化后的概率抽一个样本，`cat` 沿序列维扩展。

去掉位置嵌入，注意力无法区分不同位置的内容，模型只能依赖因果掩码提供的粗略顺序，损失通常停在 2.2 以上；把 `wpe` 的索引写成语料绝对位置，生成超过 256 个字符时越界；先初始化再绑定权重，`lm_head` 与 `wte` 各自被初始化一次，绑定后只保留后写入的值，结果仍可训练但初始化尺度不再符合设计；去掉 `generate` 中的裁剪，长文本生成会在第 257 个字符处抛出索引错误；把 `logits[:, -1, :]` 写成 `logits[:, 0, :]`，模型总是用第一个位置的预测续写，输出与前缀无关。

块 5 是数据与评估工具。`prepare_data` 先检查本地文件，缺失时下载，下载异常时写入回退语料；随后排序去重构造 `stoi` 与 `itos`，把整篇文本编码为 int64 张量，并按 90/10 连续切分。`get_batch` 用 `torch.randint(N - T, (B,))` 抽取起始位置，`x` 取 `[i, i+T)`，`y` 取 `[i+1, i+T+1)`，两者都通过 `torch.stack` 变成 `(B,T)` 后搬到设备。`estimate_loss` 在 `no_grad` 下对训练集与验证集各抽 100 批求平均，进入时 `model.eval()`、退出时 `model.train()`。`get_lr` 实现线性预热与余弦衰减，`min(1.0, ...)` 保证步数超过上限时比例不超过 1。

去掉 `model.eval()`，评估时 dropout 仍然生效，同一检查点的两次评估可能相差 0.05 以上，无法判断验证损失是否真的下降；去掉 `no_grad`，评估的 100 个批全部保留计算图，显存随评估批数增长；把划分改成随机抽样，验证集的窗口与训练集大量重叠，验证损失被低估，早停与模型选择随之失效；把 `randint` 的上界写成 `N - T + 1`，`y` 的切片短一列，`torch.stack` 抛出形状不一致错误。

块 6 是训练主循环。`torch.manual_seed` 固定初始化与批采样；参数按维度分成 `decay` 与 `no_decay` 两组交给 AdamW；每步先按 `get_lr` 设置两组的学习率，再在评估间隔上计算损失、打印日志、保存 checkpoint；随后清空梯度，循环 4 次微批前向与反传，每次损失除以 4；最后裁剪梯度并更新参数。循环上界是 `max_iters + 1`，因此第 5000 步只评估不更新，日志中的最后一行对应最终模型。训练结束后重新加载 checkpoint 并生成 300 个字符。

去掉 `optimizer.zero_grad(set_to_none=True)`，梯度会跨步累加，等效学习率随步数增长，损失在数百步内发散；把除以 `grad_accum` 写在反传之后，梯度是正确值的 4 倍，配合裁剪后等效于把学习率放大约 4 倍；把 `clip_grad_norm_` 放在每个微批之后，裁剪作用于单个微批而不是累积梯度，阈值语义改变；把 `optimizer.step()` 放进微批循环，一次「累积批」被拆成 4 次更新，等效批大小退回 12；把 checkpoint 只保存模型参数，恢复训练时 Adam 的动量被重置，损失会出现明显反弹。

### 步骤 7 运行与预期结果

（1）运行命令。把 `train.py` 放入空目录，在该目录执行：

```bash
python train.py
```

首次运行会在 `data/` 下创建 `input.txt` 并下载约 1.1 MB 的语料；下载失败时写入回退语料并在终端打印提示。训练结束后在 `out/ckpt.pt` 保存 checkpoint，并直接打印 300 个字符的生成样例。需要 GPU 时确保安装的是对应 CUDA 版本的 PyTorch，脚本会自动选择 `cuda`。

冒烟测试不需要修改文件，用一行命令覆盖 `CFG` 即可把训练缩短到 200 步：

```bash
python -c "import train; train.CFG.update(max_iters=200, eval_interval=50); train.main()"
```

该命令同样会执行完整的保存、加载与采样路径，用于在正式训练前确认环境与代码无误。若只验证模型结构而不训练，可把 `max_iters` 设为 0，此时第 0 步评估后立即保存并生成。

（2）预期日志。在 tinyshakespeare 语料、默认配置、单张消费级显卡上，日志的形态与量级如下。数值为依据配置与算力推算的典型值，实际结果随随机种子、显卡型号与 PyTorch 版本波动，其中损失波动约 0.02，单步耗时波动可达 30%。

```text
词表 65，参数量 10.75M
iter     0 | train 4.2287 | val 4.2315 | lr 9.90e-06 | 0 ms/iter
iter   250 | train 2.3014 | val 2.3186 | lr 9.89e-04 | 168 ms/iter
iter   500 | train 2.0461 | val 2.0788 | lr 9.56e-04 | 170 ms/iter
iter  1000 | train 1.8217 | val 1.8692 | lr 9.07e-04 | 172 ms/iter
iter  2500 | train 1.6064 | val 1.6603 | lr 6.35e-04 | 174 ms/iter
iter  5000 | train 1.4782 | val 1.5397 | lr 1.00e-04 | 176 ms/iter
----- 生成样例 -----
```

第 0 步的 4.2287 高于 $\ln65=4.174$，差值来自初始化后 logits 的小幅波动与有限批评估的抽样误差；若训练开始后损失在几十步内降到 1 以下，应首先检查 `y` 是否误写成 `x`。第 250 步降到 2.30，说明模型已学会字符频率与常见二元组；第 1000 步的 1.82 对应词形与空格的稳定；第 2500 步的 1.61 对应人名、冒号与换行的结构；第 5000 步的 1.48 是字符级模型在该语料上的典型收敛值，验证损失 1.54 略高，差值为 dropout 与 60 个 epoch 的过拟合共同造成。

损失曲线的形态比单个数值更重要。正常曲线在前 100 步快速下降（warmup 结束后学习率达到峰值），随后进入幂律式的缓慢下降，每翻一倍步数约下降 0.1 至 0.2；验证损失在 3000 步后下降趋缓，但不应持续上升。若训练损失下降而验证损失在第 1500 步后持续上升超过 0.05，说明 dropout 不足或模型相对数据过大；若两条曲线在 2.0 以上同时进入平台，说明学习率过低、掩码错误或位置嵌入缺失。

| 迭代步 | 训练损失 | 验证损失 | 主要学到的结构 |
|---|---|---|---|
| 0 | 4.23 | 4.23 | 无，接近均匀分布 |
| 250 | 2.30 | 2.32 | 字符频率、常见二元组 |
| 500 | 2.05 | 2.08 | 空格位置、高频短词 |
| 1000 | 1.82 | 1.87 | 词形、标点搭配 |
| 2500 | 1.61 | 1.66 | 人名与说话人标签、换行 |
| 5000 | 1.48 | 1.54 | 局部句法、诗句节奏 |

（3）单步耗时。每步的计算量可以用 $6N$ 近似：前向中每个参数约需一次乘与一次加，计 2 次浮点运算；反向约需前向的两倍，计 4 次；合计 6 次。

$$
\mathrm{FLOPs}_{\text{step}}\approx6N\cdot B\cdot T\cdot A
=6\times10{,}745{,}088\times12{,}288\approx7.92\times10^{11}.
$$

在 3060 级别显卡上，fp32 矩阵乘的有效吞吐约 4 至 6 TFLOPS，对应每步 0.13 至 0.20 秒，加上 Python 循环与 dropout 的开销约为 0.15 至 0.25 秒；A100 上启用 TF32 后有效吞吐可达 40 至 60 TFLOPS，每步约 0.03 至 0.05 秒。下表给出量级估计，用于判断实测值是否异常，而不是精确基准。

| 设备 | 单步耗时 | 5000 步总时长 | 说明 |
|---|---|---|---|
| RTX 3060 12GB | 0.15 至 0.25 s | 13 至 21 min | 默认配置，fp32 |
| RTX 4090 24GB | 0.04 至 0.08 s | 3 至 7 min | TF32 |
| A100 40GB | 0.03 至 0.05 s | 2.5 至 4 min | TF32，小模型受调度开销限制 |
| 16 核 CPU | 2 至 4 s | 3 至 6 h | 仅用于冒烟测试 |

实测单步耗时显著高于表中上限时，先检查数据是否留在 CPU、是否每步都重新创建优化器、是否在训练循环内调用了 `.item()` 或 `print` 同步 GPU；实测显著低于下限且损失不降时，检查是否误用了 `torch.no_grad()` 包裹训练步。

（4）显存占用。参数、梯度与 AdamW 两个动量都以 fp32 保存：

| 项目 | 计算式 | 大小 |
|---|---|---|
| 参数 | $10{,}745{,}088\times4$ | 43.0 MB |
| 梯度 | 同参数 | 43.0 MB |
| AdamW 一阶矩 | 同参数 | 43.0 MB |
| AdamW 二阶矩 | 同参数 | 43.0 MB |
| 参数状态合计 | — | 172.0 MB |
| 激活（$B=12,T=256$） | 约 75 MB/层 × 6 | 0.45 GB |
| logits 与损失 | $12\times256\times65\times4$ | 0.8 MB |
| CUDA 上下文 | 驱动与内核 | 0.3 至 0.6 GB |

峰值显存约 1.2 至 1.7 GB，4 GB 显卡即可运行，6 GB 以上有充足余量。激活的估算按每层保存的张量求和：LayerNorm 输出 4.7 MB、合并 QKV 14.2 MB、注意力输出 4.7 MB、输出投影 4.7 MB、第二个 LayerNorm 4.7 MB、前馈隐藏层 18.9 MB、GELU 输出 18.9 MB、前馈输出 4.7 MB。使用融合注意力时不物化 $T\times T$ 分数矩阵；走手写路径时每层额外增加 $12\times6\times256\times256\times4=18.9$ MB，六层共 113 MB。梯度累积不增加激活峰值，因为每个微批反传后计算图即被释放。

（5）生成样例的结构特征。训练 5000 步后的字符级模型输出如下形态。以下文本为结构示意，用于对照生成结果应具备的特征，不是本机训练记录。

```text
KING: The news is brought, my lord, from France to-day,
And all the soldiers that were wont to fight
Are fled to Paris with the duke again.
QUEEN: Then let the trumpet sound, and bid the guard
Attend us in the morning at the gate;
For I have seen the comfort of the night
And all the honour of our house is gone.
KING: Speak not of honour, madam, but of war.
```

示意文本体现了四个可检验特征。第一，行首出现 `KING:`、`QUEEN:` 形式的说话人标签，标签后紧跟冒号与空格，说明模型学到了语料的排版结构。第二，换行位置大致落在短语边界，而非固定字符数，说明模型对行宽与句法都有建模。第三，`the`、`and`、`of`、`to` 等高频功能词使用正确，实词之间出现少量搭配错误，说明局部语法已建立而长距离语义尚未建立。第四，文本没有贯穿多行的情节或指代一致性，同一说话人可能在相邻两行表达矛盾内容，这是 10.75M 参数、256 字符上下文与字符级建模共同决定的上限。

使用回退语料时，词表只有 38 个字符，初始损失为 $\ln38=3.64$，模型会在几十步内把训练损失压到 0.5 以下并开始逐字复述模板。这种输出只说明代码路径正确，不能用于评估模型质量。恢复真实语料的办法是删除 `data/input.txt` 并确保网络可访问数据源，或手工把任意长度超过 100 万字符的英文文本保存到该路径。

### 步骤 8 扩展练习

练习 1：改为 BPE 分词。用 BPE 在 tinyshakespeare 上训练大小为 4096 的词表，把 `prepare_data` 的字符编码替换为子词编码，`vocab_size` 改为 4096。参数量变为 $10{,}745{,}088-24{,}960+4{,}096\times384=12{,}292{,}992$，约 12.29M。由于同样 256 个位置能覆盖约 1000 个字符，训练损失（每 token）会升到 2.5 至 3.0，但每字符比特数应按步骤 2 的公式换算后低于字符级的约 2.14。验收标准：报告两种分词在相同训练步数下的 BPC、单步耗时与生成文本，并说明 BPE 的词表规模如何影响嵌入层占比。算法细节见 [[Tokenizer与BPE]]。

练习 2：增加层数。把 `n_layer` 从 6 改为 12，参数量变为 $12\times1{,}770{,}240+123{,}648=21{,}366{,}528$，约 21.37M；保持其余配置不变，训练 5000 步。验收标准：报告验证损失、单步耗时与显存峰值，并解释为什么参数量翻倍后验证损失通常只下降 0.02 至 0.05，而训练损失下降更多。若验证损失上升，说明在当前数据量下增加容量只加剧过拟合，应同时把 dropout 从 0.2 提高到 0.3 或增加数据。

练习 3：加入 RoPE。删除 `wpe`，在注意力内部对每个头的查询与键按位置施加旋转：

$$
\mathbf{q}_{m}'=R_{m}\mathbf{q}_{m},\qquad
\mathbf{k}_{n}'=R_{n}\mathbf{k}_{n},\qquad
\left(R_{m}\mathbf{q}\right)^{\top}\left(R_{n}\mathbf{k}\right)=\mathbf{q}^{\top}R_{n-m}\mathbf{k},
$$

其中 $R_{m}$ 由 $d_h/2$ 个二维旋转块组成，第 $i$ 个块的旋转角为 $m\theta_i$，$\theta_i=10000^{-2i/d_h}$。旋转使点积只依赖相对位移 $n-m$，因此位置信息不再占用参数，且具备向更长上下文外推的可能。验收标准：在 256 上下文下验证损失与学习式位置嵌入相差不超过 0.03；把 `block_size`、生成裁剪与掩码尺寸一并改为 512（不重新训练）后报告损失退化幅度，并与学习式位置嵌入在 512 上直接越界的失败对比。推导见 [[位置编码-正弦与RoPE]]。

练习 4：实现 KV Cache。运行步骤 5 的 `kv_cache.py`，确认两项一致性检查均为 `True`，并记录缓存形状，然后把 `generate` 与 `generate_cached` 的耗时各测 10 次取平均。验收标准：在 256 上下文、生成 300 个字符时报告加速比（通常在 2 至 4 倍之间）、缓存显存（按公式应为 4.5 MiB）与两版本输出是否逐 token 一致。若加速比接近 1，检查是否每步都重新计算了全部前缀；若输出不一致，检查位置偏移与 `is_causal` 的取值。分析见 [[KV缓存]]。

练习 5：混合精度。在 GPU 上把前向与损失放入 `torch.autocast(device_type="cuda", dtype=torch.bfloat16)`，反向在 autocast 外执行；若使用 `float16`，还需 `torch.amp.GradScaler("cuda")` 对损失缩放并在 `step` 前 `unscale_`。验收标准：报告显存峰值下降比例（通常 30% 至 40%）、单步耗时变化与最终验证损失；与 fp32 基线相比验证损失差值不应超过 0.05。若出现 NaN，先检查是否在 fp16 下计算了 softmax 或 LayerNorm，再检查学习率是否超过 $2\times10^{-3}$。

练习 6：增大等效批。把 `grad_accum` 从 4 改为 16，等效批从 12,288 个 token 增加到 49,152 个 token，学习率按平方根缩放从 $10^{-3}$ 提到 $1.5\times10^{-3}$ 至 $2\times10^{-3}$，训练步数降到 1250 以保持总 token 数不变。验收标准：在相同 token 预算下比较验证损失，差值应小于 0.03；报告单步耗时（约变为 4 倍）与梯度范数的变化，并解释为什么等效批增大后可以用更大的学习率。

### 步骤 9 调试清单

调试按以下顺序进行。顺序的依据是：越靠前的检查越便宜、越能解释后续现象；跳过前两项直接调超参数，通常会在错误的方向上反复尝试。

| 顺序 | 现象 | 检查 | 修复 |
|---|---|---|---|
| 1 | 任意报错 | 打印 `x.shape`、`y.shape`、`logits.shape`；检查 dtype 与 device | 形状按步骤 3 的表对齐；索引张量转 int64；模型与数据同设备 |
| 2 | 第 0 步损失异常 | 损失应接近 $\ln V$；打印 `x[0,:8]` 与 `y[0,:8]` 解码后的文本 | 若损失在几十步内迅速降到接近 0，说明 `y=x`，改为右移一位；损失大于 6 检查初始化与 logits 缩放 |
| 3 | 损失不下降 | 打印当前学习率；检查掩码是否生效；检查位置嵌入是否相加；检查 `zero_grad` 位置 | 修正掩码时机与形状；恢复位置嵌入；把 `zero_grad` 移到参数更新前 |
| 4 | 损失下降但生成乱码 | 用同一 `stoi`/`itos` 解码训练批；检查 `generate` 是否裁剪到 256；检查 prompt 字符是否在词表内 | 统一编码表；裁剪前缀；过滤词表外字符；生成前调用 `eval()` |
| 5 | 验证损失回升 | 比较训练与验证损失的差值；统计语料重复次数 | 提高 dropout；提前停止；增加数据；减小模型 |
| 6 | 损失变为 NaN | 用 `torch.autograd.set_detect_anomaly(True)` 定位算子；检查学习率、fp16 缩放、是否出现全掩码行 | 降低学习率；加 warmup 与裁剪；fp16 改用 bf16 或加 GradScaler |
| 7 | 显存不足或过慢 | 检查评估是否在 `no_grad` 下；检查是否每步 `.item()`；检查 `batch_size` 与 `grad_accum` 的乘积 | 评估加 `no_grad`；累积日志后再打印；减小批、增大累积 |
| 8 | 恢复训练后损失反弹 | 检查 checkpoint 是否含优化器状态；检查配置是否一致；检查随机种子 | 保存并加载 `optimizer.state_dict()`；用 checkpoint 中的配置重建模型 |

第 2 项与第 3 项之间有一个容易忽略的分支：损失在第 0 步正常、前 100 步也正常，但在第 100 步之后突然上升。这通常不是代码错误，而是 warmup 结束、学习率达到峰值的瞬间暴露了配置问题：批太小、学习率太高或梯度裁剪缺失。把峰值学习率降到 $5\times10^{-4}$ 并观察是否恢复，可以在一分钟内区分「配置问题」与「实现问题」。

### 步骤 10 与 nanoGPT 官方实现的差异

nanoGPT 由 `model.py`、`train.py` 与 `config/*.py` 组成，`model.py` 约 250 行，`train.py` 约 300 行。本篇把两者压缩为单文件，保留全部关键路径，删除面向大规模训练的工程组件。差异如下表。

| 项目 | nanoGPT | 本篇 | 影响 |
|---|---|---|---|
| 配置方式 | Python 配置文件加 `exec` 覆盖 | 单一 `CFG` 字典与 `GPTConfig` | 教学更直观；大规模实验不便 |
| 数据加载 | 预编码为 `train.bin`/`val.bin`，`np.memmap` 读取 | 全量读入内存，随机切片 | 1 MB 语料无差异；GB 级语料必须改 |
| 注意力 | 手写实现与 `scaled_dot_product_attention` 分支，掩码按需注册 | 同左，掩码 buffer 始终注册 | 计算等价，显存略高 |
| 混合精度 | `autocast` 加 `GradScaler`，按 dtype 分支 | 未实现 | 显存约高 30%，速度较慢 |
| 分布式 | DDP，梯度累积配 `no_sync` | 未实现 | 单卡可用，多卡需补 |
| 编译 | 可选 `torch.compile` | 未实现 | 单步慢 10% 至 30% |
| 日志 | `wandb` 可选 | `print` | 无远程曲线 |
| checkpoint | 验证损失改善时覆盖 `ckpt.pt`，支持 `resume` | 每次评估覆盖同一文件 | 不能保留最优版本；恢复需手改循环起点 |
| 评估批数 | 200 | 100 | 评估噪声略大 |
| 批与累积 | 64，单步更新 | 12 × 4 | 等效批 48 对 64 |
| $\beta_2$ | 0.99 | 0.95 | 后者对近期梯度更敏感 |
| 采样 | 温度 0.8，`top_k=None` | 温度 0.8，`top_k=40` | 字符级 $V=65$，40 有实际过滤作用 |
| 参数量口径 | 报告 10.65M（不含位置嵌入） | 总参数 10.745M | $10{,}745{,}088-98{,}304=10{,}646{,}784$ |

配置方式的差异影响实验管理。nanoGPT 用 `config/train_shakespeare_char.py` 覆盖默认值，`train.py` 通过 `exec` 读取，因此每个实验可以保存为独立文件并纳入版本控制；本篇的 `CFG` 字典适合单次运行，若要并行多组实验，应把 `CFG` 序列化为 JSON 并以命令行参数选择。数据加载的差异影响可扩展性。nanoGPT 把语料一次性编码为 `uint16` 二进制文件，训练时用 `np.memmap` 按需读取，内存占用与语料大小无关；本篇把全部索引读入内存，1 MB 语料约 8 MB 的 int64 张量，可以忽略，但 100 GB 语料会直接耗尽内存。

混合精度与分布式是最需要补回的两项。fp32 下参数、梯度与两个动量共 172 MB，bf16 混合精度只把前向激活与矩阵乘的输入转为 16 位，参数状态仍为 fp32，显存节省主要来自激活，约 30%；在 10.75M 规模下这一节省不重要，但在 1B 以上规模决定能否放入单卡。DDP 把梯度在卡间求平均，梯度累积需要 `no_sync` 避免每个微批都触发通信；这两点在本篇的单卡实现中不存在，扩展到多卡时必须补上。

checkpoint 的简化有实际代价。本篇每次评估覆盖同一个文件且只保留最后一版，若训练在 5000 步之前中断，只能回到最近的 250 步倍数；nanoGPT 只在验证损失改善或 `always_save_checkpoint` 为真时覆盖 `ckpt.pt`，并记录 `best_val_loss`，因此磁盘上的版本与最优验证损失对应。恢复训练的语义也不同：nanoGPT 有 `init_from='resume'` 分支，自动读取步数与优化器状态；本篇需要手工把 `range(CFG["max_iters"] + 1)` 的起点改为 checkpoint 中的 `iter`，并让 `get_lr` 从该步继续。若忘记修改起点，学习率会从 warmup 重新开始，损失曲线出现不必要的抖动。

参数量的口径差异需要单独说明。nanoGPT 的 `get_num_params(non_embedding=True)` 减去位置嵌入，得到 $10{,}646{,}784$，约 10.65M；本篇报告全部参数 $10{,}745{,}088$，约 10.75M。两者相差 98,304，正好是 $256\times384$ 的位置嵌入。比较不同实现的参数量时，必须先确认是否包含位置嵌入、是否绑定输出投影、LayerNorm 是否带偏置，否则 1% 至 2% 的差异会被误读为结构差异。

## 易错点

> [!warning] 以下六条均可通过一次前向、一次损失打印或一次生成直接检验。
> 1. 标签移位方向错误：`x` 取 `[i, i+T)`、`y` 取 `[i+1, i+T+1)` 才是下一个字符预测；若 `y=x`，位置 $t$ 的输入与目标相同，损失在数百步内降到 0.1 以下，但生成时模型只会重复输出当前字符。若写成 `y = data[i-1:i+T-1]`，模型看到的是上一个字符，损失同样会下降，生成则退化为固定序列。检验方法：打印 `x[0,:8]` 与 `y[0,:8]` 并解码，确认 `y` 的每个字符是 `x` 对应位置的下一个字符。
> 2. 掩码方向、时机或形状错误：掩码必须在 softmax 之前以加性 $-\infty$ 加入；形状 $(T,T)$ 需广播到 $(B,H,T,T)$；`tril` 与 `triu` 用反会使模型只能看到未来。掩码转置后训练损失异常低而生成完全无效，softmax 后置零则每行不再归一化。检验方法：只修改最后一个输入位置的字符，前面所有位置的输出必须逐元素不变。
> 3. 多头拆分顺序错误：必须先 `view(B, T, H, d_h)` 再 `transpose(1, 2)`；先 `view(B, H, T, d_h)` 会把序列切成 $H$ 段，每个头看到错位的内容。该错误不抛出异常，只表现为损失下降变慢。检验方法：对同一输入分别用两种写法，比较输出；或打印 `q[0,0,:3,:4]` 与手工切片的 `q_proj(x)[0,:3,0:4]` 是否一致。
> 4. 权重绑定顺序与状态保存错误：必须先创建 `lm_head`，再把 `wte.weight` 赋给它，最后统一初始化；若先初始化再绑定，绑定后的权重只保留后写入的值，初始化尺度与设计不符。加载 checkpoint 时若模型未做绑定，加载仍会成功，但 `lm_head` 与 `wte` 变成两份独立参数，参数量增加 $Vd$，绑定带来的参数共享与梯度相加随之消失。检验方法：打印 `model.lm_head.weight.data_ptr() == model.transformer.wte.weight.data_ptr()`，应为 `True`。
> 5. 梯度累积的除法与更新位置错误：损失必须除以 `grad_accum` 后再 `backward()`；`zero_grad` 每次参数更新只调用一次；`step()` 在微批循环之后调用一次。把除法写在反传之后、把 `step()` 放进微批循环、或在微批内清梯度，都会使等效批与学习率偏离设定，损失曲线表现为前期过快或过慢。
> 6. 评估与生成的模式、裁剪错误：评估与生成必须处于 `eval()` 且评估需 `no_grad()`；`generate` 必须把前缀裁剪到 `block_size` 以内。忘记 `eval()` 使 dropout 在评估时生效，验证损失随机波动；忘记裁剪使长文本生成在第 257 个字符处越界；把裁剪写成保留最前面的字符而不是最近的字符，最近生成的内容被丢弃，输出与前文脱节但不报错。

## 关联笔记

- 前置 [[Transformer架构详解]]：本篇的 Block 结构、Pre-LN 顺序、残差与末端 LayerNorm 直接复用该篇的层定义，该篇给出 Post-LN 与 Pre-LN 的梯度通路对比。
- 前置 [[注意力机制与QKV]]：步骤 3 的缩放点积注意力、$\sqrt{d_h}$ 的方差论证与多头拆分以该篇的推导为基础，本篇只补充合并投影与掩码 buffer 的实现细节。
- 前置 [[位置编码-正弦与RoPE]]：步骤 3 的位置嵌入相加与步骤 8 的 RoPE 替换都以该篇为正弦编码与旋转位置编码的推导来源。
- 对照 [[KV缓存]]：步骤 5 的缓存版本给出最小实现与显存公式，该篇给出 prefill/decode 两阶段的完整分析、GQA 下的缓存形状与长上下文中的显存瓶颈。
- 后续 [[自回归生成与采样]]：步骤 5 的温度、top-k 与采样循环是该篇解码策略在字符级模型上的具体实现，该篇补充 top-p、重复惩罚与束搜索。

## 达标检测

- [ ] 写出本篇的参数量公式 $N=Vd+T_{\max}d+L(4d^{2}+2dd_{ff}+2d)+d$，代入 $V=65$、$d=384$、$d_{ff}=1536$、$L=6$、$T_{\max}=256$，逐项算出 10,745,088，并说明权重绑定使哪一项为 0。
- [ ] 给定 $B=12$、$T=256$、$H=6$、$d=384$，写出 `c_attn` 输出、拆分后的 $Q/K/V$、分数矩阵、softmax 权重、合并头维后的张量形状，并指出 `view` 与 `transpose` 的顺序为什么不能交换。
- [ ] 写出 `get_batch` 中起始位置的取值范围，证明 `y = data[i+1:i+T+1]` 在 $i\le N-T-1$ 时不越界，并给出 $N=6$、$T=4$、$i=1$ 时 $x$ 与 $y$ 的具体取值。
- [ ] 运行 `train.py`（可先用 200 步冒烟），报告第 0 步损失、最终训练与验证损失、单步耗时与显存峰值，并与步骤 7 的表格比较，解释偏差来源。
- [ ] 分别制造两种错误并预测现象：把 `y` 改成 `x`；把注意力中的 `is_causal` 改为 `False`（或删去掩码）。各训练 200 步，记录损失与生成结果，说明为什么两种错误都会让损失异常低。
- [ ] 运行 `kv_cache.py`，报告三项输出与缓存显存，并解释 `is_causal=(cache is None)` 在预填充与逐 token 解码两个阶段分别取什么值、取反会怎样。
- [ ] 把字符级损失 1.48 换算为每字符比特数，说明它与 BPE 模型的每 token 损失为什么不能直接比较，并写出换算公式与代入过程。

## 参考来源

- Karpathy, nanoGPT 仓库（`karpathy/nanoGPT`）—— 对应本篇的整体结构、`shakespeare_char` 配置、训练循环、采样实现与参数量口径（不含位置嵌入时为 10.65M）。
- Karpathy, "Let's build GPT: from scratch, in code, spelled out"（2023）—— 对应步骤 3 的注意力逐行实现、因果掩码与步骤 5 的采样循环讲解。
- Karpathy, char-rnn 仓库中的 tinyshakespeare 数据集 —— 对应步骤 2 的语料来源、字符集规模与 90/10 划分方式。
- Vaswani et al., "Attention Is All You Need", arXiv:1706.03762 —— 对应步骤 3 的缩放点积注意力、多头拼接与残差结构。
- Raschka, *Build a Large Language Model (From Scratch)*, 2024, 第 4 章 —— 对应步骤 3 的 LayerNorm、GELU 前馈与 Pre-LN 组合，以及步骤 4 的交叉熵训练目标。
- PyTorch 官方文档 `torch.nn.functional.scaled_dot_product_attention`、`torch.optim.AdamW`、`torch.nn.utils.clip_grad_norm_`、`torch.autocast` —— 对应步骤 3 的融合注意力、步骤 4 的优化器与裁剪、步骤 8 的混合精度练习。
