---
tags: [nanochat, repro, experiment]
阶段: 10-复现与实验
难度: ★★☆
created: 2026-10-22
related: "[[用--depth调参]], [[跑通speedrun脚本]], [[实验日志]], [[成本-延迟-质量权衡]]"
---

# 实验记录模板

## 定义

**实验记录**（experiment record）是一次训练运行的最小可复现描述，包含九个字段：日期、假设、改动、命令、配置 diff、数据、指标、结论、下一步。它使另一个执行者在只读记录的条件下能够重现该运行，并判断改动是否有效。

本篇使用的术语：

| 术语 | 含义 |
|---|---|
| 假设（hypothesis） | 一句可被证伪的陈述，形式为「改动 X 会使指标 Y 朝方向 Z 变化」 |
| 变量（variable） | 假设中被改动的唯一一项配置 |
| 基线（baseline） | 未改动的对照运行，必须与实验运行共享全部其它配置 |
| 配对（paired） | 两个运行的深度、数据、token 预算、评测协议完全相同 |
| 配置 diff | 两次运行的命令行或 `meta.user_config` 的逐键差异 |
| 指标口径 | 指标的计算方式与采样规模，如 val bpb 用了多少 token、CORE 每任务取多少例 |
| run id | wandb 的运行标识，或本地运行目录名 |
| 失败实验 | 假设被否定的运行，其记录价值与成功实验相同 |
| 噪声尺度 | 同一配置重复运行时指标的标准差，决定最小可判定差异 |

**A/B 测试**指在配对条件下只改一个变量、各跑一次或多次、再按噪声尺度判定差异是否显著的实验方式。

记录的粒度有三档，用途不同。单次运行一条记录，回答「这次改动的效果是多少」；一组 A/B 一条汇总，回答「这个改动是否超过噪声」；一个阶段一条总结，回答「这条技术路线是否值得继续」。三档共用同一组字段，区别只在指标栏填单次值、配对差值还是累计趋势。

## 为什么重要

没有记录就无法归因。nanochat 的一次 d12 短跑只要约 5 分钟，但一次 8 卡的小时成本约 24 美元；更常见的情形是改了三处代码、跑出一个更好的 bpb，却无法判断收益来自哪一处。实验记录的作用是把「结果更好」转化为「哪一项改动带来了多少变化」。

没有统一口径就无法比较。val bpb 依赖验证集与评测 token 数，CORE 依赖每任务采样数与随机基线，`total_training_time` 只统计第 10 步之后。同一份权重在两个口径下会给出不同数字，把这些数字混在一张表里比较，得到的排序没有意义。

没有失败记录就会重复走同一条路。仓库的 `dev/LOG.md` 从 2026 年 1 月记到 5 月，其中大量条目标注 `(negative)`：DyT、Mixture of Experts、SwiGLU、多 token 预测、varlen attention 等。这些条目阻止了后来者重复同样的实验，也记录了「为什么当时看起来有希望」。

在全书中的位置：前置为 [[用--depth调参]]（确定运行规模与配置）与 [[跑通speedrun脚本]]（产物与命令）；后续为 [[实验日志]]（按周累积实际记录）与 [[常见问题踩坑]]（失败的技术原因）。懂原理对应「定义可证伪的假设」，能复现对应「让别人能照着记录重跑」，懂工程对应「用最小成本获得可判定的结论」。

## 原理与推导

### 1 九个字段及其理由

每个字段都对应一种失败模式，缺一个字段就少一道检查。

| 字段 | 内容 | 缺失后的失败模式 |
|---|---|---|
| 日期 | `YYYY-MM-DD`，与 commit 时间对应 | 无法与代码版本对齐 |
| 假设 | 一句可证伪陈述 | 实验变成「试试看」，结果无法判定 |
| 改动 | 改了哪个文件、哪个函数、哪一行语义 | 无法复现改动 |
| 命令 | 完整命令行，含全部参数与环境变量 | 无法重跑，只能重写 |
| 配置 diff | 与基线逐键比较的差异 | 隐藏的耦合改动被漏掉 |
| 数据 | 数据版本、分片数、token 预算 | 跨数据集比较 bpb |
| 指标 | 按第 3 节的口径记录 | 数字不可比 |
| 结论 | 采纳、待定或否决，附依据 | 下次重复同一实验 |
| 下一步 | 一个具体动作 | 实验线索中断 |

