---
tags: [nanochat, MOC, eval]
阶段: 08-评测Eval
难度: ★★☆
created: 2026-10-22
related: "[[评测方法论]], [[生成report成绩单]], [[如何解读指标]], [[CORE指标]]"
---

# MOC · 评测Eval

> [!summary] 本阶段地图
> 本阶段共 5 篇笔记，建议投入 9 至 11 小时。目标是建立一套可复算的评测口径：读完后能说清 base 模型与 chat 模型为何必须用两套评测、CORE/bpb/ChatCORE/pass@k/MBU 各自在回答什么问题、每个数字来自哪个脚本的哪一行输出，以及在小样本下这个数字的不确定度有多大。本阶段不重复 CORE 的完整推导（见 05 阶段的 [[CORE指标]]），只讲评测协议的分工、chat 侧任务的实现细节、成绩单的组装方式与指标解读的统计约束。

本阶段处在全书的中后段：向前依赖 05 的预训练产物与 06 的 SFT 产物，向后为 07 的 RL 与 10 的实验记录提供验收标准。它回答的问题可以压缩成一句：一个检查点训练出来之后，凭什么说它比上一个好。这个问题不能由 loss 曲线单独回答，因为 loss 只覆盖训练分布；也不能由单次人工对话回答，因为样本量为 1。评测方法论的作用是把「更好」拆成五个可测量、可复算、可比较的量，并为每个量标明适用边界。

```mermaid
flowchart LR
    A[评测方法论<br/>两类评测与五个指标] --> B[ARC与MMLU<br/>categorical 分支]
    A --> C[GSM8K与HumanEval<br/>generative 分支]
    B --> D[生成report成绩单<br/>多源产物汇总]
    C --> D
    D --> E[如何解读指标<br/>方差与口径冲突]
    A --> F[05 CORE指标<br/>base 侧完整推导]
    D --> G[10 实验记录模板]
    E --> H[09 KV Cache原理<br/>MBU 与解码代价]
```

图中实线是阅读依赖：categorical 与 generative 两条分支都建立在前一篇给出的「任务类型、判分函数、聚合方式」之上；成绩单消费两条分支的产物；解读指标消费成绩单里出现过的全部口径。指向阶段外的边是使用关系：05 的 [[CORE指标]] 讲解 22 任务与中心化的完整推导，本篇只标注两者在脚本层面的接口；09 的 [[KV Cache原理]] 解释 MBU 所在的解码机制，通用解码原理见 [[自回归生成与采样]]；10 的 [[实验记录模板]] 把本阶段的产物作为实验记录的必填字段。若尚未读 05，先读本篇的评测方法论与 CORE 小节即可继续，遇到推导再回补。

## 学习顺序与理由

1. [[评测方法论]]：先建立分类框架。它给出五个指标的定义、base 与 chat 两条评测流水线的差别、分布式聚合与可复现性约束，以及「指标—任务—脚本」对照表。先读它的理由是：没有这张表，后面三篇会各自孤立——不知道 CORE 与 ChatCORE 的基线约定不同，就会把 0.25 与 0 混用；不知道 `all_reduce` 与 `max_per_task` 的作用，就无法判断一次 8 卡评测与一次单卡快速评测的数字是否可比；不知道 `any(outcomes)` 的语义，就会把 `num_samples=1` 的结果误称为 pass@k。

2. [[ARC与MMLU]]：进入 categorical 分支。这两项任务不生成文本，而是在答案位置比较各字母 token 的 logits。先读它的理由是：`tasks/common.py` 的 `render_mc` 同时被 MMLU、ARC 以及 06 阶段的多选训练数据使用，「字母紧跟选项」这一格式约束是理解 chat 模型为何能用一个 token 作答的前提；同时 MMLU 已按 3 个 epoch 进入 SFT 数据混合，这一域内关系决定了该分数的解释边界。读完这一篇，应能解释「为什么评测不需要模型会写完整句子，却要求模型在训练时见过同样的字母 token」。

3. [[GSM8K与HumanEval]]：进入 generative 分支。这两项任务先生成再判分，判分依赖答案抽取或外部执行器。放在第三位的理由是：它复用前两篇的 ChatCORE 基线与聚合公式，同时引入新的失败来源（生成长度截断、答案抽取失败、沙箱超时或内存超限），这些来源在 categorical 分支中不存在。读完这一篇，应能解释「同一份模型输出，为什么在 `temperature=0` 与 `temperature=1.0` 下通过率不同」。

