w wyl123ly 的博客
MD

CORE指标

21 KB 2026.10.22 原文件

CORE指标

定义

CORE(DCLM 论文提出的复合指标,全称沿用论文中的写法,不作展开)是 base 语言模型在 22 个上下文学习(in-context learning,ICL)任务上的中心化准确率的算术平均:每个任务的原始准确率先减去随机猜测基线、再除以剩余的可得分空间,最后对 22 个任务等权平均。

符号定义如下。

  • 任务索引 , 为 core.yaml 中 icl_tasks 列表长度;仓库文档与 dev/estimate_gpt3_core.ipynb 记作 。
  • :任务 上的原始准确率,即 evaluate_task 返回的 mean_correct。
  • :任务 的随机猜测基线,以百分数表示(例如四选一任务为 25),来自 eval bundle 的 eval_meta_data.csv 中 Random baseline 列。
  • :基线的概率形式。
  • :任务 的中心化准确率,。
  • CORE 分数:。等权,不按样本数加权。
  • ICL 任务:模型不更新参数,仅凭提示中给出的若干示例(few-shot)与任务描述,直接对候选续写打分或生成答案的任务形式。
  • 续写(continuation):多选与 schema 任务中位于 continuation_delimiter 之后、用于判别的文本片段;语言建模任务中是待预测的整段尾文。
  • -shot:提示中提供的示例数量 ,取自 core.yaml 中 num_fewshot 列表的首元素。
  • bpb(bits per byte):另一套指标,,衡量逐 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.yamlicl_tasks 列表,每项含 label、icl_task_type、dataset_uri、num_fewshot、continuation_delimiter决定评哪些任务、怎么评
eval_data/*.jsonl每个任务一个 JSONL,字段含 query、choices、gold、context、continuation 等任务样本
eval_meta_data.csvEval Task 与 Random baseline 两列中心化所需的基线

scripts/base_eval.py 的 evaluate_core 把这些拼起来:

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') 找到公共前缀长度 ,每条提示的终点 为其 token 长度。打分取续写区间上的平均损失:

其中 是位置 对第 个 token 的交叉熵,代码用 losses[i, si-1:ei-1] 取这一段——因为位置 的损失预测的是 ,所以「预测续写 」对应损失下标 ,区间长度恰为 。预测正确当且仅当 等于 item['gold']。

第二类 schema:各候选的上下文不同、续写相同,因此公共部分是后缀。用 direction='right' 找公共后缀长度 ,起点 。

第三类 language_modeling:渲染两条提示,一条不含续写、一条含续写;先断言前者是后者的 token 前缀,再用断言得到的边界 逐 token 比较贪心预测与实际 token,要求全匹配:

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 为每个样本现场抽 个示例:

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 截断数据时,抽样空间随之改变。

数据在评测前先整体打乱:

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% 显然不是同一水平;减去基线并除以剩余空间后,两者都被映射到「超出随机的比例」。

代入定义:

性质有三条。第一, 时 ,随机水平归一为零。第二, 时 ,满分归一为一。第三, 是缩放因子: 越大,同样的准确率提升换算成 的增量越大。语言建模任务的基线为 0(要逐 token 全匹配,随机猜测的命中率可视为零),此时 。

总分是 22 个 的算术平均。每个任务权重相同,与任务样本数无关:一个只有数百条样本的任务与一个有数千条样本的任务对 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

计数为 。实际任务清单与顺序以 bundle 中 core.yaml 的 icl_tasks 列表为准:本地源码快照不包含 eval bundle(它在首次评测时下载),因此任务名与 shot 数不能凭记忆写死。

6. 与 bpb 的区别

两者回答不同的问题。bpb 是压缩率:模型对验证集每个字节平均分配多少比特,,由 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 基线,说明该格式是跨版本的稳定接口。

关键直觉

中心化把「任务的猜中概率」从分子与分母中同时扣掉,使不同选项数的任务可加

一个四选一任务答对 0.40 与一个二选一任务答对 0.40,原始准确率相同但信息量不同:前者只比随机高 0.15,后者比随机低 0.10。中心化把前者映射为 0.20、后者映射为 ,于是「高出随机的比例」成为可加量,22 个任务的算术平均才有意义。与严格定义的关系:定义中的 是分母上的归一化,直觉上它是「该任务剩余可得分空间」的大小;基线越高,空间越小,单位准确率的权重越大。

例子与代码

1. 手算一次 CORE(5 个任务的子集)

取 5 个真实任务的基线,给定一组假设准确率,逐步计算中心化值与均值。

任务选项数准确率 基线
ARC Easy40.4000250.250.2000
ARC Challenge40.2600250.250.0133
PIQA20.6200500.500.2400
LAMBADA开式0.320000.000.3200
HellaSwag40.3600250.250.1467
合计0.9200

均值为 。作为量级参照:dev/LOG.md 记录 d18 在 FineWeb-EDU 上的 CORE 为 0.199,d26 为 0.2602;GPT-2 的阈值为 0.256525。

同样的数字还能说明权重效应:在 ARC Challenge 上提高 1 个百分点,;在 LAMBADA 上提高 1 个百分点,。折算进 22 个任务的均值,前者贡献 ,后者贡献 。四选一任务的单点提升对 CORE 的边际影响约为开式任务的 1.33 倍。

2. 复现中心化公式

# 独立运行:只需要 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. 观察续写边界如何被找到

# 独立运行的最小复现:说明 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 的续写区间是 ,长度分别为 2、1、2。这正是 batch_sequences_mc 的行为:start_indices = [4, 4, 4],end_indices = [6, 5, 6]。

4. 跑一次全量 CORE

# 单个模型、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 写入分项结果。

易错点

六个可检验的错误

1. 把基线当作概率又重复乘 0.01。eval_meta_data.csv 的值是百分数(25、50),代码用 0.01 * baseline 转换;若把 25 再乘 0.01,等于把四选一的基线当成 0.0025,几乎所有任务都不再扣分,CORE 被系统性高估。

2. 多选任务用「首个 token 的 argmax」判别。实现里用续写区间的平均损失最小值,长度不同的选项因此可比;只比首 token 会系统性偏向短选项。

3. 语言建模任务忘掉 -1 的错位。位置 的预测对应 token ,因此区间是 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,以及区间长度为何等于 。
  • [ ] 能说明 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 计算公式。