假设的写法决定实验能否结束。可用的形式是「把 `--matrix-lr` 从 0.02 提到 0.025，在 d12、ratio 8、seed 42 下使 val bpb 下降至少 0.002」；不可用的形式是「试试更大的学习率」。前者给出变量、条件与判定阈值，跑完即可判定；后者没有阈值，任何结果都能被解释为「有一点变化」。

改动的记录要写到语义层而不是 diff 层。`git diff` 给出的是行级差异，实验记录需要的是「把 `cautious weight decay` 的掩码从 `>=0` 改成 `>0`」，这样即使后续重构导致行号变化，改动仍然可查。

日期字段还有一个隐含要求：记录应当写在运行之前而不是之后。先写假设与命令，再启动训练，可以避免「看到结果后补写一个匹配的假设」这一常见偏差；`dev/LOG.md` 的条目按日期倒序排列，也支持「先有计划、再有结果」的阅读顺序。

### 2 变量控制

控制变量有三个层次，逐层收紧。

第一层，单变量。一次只改一项，其余全部相同。nanochat 的配置全在命令行里，因此「相同」是可检查的：把两次运行的命令并排比较，除一项外应完全一致。

第二层，同预算。两个运行必须消费相同的 token 数或相同的 FLOPs。token 预算由 `--target-param-data-ratio` 与深度共同决定，改动深度本身就改了预算；若必须改深度，则改用 `--target-flops` 固定算力，代价是各深度的 token 数不同，横向比较的是「同等算力下的最优损失」而不是「同 token 下的损失」。

第三层，同协议。评测必须用相同的口径：`--eval-tokens` 决定 bpb 的采样量，`--core-metric-max-per-task` 决定 CORE 的采样量，`--max-seq-len` 与 `--window-pattern` 决定模型看到的上下文。用 500 例/任务的 CORE 与 100 例/任务的 CORE 比较，差异可能全部来自采样噪声。

seed 的控制需要单独说明。`compute_init` 设置 `torch.manual_seed(42)` 与 `torch.cuda.manual_seed(42)`，注释说明「大部分代码使用显式 rng 对象，全局种子主要影响模块初始化」。但 `torch.use_deterministic_algorithms(True)` 在代码中被注释掉，因此即使 seed 相同，cuBLAS 的原子加法顺序、`torch.compile` 生成的归约顺序、FA3 内核的调度都可能带来逐位差异。结论是：同 seed 能消除初始化与数据顺序的差异，不能保证逐位可复现；判定必须依赖噪声尺度而不是逐位相等。

数据顺序是另一个容易被忽略的变量。预训练 dataloader 的状态（`pq_idx`、`rg_idx`、`epoch`）随检查点保存，若两次运行从不同步数恢复，它们看到的数据顺序不同，bpb 的差异可能来自数据而不是改动。

### 3 指标口径

五个必记量覆盖「质量、能力、效率、成本」四个维度。

| 指标 | wandb key | 定义 | 方向 | 单次噪声量级 |
|---|---|---|---|---|
| 验证损失 | `val/bpb` | $\sum\text{nats}/(\ln2\cdot\sum\text{bytes})$，在 `--eval-tokens` 个 token 上估计 | 越低越好 | 约 0.001 |
| 能力分数 | `core_metric` | 22 项 ICL 任务的 centered accuracy 均值 | 越高越好 | 约 0.005 |
| 算力利用率 | `train/mfu` | $\text{FLOPs/s}/(P_{\text{peak}}\cdot W)$，按百分比 | 越高越好 | 随步波动 |
| 吞吐 | `train/tok_per_sec` | $B_{\text{total}}/\Delta t$ | 越高越好 | 随步波动 |
| 训练时长 | `total_training_time` | 只累计第 10 步之后的墙钟秒数 | 越低越好 | 与机器负载相关 |

bpb 的定义需要展开，因为它决定了跨词表可比性：

$$
\text{bpb}=\frac{\sum_{t\in\text{val}}\text{nats}_t}{\ln 2\cdot\sum_{t\in\text{val}}\text{bytes}_t},
$$

分子是交叉熵的 nats 总和，分母是同一批 token 覆盖的原始字节数乘以 $\ln 2$。分母来自 `token_bytes.pt`，因此换分词器会改变分母，进而改变 bpb；这就是「换分词器后 bpb 不可比」的算术原因。