4. [[生成report成绩单]]：把前三篇的产物汇总。它读取 `base_eval` 的 CSV、`chat_eval` 的 stdout、`infer_bench` 的末行 JSON 与 checkpoint 的 `meta_*.json`，生成一张 Markdown 表。放在第四位的理由是：只有先知道每个任务的判分与聚合方式，才知道哪些数字可以并列、哪些必须标注缺失；也只有先知道 CSV 的列宽与空列格式，才能写出不会静默丢行的解析器。

5. [[如何解读指标]]：最后处理统计与判断。它给出二项标准误、CORE 的运行间波动、bpb 的跨数据不可比性、指标冲突的实例，以及「指标—可信度—适用场景—陷阱」表。放在最后的理由是：它需要前四篇已经给出每个指标的协议与样本量，否则无法计算不确定度。读完这一篇，应能对「CORE 0.2585 比 0.2565 好」这类陈述给出一个带前提的判断，而不是一个结论。

不建议把顺序调换为「先看 leaderboard 再读方法论」。README 的排行榜只给 `time`、`val_bpb`、`CORE` 三列，没有样本量、没有 ChatCORE、没有推理代价；先读排行榜会得到「CORE 越大越好」的单指标直觉，而这正是本阶段要纠正的。也不建议把 [[如何解读指标]] 提前：在没有协议细节时，方差讨论会退化为「多跑几次」的空泛建议，而具体的重复次数取决于指标方差与待检测的效应大小。

## 阅读投入与检查点

下表给出一种可行的投入分配。检查点的判据是「能否在不看笔记的情况下写出对应产物或公式」，而不是「是否读完」。

| 次序 | 笔记 | 建议用时 | 完成检查点 |
|---|---|---|---|
| 1 | [[评测方法论]] | 2.5 至 3 小时 | 写出五个指标的定义式与三条聚合路径的 `all_reduce` 归约对象 |
| 2 | [[ARC与MMLU]] | 1.5 至 2 小时 | 手算一次字母 logits 的 argmax，并写出 `render_mc` 的完整输出 |
| 3 | [[GSM8K与HumanEval]] | 2 至 2.5 小时 | 写出 GSM8K 抽取正则与 HumanEval 程序的四段拼接顺序 |
| 4 | [[生成report成绩单]] | 1.5 小时 | 用合成产物跑通汇总脚本，得到一张含五个小节的 Markdown 表 |
| 5 | [[如何解读指标]] | 2 小时 | 算出 $n=164$、$p=0.25$ 的标准误与置信区间，并写出一个指标冲突实例 |

合计约 9.5 至 11 小时。若只有半天时间，最小路径是 1、2、5：先建立两类评测的分工，再理解 categorical 的判分机制，最后知道单次分数的可信边界；生成式评测与成绩单可以留到需要交报告时再补。


## 笔记索引

| 笔记 | 难度 | 核心问题 | 读完应能 | 关键 repo 位置 |
|---|---|---|---|---|
| [[评测方法论]] | ★★★ | base 与 chat 两类评测如何分工，五个指标各自测什么 | 说清 ICL 续写打分与生成后判分的差别；写出 centered 公式与 bpb 公式；解释 `all_reduce`、`max_per_task`、seed 的作用 | `nanochat/core_eval.py`、`scripts/base_eval.py`、`scripts/chat_eval.py`、`nanochat/loss_eval.py` |
| [[ARC与MMLU]] | ★★☆ | 多选任务如何在不生成文本的情况下判分 | 逐段解释 `run_categorical_eval` 的批量拼装与答案位置；手算一次字母 argmax；说明为何这种口径更宽容 | `tasks/arc.py`、`tasks/mmlu.py`、`tasks/common.py` 的 `render_mc`、`scripts/chat_eval.py` |
| [[GSM8K与HumanEval]] | ★★★ | 生成式任务如何抽取答案与执行判分 | 写出 GSM8K 的 `####` 抽取规则；复述 HumanEval 的程序拼接与 `execute_code` 判据；说明 `any()` 与 pass@k 的差距 | `tasks/gsm8k.py`、`tasks/humaneval.py`、`nanochat/execution.py`、`scripts/chat_eval.py`、`scripts/chat_rl.py` |
| [[生成report成绩单]] | ★★☆ | 仓库没有 `report.py` 时如何组装成绩单 | 列出四类产物与字段；运行汇总脚本生成 Markdown；说明 wandb 与本地 CSV 的分工 | `scripts/base_eval.py`、`scripts/chat_eval.py`、`scripts/infer_bench.py`、`nanochat/checkpoint_manager.py` |
| [[如何解读指标]] | ★★★ | 单个数字能支持多强的结论 | 计算二项标准误与置信区间；解释 CORE 0.256525 的含义与运行间波动；识别指标冲突 | `dev/LEADERBOARD.md`、`dev/LOG.md`、`scripts/chat_eval.py` 的基线字典 |

