---
tags: [nanochat, pretraining, eval]
阶段: 05-预训练Pretraining
难度: ★★★
created: 2026-10-22
related: "[[对比GPT-2核心指标]], [[评测方法论]], [[如何解读指标]], [[模型评估矩阵]]"
---

# CORE指标

## 定义

**CORE**（DCLM 论文提出的复合指标，全称沿用论文中的写法，不作展开）是 base 语言模型在 22 个上下文学习（in-context learning，ICL）任务上的**中心化准确率**的算术平均：每个任务的原始准确率先减去随机猜测基线、再除以剩余的可得分空间，最后对 22 个任务等权平均。

符号定义如下。

- 任务索引 $i=1,\dots,K$，$K$ 为 `core.yaml` 中 `icl_tasks` 列表长度；仓库文档与 `dev/estimate_gpt3_core.ipynb` 记作 $K=22$。
- $a_i\in[0,1]$：任务 $i$ 上的原始准确率，即 `evaluate_task` 返回的 `mean_correct`。
- $b_i$：任务 $i$ 的随机猜测基线，以百分数表示（例如四选一任务为 25），来自 eval bundle 的 `eval_meta_data.csv` 中 `Random baseline` 列。
- $p_i=b_i/100$：基线的概率形式。
- $c_i$：任务 $i$ 的中心化准确率，$c_i=\dfrac{a_i-p_i}{1-p_i}$。
- **CORE 分数**：$\mathrm{CORE}=\dfrac{1}{K}\sum_{i=1}^{K}c_i$。等权，不按样本数加权。
- **ICL 任务**：模型不更新参数，仅凭提示中给出的若干示例（few-shot）与任务描述，直接对候选续写打分或生成答案的任务形式。
- **续写**（continuation）：多选与 schema 任务中位于 `continuation_delimiter` 之后、用于判别的文本片段；语言建模任务中是待预测的整段尾文。
- **$k$-shot**：提示中提供的示例数量 $k$，取自 `core.yaml` 中 `num_fewshot` 列表的首元素。
- **bpb**（bits per byte）：另一套指标，$\mathrm{bpb}=\dfrac{\sum \text{nats}}{\ln 2\cdot\sum \text{bytes}}$，衡量逐 token 预测换算到逐字节的压缩率。

## 为什么重要

CORE 解决的是「不同模型之间如何比较能力」这一具体问题。val loss 与 bpb 衡量的是模型在同一条数据分布上的平均预测质量，一旦更换数据集（例如 FineWeb-EDU 换成 ClimbMix）、更换词表、或改变模型结构，数值就不再可比。CORE 把评测固定为一组任务、一套提示模板、一套打分规则，因而可以在不同数据、不同架构、不同训练时长之间比较。

它是 nanochat 预训练阶段唯一的外部验收标准：leaderboard 的「time-to-GPT-2」定义为在 8×H100 上把 CORE 训练到超过 0.256525 所需的墙钟时间（`dev/LEADERBOARD.md`、README）。没有这个阈值，speedrun 就只是「训练了一个模型」，无法回答「是否达到 GPT-2 级」。

它也是诊断工具：22 个任务的分项分数保存在 `base_eval/base_model_{step}.csv`，可以定位模型在哪一类能力上落后（世界知识、语言理解、常识、符号推理、阅读理解），而不是只知道一个总分。

在三个维度中，本篇属于「懂原理」与「懂工程」的交界：原理部分是三类任务的打分规则与中心化公式，工程部分是 few-shot 采样、token 边界对齐与分布式聚合的细节。

## 原理与推导

### 1. eval bundle 的三个组成部分

评测数据不打散在仓库里，而是以 zip 包形式从固定 URL 下载并解压到 `~/.cache/nanochat/eval_bundle`（`scripts/base_eval.py` 的 `EVAL_BUNDLE_URL` 与 `place_eval_bundle`）。解压后有三个部分。

