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.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 把这些拼起来:
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 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 |
均值为 。作为量级参照: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 计算公式。