MFU 与吞吐的关系为

$$
\text{tok/s}=\frac{B_{\text{total}}}{\Delta t},\qquad
\text{MFU}=100\cdot\frac{C_{\text{token}}\cdot\text{tok/s}}{P_{\text{peak}}\cdot W}.
$$

两式说明：吞吐与 MFU 不是独立指标，已知 $C_{\text{token}}$ 与峰值算力时可由一个推出另一个。记录时只需写 `tok/s` 与 `mfu` 中的一个，但两者都写便于交叉验证——若二者比例与 $C_{\text{token}}/(P_{\text{peak}}W)$ 不符，说明 `get_peak_flops` 把 GPU 型号识别错了。

噪声量级来自两个来源：`val/bpb` 的采样规模是 $80\times524288\approx4.2\times10^{7}$ token，二项近似给出千分之一量级的标准误；CORE 的单次标准差约 0.005，这一数字在 05 阶段的分析中给出，量级上与 22 项任务、每项数百例的采样规模一致。两者都意味着：bpb 差异小于 0.001 不应下结论，CORE 差异小于 0.01 不应下结论。

三个与时间有关的量必须区分。

- `total_training_time` 是训练循环内累计的墙钟，不含数据下载、分词器、评测与 SFT，是 leaderboard 的「time to GPT-2」。
- 脚本墙钟包含全部阶段，通常是前者的 1.5 到 2 倍。
- `train/dt` 是单步耗时，`train/tok_per_sec` 与它互为倒数乘以批大小；`train/mfu` 由它与峰值算力算出。

记录时三者都要写，否则无法判断「变快了」是训练变快还是评测变短。

wandb 之外还有两个数据源必须一起保存：`base_eval/base_model_{step}.csv` 记录了 22 项任务的 accuracy 与 centered，是 CORE 的唯一分解；`meta_{step}.json` 记录了 `user_config`（全部命令行参数）、`val_bpb`、`model_config` 与数据游标，是配置快照的唯一权威来源。

### 4 A/B 设计

一次 A/B 由三个决定构成：跑几次、比较什么、判定阈值多少。

跑几次取决于噪声与目标效应。若 CORE 的单次标准差为 0.005，要在 95% 置信水平下分辨 0.01 的差异，每组需要约 $(1.96\cdot2\cdot0.005/0.01)^2\approx4$ 次；分辨 0.02 的差异需要 1 次。实践中的折中是：先用一次 d12 短跑筛掉明显无效的改动，再对候选改动跑 2 至 3 次。

比较什么取决于指标。bpb 的噪声小，适合作为筛选指标；CORE 的噪声大但更接近目标，适合作为确认指标；`total_training_time` 只在两者接近时用于排序。三个指标同时改善的改动最可信，只改善其中一个的改动需要重复。

判定阈值应当预先写出，而不是看到结果后再定。可用的写法是：

$$
\Delta_{\text{judge}}=\max\left(2\sigma_{\text{noise}},\ 0.01\right),
$$

对 CORE 即约 0.01，对 bpb 即约 0.002。低于阈值的差异记为「未定」，不记为「有效」或「无效」。

A/A 测试是必要的自检：用完全相同的配置跑两次，观察指标的差异。若 A/A 差异超过上面的阈值，说明噪声估计偏低或机器状态不稳定（例如另一进程占用显存导致降频），此时任何 A/B 结论都不可信。A/A 还能量出与代码无关的系统性漂移，例如同一节点在不同时段的温度与频率差异。

### 5 失败实验的记录结构

`dev/LOG.md` 的结构可以直接借用。它的每个条目由四部分组成：标题行给出日期与一句话结论，正文给出动机、改动、结果与结论；负面结果在标题中标注 `(negative)`。

一个完整的失败记录示例结构如下，条目取自该文件 2026-02-05 的 SwiGLU 实验：动机是用 SwiGLU 替换 ReLU² 以增加表达力；改动是把 MLP 的两个矩阵换成三个矩阵、扩张比从 4 改为 $8/3$；结果是在相同参数与 FLOPs 下没有改善；结论是否决，理由是「参数与 FLOPs 都匹配时收益消失，说明原设计已经吃满了这部分容量」。该条目还保留了两组计算的对照，说明「参数相同、FLOPs 相同」这一前提是结论成立的关键。

