---
tags: [nanochat, repro, scaling]
阶段: 10-复现与实验
难度: ★★★
created: 2026-10-22
related: "[[缩放定律与模型深度]], [[跑通speedrun脚本]], [[常见问题踩坑]], [[PyTorch实战入门]]"
---

# 用 --depth 调参

## 定义

**深度调参**（depth tuning）指只改动 `--depth` 一个整数，由训练脚本自动推出宽度、头数、批大小、学习率、权重衰减与训练 token 数，从而在不同的算力预算上得到计算最优模型的操作方式。

本篇出现的符号与术语：

| 符号或术语 | 含义 |
|---|---|
| $L$ | 深度，`--depth`，Transformer 的层数 |
| $d$ | 宽度，`model_dim`、`n_embd`，残差流的维度 |
| $q$ | 每头维度，`--head-dim`，默认 128；$a$ 为纵横比 `--aspect-ratio`，默认 64 |
| $h$ | 查询头数，`n_head`，等于 $d/q$；KV 头数 $h_{kv}$ 与之相等，即不使用 GQA 压缩 |
| $N$ | 缩放参数，`transformer_matrices + lm_head` |
| $D$ | 训练 token 数 |
| ratio | `--target-param-data-ratio`，$D=\text{ratio}\times N$ |
| $B_{\text{total}}$ | 全局批大小，单位 token |
| $B_{\text{dev}}$ | 单卡批大小，`--device-batch-size` |
| $A$ | 梯度累积步数 |
| $V$ | 词表大小，32768 |
| $T$ | 上下文长度，默认 2048 |
| $W$ | 世界大小，即进程数 |
| $C_{\text{token}}$ | 每 token 的前向加反向 FLOPs |

**显存分解**是把单卡峰值显存拆成静态项、激活项与 logits 项的方法；**OOM 调整顺序**是在显存不足时按代价从小到大依次尝试的参数修改序列。

## 为什么重要

它把「换一个模型规模」从一组需要重新扫描的超参数变成一个整数。若没有这条推导链，想训一个比 speedrun 小一半的模型，就必须重新确定宽度、头数、批大小、学习率与权重衰减五组量；nanochat 用 d12 作为参考点把它们写成深度的函数，使换规模只改一个参数。

它决定了实验成本的可预测性。算力随深度约六次方增长：从 d12 到 d24，缩放参数从 1.10 亿增到 7.30 亿（6.63 倍），训练 token 同比例增长，总 FLOPs 约 44 倍。因此「d12 上有效的改动」与「d24 上有效的改动」不是同一件事，而调参的第一步就是选对验证尺度。

它是排障的前提。显存不足时，可改的参数有五个方向（单卡批、上下文、精度、深度、卡数），每个方向的代价差别很大：降单卡批只改变累积步数，降深度改变模型本身，换精度改变数值行为。不理解各项显存量级，就会在错误的方向上反复试。

在全书中的位置：前置为 [[缩放定律与模型深度]]（推导与公式）与 [[跑通speedrun脚本]]（命令与产物）；后续为 [[常见问题踩坑]]（显存与精度的故障）与 [[实验记录模板]]（把调参结果记成可比数据）。懂原理对应「由深度推出全部超参数」，能复现对应「给出两套可执行配置」，懂工程对应「在给定显卡上按顺序降级而不改变实验含义」。

## 原理与推导

### 1 从深度到形状：三步取整

`scripts/base_train.py` 的 `build_model_meta` 是唯一的形状来源：

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

三步各有约束。

第一步，$d_0=L\cdot a$。默认 $a=64$，因此 d24 的初值是 1536，d12 是 768。

第二步，向上取整到 $q$ 的倍数。取整保证 $d$ 能被 $q$ 整除，从而 $h=d/q$ 是整数且每头维度恰好等于 `--head-dim`。源码注释给出两个理由：FA3 要求头维度能被 8 整除，且这样能保证头维度精确等于设定值。默认 $q=128$ 时，因为 128 整除 64，$d_0$ 已经是 128 的倍数，取整不改变任何值；只有把 `--head-dim` 改成 64 或 96 时取整才会生效。

第三步，$h=d/q$，且 $h_{kv}=h$。后者意味着没有 GQA 压缩，KV 头数等于查询头数；`GPTConfig` 支持 $h_{kv}<h$，但 `build_model_meta` 不暴露这个自由度。若要在自有分支里启用 GQA，改动点在这里而不是在 `gpt.py`。

