w wyl123ly 的博客
MD

从第一性看nanochat的gpt.py

26 KB 2026.10.22 原文件

从第一性看nanochat的gpt.py

定义

GPT.forward 是 nanochat 的完整前向计算:输入形状为 的 token id 与可选的目标 id,输出形状为 的下一个 token logits 或标量交叉熵损失。它由十个连续阶段组成:截取 RoPE 片段、词嵌入与归一化、smear、保存 、逐层残差混合、注意力子层、MLP 子层、backout 与最终归一化、反嵌入与 softcap、损失或返回。

符号约定:批大小 、序列长度 、层数 、宽度 、查询头数 、KV 头数 、单头维度 、词表大小 、填充词表 。 表示残差流; 是 smear 之后保存的初始状态; 与 是第 层的两个标量。残差流是贯穿所有 Block 的 维向量序列,每个子层读取它的归一化版本,并把输出加回。

为什么重要

gpt.py 只有五百多行,但它是预训练、SFT、RL、评测与推理共同调用的唯一模型实现。训练脚本调用 model(x,y) 得到损失,评测脚本调用它得到 logits,Engine 调用它做 prefill 与 decode。任何一个阶段的顺序、形状或 dtype 错误都会传播到所有下游阶段:

  • 训练:logits 宽度、目标对齐或 softcap 精度错误会直接改变损失与梯度。
  • 推理:RoPE 片段偏移、KV Cache 推进或缓存布局错误会让生成结果与训练不一致。
  • 优化:Linear 的权重 cast、嵌入 dtype 与参数分组决定显存与数值稳定性。
  • 系统:是否使用滑动窗口、是否缓存 KV、是否复用注意力输出,决定吞吐与显存。

在「懂原理 / 能复现 / 懂工程」中,本篇同时覆盖三者:能脱离注释复述每一步是第一性的检验;能按形状调试是复现的检验;能解释每个技巧的代价是工程的检验。前置组件见 自注意力机制、前馈层与激活函数、位置编码与RoPE 与 残差连接与LayerNorm;本篇只讲它们如何在 nanochat 中组装。

原理与推导

GPT.forward 的调用签名是 forward(self, idx, targets=None, kv_cache=None, loss_reduction='mean')。idx 是 的 torch.long;targets 与 idx 同形状,-1 表示忽略;kv_cache 为 None 时走训练/朴素推理路径,非空时走带缓存的推理路径。下面按真实执行顺序拆成十步。

1. 截取 RoPE 片段

进入模型前先检查三个条件: 不超过旋转缓存长度(sequence_len * 10)、idx 与 cos 同设备、cos 的 dtype 等于 COMPUTE_DTYPE。若存在 KV Cache,当前位置 由 kv_cache.get_pos() 给出,旋转片段取 cos[:, T0:T0+T] 与 sin[:, T0:T0+T]。

形状:cos_sin 中两个张量均为 ,在注意力的头维上广播。去掉这一步,decode 的每个 token 都会从位置 0 开始旋转,查询与键的相对位置错误,生成质量会随上下文增长迅速下降;对训练路径,,这一步退化为取前 行,但断言仍然防止序列超过预计算缓存。

2. 词嵌入、dtype 对齐与 RMSNorm

x = self.transformer.wte(idx)   # (B, T, C)
x = x.to(COMPUTE_DTYPE)         # fp16 路径下是有效转换,bf16 下通常是空操作
x = norm(x)                     # RMSNorm over C

wte 是 的查表矩阵,输出 。norm 是 F.rms_norm(x, (C,)),没有可学习参数;它把每个位置的 维向量按其均方根归一化。去掉归一化,嵌入的初始标准差 0.8 会直接进入残差流,注意力 logits 与 MLP 激活的尺度随初始化漂移,深层训练需要重新调参;保留它则不增加任何参数与矩阵乘。

3. smear:把前一个 token 的嵌入混入当前 token

训练/预填充阶段(kv_cache is None 或 T > 1)的公式为