五篇之间的接口是四个可核对的对象，而不是概念上的引用。

第一，CORE 的 CSV。[[评测方法论]] 说明 `scripts/base_eval.py` 在 `ddp_rank == 0` 时写入 `base_eval/base_model_{step:06d}.csv`，[[ARC与MMLU]] 与 [[GSM8K与HumanEval]] 不消费它，[[生成report成绩单]] 解析它并保留每个任务的三列。因此该文件的列格式（含空白的 `Accuracy` 列）是跨篇契约。

第二，ChatCORE 的五个准确率。[[评测方法论]] 给出聚合公式，[[ARC与MMLU]] 给出前三个任务的判分，[[GSM8K与HumanEval]] 给出后两个任务的判分，[[生成report成绩单]] 把五个数与基线一并列出。任一任务的评测缺失时，`scripts/chat_eval.py` 不打印总分，成绩单必须显示「未测」而不是用部分均值代替。

第三，推理 JSON。只有 [[生成report成绩单]] 与 [[如何解读指标]] 消费它：前者取 `ttft_sec`、`tpot_sec`、`tok_per_sec`、`mbu_percent`、`peak_vram_bytes`，后者解释这些量与 CORE 不构成同一维度，不能用「智能/成本」的单一比值替代。

第四，`meta_*.json`。[[生成report成绩单]] 从中读取 `model_config`、`val_bpb`、`loop_state.total_training_time`；[[如何解读指标]] 用它说明同一模型不同 step 的分数不可混报。该文件由 `nanochat/checkpoint_manager.py` 的 `save_checkpoint` 写入，字段名是成绩单脚本的另一半契约。

本阶段不重复通用评估理论。混淆矩阵、交叉验证、评分器分类等内容见 [[模型评估矩阵]]；区间估计与假设检验的数学基础见 [[概率与统计]]。本库只写 nanochat 的取值、代码位置与工程后果。

## 阶段产物地图

本阶段的全部数字都来自四条命令的产物。命令与产物的对应关系如下，任何成绩单都必须能回溯到其中一条。

```bash
# 1) base：CORE + bpb + 采样；CORE 分项写入 base_eval/base_model_{step:06d}.csv
OMP_NUM_THREADS=1 torchrun --standalone --nproc_per_node=8 -m scripts.base_eval -- \
    --model-tag=d24 --eval=core,bpb

# 2) chat：一次跑全 5 个任务，ChatCORE 只在 5 个任务都完成时打印
OMP_NUM_THREADS=1 torchrun --standalone --nproc_per_node=8 -m scripts.chat_eval -- \
    -i sft -a 'ARC-Easy|ARC-Challenge|MMLU|GSM8K|HumanEval' | tee chat_eval_sft.log

# 3) 推理：最后一行是单行 JSON，其余是人类可读表格
python -m scripts.infer_bench -i sft -g d24 | tee infer_bench.log

# 4) 读取训练元数据：checkpoint 目录下的 meta_{step:06d}.json
ls ~/.cache/nanochat/base_checkpoints/d24/meta_*.json
```

| 产物 | 生成者 | 默认位置 | 主要字段 | 消费方 |
|---|---|---|---|---|
| CORE CSV | `base_eval.py` | `~/.cache/nanochat/base_eval/base_model_{step:06d}.csv` | 每任务 `Accuracy`、`Centered`，末行 `CORE` | 成绩单脚本、`dev/estimate_gpt3_core.ipynb` |
| bpb | `base_eval.py` | stdout 的 `train bpb`、`val bpb` | 两个浮点数 | 成绩单、leaderboard |
| ChatCORE | `chat_eval.py` | stdout 的 `ChatCORE metric` | 一个浮点数与 5 个准确率 | 成绩单 |
| 推理 JSON | `infer_bench.py` | stdout 最后一行 | `prefill`、`sweep`、`num_params`、`weight_bytes` | 成绩单、部署成本估算 |
| 训练元数据 | `base_train.py` / `chat_sft.py` | `meta_{step:06d}.json` | `model_config`、`val_bpb`、`loop_state` | 成绩单 |