对奇数深度，宽度依然整齐：d13 给出 $13\times64=832$，832 是 128 的倍数吗，$832/128=6.5$，不是；向上取整到 896，头数 7。因此 d13 的宽度等于 d14 的宽度（896），两者参数相同，只有层数差一。这是「按深度扫描」时会出现平台的原因。

| 深度 | $d_0=64L$ | 取整后 $d$ | $h=d/128$ | 缩放参数 $N$ |
|---|---|---|---|---|
| d6（`--head-dim=64`） | 384 | 384 | 6 | 23,199,960 |
| d8 | 512 | 512 | 4 | 41,943,232 |
| d12 | 768 | 768 | 6 | 110,100,912 |
| d16 | 1024 | 1024 | 8 | 234,881,792 |
| d20 | 1280 | 1280 | 10 | 435,160,240 |
| d24 | 1536 | 1536 | 12 | 729,810,624 |
| d26 | 1664 | 1664 | 13 | 918,423,532 |
| d32 | 2048 | 2048 | 16 | 1,677,724,672 |

d6 一行是 `runs/runcpu.sh` 的配置，它把 `--head-dim` 降到 64，因此头数是 6 而不是 3。

### 2 参数与 FLOPs 随深度的标度

缩放参数由三部分组成：每层 $12d^2$ 的矩阵、value embedding 层额外的 `ve_gate`、以及 $V\cdot d$ 的 `lm_head`。

$$
N=12Ld^2+12h\cdot n_{\text{ve}}+Vd .
$$

其中 $n_{\text{ve}}$ 是带 value embedding 的层数，等于 $\lceil L/2\rceil$；每个这样的层有一个 $12\times h$ 的 `ve_gate`。d24 上这一项是 $12\times12\times12=1728$，相对 7.3 亿可以忽略，但用它核对 `num_scaling_params()` 的输出时差额恰好来自这里。

取 $d=64L$ 近似，$N\approx12L(64L)^2+V\cdot64L$，主导项按 $L^3$ 增长。

$C_{\text{token}}$ 在此之上加注意力项：

$$
C_{\text{token}}=6N+12\sum_{\ell=1}^{L}h\cdot q\cdot\min(w_\ell,T),
$$

$w_\ell$ 是第 $\ell$ 层的窗口。窗口模式 `SSSL` 按 4 层循环，最后一行强制为全上下文；$T=2048$ 时短窗为 512。

$$
C_{\text{token}}=6N+12hq\left(n_S\cdot512+n_L\cdot2048\right),
$$

$n_S$ 与 $n_L$ 是短窗与全上下文层数。d24 为 18 与 6，d12 为 9 与 3。代入得 $C_{\text{token}}(\text{d12})=7.597\times10^{8}$、$C_{\text{token}}(\text{d24})=4.775\times10^{9}$。

总训练 FLOPs 为 $C_{\text{token}}\cdot D$。$D=\text{ratio}\cdot N$，故 $C\propto N^2\propto L^6$：在 d24 附近深度加 2，参数乘 1.26、训练 FLOPs 乘 1.58。这条关系是「深度是算力预算的对数刻度」的来源。

### 3 训练 horizon 的三级优先级

`num_iterations` 有三个来源，代码按固定顺序判断，先命中者生效：

```python
assert args.num_iterations > 0 or args.target_param_data_ratio > 0 or args.target_flops > 0
if args.num_iterations > 0:
    num_iterations = args.num_iterations
elif args.target_flops > 0:
    num_iterations = round(args.target_flops / (num_flops_per_token * total_batch_size))
elif args.target_param_data_ratio > 0:
    num_iterations = target_tokens // total_batch_size
```

三者的适用场景不同。

| 参数 | 语义 | 典型用法 | 副作用 |
|---|---|---|---|
| `--num-iterations` | 直接给定步数 | 冒烟测试、固定预算复现 | 忽略 ratio 与 flops，LR 调度长度随之改变 |
| `--target-flops` | 给定总算力 | `runs/scaling_laws.sh` 扫同等算力下的不同规模 | 每个深度得到不同 token 数，横向不可比 |
| `--target-param-data-ratio` | 给定 token 与参数之比 | speedrun 与 miniseries | 深度越大训得越久，横向比较的是「计算最优点」 |

