---
tags: [nanochat, transformer, config]
阶段: 04-Transformer架构
难度: ★★★
created: 2026-10-22
related: "[[从第一性看nanochat的gpt.py]], [[nanochat架构特化技巧]], [[缩放定律与模型深度]]"
---

# GPT模型类与config

## 定义

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

符号约定如下。层数 $L$、模型宽度 $C$（即 `n_embd`）、查询头数 $H$、KV 头数 $H_{kv}$、单头维度 $D=C/H$、序列长度 $T$、词表大小 $V$、填充后的词表大小 $V'$。

| 符号 | 含义 | 在 `GPTConfig` 中的字段 |
|---|---|---|
| $L$ | Transformer 层数 | `n_layer` |
| $C$ | 残差流宽度 | `n_embd` |
| $H$ | 查询头数 | `n_head` |
| $H_{kv}$ | 键/值头数 | `n_kv_head` |
| $D$ | 单头维度，$D=C/H$ | 无独立字段，由前两者推出 |
| $T$ | 最大序列长度 | `sequence_len` |
| $V$ | 词表大小 | `vocab_size` |
| $V'$ | 填充到 64 的倍数的词表大小 | 无字段，由 $V$ 推出 |
| — | 滑动窗口模式串 | `window_pattern` |

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

## 为什么重要

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

1. 形状链路：$C$ 决定注意力投影与 MLP 的矩阵形状，$H$ 决定每头维度，$V'$ 决定 `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` 由 $L,H_{kv},D$ 和窗口模式推出，决定解码显存与带宽。

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

## 原理与推导

### 1. 配置字段与默认值

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

| 字段 | 默认值 | 含义与约束 |
|---|---:|---|
| `sequence_len` | 2048 | 训练与推理的最大上下文长度；RoPE 缓存按它的 10 倍预计算 |
| `vocab_size` | 32768 | 分词器词表大小；构造时填充到 64 的倍数 |
| `n_layer` | 12 | Transformer 层数 $L$ |
| `n_head` | 6 | 查询头数 $H$，必须整除 `n_embd` |
| `n_kv_head` | 6 | KV 头数 $H_{kv}$，必须满足 $H_{kv}\le H$ 且 $H$ 能被 $H_{kv}$ 整除 |
| `n_embd` | 768 | 残差流宽度 $C$ |
| `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)` 是唯一的推导入口：

```python
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`，于是

$$
C=\left\lceil \frac{64L}{128}\right\rceil\cdot 128,\qquad
H=\frac{C}{128},\qquad H_{kv}=H.
$$

`base_dim = 64L` 是「宽度约等于 64 倍深度」的缩放约定；向上取整到 128 的倍数保证 $D=128$ 且 $C$ 能被 $H$ 整除。$H_{kv}=H$ 表示默认配置不使用 GQA 的 KV 头缩减；`CausalSelfAttention` 仍按通用 GQA 实现，改 `n_kv_head` 即可获得推理收益（见 [[分组查询注意力GQA]]）。

| depth | $C$ | $H$ | $H_{kv}$ | 备注 |
|---:|---:|---:|---:|---|
| 8 | 512 | 4 | 4 | 小规模调试 |
| 12 | 768 | 6 | 6 | 默认配置与超参基准 |
| 20 | 1280 | 10 | 10 | 旧版 speedrun 规模 |
| 24 | 1536 | 12 | 12 | 当前 speedrun 规模 |
| 26 | 1664 | 13 | 13 | README 所述 GPT-2 能力附近 |

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

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

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

```python
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` 会在真实设备上重算并覆盖。

训练脚本的调用顺序是：