路径中的根目录由 `nanochat/common.py` 的 `get_base_dir` 决定：默认是 `~/.cache/nanochat`，可用环境变量 `NANOCHAT_BASE_DIR` 覆盖。表中的 `{step:06d}` 是六位补零的 step，例如 16704 写作 `016704`。

四条命令的参数并非全部等价可换。下表列出本阶段会用到的参数与改动后的后果，便于在复现他人结果时定位口径差异。

| 命令 | 参数 | 作用 | 改动后的后果 |
|---|---|---|---|
| `base_eval` | `--eval=core,bpb,sample` | 选择要跑的评测子集 | 只跑 `bpb` 时不写 CSV；只跑 `core` 时没有 bpb 对照 |
| `base_eval` | `--max-per-task=500` | 每任务最多评测条数 | 改变 few-shot 采样池，结果不是全量均值 |
| `base_eval` | `--model-tag` / `--step` | 指定检查点 | 缺省时按 `d<数字>` 最大者与最后 step 猜测，易评错模型 |
| `base_eval` | `--split-tokens=40*524288` | bpb 的评测 token 数 | 调小后 bpb 方差变大，跨运行比较不可靠 |
| `chat_eval` | `-i sft` 或 `-i rl` | 选择 chat 检查点来源 | 指向错误目录时评的是另一个训练阶段 |
| `chat_eval` | `-a` 任务名列表 | 任务子集，多个任务名以竖线分隔 | 少于 5 个任务时不打印 ChatCORE |
| `chat_eval` | `-t 0`、`-n 1`、`-m 512` | 温度、采样数、最大新 token | 温度大于 0 时结果依赖采样，跨运行复现性下降；`-n>1` 时准确率变为 any 口径 |
| `chat_eval` | `-b 8` | categorical 批大小 | 只影响速度与显存，不改变判分 |
| `chat_eval` | `-x` | 每题上限 | 用于快速估计，结果方差大 |
| `infer_bench` | `-i base`、`-g d12` | 模型来源与标签 | 与 ChatCORE 不是同一检查点时不能并列 |
| `infer_bench` | `--prompt-tokens` / `--decode-tokens` | 上下文与生成长度 | 超出 `sequence_len` 时提示被截断并打印提示 |
| `infer_bench` | `--batch-sizes` | 批扫描点 | MBU 随批大小变化，只报单点会误导 |

## 评测流程时序

本阶段的数据流是单向的：训练脚本写出检查点与元数据，三个评测脚本各自读检查点、各自写产物，成绩单脚本只读产物、不回写。下面的时序图把这一顺序固定下来，任何一步的顺序颠倒都会导致成绩单引用旧产物。

```mermaid
sequenceDiagram
    participant T as base_train 或 chat_sft
    participant B as scripts.base_eval
    participant C as scripts.chat_eval
    participant I as scripts.infer_bench
    participant F as 本地文件与 stdout
    T->>F: 写出 meta_016704.json 与检查点
    B->>F: 写出 base_eval/base_model_016704.csv
    B-->>T: 打印 train bpb 与 val bpb
    C-->>T: 打印 5 个准确率与 ChatCORE
    I-->>T: 末行打印 prefill 与 sweep 的 JSON
    Note over F: 成绩单脚本读取以上四类产物
```


## 符号约定与关键事实