三者都未给出时断言失败。三者同时给出时，`--num-iterations` 胜出且不报错，这是最常见的误用：实验者以为在扫 ratio，实际步数被硬编码覆盖。

一个容易忽略的性质是：ratio 只决定 $D$，不决定批大小、学习率缩放与权重衰减。原因是批大小公式中的 $D/D_{\text{ref}}$ 把 ratio 消掉了，而权重衰减公式中的 $D_{\text{ref}}/D$ 同样消掉：

$$
\frac{D}{D_{\text{ref}}}=\frac{\text{ratio}\cdot N}{\text{ratio}\cdot N_{12}}=\frac{N}{N_{12}},\qquad
\lambda=\lambda_{\text{ref}}\sqrt{\frac{B}{B_{\text{ref}}}}\cdot\frac{N_{12}}{N}.
$$

因此把 speedrun 的 ratio 从 8 改成 12，只改变步数（5568 变 8352），学习率与权重衰减不变。用 `--target-flops` 时这条性质仍然成立，因为 $D_{\text{ref}}$ 与 `target_tokens` 同时取负、比值不变。

### 4 批大小：自动推导、覆盖与整除约束

批大小有两级：全局批由缩放律推出，单卡批由显存决定。

```python
total_batch_size = args.total_batch_size
if total_batch_size == -1:
    batch_size_ratio = target_tokens / D_REF
    predicted_batch_size = B_REF * batch_size_ratio ** 0.383
    total_batch_size = 2 ** round(math.log2(predicted_batch_size))
```

$B_{\text{ref}}=2^{19}$，指数 0.383 来自 Power Lines。结果取最近的 2 的幂，因此呈阶梯状：d8 为 $2^{18}$，d12 到 d16 为 $2^{19}$，d20 到 d26 为 $2^{20}$，d32 为 $2^{21}$。

单卡批与累积步数满足

$$
A=\frac{B_{\text{total}}}{B_{\text{dev}}\cdot T\cdot W},
$$

代码对此有硬断言：`assert total_batch_size % world_tokens_per_fwdbwd == 0`。它意味着 $B_{\text{dev}}$ 不能随意取，必须使分母整除分子。以 d8 为例，$B_{\text{total}}=2^{18}=262{,}144$，在 $T=2048$、$W=8$ 下，$B_{\text{dev}}=32$ 给出 $524{,}288$，大于总批，断言直接失败；$B_{\text{dev}}=16$ 给出 $A=1$ 才成立。d8 的批太小，8 卡时单卡批上限是 16。

`--total-batch-size` 可以覆盖自动值。覆盖后学习率仍按 $B/B_{\text{ref}}$ 的平方根缩放，权重衰减也按新批重算，因此「手工调批」不是只改一个数，它同时改变优化器配置。

### 5 显存的四项分解

单卡峰值显存可以拆成四项，前三项在训练中存在，第四项只在推理中存在。

**静态项**由参数、梯度与优化器状态组成。参数按 dtype 分开计算：矩阵与 `lm_head` 为 fp32，`wte` 与 value embeddings 为 bf16。梯度与参数同 dtype。优化器状态是 ZeRO-2 分片的，AdamW 与 Muon 的部分要除以 $W$：

$$
M_{\text{static}}\approx2\left(4P_{\text{fp32}}+2P_{\text{bf16}}\right)+\frac{M_{\text{AdamW}}+M_{\text{Muon}}}{W}.
$$

$P_{\text{fp32}}=N$，$P_{\text{bf16}}=Vd\left(1+n_{\text{ve}}\right)$，$M_{\text{AdamW}}=2\cdot4\cdot Vd+2\cdot2\cdot Vd+2\cdot2\cdot n_{\text{ve}}Vd$，$M_{\text{Muon}}=4N$。注意只有优化器状态被分片，参数与梯度在每个 rank 上都是完整副本。

**激活项**随层数、单卡批与宽度线性增长。每层需要保存约 12 个宽度为 $d$ 的张量（q、k、v、注意力输出、两次 norm 输出等）与 2 个宽度为 $4d$ 的 MLP 中间量，按 bf16 计：

$$
M_{\text{act}}\approx24\cdot L\cdot B_{\text{dev}}\cdot T\cdot d .
$$