另一类结构适合「一次扫多个想法」的条目，见该文件 2026-03-24 的 parameter-golf 扫描：先用一小节写判定标准，再用分点列出每个想法的改动与结果，最后用一小节给总体结论。当一次实验包含多个互不依赖的小改动时，这种结构比逐条建文件更省事，代价是单个想法的细节必须压缩到两三行。

失败记录有三条写作要求。第一，写明改动在什么条件下被测试，尤其是深度与 token 预算；同一改动在 d12 与 d24 上可能给出相反结论。第二，写明判定用的指标与阈值，避免「效果不明显」这类无法复核的表述。第三，写明复现所需的最小信息，包括分支名或 commit，使后来者能直接重跑。

失败记录的标题应当包含方向而不是情绪。「SwiGLU 激活（负面结果）」是可检索的标题，「一次失败的尝试」不是。

### 6 存储与命名

一次运行应产生一个目录，目录内放四类文件：

```text
runs/<run_id>/
├── provenance.txt      # 时间、commit、GPU、驱动、torch 版本、完整命令
├── config.json         # meta_*.json 中的 user_config
├── metrics.csv         # 从 wandb 或日志导出的 step/val_bpb/loss/mfu
└── notes.md            # 本篇模板填写后的记录
```

`run_id` 建议用 `YYYYMMDD-<depth>-<短描述>` 的形式，例如 `20261022-d12-mlr0.025`。它与 `--run` 传给 wandb 的名字一致，使本地目录、wandb run 与检查点目录三者可互相定位。检查点目录用 `--model-tag` 单独指定，因为同一深度可能对应多次实验。

三个必须落盘的元数据是 commit、完整命令与 GPU 型号。commit 决定代码版本，命令决定配置版本，GPU 型号决定 `get_peak_flops` 的取值与 MFU 的可比性。三者缺一，跨机器比较就失去意义。

检查点本身也是记录的一部分。`meta_{step}.json` 的 `user_config` 是训练脚本对自身配置的完整快照，比手工抄写的命令行更可靠；因此记录中的命令栏可以从该文件反推并核对，二者不一致时以 meta 为准。

### 7 从记录到决策

记录的目的是支持三档决策，每档有明确的判据。

| 决策 | 判据 | 后续动作 |
|---|---|---|
| 采纳 | 主指标改善超过阈值，且至少一个副指标不变差 | 合入，并加入 [[实验日志]] |
| 待定 | 主指标改善但低于阈值，或仅单次运行 | 重复 2 至 3 次，或换 d16 确认 |
| 否决 | 主指标不变差但成本上升，或多次运行无一致方向 | 记为失败实验，写明条件 |

三档之外的第四种情况是「无法判定」，通常由三个原因造成：评测被截断（CORE 只跑了部分任务）、配置 diff 不止一项、机器状态异常（显存不足导致换页或降频）。这三种情况应当在记录中显式标出，而不是归入「待定」。

### 8 团队协作中的约定

多人共用一台节点时，记录还要解决资源冲突与结果归属。两条约定足够：第一，运行目录名带用户名或缩写，例如 `20261022-d12-mlr0.025-wyl`，避免两个同名 run 互相覆盖；第二，检查点目录通过 `--model-tag` 与 run id 绑定，不共用 `d12` 这类通用名，否则后一次运行会覆盖前一次的 `model_001680.pt` 与 `meta_001680.json`。

wandb 侧用 `--run` 区分运行名，项目名由脚本写死（预训练为 `nanochat`），因此同一个项目下会混入所有人的运行。筛选依赖运行名的前缀约定，这也是把 run id 写进运行名的第二个理由。

跨机器比较必须记录 GPU 型号与驱动版本，因为 `get_peak_flops` 按设备名查表，未识别的卡返回 `inf` 使 MFU 显示为 0%。这不影响训练，但会让「哪台机器更快」的判断失真。

### 在 nanochat 中的落地