| 事实 | 取值 | 可核对位置 |
|---|---|---|
| CORE 任务数 | 22 项 ICL 任务，等权平均 | `core.yaml` 的 `icl_tasks`；`dev/estimate_gpt3_core.ipynb` |
| GPT-2 CORE 门槛 | 0.256525 | README、`dev/LEADERBOARD.md` |
| centered accuracy | $c=(a-0.01b)/(1-0.01b)$，$b$ 为百分数 | `scripts/base_eval.py` 的 `evaluate_core` |
| bpb | $\mathrm{bpb}=\sum\text{nats}/(\ln2\cdot\sum\text{bytes})$ | `nanochat/loss_eval.py` 的 `evaluate_bpb` |
| ChatCORE | 5 任务 centered accuracy 的均值 | `scripts/chat_eval.py` 末尾、`scripts/chat_sft.py` 的 ChatCORE 段 |
| ChatCORE 基线 | ARC 两项、MMLU 为 0.25；GSM8K、HumanEval 为 0 | `scripts/chat_eval.py` 的 `baseline_accuracies` |
| chat 生成默认值 | `max_new_tokens=512`、`temperature=0.0`、`top_k=50`、`num_samples=1` | `scripts/chat_eval.py` 的 `run_chat_eval` |
| categorical 判据 | 只比较答案位置处各候选字母的 logits，字母必须为单 token | `scripts/chat_eval.py` 的 `run_categorical_eval` |
| HumanEval 沙箱 | 5 秒超时、256 MB rlimit、`returncode==0` 判成功 | `nanochat/execution.py` 的 `execute_code` |
| MBU | $100\cdot\frac{w+B\cdot \text{kv\_read}}{\text{tpot}}\big/\text{peak\_bw}$ | `scripts/infer_bench.py` |
| MMLU 学科数 | 57 个 `groups` | `tasks/mmlu.py` 的 `groups` 元组 |
| 目录约定 | 默认 `~/.cache/nanochat`，可用 `NANOCHAT_BASE_DIR` 覆盖 | `nanochat/common.py` 的 `get_base_dir` |

符号说明：$a$ 为原始准确率，$b$ 为随机基线百分数，$c$ 为中心化准确率；$w$ 为权重字节数，$B$ 为解码批大小，$\text{tpot}$ 为每输出 token 时间，$\text{peak\_bw}$ 为 GPU 峰值带宽。表中「22 项」「0.256525」等数字的具体推导见 [[CORE指标]] 与 [[对比GPT-2核心指标]]。

ChatCORE 的聚合公式只有一行，可用最小复现核对数值：

```python
# 与 scripts/chat_eval.py 的 baseline_accuracies 一致；此处为演示用假设准确率
baselines = {"ARC-Easy": 0.25, "ARC-Challenge": 0.25, "MMLU": 0.25,
             "GSM8K": 0.0, "HumanEval": 0.0}
accs = {"ARC-Easy": 0.40, "ARC-Challenge": 0.28, "MMLU": 0.30,
        "GSM8K": 0.10, "HumanEval": 0.05}
centered = {k: (accs[k] - b) / (1.0 - b) for k, b in baselines.items()}
print({k: round(v, 4) for k, v in centered.items()})
# 预期：{'ARC-Easy': 0.2, 'ARC-Challenge': 0.04, 'MMLU': 0.0667, 'GSM8K': 0.1, 'HumanEval': 0.05}
print(round(sum(centered.values()) / len(centered), 4))   # 预期：0.0913
```

五个指标的分工可用一张速查表记住，细节均在各篇展开，此处只标出「基线」与「产物」两个最容易记错的字段。

| 指标 | 一句话 | 随机基线 | 产物 | 详见 |
|---|---|---|---|---|
| CORE | base 的 22 项 ICL 中心化均值 | 每任务不同，见 `eval_meta_data.csv` | `base_eval/base_model_{step:06d}.csv` | [[评测方法论]]、[[CORE指标]] |
| bpb | 每字节所需比特数 | 无 | stdout | [[评测方法论]] |
| ChatCORE | 5 项 chat 任务中心化均值 | 0.25 与 0 | stdout | [[评测方法论]]、[[如何解读指标]] |
| pass@k | 至少一个解通过的比例 | 0 | stdout 与 wandb | [[GSM8K与HumanEval]] |
| MBU | 解码带宽利用率 | 无 | 末行 JSON | [[生成report成绩单]]、[[KV Cache原理]] |


## 术语中英对照