**logits 项**是词表投影的峰值，等于 logits 与其梯度两份：

$$
M_{\text{logits}}\approx2\cdot B_{\text{dev}}\cdot T\cdot V\cdot2\ \text{字节}.
$$

d24、$B_{\text{dev}}=16$ 时这一项是 4.3 GB；$B_{\text{dev}}=32$ 时翻倍到 8.6 GB。这是小模型也想把单卡批调小的直接原因：$V$ 固定为 32768，logits 与模型宽度无关。

**KV 项**只在推理与评测时出现。`GPT.kv_bytes_per_token()` 给出

$$
\text{KV bytes/token}=L\cdot2\cdot h_{kv}\cdot q\cdot\text{sizeof}(\text{COMPUTE\_DTYPE}),
$$

d24 在 bf16 下为 $24\times2\times12\times128\times2=147{,}456$ 字节，即 144 KiB/token；2048 上下文单行约 288 MiB，16 个采样行约 4.5 GiB。d12 为 36 KiB/token，单行 72 MiB。训练不使用 KV 缓存，但 `base_eval` 的抽样与 `chat_cli` 的生成会用到它，因此在同一张卡上「训练能跑」不代表「评测与对话也能跑」。

### 6 OOM 的调整顺序

按「改变实验含义的程度」从小到大排列，得到下面的顺序。前两步不改变模型与优化目标，第三步改变数值行为，第四步改变模型本身。

| 顺序 | 动作 | 显存变化 | 代价 |
|---|---|---|---|
| 1 | `--device-batch-size` 16 → 8 → 4 → 2 → 1 | 激活与 logits 线性下降 | $A$ 自动增大，总批不变，吞吐略降 |
| 2 | `--max-seq-len` 2048 → 1024 | 激活与 logits 线性下降 | 上下文能力改变，等于换了模型设定 |
| 3 | 加 `--fp8` | 矩阵乘临时量下降，d26 实测约 9 GB | 需要 sm89 以上，数值路径改变 |
| 4 | `--depth` 24 → 20 → 16 | 静态、激活、logits 全部下降 | 换成另一个模型，实验不可比 |
| 5 | 增加 $W$ | 只降低分片后的优化器状态 | 参数与梯度仍为每卡完整副本，收益有限 |

第 1 步之所以最优先，是因为它不改变任何超参数语义。$B_{\text{total}}$ 不变，学习率与权重衰减不变，只是把一个优化器步拆成更多微批。d24 从 $B_{\text{dev}}=16$ 降到 8，$A$ 从 4 变 8，显存从约 42 GB 降到约 26 GB，训练时间增加的比例小于 2 倍。

第 2 步的隐患是窗口模式。`SSSL` 的短窗等于 $T/4$ 向上取整到 128，$T$ 从 2048 降到 1024 时短窗从 512 变 256，注意力的计算量与激活都下降，但模型见过的最长依赖也减半。若只做短跑对比，两个实验必须用同一个 $T$。第 5 步的收益容易被高估：d24 在 $W=8$ 时优化器状态每卡约 0.72 GB，占静态项的 8%；即使把 $W$ 翻倍也只省 0.36 GB，而参数与梯度合计 8.5 GB 不会减少。

### 7 FP8 的硬件门槛与收益

`--fp8` 的实现是 `nanochat/fp8.py` 的 `Float8Linear`，它把三次矩阵乘的操作数量化到 FP8 并调用 `torch._scaled_mm`。

门槛有三层。

- 硬件：`torch._scaled_mm` 的 FP8 内核需要计算能力 8.9 以上，即 L40S、RTX 4090、H100、H200。`base_train.py` 的帮助文本写「requires H100+ GPU」，但代码只检查 `device_type != "cuda"`，因此在 A100 上会完成模块替换并在第一次矩阵乘处失败。
- 精度：FA3 的 Hopper 内核只支持 bf16 与 fp8，与 `--fp8` 不冲突；但若用 `NANOCHAT_DTYPE=float16`，FA3 会关闭，FP8 的收益被 SDPA 的损失部分抵消。
- 形状：`fp8_module_filter` 只转换 `in_features` 与 `out_features` 都能被 16 整除、且最小维度不小于 128 的线性层。d24 上的 `ve_gate` 是 $12\times12$，被跳过；脚本会打印 `converted X/Y linear layers, skipped Z (too small)`。