其中 , 是 sigmoid, 是 smear_gate 的权重, 是 smear_lambda。门只读取当前 token 的前 24 个通道,输出一个标量,再在 维上广播。形状:门为 ,前一 token 嵌入为 ,相加后仍为 。

解码阶段(T=1 且缓存已有内容)改为读取 kv_cache.prev_embedding:在修改当前嵌入之前,先把它存为下一步的 prev_embedding;然后用当前 token 的前 24 个通道算门,加上缓存的上一 token 嵌入。这样训练、预填充、解码三条分支在数学上一致。

去掉 smear,模型仍可通过注意力学习相邻 token 的关系,但需要额外的层与头去实现一个一阶 bigram 查表;保留它的代价是 25 个参数、一次 sigmoid 与 的逐元素运算。dev/LOG.md 记录过早期全宽度门控版本「收益可忽略」,当前版本把门输入压到 24 个通道,成本已降到可忽略量级,但它不是模型能力的必要条件。

4. 保存 与 backout 槽位

x0 = x
backout_layer = n_layer // 2
x_backout = None

是 smear 之后的归一化嵌入,不是 wte(idx) 的原始输出;这一点决定了 已经包含一阶邻接信息。backout_layer 是 ,d24 时为 12,即在第 12 号 Block(第 13 层)之后缓存残差。去掉 ,后续每层的 混合项就没有输入,x0_lambdas 失效;去掉 backout 槽位,最后的减项没有缓存可用。

5. 逐层残差混合

每个 Block 之前先做一次逐元素混合:

形状不变,仍为 。初始化规则是

浅层的残差增益大于 1,深层略低于 1.05; 的混入从 0.20 递减到 0.05。去掉这一行,模型退化为标准残差(系数 1)且没有 捷径;实验记录显示这两个标量在各深度上带来稳定的 bpb 改善,详见 nanochat架构特化技巧。

6. 注意力子层

Block 采用 pre-norm:先归一化,再进注意力,最后把输出加回残差流。CausalSelfAttention.forward 的顺序如下。

6.1 投影。 输入 ,三个输入投影给出

注意力输出再过输出投影:

其中 表示带因果与窗口掩码的缩放点积注意力,定义见 自注意力机制;,,。reshape 后 为 , 为 。去掉任一输入投影,注意力就没有对应的查询、键或值;去掉输出投影,多头结果无法混合回 维。

6.2 值嵌入。 若该层有值嵌入(has_ve(i,L) 为真),先查表得到 ,reshape 为 ;门为

然后 (在 维上广播)。门输入只取前 12 个通道,输出维度是 ;去掉值嵌入,模型少了一条几乎不耗 FLOPs 的容量通路,参数量减少约 6 个(d12)或 12 个(d24)词表大小的矩阵。

6.3 RoPE 与 QK norm。 对 的最后一维按前后两半做旋转:

代码旋转 ,与教科书约定互为转置;由于只有 与 的相对旋转进入内积,两者功能等价,保留负号是为了检查点兼容。旋转后对每个头做 RMSNorm,再乘 1.2:

去掉 RoPE,模型失去位置信息;去掉 QK norm,注意力 logits 的尺度随头维度与初始化漂移;去掉 1.2,注意力分布更平缓。1.2 是把缩放分摊到 与 上的经验选择,代码注释承认尚未从第一性推出最优值。

6.4 Flash Attention。 训练路径调用

y = flash_attn.flash_attn_func(q, k, v, causal=True, window_size=window_size)

输入 为 , 为 ,输出 为 。window_size 是 (left, 0):left 表示每个位置只向前看 left 个 token(含自身共 left+1 个键),(-1, 0) 表示全上下文。去掉 Flash Attention,标准实现要物化 的分数矩阵;去掉 causal,当前位置会看到未来 token;去掉窗口,短窗口层的注意力计算与显存回到全上下文。

6.5 缓存路径与输出。 推理时调用 flash_attn_with_kvcache,把当前步的 原地写入该层的 k_cache/v_cache,用 cache_seqlens 定位,输出仍为 。缓存位置只由最后一层推进一次(if self.layer_idx == kv_cache.n_layers - 1: kv_cache.advance(T)),否则每层都会把位置推进 ,下一步读到错误的槽位。最后把 reshape 为 ,过 ,加回残差流。