| 路径 | 内容 | 作用 |
|---|---|---|
| `core.yaml` | `icl_tasks` 列表，每项含 `label`、`icl_task_type`、`dataset_uri`、`num_fewshot`、`continuation_delimiter` | 决定评哪些任务、怎么评 |
| `eval_data/*.jsonl` | 每个任务一个 JSONL，字段含 `query`、`choices`、`gold`、`context`、`continuation` 等 | 任务样本 |
| `eval_meta_data.csv` | `Eval Task` 与 `Random baseline` 两列 | 中心化所需的基线 |

`scripts/base_eval.py` 的 `evaluate_core` 把这些拼起来：

```python
config_path = os.path.join(eval_bundle_dir, "core.yaml")
data_base_path = os.path.join(eval_bundle_dir, "eval_data")
eval_meta_data = os.path.join(eval_bundle_dir, "eval_meta_data.csv")
with open(config_path, 'r', encoding='utf-8') as f:
    config = yaml.safe_load(f)
tasks = config['icl_tasks']
# 读取随机基线：值是百分数，例如 25 表示 25%
random_baselines = {}
with open(eval_meta_data, 'r', encoding='utf-8') as f:
    reader = csv.DictReader(f)
    for row in reader:
        random_baselines[row['Eval Task']] = float(row['Random baseline'])
for task in tasks:
    task_meta = {
        'task_type': task['icl_task_type'],
        'dataset_uri': task['dataset_uri'],
        'num_fewshot': task['num_fewshot'][0],
        'continuation_delimiter': task.get('continuation_delimiter', ' '),
    }
    ...
    accuracy = evaluate_task(model, tokenizer, data, device, task_meta)
    centered = (accuracy - 0.01 * random_baselines[label]) / (1.0 - 0.01 * random_baselines[label])
```

注意两个约定：`num_fewshot` 是列表，代码只取第 0 项；`continuation_delimiter` 缺省为单个空格，部分任务显式指定为换行。

### 2. 三类任务与打分方式

`nanochat/core_eval.py` 的 `evaluate_example` 按 `task_type` 分三支，三支的判别对象不同。

第一类 **multiple_choice**：各候选共享同一段上下文，只有选项文本不同，因此完整提示的公共前缀就是上下文，公共前缀之后是续写。用 `find_common_length(tokens, direction='left')` 找到公共前缀长度 $s$，每条提示的终点 $e$ 为其 token 长度。打分取续写区间上的平均损失：

$$
\ell_j=\frac{1}{e_j-s}\sum_{t=s-1}^{e_j-2}\mathrm{CE}_t,\qquad \hat j=\arg\min_j \ell_j
$$

其中 $\mathrm{CE}_t$ 是位置 $t$ 对第 $t+1$ 个 token 的交叉熵，代码用 `losses[i, si-1:ei-1]` 取这一段——因为位置 $t$ 的损失预测的是 $t+1$，所以「预测续写 $[s,e)$」对应损失下标 $[s-1,e-1)$，区间长度恰为 $e-s$。预测正确当且仅当 $\hat j$ 等于 `item['gold']`。

第二类 **schema**：各候选的上下文不同、续写相同，因此公共部分是后缀。用 `direction='right'` 找公共后缀长度 $L$，起点 $s_j=e_j-L$。

第三类 **language_modeling**：渲染两条提示，一条不含续写、一条含续写；先断言前者是后者的 token 前缀，再用断言得到的边界 $(s,e)$ 逐 token 比较贪心预测与实际 token，要求全匹配：

```python
if task_type == 'language_modeling':
    si = start_idxs[0]           # 不含续写的提示长度
    ei = end_idxs[0]             # 含续写的提示长度
    predicted_tokens = predictions[0, si-1:ei-1]   # 位置 t 预测 t+1
    actual_tokens = input_ids[0, si:ei]
    is_correct = torch.all(predicted_tokens == actual_tokens).item()
```

这一支没有「概率」成分，只有 argmax 是否逐 token 命中，因此对分词边界敏感。