收益在 `dev/LOG.md` 2026-02-02 有 d26 的实测：吞吐从 630K tok/s 升到 740K tok/s（1.17 倍），显存减少约 9 GB。这不是 2 倍，原因是词表只有 32768，`lm_head` 在总 FLOPs 中的占比有限，且缩放与 cast 的逐元素开销需要 `torch.compile` 才能摊薄。

### 8 深度档位与用途分工

深度不是越大越好，每个尺度回答不同的问题。

| 深度 | 规模 | 8×H100 时间量级 | 用途 | 不适用 |
|---|---|---|---|---|
| d6 | 384 维、2320 万参数 | CPU 上约 30 分钟 | 路径冒烟：验证数据、优化器、检查点 | 任何能力结论 |
| d8 | 512 维、4194 万参数 | 2–4 分钟 | 单卡快速回归、CI 式检查 | 需要稳定 bpb 的对比 |
| d12 | 768 维、1.10 亿参数 | 4–8 分钟 | 研究迭代的标准尺度，单变量 A/B | 与 d24 直接比较绝对值 |
| d16 | 1024 维、2.35 亿参数 | 12–20 分钟 | 确认改动在更大宽度上仍成立 | 频繁迭代 |
| d20 | 1280 维、4.35 亿参数 | 40–70 分钟 | 正式实验的廉价替代 | 复现 GPT-2 门槛 |
| d24 | 1536 维、7.30 亿参数 | 1.65–2.0 小时 | speedrun 正式配置，GPT-2 级 | 快速试错 |
| d26 | 1664 维、9.18 亿参数 | 2–3 小时 | 与旧版叙述对照 | 当前 speedrun |

`runs/miniseries.sh` 扫 d12 到 d26 共八个深度，正是为了给出这条曲线；它的 CSV 记录每档的参数量、步数、token 数、参数数据比、val bpb、CORE 与训练时间。选择原则是：验证改动用 d12，确认规模效应再用 d16 或 d20，最后才上 d24；只在 d24 上有效的技巧不足以支撑整条曲线。

### 9 两套配置表

下表给出 d12 与 d24 的完整配置。时间与显存是量级估计，条件是 8×H100、$T=2048$、`SSSL`、bf16；实际值以运行结束打印的 `Peak memory usage` 与 `Total training time` 为准。

| 项 | d12 | d24 |
|---|---|---|
| `--depth` | 12 | 24 |
| `model_dim` | 768 | 1536 |
| `n_head` / `n_kv_head` | 6 / 6 | 12 / 12 |
| `--head-dim` | 128 | 128 |
| 缩放参数 $N$ | 110,100,912 | 729,810,624 |
| 总参数 | 286,261,719 | 1,384,122,122 |
| `--target-param-data-ratio` | 8 | 8 |
| 训练 token $D$ | 880,807,296 | 5,838,484,992 |
| $B_{\text{total}}$ | 524,288 | 1,048,576 |
| `num_iterations` | 1680 | 5568 |
| `--device-batch-size` | 32 | 16 |
| $A$（$W=8$） | 1 | 4 |
| $C_{\text{token}}$ | $7.597\times10^{8}$ | $4.775\times10^{9}$ |
| 训练显存（8 卡） | 约 25 GB | 约 42 GB |
| 8×H100 时间 | 4–8 分钟 | 1.65–2.0 小时 |
| `--fp8` | 可选 | 推荐 |
| KV 缓存 | 36 KiB/token | 144 KiB/token |
| 用途 | 研究迭代与 A/B | speedrun 与能力验收 |

两套配置的差别不只是规模。d12 的 $A=1$，即一次前向反向就是一步；d24 的 $A=4$，一步包含四次前向反向。显存结构也不同：d12 的 logits 占估计峰值的三分之一（8.6 GB），d24 的激活占绝对多数（约 29 GB）。调优方向据此不同：d12 想省显存应优先降单卡批，d24 想省显存应先考虑 `--fp8` 或降单卡批。

### 在 nanochat 中的落地