7. MLP 子层

Block 的第二个子层同样是 pre-norm:

其中 ,。形状:c_fc 输出 ,ReLU² 不改变形状,c_proj 回到 。去掉 ReLU²,两个线性层退化为一个线性映射;去掉 4 倍扩张,MLP 容量不足;去掉残差,深层梯度无法直接回传。ReLU² 是 前馈层与激活函数 的主题,本篇只确认它在 MLP.forward 中的位置。

8. backout 与最终归一化

循环结束后,如果缓存了中层残差:

其中 是 backout_lambda,初值 0.2; 是第 个 Block 之后的残差。随后做一次 norm(x)。去掉减项,最终表示仍携带浅层特征;去掉最终归一化,lm_head 的输入尺度不受控,logits 会随训练发散。注意 backout 在最终归一化之前、所有 Block 之后执行,不是在每个 Block 内。

9. 反嵌入、切片与 logit softcap

logits = self.lm_head(x)                 # (B, T, V')
logits = logits[..., :self.config.vocab_size]  # (B, T, V)
logits = logits.float()                  # fp32
logits = 15 * torch.tanh(logits / 15)    # (-15, 15)

lm_head 是 的无 bias 线性层,权重 master 精度为 fp32,前向时由 Linear cast 到激活 dtype。切片去掉词表填充;float() 把 logits 转到 fp32;softcap 用 平滑压缩到 ,其导数为 ,在 时趋近 0,防止极端 logits 让交叉熵梯度爆炸。

去掉切片,损失的目标索引只在 内,填充列永远不参与正确类,等价于给每行加一个固定偏置,浪费计算;去掉 float(),softcap 与交叉熵在 bf16 下做, 饱和区的微小差异会被舍入;去掉 softcap,logits 无界,训练后期可能出现极端值。nanochat 当前代码把 softcap 硬编码为 15;dev/LOG.md 在 d24 上扫过 5 到 30,记录 20 最优(val loss 0.716 → 0.715),但当前快照仍是 15,两者不一致,阅读时以代码为准。

10. 损失或返回 logits

若 targets 非空:

loss = F.cross_entropy(logits.view(-1, logits.size(-1)),
                       targets.view(-1), ignore_index=-1,
                       reduction=loss_reduction)
return loss

targets 与 idx 同形状,-1 的位置被忽略,用于 SFT/RL 的掩码。若 targets 为空,直接返回 的 logits,供生成或评测使用。去掉 ignore_index=-1,padding 位置会被当作合法类别参与损失;去掉 reduction 参数,RL 无法按样本求和。

11. 组件选择:RMSNorm、Linear、无 bias、不共享权重

RMSNorm。 norm 直接调用 F.rms_norm(x, (C,)),没有 或 。公式为

PyTorch 在未显式传入 eps 时按 dtype 取默认值;bf16 下的 比 fp32 大,这是 bf16 归一化仍能稳定工作的原因之一。没有可学习缩放,参数为零;代价是失去逐通道的再缩放能力,收益是少一组需要初始化的参数,且不会与残差标量重复。

Linear 的 dtype cast。 Linear 继承 nn.Linear,只重写 forward:

class Linear(nn.Linear):
    def forward(self, x):
        return F.linear(x, self.weight.to(dtype=x.dtype))

master 权重保持 fp32 供优化器更新;每次前向把权重临时 cast 到激活 dtype(通常是 bf16),矩阵乘在 bf16 中进行。nanochat 删除了 torch.amp.autocast,因为 autocast 只实际 cast 了 Linear 权重,而 RMSNorm、交叉熵与 Flash Attention 都自行处理 dtype;显式 cast 让精度路径可读、可调。去掉这个 cast,fp32 权重与 bf16 激活会在 F.linear 处 dtype 不匹配;改用 autocast 则重新引入不可控的算子白名单。

