w wyl123ly 的博客
MD

GPT模型类与config

24 KB 2026.10.22 原文件

GPT模型类与config

定义

GPTConfig 是 nanochat 中描述 GPT 形状与注意力窗口模式的数据类;GPT 是依据该配置在 meta device 上先构造全部参数形状、再在 init_weights 中一次性填充数值的 torch.nn.Module。模型宽度、头数、层数与词表规模由配置决定,优化器分组、每 token FLOPs 与 KV Cache 大小都由这些形状派生。

符号约定如下。层数 、模型宽度 (即 n_embd)、查询头数 、KV 头数 、单头维度 、序列长度 、词表大小 、填充后的词表大小 。

符号含义在 GPTConfig 中的字段
Transformer 层数n_layer
残差流宽度n_embd
查询头数n_head
键/值头数n_kv_head
单头维度,无独立字段,由前两者推出
最大序列长度sequence_len
词表大小vocab_size
填充到 64 的倍数的词表大小无字段,由 推出
—滑动窗口模式串window_pattern

meta device 是 PyTorch 的一种虚拟设备:张量只携带形状、dtype 与设备标签,不分配存储;对它的数据读写会报错,但形状推导与模块构造可以正常进行。参数组(parameter group)是优化器为不同参数指定不同超参数而维护的列表,每组可有自己的学习率、betas、权重衰减与更新规则。

为什么重要

nanochat 的全部模型规模由 --depth 一个整数控制。base_train.py 先用 build_model_meta(depth) 把 depth 翻译成 GPTConfig,再以该配置构造模型、统计参数量、推导训练 token 数、批大小与学习率。配置一旦改变,下面四条链路会同时改变:

  1. 形状链路: 决定注意力投影与 MLP 的矩阵形状, 决定每头维度, 决定 wte 与 lm_head 的参数数量。
  2. 优化链路:setup_optimizer 按参数来源与形状分组;漏掉一个参数会触发断言,分组错误会让某个矩阵误用 AdamW 或 Muon。
  3. 计算链路:estimate_flops 用 num_matmul_params 与每层窗口大小估算训练 FLOPs,进而决定 num_iterations 与成本。
  4. 推理链路:kv_bytes_per_token 与 kv_read_bytes 由 和窗口模式推出,决定解码显存与带宽。

在「懂原理 / 能复现 / 懂工程」三条主线中,本篇属于复现与工程的交界:不理解配置,就无法解释 speedrun 为什么用 d24、为什么参数量是 13.8 亿、为什么优化器有 6 个 AdamW 组和 4 个 Muon 形状组。没有 meta device 的两阶段初始化,构造大模型会先分配一份未初始化显存再覆盖,峰值显存与初始化时间都不可控。

原理与推导

1. 配置字段与默认值

GPTConfig 是一个普通 @dataclass,字段与默认值如下。默认值对应 d12 参考模型,而不是 speedrun 的 d24。

字段默认值含义与约束
sequence_len2048训练与推理的最大上下文长度;RoPE 缓存按它的 10 倍预计算
vocab_size32768分词器词表大小;构造时填充到 64 的倍数
n_layer12Transformer 层数
n_head6查询头数 ,必须整除 n_embd
n_kv_head6KV 头数 ,必须满足 且 能被 整除
n_embd768残差流宽度
window_pattern"SSSL"按层平铺的窗口模式,字符只允许 S 与 L;最后一层强制为 L

配置中没有 dropout、bias、tie-weights、激活函数类型等开关。这些选择在 GPT 内硬编码:Linear 一律 bias=False,wte 与 lm_head 不共享,MLP 固定 ReLU²,归一化固定为无参数的 RMSNorm。这样做的代价是灵活性,收益是配置面小、检查点兼容性好、读者只需看一处。

2. 由 depth 推导宽度与头数

scripts/base_train.py 的 build_model_meta(depth) 是唯一的推导入口:

base_dim = depth * args.aspect_ratio
model_dim = ((base_dim + args.head_dim - 1) // args.head_dim) * args.head_dim
num_heads = model_dim // args.head_dim
config = GPTConfig(
    sequence_len=args.max_seq_len, vocab_size=vocab_size,
    n_layer=depth, n_head=num_heads, n_kv_head=num_heads, n_embd=model_dim,
    window_pattern=args.window_pattern,
)
with torch.device("meta"):
    model_meta = GPT(config)
return model_meta

默认 --aspect-ratio=64、--head-dim=128,于是

base_dim = 64L 是「宽度约等于 64 倍深度」的缩放约定;向上取整到 128 的倍数保证 且 能被 整除。 表示默认配置不使用 GQA 的 KV 头缩减;CausalSelfAttention 仍按通用 GQA 实现,改 n_kv_head 即可获得推理收益(见 分组查询注意力GQA)。

depth备注
851244小规模调试
1276866默认配置与超参基准
2012801010旧版 speedrun 规模
2415361212当前 speedrun 规模
2616641313README 所述 GPT-2 能力附近

d24 的具体数字:n_embd=1536、n_head=12、n_kv_head=12、单头维度 。这三项会在后面的参数统计、优化器分组与 KV Cache 计算中反复出现。

3. meta device 约束与两阶段初始化

GPT.__init__ 的文档字符串明确警告:这个函数运行在 meta device 上下文中,里面的一切计算只产生形状与 dtype,不产生真实数据。因此

self.resid_lambdas = nn.Parameter(torch.ones(config.n_layer))   # 假初始化
self.x0_lambdas = nn.Parameter(torch.zeros(config.n_layer))     # 假初始化
self.backout_lambda = nn.Parameter(0.2 * torch.ones(1))         # 假初始化

在 __init__ 中写入的 1.0、0.0、0.2 都不会进入真实存储;真正的数值由 init_weights 重新赋值。旋转位置编码的 cos/sin 也在 __init__ 中预计算一次,但那时 wte 还是 meta 张量,得到的只是 meta 缓冲;init_weights 会在真实设备上重算并覆盖。

训练脚本的调用顺序是:

model = build_model_meta(args.depth)  # 1) 只建形状
model.to_empty(device=device)         # 2) 分配未初始化存储
model.init_weights()                  # 3) 写入全部数值

to_empty 是 meta 张量落地的正确方式;直接 model.to(device) 会因「不能从 meta 张量复制数据」而报错。init_weights 用 @torch.no_grad() 修饰,内部对每个参数做原地初始化,并在最后把 wte 与 value_embeds 转成 COMPUTE_DTYPE(fp16 路径例外,保持 fp32 以便 GradScaler 反缩放)。

4. 词表填充与模块字典

GPT.__init__ 先把词表填充到 64 的倍数:

默认 已经是 64 的倍数,因此不触发填充;若分词器词表是 32769,则 。填充只是矩阵乘与分布式集合通信的形状优化,输出会在 forward 中切回 。lm_head 的输出形状是 ,logits[..., :V] 之后才进入损失或采样。

模块结构为:

self.transformer = nn.ModuleDict({
    "wte": nn.Embedding(padded_vocab_size, config.n_embd),
    "h": nn.ModuleList([Block(config, layer_idx) for layer_idx in range(config.n_layer)]),
})
self.lm_head = Linear(config.n_embd, padded_vocab_size, bias=False)
self.value_embeds = nn.ModuleDict({
    str(i): nn.Embedding(padded_vocab_size, kv_dim)
    for i in range(config.n_layer) if has_ve(i, config.n_layer)
})

ModuleDict 让 state_dict 的键稳定为 transformer.wte.weight、transformer.h.0.attn.c_q.weight 等;ModuleList 让层可以按索引遍历;value_embeds 的键是字符串,因为只有部分层有值嵌入。lm_head 放在顶层而不是 transformer 内,是为了让参数分组时能单独取到它。

参数与标量分为以下几类:

  • 矩阵参数:每个 Block 内的 attn.c_q/c_k/c_v/c_proj 与 mlp.c_fc/c_proj,以及值嵌入层的 ve_gate。
  • 嵌入参数:wte、value_embeds、lm_head。
  • 标量参数:resid_lambdas( 个)、x0_lambdas( 个)、smear_gate.weight( 个)、smear_lambda(1 个)、backout_lambda(1 个)。

5. init_weights 的初始化规则

init_weights 的规则集中在一个函数里,便于核对:

参数初始化目的
wte.weight正态 嵌入初始尺度略低于 1
lm_head.weight正态 初始 logits 接近 0,softmax 接近均匀
attn.c_q/c_k/c_v均匀 与正态同标准差,避免离群值
attn.c_proj全零每个 Block 初始为恒等映射
mlp.c_fc均匀 降低 MLP 初始增益
mlp.c_proj全零残差分支初始为零
resid_lambdas[i]浅层残差增益大,深层小
x0_lambdas[i]浅层多混入初始嵌入,深层少
smear_gate.weight均匀 门初始接近 0.5,但整体乘 smear_lambda=0
smear_lambda0初始禁用 smear
backout_lambda0.2初始减去 20% 中层残差
value_embeds均匀 与 c_v 同尺度
ve_gate.weight均匀 门初始略高于中性

注意 wte 的文档字符串写的是 std=1.0,而代码实际使用 std=0.8;以代码为准。c_proj 与 mlp.c_proj 零初始化使每个 Block 在初始时是恒等映射,梯度可以穿过残差流回传;这是深层 Transformer 能稳定起步的关键,不是可有可无的细节。

6. num_scaling_params 的分组

num_scaling_params 返回一个字典,逐组统计参数量,并在末尾断言各组之和等于 self.parameters() 的总数:

wte = sum(p.numel() for p in self.transformer.wte.parameters())
value_embeds = sum(p.numel() for p in self.value_embeds.parameters())
lm_head = sum(p.numel() for p in self.lm_head.parameters())
transformer_matrices = sum(p.numel() for p in self.transformer.h.parameters())
scalars = (self.resid_lambdas.numel() + self.x0_lambdas.numel()
           + self.smear_gate.weight.numel() + self.smear_lambda.numel()
           + self.backout_lambda.numel())
组d12d24
wte25,165,82450,331,648
value_embeds150,994,944603,979,776
lm_head25,165,82450,331,648
transformer_matrices84,935,088679,478,976
scalars5074
total286,261,7301,384,122,122
transformer_matrices + lm_head110,100,912729,810,624

最后一行是 base_train.py 的 get_scaling_params 实际使用的口径:只把 Transformer 矩阵与 lm_head 计入缩放律,嵌入查表不计入 FLOPs。这与 Kaplan 等人排除嵌入参数、Chinchilla 包含全部参数的做法不同;nanochat 在 dev/LOG.md 中比较过三种口径,认为「矩阵 + lm_head」的缩放最稳定。--target-param-data-ratio 乘的就是这个数,而不是 total。

7. setup_optimizer 的参数分组与学习率

setup_optimizer 先把参数来源拆开,再用断言保证没有遗漏:

matrix_params = list(self.transformer.h.parameters())
value_embeds_params = list(self.value_embeds.parameters())
embedding_params = list(self.transformer.wte.parameters())
lm_head_params = list(self.lm_head.parameters())
resid_params = [self.resid_lambdas]
x0_params = [self.x0_lambdas]
smear_params = [self.smear_gate.weight, self.smear_lambda, self.backout_lambda]

随后构造 6 个 AdamW 组与若干 Muon 组。AdamW 组的学习率都乘一个宽度修正因子

以便把在 上调好的学习率迁移到其他宽度;d12 的 ,d24 的 。

#组参数学习率(签名默认)学习率(base_train 默认)betasweight decay
1lm_headlm_head.weightunembedding_lr·s_C = 0.0040.008·s_C(0.8, 0.96)0.01
2wtewte.weightembedding_lr·s_C = 0.20.3·s_C(0.8, 0.995)0.001
3value_embeds全部值嵌入0.5·embedding_lr·s_C = 0.10.15·s_C(0.8, 0.995)0.01
4resid_lambdas 个标量0.01·scalar_lr = 0.0050.005(0.8, 0.95)0.05
5x0_lambdas 个标量scalar_lr = 0.50.5(0.96, 0.95)0.0
6smear门、、固定 0.20.2(0.8, 0.95)0.0

所有 AdamW 组的 eps=1e-10。第 6 组的学习率是硬编码的 0.2,不乘 ,也不受 scalar_lr 控制;这是读代码时容易忽略的一处不对称。resid_lambdas 是乘性缩放,学习率被压到 scalar_lr 的 1%;x0_lambdas 是加性混合,使用完整的 0.5。

Muon 组按参数形状分桶:

for shape in sorted({p.shape for p in matrix_params}):
    group_params = [p for p in matrix_params if p.shape == shape]
    param_groups.append(dict(kind='muon', params=group_params, lr=matrix_lr,
                             momentum=0.95, ns_steps=5, beta2=0.9,
                             weight_decay=weight_decay))

d12 的形状桶是 (6,12)(ve_gate,6 个)、(768,768)(Q/K/V/O,48 个)、(3072,768)(c_fc,12 个)、(768,3072)(mlp.c_proj,12 个)。d24 对应 (12,12) 12 个、(1536,1536) 96 个、(6144,1536) 24 个、(1536,6144) 24 个。ve_gate 虽然只有 12×12,仍被归入 Muon 组,而不是 AdamW;这是分组逻辑的副产物,改参数结构时需要重新检查。

d24 在 s_C=0.707107、忽略 batch_lr_scale 与权重衰减调度时,各组的实际学习率为:lm_head 0.005657、wte 0.212132、值嵌入 0.106066、resid 0.005、x0 0.5、smear 0.2、Muon 0.02。训练脚本会把每组的 initial_lr 存下来,再按 warmup/warmdown 的倍数缩放;因此上表是基准值,不是训练全程的常数。

在 nanochat 中的落地

位置符号作用
nanochat/gpt.pyGPTConfig形状、词表、窗口模式的唯一来源
nanochat/gpt.pyGPT.__init__在 meta device 上建形状、模块字典与标量
nanochat/gpt.pyGPT.init_weights真实初始化;标量、旋转缓存、嵌入 dtype 都在这里落地
nanochat/gpt.pyGPT.num_scaling_params分组统计参数量,供缩放律与日志使用
nanochat/gpt.pyGPT.setup_optimizer6 个 AdamW 组 + 按形状的 Muon 组
scripts/base_train.pybuild_model_meta由 depth、aspect ratio、head dim 生成配置并建 meta 模型
scripts/base_train.pymodel.to_empty + init_weights两阶段落地
nanochat/checkpoint_manager.py配置补丁旧检查点缺 window_pattern 时补 "L",缺 resid_lambdas 时补 1.0

最后一条是版本兼容性的直接体现:早期模型没有滑动窗口与残差标量,加载时必须补默认值,否则 load_state_dict(strict=True) 会失败。

关键直觉

配置是「形状骨架」,不是「权重容器」

GPTConfig 的每个字段只决定张量形状、模块数量与窗口模式;所有数值都在 init_weights 中才出现。把 __init__ 当成普通构造函数、在其中读取或写入真实数值,是 meta device 路径下最常见的错误。深度 --depth 是唯一的规模旋钮:它先决定 与 ,再由 决定参数量、学习率修正、训练 token 数与显存。这个关系是定义中「配置派生一切」的严格版本。

例子与代码

下面的脚本只依赖 torch,在与 GPT.__init__ 相同的 meta device 上构造参数形状,打印 d12/d24 的配置、AdamW 组大小、Muon 形状桶与宽度修正后的学习率。它不训练模型,也不读取真实数据。

import math
import torch

def config(depth):
    C = math.ceil(depth * 64 / 128) * 128
    return dict(sequence_len=2048, vocab_size=32768, n_layer=depth,
                n_head=C // 128, n_kv_head=C // 128, n_embd=C,
                window_pattern="SSSL")

def has_ve(i, L):
    return i % 2 == (L - 1) % 2

def groups(c):
    # 在 meta device 上构造与 GPT.__init__ 相同的参数形状
    V, C, L = c["vocab_size"], c["n_embd"], c["n_layer"]
    kv = c["n_kv_head"] * (C // c["n_head"])
    with torch.device("meta"):
        g = {"wte": [torch.empty(V, C)], "lm_head": [torch.empty(V, C)],
             "value_embeds": [torch.empty(V, kv) for i in range(L) if has_ve(i, L)],
             "resid": [torch.empty(L)], "x0": [torch.empty(L)],
             "smear": [torch.empty(1, 24), torch.empty(1), torch.empty(1)],
             "matrix": []}
        for i in range(L):
            g["matrix"] += [torch.empty(C, C) for _ in range(4)]
            g["matrix"] += [torch.empty(4 * C, C), torch.empty(C, 4 * C)]
            if has_ve(i, L):
                g["matrix"].append(torch.empty(c["n_kv_head"], 12))
    return g

for d in (12, 24):
    c = config(d)
    g = groups(c)
    print(f"d{d}: {c}")
    print("  AdamW groups: " + ", ".join(
        f"{k}={sum(t.numel() for t in v):,}" for k, v in g.items() if k != "matrix"))
    n_matrix = sum(t.numel() for t in g["matrix"])
    n_lm = sum(t.numel() for t in g["lm_head"])
    print(f"  matrix={n_matrix:,}, total="
          f"{sum(t.numel() for v in g.values() for t in v):,}, "
          f"scaling={n_matrix + n_lm:,}")
    scale = (c["n_embd"] / 768) ** -0.5
    print(f"  scale={scale:.6f} lr lm_head={0.008*scale:.6f} "
          f"wte={0.3*scale:.6f} ve={0.15*scale:.6f} "
          f"resid={0.005:.6f} x0={0.5:.6f} smear={0.2:.6f}")
    shapes = {}
    for t in g["matrix"]:
        shapes[tuple(t.shape)] = shapes.get(tuple(t.shape), 0) + 1
    print("  Muon shapes: " + ", ".join(f"{s}x{n}" for s, n in sorted(shapes.items())))
    print()

预期输出(数值已与 GPT(GPTConfig()) 的 num_scaling_params() 核对):

d12: {'sequence_len': 2048, 'vocab_size': 32768, 'n_layer': 12, 'n_head': 6, 'n_kv_head': 6, 'n_embd': 768, 'window_pattern': 'SSSL'}
  AdamW groups: wte=25,165,824, lm_head=25,165,824, value_embeds=150,994,944, resid=12, x0=12, smear=26
  matrix=84,935,088, total=286,261,730, scaling=110,100,912
  scale=1.000000 lr lm_head=0.008000 wte=0.300000 ve=0.150000 resid=0.005000 x0=0.500000 smear=0.200000
  Muon shapes: (6, 12)x6, (768, 768)x48, (768, 3072)x12, (3072, 768)x12

d24: {'sequence_len': 2048, 'vocab_size': 32768, 'n_layer': 24, 'n_head': 12, 'n_kv_head': 12, 'n_embd': 1536, 'window_pattern': 'SSSL'}
  AdamW groups: wte=50,331,648, lm_head=50,331,648, value_embeds=603,979,776, resid=24, x0=24, smear=26
  matrix=679,478,976, total=1,384,122,122, scaling=729,810,624
  scale=0.707107 lr lm_head=0.005657 wte=0.212132 ve=0.106066 resid=0.005000 x0=0.500000 smear=0.200000
  Muon shapes: (12, 12)x12, (1536, 1536)x96, (1536, 6144)x24, (6144, 1536)x24

脚本里的 matrix 已经包含每个值嵌入层的 ve_gate(形状 (H_kv,12)),所以 d12 的 transformer_matrices 是 84,935,088,而不是只算 12 个 Block 主矩阵的 84,934,656。smear=26 由 smear_gate.weight 的 24 个元素、smear_lambda 的 1 个与 backout_lambda 的 1 个组成。若把 weight_decay 与 batch_lr_scale 也算进去,表中学习率还要乘训练脚本的调度系数;脚本只打印基准值。

build_model_meta 在训练脚本中的完整用法如下,它解释了为什么配置必须先于模型、优化器与数据加载器:

model = build_model_meta(args.depth)      # 形状
model_config = model.config
model_config_kwargs = asdict(model_config)
print0(f"Model config:\n{json.dumps(model_config_kwargs, indent=2)}")
model.to_empty(device=device)             # 存储
model.init_weights()                      # 数值

param_counts = model.num_scaling_params()
num_scaling_params = param_counts['transformer_matrices'] + param_counts['lm_head']
target_tokens = int(args.target_param_data_ratio * num_scaling_params)
optimizer = model.setup_optimizer(
    unembedding_lr=args.unembedding_lr * batch_lr_scale,
    embedding_lr=args.embedding_lr * batch_lr_scale,
    scalar_lr=args.scalar_lr * batch_lr_scale,
    matrix_lr=args.matrix_lr * batch_lr_scale,
    weight_decay=weight_decay_scaled,
)

易错点

六个可检验的错误

1. 在 GPT.__init__ 里给 resid_lambdas、x0_lambdas、backout_lambda 赋真实数值。它们位于 meta 上下文,赋值不会进入真实存储;必须在 init_weights 中写。

2. 把 vocab_size 当作 lm_head 的输出宽度。lm_head 输出的是 ,forward 在 softcap 与损失之前才切到 ;忘记切片会让交叉熵的目标索引与 logits 宽度不一致。

3. 只按 n_embd 统计参数量,漏掉 value_embeds 与 ve_gate。d12 的值嵌入有 1.51 亿参数,超过 transformer_matrices 的 0.85 亿。

4. 新增一个参数却忘记加入 setup_optimizer 的某个组。函数末尾的断言会立即报错,这是有意的保护;不要为了通过断言把它塞进无关的组。

5. 把 dmodel_lr_scale 与 batch_lr_scale 重复相乘。前者在 setup_optimizer 内按宽度修正 AdamW 组,后者在 base_train.py 中按批大小修正传给 setup_optimizer 的基准学习率;两者作用对象不同。

6. 用 model.to(device) 把 meta 模型搬到真实设备。正确做法是 to_empty 后 init_weights,否则会触发 meta 张量复制错误或得到未初始化数据。

关联笔记

  • 前置:自注意力机制、前馈层与激活函数。配置中的 n_head、n_kv_head、n_embd 分别对应这两篇里的头拆分与 4 倍扩张。
  • 后续:从第一性看nanochat的gpt.py。配置只给形状,前向顺序与每步张量形状在那篇展开。
  • 后续:训练脚本与speedrun。build_model_meta 只是训练脚本的第一步,后面还有批大小、学习率与 token 数的推导。
  • 对照:缩放定律与模型深度。num_scaling_params 的口径直接决定缩放律与 --target-param-data-ratio。
  • 跨库:Transformer架构详解。通用 Transformer 的组件定义见该篇,本篇只讲 nanochat 的配置与参数组织。

达标检测

  • [ ] 不查代码,写出 GPTConfig 的 7 个字段与默认值,并说明默认值是 d12 而不是 d24。
  • [ ] 由 depth=24、aspect_ratio=64、head_dim=128 推出 n_embd=1536、n_head=12、n_kv_head=12,并解释为什么要向上取整到 128。
  • [ ] 解释 meta device 下 torch.ones 与 init_weights 的分工,说明 to_empty 为什么必要。
  • [ ] 计算 d24 的 wte、value_embeds、lm_head、transformer_matrices 与 total,并与 1,384,122,122 对照。
  • [ ] 列出 6 个 AdamW 组的学习率公式,指出哪一个组不乘 dmodel_lr_scale。
  • [ ] 说明 Muon 为什么按形状分组,以及 d24 的四个形状桶各有多少个参数张量。
  • [ ] 运行本篇脚本,核对 d12/d24 的 scaling 数值与 Muon shapes 输出。
  • [ ] 找出一个「配置正确但检查点加载失败」的场景,并说明 checkpoint_manager.py 的补丁如何避免它。

参考来源

  • Karpathy, nanochat(commit 92d63d4),nanochat/gpt.py 的 GPTConfig、GPT.__init__、init_weights、num_scaling_params、setup_optimizer —— 对应本篇全部字段、初始化与分组。
  • Karpathy, nanochat,scripts/base_train.py 的 build_model_meta、get_scaling_params、setup_optimizer 调用 —— 对应 depth 推导与训练期学习率。
  • Karpathy, modded-nanogpt —— 每层残差标量与零初始化投影的来源;nanochat 的 resid_lambdas、x0_lambdas 沿用其思路。
  • Hoffmann et al., Training Compute-Optimal Large Language Models, arXiv:2203.15556 —— 参数统计口径与 Chinchilla 的「包含全部参数」约定。
  • Kaplan et al., Scaling Laws for Neural Language Models, arXiv:2001.08361 —— 排除嵌入参数的另一种口径,对应本篇 transformer_matrices + lm_head 的讨论。