三类任务的公共准备是 `forward_model`：整批前向一次，用 `torch.roll(input_ids, shifts=-1, dims=1)` 得到自回归目标，逐位置算交叉熵，并把最后一列置为 `nan`（没有下一个 token 可预测）。批内序列右侧用 BOS 补齐（`pad_token_id = tokenizer.get_bos_token_id()`）——补在右侧意味着补齐位不会进入任何 `[s-1,e-1)` 区间，这是选择 BOS 而不是 0 作为 pad 的原因：代价仅是浪费一点算力，不改变判定。

### 3. few-shot 采样与数据顺序

`evaluate_example` 为每个样本现场抽 $k$ 个示例：

```python
if num_fewshot > 0:
    rng = random.Random(1234 + idx)
    available_indices = [i for i in range(len(data)) if i != idx]
    fewshot_indices = rng.sample(available_indices, num_fewshot)
    fewshot_examples = [data[i] for i in fewshot_indices]
```

三个性质由此确定：种子是 `1234 + idx`，同一 idx 无论何时运行都得到同一组示例；候选池排除了自身，避免答案泄漏；候选池的大小是 `len(data)`，因此当 `--max-per-task` 截断数据时，抽样空间随之改变。

数据在评测前先整体打乱：

```python
shuffle_rng = random.Random(1337)
shuffle_rng.shuffle(data)
if max_per_task > 0:
    data = data[:max_per_task]
```

seed 1337 使「全量评测」与「固定子集评测」在同一次运行内可复现；但 `max_per_task` 改变的不只是样本数，还改变了 few-shot 的候选池，因此 `--max-per-task=500` 的结果不是全量结果的子集平均值，两者存在系统性小偏差。这一点在 `base_train.py` 的默认配置中直接可见：训练中每 2000 步用 `--core-metric-max-per-task=500` 做快速估计，最终评测则用 `-1`（全量）。

### 4. 中心化与等权平均

中心化的动机是让「随机猜测也能得分」的部分不进入比较。四选一任务的随机基线是 25%，答对 50% 与二选一任务答对 50% 显然不是同一水平；减去基线并除以剩余空间后，两者都被映射到「超出随机的比例」。

代入定义：

$$
c_i=\frac{a_i-p_i}{1-p_i},\qquad p_i=\frac{b_i}{100}.
$$

性质有三条。第一，$a_i=p_i$ 时 $c_i=0$，随机水平归一为零。第二，$a_i=1$ 时 $c_i=1$，满分归一为一。第三，$1-p_i$ 是缩放因子：$p_i$ 越大，同样的准确率提升换算成 $c_i$ 的增量越大。语言建模任务的基线为 0（要逐 token 全匹配，随机猜测的命中率可视为零），此时 $c_i=a_i$。

总分是 22 个 $c_i$ 的算术平均。每个任务权重相同，与任务样本数无关：一个只有数百条样本的任务与一个有数千条样本的任务对 CORE 的贡献相同。

### 5. 22 个任务的构成

`dev/estimate_gpt3_core.ipynb` 按能力类别列出了 22 项任务，与 `dev/LEADERBOARD.md` 的「over 22 evaluations」一致。

| 类别 | 任务 |
|---|---|
| 世界知识 | Jeopardy、ARC Easy、ARC Challenge、BigBench QA Wikidata |
| 语言理解 | HellaSwag（0-shot 与 10-shot 各一项）、LAMBADA、Winograd、Winogrande、BigBench Language ID |
| 常识推理 | COPA、CommonsenseQA、PIQA、OpenBookQA |
| 符号问题求解 | BigBench Dyck、Operators、CS Algorithms、Repeat Copy Logic、AGI Eval LSAT-AR |
| 阅读理解 | SQuAD、CoQA、BoolQ |

计数为 $4+6+4+5+3=22$。实际任务清单与顺序以 bundle 中 `core.yaml` 的 `icl_tasks` 列表为准：本地源码快照不包含 eval bundle（它在首次评测时下载），因此任务名与 shot 数不能凭记忆写死。

### 6. 与 bpb 的区别

两者回答不同的问题。bpb 是压缩率：模型对验证集每个字节平均分配多少比特，$\mathrm{bpb}=\sum\text{nats}/(\ln 2\cdot\sum\text{bytes})$，由 `nanochat/loss_eval.py` 的 `evaluate_bpb` 计算，特殊 token 与 mask 掉的 token 不计入字节数。它是连续的、低方差的，适合在训练中每 250 步监控。