| 位置 | 作用 | 与记录的关系 |
|---|---|---|
| `base_train.py` 的 `user_config = vars(args).copy()` | 把全部命令行参数写入 wandb config 与 meta | 配置快照的唯一权威来源 |
| `save_checkpoint` 的 `meta_data["user_config"]` | 每个检查点自带配置 | 事后重建命令行 |
| `base_train.py` 每 100 步的 `wandb_run.log` | 写入 `train/loss`、`train/mfu`、`train/tok_per_sec` 等 | 曲线的原始数据 |
| 评测时的 `wandb_run.log` | 写入 `val/bpb`、`core_metric`、`centered_results` | 指标的原始数据 |
| `base_eval.py` 的 CSV | 22 项任务的分解 | CORE 的可核对明细 |
| `dev/LOG.md` | 仓库维护的实验日志 | 失败记录的结构范本 |
| `runs/miniseries.sh` 的 CSV | 每档深度的参数、token、bpb、CORE、时间 | 跨深度对比的现成表结构 |

## 关键直觉

> [!tip] 记录的价值等于「别人能否只读记录就重跑」，而不是「写得多详细」
> 判据很具体：给出记录中的命令与配置，另一位执行者应能在相同硬件上得到相同量级的 bpb 与 CORE，并把差异归因到唯一一项改动。因此记录的核心不是叙述，而是三样可机读的东西：完整命令行、commit、以及按统一口径记录的五个指标。这与第 1 节的九字段、第 3 节的指标表、第 4 节的阈值是同一件事的三个层次：字段保证信息完整，口径保证数字可比，阈值保证结论可判定。

## 例子与代码

### 例 1：可复制的记录模板

下面这段可以直接粘贴到 `runs/<run_id>/notes.md`，替换尖括号内容。为便于整块复制，内部标题使用三级标题。

````markdown
# <YYYY-MM-DD> <一句话结论>

### 假设

在 <深度、ratio、seed、评测协议> 下，把 <改动> 从 <旧值> 改为 <新值>，
会使 <主指标> <下降/上升> 至少 <阈值>。

### 改动

- 文件与函数：`<nanochat/gpt.py:setup_optimizer>`
- 语义变化：<把 cautious weight decay 的掩码从 >=0 改为 >0>
- commit：`<git rev-parse --short HEAD>`
- 分支：`<branch>`

### 命令

```bash
<完整命令行，含 export 的环境变量>
```

### 配置 diff

| 键 | 基线 | 本次 |
|---|---|---|
| `<--matrix-lr>` | `<0.02>` | `<0.025>` |
| 其它键 | 全部相同 | 全部相同 |

### 数据

- 数据集：`climbmix-400b-shuffle`，分片数 `<171>`
- 训练 token：`<5,838,484,992>`
- 验证 token：`<41,943,040>`

### 指标

| 指标 | 基线 | 本次 | 差异 | 是否超过阈值 |
|---|---|---|---|---|
| val bpb | `<0.9781>` | `<0.9759>` | `<0.0022>` | `<是>` |
| CORE | `<0.2310>` | `<0.2342>` | `<0.0032>` | `<否>` |
| train/mfu | `<28.4>` | `<28.6>` | `<0.2>` | `<否>` |
| tok/s | `<2,910,000>` | `<2,930,000>` | `<0.7%>` | `<否>` |
| total_training_time | `<5.9m>` | `<5.8m>` | `<-1.7%>` | `<否>` |

### 结论

<采纳 / 待定 / 否决>，依据：<主指标超过阈值，副指标不变差>。

### 下一步

<在 d16 上重复一次，或换 seed 复跑两次确认稳定性>。
````

模板中的三处设计是刻意的：指标表带「是否超过阈值」一列，强制在写结论前先判定；配置 diff 表要求写出「其它键全部相同」，把单变量条件显式化；结论只能是三档之一，避免「效果不错」这类不可判定的表述。

### 例 2：采集运行指纹

```bash
# collect_provenance.sh —— 在启动训练前执行，把可复现所需的元数据写入 runs/<run_id>/
set -euo pipefail

RUN_ID="${1:?用法: bash collect_provenance.sh <run_id>}"
shift
OUT="runs/$RUN_ID"
mkdir -p "$OUT"

{
    echo "run_id: $RUN_ID"
    echo "started_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
    echo "host: $(hostname)"
    echo "pwd: $(pwd)"
    echo "git_commit: $(git rev-parse --short HEAD)"
    echo "git_branch: $(git rev-parse --abbrev-ref HEAD)"
    echo "git_dirty_files: $(git status --porcelain | wc -l)"
    echo "python: $(python -V 2>&1)"
    echo "torch: $(python -c 'import torch; print(torch.__version__, torch.version.cuda)')"
    echo "gpu: $(nvidia-smi --query-gpu=name,driver_version --format=csv,noheader | sort -u | tr '\n' ';')"
} > "$OUT/provenance.txt"

# 完整命令由调用方传入，脚本不猜测参数
printf 'command: %s\n' "$*" >> "$OUT/provenance.txt"
cat "$OUT/provenance.txt"
```