| 中文 | 英文 | 本库用法 |
|---|---|---|
| 上下文学习 | in-context learning | base 侧 22 项任务的核心形式 |
| 续写 | continuation | 分隔符之后、参与打分的文本片段 |
| 中心化准确率 | centered accuracy | 减去随机基线再除以剩余空间 |
| 每字节比特数 | bits per byte | 与词表无关的压缩率 |
| 分类式评测 | categorical evaluation | 只比较答案位置字母 logits |
| 生成式评测 | generative evaluation | 采样后用抽取或执行器判分 |
| 通过率 | pass@k | 至少一个解通过的比例 |
| 模型带宽利用率 | model bandwidth utilization | 解码实测搬移字节与峰值带宽之比 |
| 数据污染 | contamination | 评测样本进入训练语料 |
| 少样本 | few-shot | 提示中给出的示例数 $k$ |
| 子采样 | subsampling | `max_per_task` 的截断行为 |

## 与相邻阶段的边界

本阶段与 05、06、07、09、10 的边界必须写清，否则会出现重复讲解与口径漂移。

| 相邻阶段 | 本阶段负责 | 相邻阶段负责 |
|---|---|---|
| 05 预训练 | 评测协议的脚本接口与产物格式 | CORE 的 22 任务构成、续写边界、中心化推导、leaderboard 读法 |
| 06 SFT | ChatCORE 的聚合与统计解释 | 对话模板、`render_conversation` 的 mask、MMLU 与 GSM8K 如何进入训练混合 |
| 07 RL | 生成式评测的判分函数与 pass@k 口径 | REINFORCE 推导、reward 的定义、RL 训练循环与 rollout 采样 |
| 09 推理 | MBU 的定义与成绩单位置 | KV Cache 的形状、prefill/decode 的 roofline、工具调用状态机 |
| 10 复现 | 实验记录中应填的评测字段 | 环境搭建、speedrun 全流程、故障树 |

边界的判据是「是否出现新公式」。CORE 的中心化公式在 05 已完整推导，本阶段只引用；pass@k 的无偏估计量在 07 才被用于训练选择，本阶段只给出两种口径的差别；MBU 的字节账在 09 才展开，本阶段只把它作为成绩单的一列。

## 本阶段不覆盖的内容

以下三类评测不在本阶段范围内。列出它们的目的不是留待后续，而是界定本阶段结论的适用边界。

第一，安全与越狱评测。nanochat 的 chat 训练数据是 SmolTalk 与少量任务数据，没有安全对齐目标，也没有红队集；因此本阶段的任何分数都不能解释为「模型安全」。相关通用方法见 [[模型评估矩阵]] 与 [[幻觉与缓解]]。

第二，长上下文与检索评测。`sequence_len` 默认为 2048，CORE 与 ChatCORE 的提示都在该长度内构造；超过该长度的能力没有对应脚本，`infer_bench` 也会把提示截断到 `sequence_len - decode_tokens` 并在截断时打印提示。

第三，人工评估与偏好比较。仓库没有人工评分流程，`chat_cli` 只用于单次对话观察；对话质量只能由 5 个自动任务近似，而自动任务与人类偏好的相关性未在仓库中测量。这一缺口在 [[如何解读指标]] 中作为「指标冲突」的来源之一处理。

## 各篇验收问题

每篇读完后先回答下列问题，答不出就回到对应小节。问题只用文字与数值回答，不要求背代码。

[[评测方法论]]：base 与 chat 的判分分别发生在生成的哪个阶段；五个指标的基线各是什么；`all_reduce` 在 CORE、bpb、生成式三处分别归约什么量；`max_per_task` 为什么改变结果的含义；评测侧的哪一部分本质上不可复现。

[[ARC与MMLU]]：`render_mc` 为什么要求字母紧跟 `=`；`answer_time_positions` 为什么是 `len(ids) - 1`；字母 token 缓存为什么可以复用；为什么只比较字母 logits 比生成字母更宽容；ARC 的基线 0.25 在选项数不固定时意味着什么。

[[GSM8K与HumanEval]]：GSM8K 的答案抽取正则接受哪些字符；为什么 `10` 与 `10.0` 判为不等；HumanEval 的 `extract_imports` 从哪里取 import；程序拼接的四段顺序；5 秒超时与 256 MB 限制分别会把哪类正确解判错；`any()` 与无偏 pass@k 的差别。

[[生成report成绩单]]：仓库为什么没有 `report.py`；CSV 的 `CORE` 行为什么有一列空白；`chat_eval` 的 ChatCORE 在什么条件下不打印；`infer_bench` 的机器可读结果在第几行；wandb 与本地 CSV 各保存什么；成绩单中哪些单元格在缺产物时必须写「未测」。