CORE 是任务准确率，衡量的是「看了几个示例后能否照做」，即 ICL 能力。它离散、方差大（`dev/LOG.md` 记录同一配置 7 次独立运行的极差为 0.01646），而且只覆盖 22 个固定任务，存在被针对性训练的风险。

两者的关系不是单调映射：数据分布变化会显著改变 bpb 而 CORE 仍可比（`dev/LEADERBOARD.md` Run 4 明确指出该次 `val_bpb` 因换数据而不可与前几次比较）；反之，CORE 提升也可能来自提示格式或分词边界的变化。因此 leaderboard 同时报告两者，用 bpb 作为平滑的辅助信号，用 CORE 作为验收标准。

### 7. 从 CSV 到跨版本复核

`scripts/base_eval.py` 把每个任务的三列写入 `~/.cache/nanochat/base_eval/base_model_{step}.csv`：表头为 `Task, Accuracy, Centered`，每个任务一行，最后一行任务名固定为 `CORE`，`Accuracy` 列为空、`Centered` 列为总分。这一格式有两个用途。

第一，分项诊断。22 行里如果只有少数几项显著低于同规模模型的常见水平，问题通常出在数据或分词，而不是训练本身；若全部按同一比例偏低，则更可能是训练不足或学习率问题。

第二，跨版本复核。`dev/estimate_gpt3_core.ipynb` 用 `parse_csv` 读取同格式的 GPT-2 CSV，`core = results['CORE']['centered']`，再以六个任务为中心化基准做回归。这说明「任务名 → 准确率 → 中心化值」的三列结构在 base_eval 移除 `--hf-path` 支持之后仍是稳定接口；`dev/LEADERBOARD.md` 注明，若要自行复算 GPT-2 的 0.256525，需要回到提交 `21a7774` 或更早的版本使用 HuggingFace 加载路径。

复核时要注意：CSV 中的 `Accuracy` 是未中心化的原始准确率，跨任务不可直接平均；只有 `Centered` 列可以相加，`CORE` 行就是它们的均值。若手动重算发现末行不等于前 22 行的均值，通常是因为任务名与 `core.yaml` 的 `label` 不一致导致某行被漏计，或读取时把表头行当成了任务行。

### 在 nanochat 中的落地

第一处是 `nanochat/core_eval.py` 的 `evaluate_task`。它按 rank 轮转样本（`for idx in range(rank, len(data), world_size)`），每个 rank 只评自己的子集，然后把 `correct` 张量 `all_reduce` 求和再取均值。这样 8 卡上每个 rank 的评测时间接近，且不需要把全部样本复制到每张卡。

第二处是 `scripts/base_train.py` 的调用频率与预算：`--core-metric-every=2000`、`--core-metric-max-per-task=500`、`--eval-tokens=80*524288`（约 41.9M token 用于 bpb）。训练中 CORE 是稀疏的粗估，最终 CORE 才用 `base_eval.py` 全量跑。

第三处是 `scripts/base_eval.py` 的输出格式：CSV 三列 `Task, Accuracy, Centered`，最后一行任务名为 `CORE`。`dev/estimate_gpt3_core.ipynb` 正是解析这种 CSV 来复核 GPT-2 基线，说明该格式是跨版本的稳定接口。

## 关键直觉

> [!tip] 中心化把「任务的猜中概率」从分子与分母中同时扣掉，使不同选项数的任务可加
> 一个四选一任务答对 0.40 与一个二选一任务答对 0.40，原始准确率相同但信息量不同：前者只比随机高 0.15，后者比随机低 0.10。中心化把前者映射为 0.20、后者映射为 $-0.20$，于是「高出随机的比例」成为可加量，22 个任务的算术平均才有意义。与严格定义的关系：定义中的 $1-p_i$ 是分母上的归一化，直觉上它是「该任务剩余可得分空间」的大小；基线越高，空间越小，单位准确率的权重越大。