预期输出形如下面几行，其中 `git_dirty_files` 是关键：非零表示工作区有未提交改动，此时 commit 不能唯一确定代码版本。

```text
run_id: 20261022-d12-mlr0.025
started_at: 2026-10-22T09:12:04Z
host: gpu-node-07
pwd: /home/user/nanochat
git_commit: 92d63d4
git_branch: master
git_dirty_files: 0
python: Python 3.10.19
torch: 2.9.1+cu128 12.8
gpu: NVIDIA H100 80GB HBM3, 570.86.15;
command: python -m scripts.base_train -- --depth=12 --matrix-lr=0.025
```

### 例 3：对比两次运行的配置

```python
# diff_config.py —— 比较两次运行的配置字典，只打印差异键
base = {
    "depth": 12, "target_param_data_ratio": 8, "device_batch_size": 32,
    "matrix_lr": 0.02, "embedding_lr": 0.3, "unembedding_lr": 0.008,
    "weight_decay": 0.28, "fp8": False, "max_seq_len": 2048,
}
cand = dict(base, matrix_lr=0.025)

keys = sorted(set(base) | set(cand))
changed = [(k, base.get(k), cand.get(k)) for k in keys if base.get(k) != cand.get(k)]

print(f"changed keys: {len(changed)} / {len(keys)}")
for k, old, new in changed:
    print(f"  {k}: {old} -> {new}")
print("single_variable:", len(changed) == 1)
```

预期输出：

```text
changed keys: 1 / 9
  matrix_lr: 0.02 -> 0.025
single_variable: True
```

第三行是单变量条件的机检结果。真实使用时把两个 `meta_*.json` 的 `user_config` 载入为两个字典即可，键集来自 `vars(args)`，因此它天然覆盖全部命令行参数。若 `single_variable` 为 `False`，需要先解释每个差异键，再决定这次实验是否还能作为 A/B。

### 例 4：把多档深度的结果汇成一张表

```python
# summary.py —— 把 miniseries 风格的 CSV 行整理成对比表，只依赖标准库
rows = [
    {"depth": 12, "iters": 1680, "tokens": 880_807_296, "bpb": 1.0472, "core": 0.1021},
    {"depth": 16, "iters": 3584, "tokens": 1_879_054_336, "bpb": 0.9481, "core": 0.1487},
    {"depth": 20, "iters": 3320, "tokens": 3_481_281_920, "bpb": 0.8725, "core": 0.1936},
]

print(f"{'depth':>5} {'iters':>7} {'tokens(B)':>10} {'bpb':>8} {'core':>8} {'bpb/Btok':>12}")
for r in rows:
    # 把 bpb 折算到每十亿 token，用于观察「更低的 bpb」是否只是「训得更久」
    print(f"{r['depth']:>5} {r['iters']:>7} {r['tokens'] / 1e9:>10.2f} "
          f"{r['bpb']:>8.4f} {r['core']:>8.4f} {r['bpb'] / r['tokens'] * 1e9:>12.4f}")

best_bpb = min(rows, key=lambda r: r["bpb"])["depth"]
best_core = max(rows, key=lambda r: r["core"])["depth"]
print("最低 bpb:", best_bpb, "层 | 最高 core:", best_core, "层 | 同一档:", best_bpb == best_core)
```

预期输出：

```text
depth   iters  tokens(B)      bpb     core     bpb/Btok
   12    1680       0.88   1.0472   0.1021       1.1889
   16    3584       1.88   0.9481   0.1487       0.5046
   20    3320       3.48   0.8725   0.1936       0.2506
最低 bpb: 20 层 | 最高 core: 20 层 | 同一档: True
```