| 位置 | 作用 | 写错或去掉的后果 |
|---|---|---|
| `base_train.py:build_model_meta` | 由深度推出宽度与头数 | 手工设 $d$ 与 $h$ 会导致 $d\%h\ne0$ 断言失败 |
| `base_train.py` 的缩放律段 | 由 $N$ 推出 $D$、$B$、LR 与 WD | 跳过则使用默认批与默认学习率，偏离计算最优 |
| `base_train.py:get_scaling_params` | 只取 `transformer_matrices + lm_head` | 用总参数会把 d24 的 token 数放大近一倍 |
| `base_train.py` 的 horizon 分支 | 三级优先级的实现 | 同时给三个参数时静默采用 `--num-iterations` |
| `base_train.py` 的整除断言 | 保证累积步数为整数 | 单卡批过大时启动即失败 |
| `gpt.py:setup_optimizer` 的 `dmodel_lr_scale` | AdamW 学习率按 $1/\sqrt{d}$ 缩放 | 大宽度下 AdamW 学习率过高 |
| `gpt.py:kv_bytes_per_token` | KV 显存的第一性公式 | 低估评测与对话阶段的显存 |
| `base_train.py` 的 FP8 过滤 | 只转换够大的线性层 | 小层被量化会带来精度损失而无速度收益 |

## 关键直觉

> [!tip] 深度决定形状与算力，ratio 只决定在形状上训多久
> 形状由 $L$ 经 $d=\lceil64L/128\rceil\cdot128$、$h=d/128$ 唯一确定，$N$ 随之确定；批大小、学习率缩放与权重衰减都只是 $N$ 的函数，而 $D=\text{ratio}\cdot N$ 是唯一被 ratio 改变的量。因此「把模型做大」与「把模型训久」是两个独立旋钮，前者改 `--depth`，后者改 `--target-param-data-ratio`。这条分工与第 1 节的取整、第 3 节的 cancelling、第 9 节的两套配置表一一对应，也是判断一次实验到底改了什么的第一道检查。

## 例子与代码

### 例 1：由深度复算配置

```python
# depth_plan.py —— 复算第 1、3、4、9 节的表，只依赖标准库
import math

V, ASPECT, HEAD_DIM, RATIO, T, WORLD = 32768, 64, 128, 8, 2048, 8

def shape(depth):
    base = depth * ASPECT
    d = ((base + HEAD_DIM - 1) // HEAD_DIM) * HEAD_DIM
    return d, d // HEAD_DIM

def n_ve(depth):
    # 带 value embedding 的层：与最后一层同奇偶的层
    return sum(1 for i in range(depth) if i % 2 == (depth - 1) % 2)

def scaling_params(depth):
    d, h = shape(depth)
    matrices = depth * (4 * d * d + 2 * d * 4 * d) + n_ve(depth) * 12 * h
    return matrices + d * V

def flops_per_token(depth):
    d, h = shape(depth)
    short = -(-T // 4 // 128) * 128          # 2048 -> 512
    windows = [T if "SSSL"[i % 4] == "L" else short for i in range(depth)]
    windows[-1] = T                          # 最后一层强制全上下文
    return 6 * scaling_params(depth) + sum(12 * h * (d // h) * w for w in windows)

N12 = scaling_params(12)

def plan(depth, dev):
    N = scaling_params(depth)
    D = RATIO * N
    # ratio 在 D/D_ref 中消掉，批大小只取决于 N/N12
    B = 2 ** round(math.log2(2**19 * (N / N12) ** 0.383))
    A = B // (dev * T * WORLD)
    print(f"d{depth:<2} dim={shape(depth)[0]:<4} h={shape(depth)[1]:<2} "
          f"N={N:>13,} D={D:>13,} B={B:>9,} iters={D // B:>5,} "
          f"dev={dev:<2} A={A} C_tok={flops_per_token(depth) / 1e9:.3f}e9")

for depth, dev in ((8, 16), (12, 32), (16, 32), (20, 16), (24, 16), (26, 16), (32, 16)):
    plan(depth, dev)
```

预期输出如下。d8 的 `dev=16` 不是随意选择：它的总批只有 $2^{18}$，在 $W=8$ 与 $T=2048$ 下 `dev=32` 会使分母超过分子，断言失败。