无 bias。 所有 Linear 都是 bias=False;RMSNorm 也没有平移参数。每个线性层少一个输出维度大小的向量,d24 的 lm_head 少 32768 个参数,注意力与 MLP 少 或 个。无 bias 会失去每层独立的常数偏移,但后续线性层与残差路径可以吸收这些偏移;RMSNorm 只归一化尺度,不做中心化,因此「后续归一化会重新中心化」不能作为无 bias 的理由。无 bias 主要是减少参数、简化内核并避免偏置与归一化的冗余,属于架构选择而非纯优化。

不共享权重。 wte 与 lm_head 是两个独立的 矩阵,d24 各 50,331,648 个参数,合计约 1.0 亿。共享可以省一半嵌入参数,但会把「输入查表」与「输出分类」的梯度绑在一起:两者的学习率在 setup_optimizer 中分别是 0.212 与 0.0057(d24),量级相差近 37 倍,共享后无法同时满足。nanochat 选择不共享,并用独立的初始化尺度(wte 0.8,lm_head 0.001)控制初始 logits。

前向数据流表

步操作输入形状输出形状去掉会怎样
1取 RoPE 片段cos 缓存解码位置错误
2wte + cast + RMSNorm嵌入尺度失控
3smear少一条一阶邻接通路
4保存 / backout 槽引用后续标量失效
5resid/x0 混合退化为标准残差
6注意力子层无上下文聚合
7MLP 子层无逐位置非线性
8backout + 最终 norm浅层特征残留/尺度漂移
9lm_head + slice + float + softcap无词表分布/数值不稳
10交叉熵或返回标量或 无训练信号

表中 指 sequence_len;旋转缓存长度是它的 10 倍(默认 20480),实际前向只截取前 行。cos/sin 的形状是 ,不是 ;如果把它按当前序列长度预分配,decode 超过该长度时会触发断言。

generate 的朴素实现与 Engine 的差异

GPT.generate 是给调试用的最小自回归循环:断言输入是 Python list、批大小为 1,把 token 列表转成 ,每一步把完整序列送入 forward,取最后一个位置的 logits,做 top-k、温度缩放、multinomial 或 argmax,拼回序列并 yield 一个整数。它没有 KV Cache,因此第 步的注意力要重算前 个位置;生成 个 token 的总计算是 (每步 ),显存也随序列增长。

Engine.generate_batch 使用 KVCache:先对提示做一次 prefill,得到最后位置的 logits 与缓存;再分配 num_samples 行的解码缓存,把提示的 K/V 复制到每一行,之后每步只送一个 token,调用 flash_attn_with_kvcache 追加缓存。它支持批内多行采样、停止 token、工具调用状态机与温度/top-k 参数,是评测、CLI 与 RL rollout 的实际路径。两者的数学定义相同,工程路径不同;不要用 generate 的耗时评估模型吞吐。

在 nanochat 中的落地

文件/函数关键语句作用
nanochat/gpt.py: GPT.forwardx = norm(self.transformer.wte(idx))嵌入与归一化
nanochat/gpt.py: GPT.forwardx = torch.cat([x[:, :1], x[:, 1:] + gate * x[:, :-1]], dim=1)训练/预填充 smear
nanochat/gpt.py: GPT.forwardx = self.resid_lambdas[i] x + self.x0_lambdas[i] x0逐层混合
nanochat/gpt.py: CausalSelfAttention.forwardq, k = norm(q), norm(k);q = q * 1.2QK norm 与缩放
nanochat/gpt.py: CausalSelfAttention.forwardflash_attn.flash_attn_with_kvcache缓存推理
nanochat/gpt.py: GPT.forwardlogits = softcap * torch.tanh(logits / softcap)logit softcap
nanochat/gpt.py: GPT.generatelogits = self.forward(ids)[:, -1, :]朴素生成
nanochat/engine.py: Engine.generate_batchKVCache + sample_next_token生产级生成

关键直觉

前向是「一条残差流 + 四类注入」