这张表说明跨深度比较的两个陷阱。第一，bpb 随深度单调下降，但训练 token 同时增加，因此「bpb 更低」不等于「同预算下更好」；第五列的除法只是把 bpb 折算到每十亿 token，不能替代真正的成本归一，真实汇总应把 `tokens` 换成 `total_training_time`。第二，最低 bpb 与最高 CORE 是否落在同一档需要显式检查；本例中二者一致，而真实实验中不一致时就必须按目标函数选择，而不是只报告更好看的那个数。表中的数值是示例，用于演示汇总脚本的形状，不对应任何一次真实运行。

## 易错点

> [!warning] 以下六条都能在记录或产物中核对
> 1. 记录命令时省略环境变量。`NANOCHAT_BASE_DIR`、`OMP_NUM_THREADS`、`NANOCHAT_DTYPE` 都会改变结果或产物位置。检验：把命令原样粘贴到新终端能否得到同一产物路径。
> 2. 用脚本墙钟代替 `total_training_time`。前者含下载、评测与 SFT，后者只含训练步。检验：两者相减应约等于其余阶段耗时。
> 3. 在 dirty 工作区上做 A/B。`git_dirty_files` 非零时 commit 不能确定代码。检验：`git status --porcelain | wc -l`。
> 4. 把 CORE 的 0.003 差异当作有效。单次 CORE 的标准差约 0.005，低于 0.01 的差异落在噪声内。检验：同配置跑两次比较差值。
> 5. 只记 bpb 不记 CORE。bpb 改善但 CORE 不变的情形在仓库中有先例，只记一个指标会得出错误结论。检验：记录表中两个指标是否都有阈值判定。
> 6. 失败实验不写条件。缺少深度、token 预算与评测口径的失败记录无法复用，别人会在不同条件下重做并得到相反结论。检验：记录中是否有「假设」与「判定阈值」两段。

## 关联笔记

- 前置 [[用--depth调参]]：提供两套可执行配置与显存、时间的量级，本篇把这些量转成可比对的字段。
- 前置 [[跑通speedrun脚本]]：提供命令、产物路径与 CORE 的校验方法，本篇的记录直接引用这些产物。
- 后续 [[实验日志]]：本篇定义单次记录的格式，该篇是按周累积的实例。
- 对照 [[常见问题踩坑]]：本篇记录「为什么改」，该篇记录「为什么失败」的技术原因。
- 跨库 [[成本-延迟-质量权衡]]：通用原理见该篇，本篇只写 nanochat 中「质量指标」与「时间成本」的换算与判定阈值。

## 达标检测

- [ ] 能写出实验记录的九个字段，并说明每个字段缺失会导致哪种失败模式。
- [ ] 能给出一个可证伪的假设，包含变量、条件与判定阈值。
- [ ] 能解释为什么同 seed 不能保证逐位可复现，并指出代码中关闭确定性的那一行。
- [ ] 能列出五个必记指标及其 wandb key，说明 bpb 与 CORE 的噪声量级。
- [ ] 能由 bpb 的定义说明换分词器后 bpb 不可比的原因。
- [ ] 能设计一个 A/B：给出运行次数、判定阈值与 A/A 自检方法。
- [ ] 能按 `dev/LOG.md` 的结构写一条失败实验记录，标题包含方向。
- [ ] 能用 `meta_*.json` 的 `user_config` 生成配置 diff，并判断是否满足单变量条件。

## 参考来源

- Karpathy, *nanochat*（commit `92d63d4`），`dev/LOG.md` —— 对应失败实验的记录结构、动机与结论写法，以及多个 `(negative)` 条目的组织方式。
- Karpathy, *nanochat*（commit `92d63d4`），`scripts/base_train.py` 的 wandb 记录段与 `save_checkpoint` 的 meta 字段 —— 对应五个指标的 key、`user_config` 与 `total_training_time` 的口径。
- Karpathy, *nanochat*（commit `92d63d4`），`scripts/base_eval.py` 的 CSV 输出与 `README` 的 Research 一节 —— 对应 CORE 分解与「监控三组曲线」的建议。
- Karpathy, *nanochat* `dev/LEADERBOARD.md` —— 对应 time-to-GPT-2 的记录格式与可比性条件。
- Sculley et al., *Hidden Technical Debt in Machine Learning Systems*（NeurIPS 2014） —— 对应配置漂移、未记录的数据依赖与实验不可复现的成因。
- PyTorch documentation, *Reproducibility* —— 对应 `torch.manual_seed`、`use_deterministic_algorithms` 与 cuBLAS 非确定性的说明。