```text
d8  dim=512  h=4  N=   41,943,232 D=  335,545,856 B=  262,144 iters=1,280 dev=16 A=1 C_tok=0.296e9
d12 dim=768  h=6  N=  110,100,912 D=  880,807,296 B=  524,288 iters=1,680 dev=32 A=1 C_tok=0.760e9
d16 dim=1024 h=8  N=  234,881,792 D=1,879,054,336 B=  524,288 iters=3,584 dev=32 A=1 C_tok=1.585e9
d20 dim=1280 h=10 N=  435,160,240 D=3,481,281,920 B=1,048,576 iters=3,320 dev=16 A=4 C_tok=2.886e9
d24 dim=1536 h=12 N=  729,810,624 D=5,838,484,992 B=1,048,576 iters=5,568 dev=16 A=4 C_tok=4.775e9
d26 dim=1664 h=13 N=  918,423,532 D=7,347,388,256 B=1,048,576 iters=7,007 dev=16 A=4 C_tok=5.991e9
d32 dim=2048 h=16 N=1,677,724,672 D=13,421,797,376 B=2,097,152 iters=6,400 dev=16 A=8 C_tok=10.771e9
```

三行可单独核对：d12 的 $B_{\text{total}}=524{,}288$ 与 `dev=32` 恰好相等，所以 $A=1$；d24 的 $1{,}048{,}576/(16\times2048\times8)=4$；d32 的总批升到 $2^{21}$，同样 $B_{\text{dev}}=16$ 时 $A=8$。

### 例 2：显存分解

```python
# depth_mem.py —— 用第 5 节的四项公式估计单卡峰值，单位 GB
def counts(depth):
    d, h = shape(depth)
    matrices = depth * (4 * d * d + 2 * d * 4 * d) + n_ve(depth) * 12 * h
    lm = d * V
    wte = V * d
    ve = n_ve(depth) * V * d
    return d, h, matrices, lm, wte, ve

def plan_memory(depth, dev, world):
    d, h, matrices, lm, wte, ve = counts(depth)
    params = 4 * (matrices + lm) + 2 * (wte + ve)        # fp32 矩阵 + bf16 嵌入
    adamw = 2 * 4 * lm + 2 * 2 * wte + 2 * 2 * ve        # 一阶矩与二阶矩
    muon = 4 * matrices                                   # 动量
    static = 2 * params + (adamw + muon) / world          # 参数 + 梯度 + 分片状态
    logits = 2 * dev * T * V * 2                          # logits 与其梯度
    act = 24 * depth * dev * T * d                        # 每层约 12 个宽度 d 的张量
    kv = depth * 2 * h * HEAD_DIM * 2                     # bf16
    total = (static + logits + act) / 1e9
    print(f"d{depth} dev{dev} W{world}: total {total:.1f} GB "
          f"= static {static / 1e9:.2f} + logits {logits / 1e9:.1f} + act {act / 1e9:.1f} "
          f"| KV {kv / 1024:.0f} KiB/token")

for depth, dev, world in ((12, 32, 8), (12, 16, 8), (24, 16, 8), (24, 8, 8)):
    plan_memory(depth, dev, world)
```

预期输出：

```text
d12 dev32 W8: total 24.8 GB = static 1.74 + logits 8.6 + act 14.5 | KV 36 KiB/token
d12 dev16 W8: total 13.3 GB = static 1.74 + logits 4.3 + act 7.2 | KV 36 KiB/token
d24 dev16 W8: total 42.5 GB = static 9.17 + logits 4.3 + act 29.0 | KV 144 KiB/token
d24 dev8 W8: total 25.8 GB = static 9.17 + logits 2.1 + act 14.5 | KV 144 KiB/token
```

读法有三条。第一，d24 的激活占 29 GB，是最大单项，因此降单卡批的收益最直接。第二，d24 的静态项 9.17 GB 中，参数与梯度各占 4.23 GB，优化器分片只占 0.72 GB；换更多卡不能解决静态项。第三，logits 与宽度无关，d12 在 `dev=32` 时 logits 反而比 d24 在 `dev=16` 时更大。

### 例 3：两条可执行命令

```bash
# 1) d12 研究迭代：关闭中途 CORE、采样与中间保存，约 5 分钟
OMP_NUM_THREADS=1 torchrun --standalone --nproc_per_node=8 -m scripts.base_train -- \
    --depth=12 --run=d12 --model-tag=d12 \
    --core-metric-every=999999 --sample-every=-1 --save-every=-1

# 2) d24 speedrun 正式配置，先降一档单卡批以留余量
OMP_NUM_THREADS=1 torchrun --standalone --nproc_per_node=8 -m scripts.base_train -- \
    --depth=24 --target-param-data-ratio=8 --device-batch-size=8 --fp8 --run=d24_try
```