把 看成一条从嵌入流向 logits 的主干。主干上只有四类写操作:词嵌入提供 token 身份,smear 提供前一 token 的短期记忆, 提供回到初始状态的捷径,值嵌入提供按 token 查表的额外容量;注意力的输出与 MLP 的输出则是每次读取归一化主干后的加性更新。归一化发生在每次读取之前,标量 控制主干自身的增益。这个视角与定义中的十步一一对应:每一步要么是注入,要么是读取,要么是压缩。

例子与代码

GPT.forward 的核心段落如下(省略了断言与 KV Cache 分支):

def forward(self, idx, targets=None, kv_cache=None, loss_reduction='mean'):
    B, T = idx.size()
    T0 = 0 if kv_cache is None else kv_cache.get_pos()
    cos_sin = self.cos[:, T0:T0+T], self.sin[:, T0:T0+T]

    x = self.transformer.wte(idx)
    x = x.to(COMPUTE_DTYPE)
    x = norm(x)
    gate = self.smear_lambda.to(x.dtype) * torch.sigmoid(self.smear_gate(x[:, 1:, :24]))
    x = torch.cat([x[:, :1], x[:, 1:] + gate * x[:, :-1]], dim=1)  # smear
    x0 = x

    x_backout = None
    for i, block in enumerate(self.transformer.h):
        x = self.resid_lambdas[i] * x + self.x0_lambdas[i] * x0
        ve = self.value_embeds[str(i)](idx).to(x.dtype) if str(i) in self.value_embeds else None
        x = block(x, ve, cos_sin, self.window_sizes[i], kv_cache)
        if i == self.config.n_layer // 2:
            x_backout = x

    x = x - self.backout_lambda.to(x.dtype) * x_backout
    x = norm(x)
    logits = self.lm_head(x)[..., :self.config.vocab_size].float()
    logits = 15 * torch.tanh(logits / 15)
    if targets is not None:
        return F.cross_entropy(logits.view(-1, logits.size(-1)),
                               targets.view(-1), ignore_index=-1,
                               reduction=loss_reduction)
    return logits

这段代码为了展示顺序做了压缩,gate 的定义与缓存分支在上文第 6 步给出;真实实现还包含 KV Cache 的空值判断与形状断言,generate 外层则用 torch.inference_mode 包裹。下面是一段可独立运行的形状复现,使用 d24 的维度,逐步打印每步张量形状;它不计算真实注意力,只验证形状链路:

import torch
import torch.nn.functional as F

B, T, C, H, Hkv, D, V = 2, 8, 1536, 12, 12, 128, 32768
x = torch.zeros(B, T, C)
print("embedding", tuple(x.shape))

x = F.rms_norm(x, (C,))
gate = torch.zeros(B, T - 1, 1)
x = torch.cat([x[:, :1], x[:, 1:] + gate * x[:, :-1]], dim=1)
print("after smear", tuple(x.shape))

x0 = x
for i in range(2):  # 只演示两层的形状
    x = 1.1 * x + 0.1 * x0
    q = torch.zeros(B, T, H, D)
    k = torch.zeros(B, T, Hkv, D)
    v = torch.zeros(B, T, Hkv, D)
    ve = torch.zeros(B, T, Hkv, D)
    v = v + torch.zeros(B, T, Hkv, 1) * ve
    y = torch.zeros(B, T, H, D).reshape(B, T, C)
    x = x + y
    h = F.relu(torch.zeros(B, T, 4 * C)).square()
    x = x + torch.zeros(B, T, C)

x = x - torch.zeros(1) * x
x = F.rms_norm(x, (C,))
logits = 15 * torch.tanh(torch.zeros(B, T, V) / 15)
print("q/k/v", tuple(q.shape), tuple(k.shape), tuple(v.shape))
print("mlp hidden", tuple(h.shape))
print("logits", tuple(logits.shape))

预期输出:

embedding (2, 8, 1536)
after smear (2, 8, 1536)
q/k/v (2, 8, 12, 128) (2, 8, 12, 128) (2, 8, 12, 128)
mlp hidden (2, 8, 6144)
logits (2, 8, 32768)

形状脚本里 q 的最后一维是 D=128,k/v 的第三维是 Hkv=12;若把 n_kv_head 改成 6,k/v 形状会变为 (2,8,6,128),而 q 仍是 (2,8,12,128),这就是 GQA 的广播前提。c_fc 的 4 倍扩张在 d24 下是 1536 → 6144。