[[如何解读指标]]：CORE 0.256525 的来源与复算条件；同一命令 7 次运行的极差；$n=164$ 与 $n=14042$ 的标准误差多少倍；为什么 bpb 换数据后不可比；CORE 高而对话差的两个机制；报告一个分数时必须附带的四项信息。

## 故障定位索引

下表按「症状」索引到最可能的原因与检查位置。它不替代各篇的易错点，只用于从异常现象快速回到协议层。

| 症状 | 最可能的原因 | 检查位置 |
|---|---|---|
| CSV 末行不等于上方各任务 Centered 的均值 | 解析时漏行，或把表头当作任务 | 行数与任务名，尤其 `CORE` 行的空列 |
| `chat_eval` 没有打印 ChatCORE | 5 个任务未全部评测 | `-a` 的任务列表与每条 `accuracy` 行 |
| HumanEval 准确率恒为 0 | 代码块围栏缺失、执行超时或测试失败 | 生成文本是否含三反引号；`execute_code` 的 `timeout` 与 `stderr` |
| GSM8K 准确率恒为 0 | 未生成 `####`，或数值格式不同 | `max_new_tokens` 是否截断；抽取正则与字符串比较 |
| 评测 CORE 低于训练中记录 | 评测精度、子采样或 tokenizer 不一致 | 是否 `disable_fp8`；`max_per_task`；词表大小断言 |
| bpb 与上一次不可比 | 预训练数据分布改变 | 数据 shard 版本与 split |
| `infer_bench` 直接报错 | 非 CUDA、多卡或提示超出上下文 | 脚本内的 `assert` 与 `sequence_len` |
| 成绩单任务名与仓库不一致 | eval bundle 的 `label` 变化 | `core.yaml` 的 `icl_tasks` 与 CSV 首列 |

## 达标清单

- [ ] 能写出 base 评测与 chat 评测的完整命令，并说明每条命令的产物落在哪个文件或 stdout 的哪一行。
- [ ] 能区分 CORE、bpb、ChatCORE、pass@k、MBU 五个指标的度量对象，并为每个指标写出定义式。
- [ ] 能解释 centered accuracy 中 $b$ 为何以百分数存储、代码为何乘 0.01，并手算 5 任务 ChatCORE 得到 0.0913。
- [ ] 能说明 `run_categorical_eval` 为什么不生成文本，以及 `answer_time_positions` 的取值依据。
- [ ] 能复述 HumanEval 的程序拼接顺序与 `execute_code` 的成功判据，并指出 5 秒超时对通过率的影响方向。
- [ ] 能解释 `any(outcomes)` 在 `num_samples>1` 时等价于哪种 pass@k，并说明它与无偏估计量的差别。
- [ ] 能计算 $n=164$、$p=0.25$ 时的二项标准误与 95% 置信区间，并据此判断两个 HumanEval 分数的差异是否可信。
- [ ] 能从 `base_eval` CSV、`chat_eval` 日志与 `infer_bench` JSON 组装一张成绩单，并标注每个单元格的来源。
- [ ] 能指出「CORE 高但对话质量差」的两个具体机制，并给出至少一项补充证据。
- [ ] 能说明 `meta_*.json` 中哪三个字段进入成绩单，以及缺少 `loop_state.total_training_time` 时成本一栏应如何标注。

## 参考来源

- Karpathy, *nanochat* README（commit 92d63d4），Time-to-GPT-2 Leaderboard 与 File structure —— 对应本阶段地图、0.256525 门槛与三类评测脚本的位置。
- Karpathy, *nanochat* `scripts/base_eval.py`、`scripts/chat_eval.py`、`scripts/infer_bench.py`（commit 92d63d4）—— 对应本阶段五个指标的命令与产物。
- DCLM 团队, *DataComp-LM: In search of the next generation of training sets for language models*（2406.11794）—— 对应 CORE 指标与中心化基线。
- Karpathy, *nanochat* `tasks/common.py`、`tasks/arc.py`、`tasks/mmlu.py`、`tasks/gsm8k.py`、`tasks/humaneval.py`（commit 92d63d4）—— 对应本阶段五项任务的数据字段与判分函数。
- Karpathy, *nanochat* `dev/LEADERBOARD.md`（commit 92d63d4），Run 1 至 Run 6 —— 对应成绩单字段与运行间波动的实例。