## 例子与代码

### 1. 手算一次 CORE（5 个任务的子集）

取 5 个真实任务的基线，给定一组假设准确率，逐步计算中心化值与均值。

| 任务 | 选项数 | 准确率 $a_i$ | 基线 $b_i$ | $p_i$ | $c_i=(a_i-p_i)/(1-p_i)$ |
|---|---|---|---|---|---|
| ARC Easy | 4 | 0.4000 | 25 | 0.25 | 0.2000 |
| ARC Challenge | 4 | 0.2600 | 25 | 0.25 | 0.0133 |
| PIQA | 2 | 0.6200 | 50 | 0.50 | 0.2400 |
| LAMBADA | 开式 | 0.3200 | 0 | 0.00 | 0.3200 |
| HellaSwag | 4 | 0.3600 | 25 | 0.25 | 0.1467 |
| 合计 | | | | | 0.9200 |

均值为 $0.9200/5=0.1840$。作为量级参照：`dev/LOG.md` 记录 d18 在 FineWeb-EDU 上的 CORE 为 0.199，d26 为 0.2602；GPT-2 的阈值为 0.256525。

同样的数字还能说明权重效应：在 ARC Challenge 上提高 1 个百分点，$\Delta c=0.01/0.75=0.0133$；在 LAMBADA 上提高 1 个百分点，$\Delta c=0.01$。折算进 22 个任务的均值，前者贡献 $0.000606$，后者贡献 $0.000455$。四选一任务的单点提升对 CORE 的边际影响约为开式任务的 1.33 倍。

### 2. 复现中心化公式

```python
# 独立运行：只需要 Python 标准库
BASELINES = {"arc_easy": 25, "arc_challenge": 25, "piqa": 50, "lambada": 0, "hellaswag": 25}
ACCS = {"arc_easy": 0.40, "arc_challenge": 0.26, "piqa": 0.62, "lambada": 0.32, "hellaswag": 0.36}

centered = {}
for task, acc in ACCS.items():
    p = 0.01 * BASELINES[task]          # 基线以百分数给出，先转概率
    centered[task] = (acc - p) / (1.0 - p)
core = sum(centered.values()) / len(centered)
print({k: round(v, 4) for k, v in centered.items()})
print(round(core, 4))
# 预期：{'arc_easy': 0.2, 'arc_challenge': 0.0133, 'piqa': 0.24, 'lambada': 0.32, 'hellaswag': 0.1467}
# 预期：0.184
```

### 3. 观察续写边界如何被找到

```python
# 独立运行的最小复现：说明 multiple_choice 任务的公共前缀切分
def find_common_length(token_sequences, direction='left'):
    min_len = min(len(seq) for seq in token_sequences)
    indices = {'left': range(min_len), 'right': range(-1, -min_len - 1, -1)}[direction]
    for i, idx in enumerate(indices):
        token = token_sequences[0][idx]
        if not all(seq[idx] == token for seq in token_sequences):
            return i
    return min_len

prompts = [[11, 22, 33, 44, 55, 66], [11, 22, 33, 44, 77], [11, 22, 33, 44, 88, 99]]
print(find_common_length(prompts, direction='left'))    # 4，公共前缀 [11,22,33,44]
print(find_common_length(prompts, direction='right'))   # 0，无公共后缀
```

三条提示的前 4 个 token 相同，因此 multiple_choice 的续写区间是 $[4, e_j)$，长度分别为 2、1、2。这正是 `batch_sequences_mc` 的行为：`start_indices = [4, 4, 4]`，`end_indices = [6, 5, 6]`。

### 4. 跑一次全量 CORE

```bash
# 单个模型、8 卡、全量 22 任务；不指定 --step 时取该模型目录下的最后一步
OMP_NUM_THREADS=1 torchrun --standalone --nproc_per_node=8 -m scripts.base_eval -- \
    --model-tag=d24 \
    --eval=core \
    --max-per-task=-1

# 快速近似：每任务只取 100 条，单卡即可
python -m scripts.base_eval --model-tag=d24 --eval=core --max-per-task=100 --split-tokens=524288
```