易错点

六个可检验的错误

1. 认为 是 wte(idx) 的原始输出。它在 norm 与 smear 之后保存,已经包含相邻 token 信息;把 改到更早的位置会改变所有层的混合语义。

2. 在带缓存的 decode 中让每个 Block 都推进 kv_cache.advance(T)。真实实现只在最后一层推进一次,否则位置会一次跳 。

3. 把 cos_sin 的偏移写成 0。decode 时必须用 kv_cache.get_pos() 截取当前绝对位置的旋转片段,否则位置编码与缓存内容错位。

4. 在 softcap 之前把 logits 切回 bf16,或先做交叉熵再做 softcap。正确顺序是 lm_head → slice → float → softcap → cross_entropy。

5. 忘记 targets 的 -1 掩码。SFT 与 RL 用 -1 标记不参与损失的位置;去掉 ignore_index 会让这些位置被当作类别 0 以外的非法索引而报错,或污染损失。

6. 用 GPT.generate 的耗时判断推理性能。它没有 KV Cache,生成长度 的总计算约为 ;生产路径是 Engine.generate_batch。

关联笔记

  • 前置:自注意力机制、前馈层与激活函数、位置编码与RoPE。分别对应本篇第 6、7 步与 RoPE 片段。
  • 前置:残差连接与LayerNorm。pre-norm、RMSNorm 与残差流的通用原理见该篇。
  • 后续:nanochat架构特化技巧。smear、值嵌入、、backout、softcap 的动机、消融与代价在该篇展开。
  • 后续:KV Cache原理。本篇只讲缓存分支的位置,缓存布局、显存与 prefill/decode 的完整推导见该篇。
  • 跨库:Transformer架构详解。通用 Transformer 的编码器/解码器结构与多头注意力推导见该篇,本篇只讲 nanochat 的组装顺序。

达标检测

  • [ ] 不看代码,按顺序写出 GPT.forward 的十个阶段,并标出每个阶段的输出形状。
  • [ ] 解释 为什么在 smear 之后保存,以及去掉 会影响哪些参数。
  • [ ] 手算 d24 的 q、k/v、c_fc、logits 形状,说明 GQA 下 k/v 的第三维为什么可以小于 q。
  • [ ] 说明 Linear 为什么要显式把权重 cast 到输入 dtype,以及它与 autocast 的区别。
  • [ ] 解释 logit softcap 的公式、导数与必须在 fp32 中执行的原因。
  • [ ] 指出 GPT.generate 与 Engine.generate_batch 的三处工程差异,并估算前者生成 个 token 的复杂度。
  • [ ] 运行形状脚本,核对输出与文中表格一致;再把 Hkv 改为 6 观察 k/v 形状变化。
  • [ ] 找出「decode 位置偏移」与「softcap 精度」两类 bug 的最小复现条件。

参考来源

  • Karpathy, nanochat(commit 92d63d4),nanochat/gpt.py 的 GPT.forward、CausalSelfAttention.forward、MLP.forward、GPT.generate —— 对应本篇全部执行顺序与形状。
  • Karpathy, nanochat,dev/LOG.md 中 2026-01-11 的 per-layer scalars、2026-01-16 的架构消融、2026-03-02 的 softcap 调参 —— 对应标量、backout 与 softcap 的实验记录。
  • Vaswani et al., Attention Is All You Need, arXiv:1706.03762 —— 缩放点积注意力与残差/归一化的原始结构。
  • Zhang & Sennrich, Root Mean Square Layer Normalization, arXiv:1910.07467 —— 无参数 RMSNorm 的定义与数值性质。
  • So et al., Primer: Searching for Efficient Transformers for Language Modeling, arXiv:2109.08668 —— ReLU² 激活的来源。
  • Su et al., RoFormer: Enhanced Transformer with Rotary Position Embedding, arXiv:2104.09864 —— RoPE 的相对位置性质;nanochat 的负角度约定与基频以其代码为准。