第 2 条把 `--device-batch-size` 从 16 降到 8 后，$A$ 变为 8，总批与学习率不变，显存从约 42 GB 降到约 26 GB。固定算力的扫描用 `--target-flops` 替代 ratio，写法见 `runs/scaling_laws.sh`。

## 易错点

> [!warning] 以下六条都可在启动日志中检验
> 1. 把 `--device-batch-size` 当成总批。它只影响单卡显存与累积步数；总批由缩放律或 `--total-batch-size` 决定。检验：日志中 `Tokens / micro-batch / rank` 与 `Total batch size` 是两行不同的数。
> 2. 单卡批大到破坏整除。d8 在 $W=8$ 时 `dev=32` 使分母大于分子，断言失败。检验：`total_batch_size % (dev*T*W) == 0`。
> 3. 同时给 `--num-iterations` 与 `--target-param-data-ratio`。前者胜出且不报警，实验者以为在扫 ratio。检验：日志打印 `Using user-provided number of iterations`。
> 4. 以为改 ratio 会改批大小与学习率。比值在 $D/D_{\text{ref}}$ 中抵消，三者在不同 ratio 下相同。检验：用两个 ratio 各跑一次，比较 `Auto-computed optimal batch size` 与 `Scaling LRs by`。
> 5. 在 A100 上加 `--fp8`。代码只检查 CUDA，sm80 会在 `torch._scaled_mm` 处失败。检验：`torch.cuda.get_device_capability() >= (8, 9)`。

## 关联笔记

- 前置 [[缩放定律与模型深度]]：给出 $B\propto D^{0.383}$、T_epoch 权重衰减与逐深度表的完整推导，本篇只把它转成配置与命令。
- 前置 [[跑通speedrun脚本]]：给出 speedrun 的九个步骤与产物，本篇聚焦第 6 步的五个参数。
- 后续 [[常见问题踩坑]]：把 OOM、FP8 与整除断言展开为症状到修复的映射。
- 后续 [[实验记录模板]]：把两套配置表变成可比对的实验记录字段。
- 跨库 [[PyTorch实战入门]]：通用原理见该篇，本篇只写 nanochat 的显存分解与精度开关。

## 达标检测

- [ ] 能由 `--depth=20` 手算出宽度、头数、缩放参数、训练 token、批大小与步数。
- [ ] 能解释 `model_dim` 为何要向上取整到 `head_dim` 的倍数，以及取整在默认参数下何时生效。
- [ ] 能写出 `num_iterations` 的三级优先级，并说明三者同时给出时的实际行为。
- [ ] 能证明改 ratio 不改变批大小、学习率缩放与权重衰减。
- [ ] 能列出显存的四项分解，并说明哪一项对 d24 最大、哪一项与宽度无关。
- [ ] 能按代价从小到大给出 OOM 的五步调整顺序，并指出哪一步改变了实验含义。
- [ ] 能说明 FP8 的三层门槛，并解释为什么 d24 上的加速不是 2 倍。

## 参考来源

- Karpathy, *nanochat*（commit `92d63d4`），`scripts/base_train.py` 的 `build_model_meta`、缩放律段与 horizon 分支 —— 对应第 1、3、4 节的全部公式与默认值。
- Karpathy, *nanochat*（commit `92d63d4`），`nanochat/gpt.py` 的 `num_scaling_params`、`estimate_flops`、`kv_bytes_per_token`、`setup_optimizer` —— 对应第 2、5 节与宽度缩放。
- Karpathy, *nanochat*（commit `92d63d4`），`nanochat/fp8.py` 与 `dev/LOG.md` 2026-02-02 —— 对应第 7 节的过滤条件、吞吐与显存实测。
- Bergsma et al., *Power Laws for Batch Size, Model Size, and Training Horizon*（arXiv:2505.13738） —— 对应 $B_{\text{opt}}\propto D^{0.383}$ 与 2 的幂取整。
- Chowdhery et al., *PaLM: Scaling Language Modeling with Pathways*（arXiv:2204.02311） —— 对应 $6N+12hqT$ 的 FLOPs 估算。
- PyTorch documentation, *CUDA memory management* 与 `torch.cuda.max_memory_allocated` —— 对应显存估算与实测口径的差别。