输出末尾会打印该次运行的 CORE（例如 Run 6 的 `CORE metric: 0.2626`），并在 `~/.cache/nanochat/base_eval/base_model_{step}.csv` 写入分项结果。

## 易错点

> [!warning] 六个可检验的错误
> 1. 把基线当作概率又重复乘 0.01。`eval_meta_data.csv` 的值是百分数（25、50），代码用 `0.01 * baseline` 转换；若把 25 再乘 0.01，等于把四选一的基线当成 0.0025，几乎所有任务都不再扣分，CORE 被系统性高估。
> 2. 多选任务用「首个 token 的 argmax」判别。实现里用续写区间的平均损失最小值，长度不同的选项因此可比；只比首 token 会系统性偏向短选项。
> 3. 语言建模任务忘掉 `-1` 的错位。位置 $t$ 的预测对应 token $t+1$，因此区间是 `predictions[si-1:ei-1]` 对 `input_ids[si:ei]`；写成 `predictions[si:ei]` 会把最后一个位置换成 `nan` 列并整体错一位。
> 4. 认为 `--max-per-task` 只是随机子集。它先打乱再截断，截断改变了 `len(data)`，因此 few-shot 采样空间也改变，子集均值不等于全量均值。
> 5. 把 CORE 当作连续平滑指标用于早期模型选择。单次运行的标准差约 0.005，模型间差异小于该量级时不可区分；应重复运行或同时看 bpb。
> 6. 认为 CORE 分数按样本数加权。总分是 22 个任务中心化值的等权平均，任务规模不影响权重。

## 关联笔记

- 对照 [[对比GPT-2核心指标]]：把 CORE 换算成时间与成本，是 CORE 的直接用途。
- 前置 [[评测方法论]]：准确率、基线与聚合口径的一般讨论。
- 后续 [[如何解读指标]]：CORE、ChatCORE 与 bpb 的联合解读。
- 对照 [[ARC与MMLU]]：同一批任务在 chat 模型上的 categorical 评测方式。
- 跨库 [[模型评估矩阵]]：通用原理见该篇，本篇只讲 nanochat 的 22 项 ICL 协议与中心化实现。

## 达标检测

- [ ] 能写出 CORE 的定义式，并说明基线为何以百分数存储、代码如何转换。
- [ ] 能对给定的 5 个任务准确率与基线手算出 CORE，结果与本文的 0.1840 一致。
- [ ] 能区分 multiple_choice、schema、language_modeling 三类任务的判别对象与边界查找方向。
- [ ] 能解释 `losses[i, si-1:ei-1]` 的下标为什么是 `si-1` 到 `ei-1`，以及区间长度为何等于 $e_i-s_i$。
- [ ] 能说明 `random.Random(1234 + idx)` 与 `random.Random(1337)` 各自固定了什么，以及 `max_per_task` 如何影响 few-shot 采样。
- [ ] 能解释 CORE 与 bpb 在「跨数据集可比性」和「方差」两个维度上的差异，并各举一个 leaderboard 中的证据。
- [ ] 能说明为什么总分是等权平均而不是按样本数加权，并给出该选择的一个后果。

## 参考来源

- DCLM 团队, *DataComp-LM: In search of the next generation of training sets for language models*（2406.11794）—— CORE 指标与中心化定义的原始出处。
- Karpathy, *nanochat*（commit 92d63d4），`nanochat/core_eval.py` —— 对应本篇三类任务打分、few-shot 采样与续写边界。
- Karpathy, *nanochat*（commit 92d63d4），`scripts/base_eval.py` —— 对应 eval bundle 结构、中心化实现与 CSV 输出。
- Karpathy, *nanochat*（commit 92d63d4），`dev/estimate_gpt3_core.ipynb` —— 对应 22 项任务的类别清单与基线取值。
- Karpathy, *nanochat*（commit 92d63d4），`dev/LEADERBOARD.md` 与 `nanochat/loss_eval.py` —— 对应 0.256525 阈值与 bpb 计算公式。