```python
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 的倍数：

$$
V'=\left\lceil \frac{V}{64}\right\rceil\cdot 64.
$$

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

模块结构为：

```python
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`（$L$ 个）、`x0_lambdas`（$L$ 个）、`smear_gate.weight`（$24$ 个）、`smear_lambda`（1 个）、`backout_lambda`（1 个）。

### 5. init_weights 的初始化规则

`init_weights` 的规则集中在一个函数里，便于核对：

| 参数 | 初始化 | 目的 |
|---|---|---|
| `wte.weight` | 正态 $\mathcal{N}(0,0.8^2)$ | 嵌入初始尺度略低于 1 |
| `lm_head.weight` | 正态 $\mathcal{N}(0,0.001^2)$ | 初始 logits 接近 0，softmax 接近均匀 |
| `attn.c_q/c_k/c_v` | 均匀 $[-\sqrt{3/C},\sqrt{3/C}]$ | 与正态同标准差，避免离群值 |
| `attn.c_proj` | 全零 | 每个 Block 初始为恒等映射 |
| `mlp.c_fc` | 均匀 $[-0.4\sqrt{3/C},0.4\sqrt{3/C}]$ | 降低 MLP 初始增益 |
| `mlp.c_proj` | 全零 | 残差分支初始为零 |
| `resid_lambdas[i]` | $1.15-0.10\,i/(L-1)$ | 浅层残差增益大，深层小 |
| `x0_lambdas[i]` | $0.20-0.15\,i/(L-1)$ | 浅层多混入初始嵌入，深层少 |
| `smear_gate.weight` | 均匀 $[0,0.02]$ | 门初始接近 0.5，但整体乘 `smear_lambda=0` |
| `smear_lambda` | 0 | 初始禁用 smear |
| `backout_lambda` | 0.2 | 初始减去 20% 中层残差 |
| `value_embeds` | 均匀 $[-\sqrt{3/C},\sqrt{3/C}]$ | 与 `c_v` 同尺度 |
| `ve_gate.weight` | 均匀 $[0,0.02]$ | 门初始略高于中性 |

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

### 6. num_scaling_params 的分组

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

```python
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())
```

| 组 | d12 | d24 |
|---|---:|---:|
| `wte` | 25,165,824 | 50,331,648 |
| `value_embeds` | 150,994,944 | 603,979,776 |
| `lm_head` | 25,165,824 | 50,331,648 |
| `transformer_matrices` | 84,935,088 | 679,478,976 |
| `scalars` | 50 | 74 |
| `total` | 286,261,730 | 1,384,122,122 |
| `transformer_matrices + lm_head` | 110,100,912 | 729,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` 先把参数来源拆开，再用断言保证没有遗漏：

```python
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 组的学习率都乘一个宽度修正因子

$$
s_{C}=\left(\frac{C}{768}\right)^{-1/2},
$$

以便把在 $C=768$ 上调好的学习率迁移到其他宽度；d12 的 $s_C=1$，d24 的 $s_C=0.707107$。

| # | 组 | 参数 | 学习率（签名默认） | 学习率（`base_train` 默认） | betas | weight decay |
|---:|---|---|---|---|---|---|
| 1 | `lm_head` | `lm_head.weight` | `unembedding_lr·s_C` = 0.004 | 0.008·s_C | (0.8, 0.96) | 0.01 |
| 2 | `wte` | `wte.weight` | `embedding_lr·s_C` = 0.2 | 0.3·s_C | (0.8, 0.995) | 0.001 |
| 3 | `value_embeds` | 全部值嵌入 | `0.5·embedding_lr·s_C` = 0.1 | 0.15·s_C | (0.8, 0.995) | 0.01 |
| 4 | `resid_lambdas` | $L$ 个标量 | `0.01·scalar_lr` = 0.005 | 0.005 | (0.8, 0.95) | 0.05 |
| 5 | `x0_lambdas` | $L$ 个标量 | `scalar_lr` = 0.5 | 0.5 | (0.96, 0.95) | 0.0 |
| 6 | `smear` | 门、$\lambda_s$、$\lambda_b$ | 固定 0.2 | 0.2 | (0.8, 0.95) | 0.0 |

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

Muon 组按参数形状分桶：

```python
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.py` | `GPTConfig` | 形状、词表、窗口模式的唯一来源 |
| `nanochat/gpt.py` | `GPT.__init__` | 在 meta device 上建形状、模块字典与标量 |
| `nanochat/gpt.py` | `GPT.init_weights` | 真实初始化；标量、旋转缓存、嵌入 dtype 都在这里落地 |
| `nanochat/gpt.py` | `GPT.num_scaling_params` | 分组统计参数量，供缩放律与日志使用 |
| `nanochat/gpt.py` | `GPT.setup_optimizer` | 6 个 AdamW 组 + 按形状的 Muon 组 |
| `scripts/base_train.py` | `build_model_meta` | 由 depth、aspect ratio、head dim 生成配置并建 meta 模型 |
| `scripts/base_train.py` | `model.to_empty` + `init_weights` | 两阶段落地 |
| `nanochat/checkpoint_manager.py` | 配置补丁 | 旧检查点缺 `window_pattern` 时补 `"L"`，缺 `resid_lambdas` 时补 1.0 |

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

## 关键直觉

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

## 例子与代码

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

```python
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()` 核对）：

```text
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` 在训练脚本中的完整用法如下，它解释了为什么配置必须先于模型、优化器与数据加载器：

```python
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,
)
```

## 易错点

> [!warning] 六个可检验的错误
> 1. 在 `GPT.__init__` 里给 `resid_lambdas`、`x0_lambdas`、`backout_lambda` 赋真实数值。它们位于 meta 上下文，赋值不会进入真实存储；必须在 `init_weights` 中写。
> 2. 把 `vocab_size` 当作 `lm_head` 的输出宽度。`lm_head` 输出的是 $V'$，`forward` 在 softcap 与损失之前才切到 $V$；忘记切片会让交叉熵的目标索引与 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` 的讨论。
