Kiln 评估数据集 train/val/test 拆分:V1(TaskRun)与 V2(EvalInput)双数据源的统一建模实践
Kiln 评估数据集 train/val/test 拆分:V1(TaskRun)与 V2(EvalInput)双数据源的统一建模实践
导读
本文围绕 Kiln 仓库中 specs/projects/eval_splits_v1_v2 项目讲解一个核心问题:如何让评估(eval)的 train / val / test 三份数据拆分(splits) 同时工作在 V1(TaskRun)与 V2(EvalInput)两种评估数据源之上,并且通过同一套 API 表面对外暴露,使调用方无需关心数据来自哪个存储。读完本文你将掌握:两种"v2"概念(judge 轴与数据源轴)如何区分、Eval 数据模型上拆分字段的最终形态(splits 字典 + 类型化 SplitRef 联合体)、resolve_split 访问器如何把"按名字取拆分"统一成一条无分支的代码路径,以及合流过程中九个容易静默出错的问题点及其解决思路。
背景:两个都叫 "v2" 的轴,必须分开看
这个项目最初的问题,源于把两个彼此独立的 "v2" 概念混为一谈。它们必须分开讨论:
| 轴 | V1 | V2 |
|---|---|---|
Judge(评判器) — EvalConfig.config_type |
g_eval、llm_as_judge |
v2 + V2EvalType(llm_judge、exact_match、pattern_match、set_check) |
数据源 — Eval.*_filter_id |
eval_set_filter_id → TaskRun |
eval_input_filter_id → EvalInput |
关键事实:一个 eval 完全可以是 "v2 judge + v1 数据" —— 这正是今天 UI 创建的每个 eval 的形态。本项目只关心数据源轴;judge 轴不需要任何改动。文档(project_overview.md)中明确给出了这张对照表,并指出两条线的合并(scosman/evals_v2 与 PR #1621 的 eval-api-improvements)之所以冲突面很大,正是因为二者分别沿数据源和 judge 两个方向演进。
合流前的数据源现状
TaskRun 数据源:在 scosman/evals_v2 上拥有四个 filter 角色,全部是 DatasetFilterId,统一经 dataset_filter_from_id() 解析为 TagFilter(task_run.tags)(dataset_filters.py 中 TagFilter 及 dataset_filter_from_id 实现):
eval_set_filter_id—— test 集("eval set" 这个名字是历史遗留)eval_configs_filter_id—— golden 集(人工评分的 TaskRun,用于给 judge 打分而不是给模型打分)train_set_filter_id—— 被 prompt 优化和进度计数器读取val_set_filter_id—— 由 #1621 分支新增,evals_v2 上还不存在
EvalInput 数据源:只有一个 filter 槽:
eval_input_filter_id,类型为EvalInputFilterId,经eval_input_filter_from_id()解析为TagEvalInputFilter(eval_input.tags)(dataset_filters.py 第 205~259 行)。- 该类型只接受
all和tag::<x>,不接受multi_filter::、high_rating(那些都要读取 TaskRun 的评分数据)。 EvalInput模型本身携带data、reference、tags(eval.py)。Eval.validate_filter_fields强制eval_set_filter_id/eval_input_filter_id恰好只能有一个。
项目目标一句话概括:让 EvalInput 支撑的 eval 也拥有与 TaskRun 支撑 eval 完全相同的三个拆分,并通过完全相同的 API 表面寻址。没有任何调用方应该因为数据源不同而分叉分支。
范围界定:做什么、不做什么
在范围内
EvalInput支撑的 eval 获得可用的 train / val / test 拆分;- 拆分通过与 TaskRun 源相同的 API 表面寻址,调用方不按数据源分支;
- 合并
scosman/evals_v2与 #1621 分支并解决冲突; EvalProgress在既有 train 计数的旁边报告 val 计数,保持对称。
明确不做(out of scope)
EvalInput的 golden 集:eval_configs_filter_id与 judge 对比保持 TaskRun 专用。关键是必须大声(loudly)且可理解地失败,而不是静默返回空集或误导性结果(对应下文"问题 §6")。- EvalInput 拆分的数据创建路径:未来的 copilot 会负责填充
EvalInput,创建时把条目打标进拆分是那个项目的职责。 - 超出
EvalProgressval 计数的 UI 工作。
核心设计问题:一个 EvalInput eval 如何表达它的拆分
这是整个项目的中心设计问题,其余一切都由它衍生:一个 filter 字段必须变成多个,而这个数据源的 filter-id 类型比 TaskRun 的更窄。
项目文档记录了四个被考虑的方向(原文为 Rough guidance,要求 spec 过程确认最优方案):
- (a) 并行字段:按源分别建
train_eval_input_filter_id等字段。显式,但最终会在Eval上积累七八个 filter 字段外加一个需要维护的互斥校验器。 - (b) 拆分字典:
splits: dict[EvalSplitName, FilterId],filter-id 类型按 eval 的源模式校验。端到端最干净,但迁移面最大——磁盘上每一个既有 eval 和每一个读取方都受影响。 - (c) 拓宽现有字段:让现有字段可容纳两种 filter 类型,按源模式校验。diff 最小,但放弃了"
DatasetFilterId就是 TaskRun 形态"的类型级保证。 - (d) 其他方案:speccing 过程中提出并达成一致的更好设计。
最终落地的形态:splits 字典(源码验证)
从当前仓库源码看,最终实现采纳了方案 (b) 的精神,并做了类型化收口。在 eval.py 中:
class TaskRunSplit(BaseModel):
"""A split whose items are TaskRuns, selected by a dataset filter."""
model_config = ConfigDict(extra="allow")
source: Literal["task_run"] = "task_run"
filter_id: DatasetFilterId
class EvalInputSplit(BaseModel):
"""A split whose items are EvalInputs, selected by an eval-input filter."""
model_config = ConfigDict(extra="allow")
source: Literal["eval_input"] = "eval_input"
filter_id: EvalInputFilterId
SplitRef = Annotated[
Union[TaskRunSplit, EvalInputSplit],
Discriminator("source"),
]
SplitRef 是一个以 source 字段做判别器(Discriminator)的联合体——拆分的"数据源"是值的一部分,而不是读取方需要知道的约定。Eval 上的拆分字段为:
EvalSplitName = Literal["train", "val", "test"] # API 可寻址的拆分名
splits: Dict[str, SplitRef] = Field(default_factory=dict, ...)
两个值得注意的源码级细节:
- 字典键用
str而非EvalSplitName(Literal):Kiln 项目文件经 git 同步、会被不同版本 App 打开。若键是Literal,一个包含未来拆分名的文件会校验失败,导致整个Eval无法加载——未来新增拆分名会把旧版本构建"打崩"。用str键,未知键可以被加载、在往返(round-trip)中保留,只是不对外暴露。EvalSplitName才是可寻址表面:API 只接受这三个名字,未来加第四个拆分只是这一行的改动,数据模型零变更。 - 类型安全是结构性的:
EvalInputSplit.filter_id被声明为EvalInputFilterId,因此multi_filter::…或high_rating出现在 EvalInput 支撑的拆分上不是"忘了校验"而是"无法表达"。测试 test_eval_model.py 中的test_eval_input_split_rejects_task_run_only_filters用参数化断言:multi_filter::high_rating&all、high_rating、thinking_model、thinking_model_high_rated四种 TaskRun-only 形式都会让EvalInputSplit抛出ValidationError,而TaskRunSplit则全部接受。
旧字段的处置:单向迁移,而非双写
eval_set_filter_id 和 train_set_filter_id 仍然作为已声明、已存储、可选的字段保留在模型上(它们是存量项目文件能继续被旧版本 Kiln 读取的格式工件),但应用代码不再读它们。Eval.migrate_legacy_split_fields(mode="after" 校验器)在加载时只读取一次,把值折入 splits 并立即清空原字段:
for name, field_name in LEGACY_SPLIT_FIELDS.items():
filter_id = self.__dict__.get(field_name)
if filter_id is not None and name not in self.splits:
self.splits[name] = TaskRunSplit(filter_id=filter_id)
self.__pydantic_fields_set__.add("splits")
self.__dict__[field_name] = None
LEGACY_SPLIT_FIELDS 映射为 {"test": "eval_set_filter_id", "train": "train_set_filter_id"}。两个细节值得注意:
splits优先:如果splits已经描述了某个拆分(手编文件、或旧构建在新构建之后写入的遗留值),遗留字段被忽略而不是反过来覆盖——迁移是单向的。- 校验器声明顺序重要:
migrate_legacy_split_fields必须声明在validate_splits之前,因为后者要求必须有 test 拆分;一个只带遗留字段的 eval 的 test 拆分来自前者。测试集专门覆盖了这个顺序依赖。
validate_splits 取代了旧的 validate_filter_fields:
@model_validator(mode="after")
def validate_splits(self) -> Self:
if "test" not in self.splits:
raise ValueError("An eval must have a test split. Set splits['test'].")
return self
旧的"eval_set_filter_id / eval_input_filter_id 恰好一个"不变式从模型中消失而非被重写:splits["test"] 是单一值,一个拆分两个 backing 根本不是一个模型可达的状态——这是"每个拆分恰好一个数据源"的结构化表达。
set_split():写入拆分的正确入口
Eval.set_split(name, split) 等价于 eval.splits[name] = split,外加两件事:拒绝修改只读(缓存)eval,以及把 splits 标记为已设置(保证 exclude_unset 转储仍携带它)。文档强调:直接赋值与 set_split 在内存里结果相同,只在序列化字节上不同——因此任何"写拆分"的测试都应断言 model_dump() 或保存后的文件,而不是断言 eval.splits。测试 test_writing_a_train_split_lands_in_splits 验证了无论 eval 以何种格式到达,更新端点写入的 train 拆分都会落到 splits。
访问器缝(accessor seam):整个项目唯一的源分支点
新模块 eval_splits.py 是"哪条存储支撑某个拆分"的唯一知情人。它的两个核心概念:
ItemSource = Literal["task_run", "eval_input"]
ItemKey = Tuple[ItemSource, ID_TYPE] # 身份永远不是裸 id
为什么 ItemKey 必须携带源:Kiln 的 id 是 str(uuid.uuid4().int)[:12]——12 位十进制数字,由所有模型类型共享的同一个生成器产生。这是约 10¹² 的空间而非完整 UUID,TaskRun 与 EvalInput 从同一池取 id,跨存储碰撞"不太可能"而非"不可能";一旦碰撞,不会大声失败,而是把一个条目的结果静默并入另一个条目的拆分。因此任何缓存键、查找、成员测试都必须携带 source。
@dataclass(frozen=True)
class ResolvedSplit:
name: str
source: ItemSource
items: List[TaskRun] | List[EvalInput]
eval_id: ID_TYPE
# 提供 item_keys() / __contains__ / __len__
def resolve_split(task: Task, eval: Eval, split: EvalSplitName) -> ResolvedSplit | None:
split_ref = eval.splits.get(split)
match split_ref:
case None: return None
case TaskRunSplit():
... # dataset_filter_from_id 作用于 task.runs(readonly=True)
case EvalInputSplit():
... # eval_input_filter_from_id 作用于 task.eval_inputs(readonly=True)
设计要点:
resolve_split是唯一在source上分支的地方:一个match覆盖SplitRef联合体,其余全部调用方保持源无关。- 返回
None而非抛异常:三个调用方对"拆分缺失"要三种不同反应(422、0、跳过),异常会迫使每个调用方去捕获。 ResolvedSplit.__len__返回去重键数而非len(items):每个按拆分度量进度的消费者用 item key 交集构建分子,若分母取自 item 列表,进度会卡在 100% 以下、is_complete永不触发(源码注释对此有详细说明)。__bool__恒为 True:区分"拆分存在但暂无条目"(空ResolvedSplit)与"eval 没有这个拆分"(None)——前者提示用户去生成数据,后者提示去配置拆分。
成员判定由 eval_run_item_key(eval_run) 完成:EvalRun 恰好记录 dataset_id(TaskRun)或 eval_input_id(EvalInput)之一,于是 eval_run_item_key(run) in resolved_split 按构造就是源感知的,任何调用方都无法通过比较裸 id 弄错。ResolvedSplit 还携带 eval_id(phase 4 加入),使 EvalRunner(eval_configs=[a_config], split=resolve_split(task, other_eval, "test")) 这种"把 A eval 的拆分喂给 B eval 跑"的错用从约定变成了构造性不可能(构造函数会直接抛 ValueError)。
九个被识别出的问题:合流最容易静默出错的地方
文档的 "Problems detected" 部分是观察而非设计清单——合流在哪里最可能坏、设计必须回答哪些问题。逐条拆解:
§1 一个 EvalInput eval 如何表达拆分
即上文核心设计问题(方案 a/b/c/d),最终以 splits 字典落地。
§2 拆分覆盖参数到不了 EvalInput 路径
#1621 的 EvalRunner.eval_set_filter_id_override 只影响 collect_tasks_for_task_run_eval;而 evals_v2 的 collect_tasks() 在 _source_mode == "eval_input" 时短路到 collect_tasks_for_eval_input()。naive 合并后,对 EvalInput eval 传的覆盖参数被静默忽略:请求成功、跑的却是全集。静默错误(silent-wrong)正是本设计要消灭的失败模式。
源码现状印证了修复方向:EvalRunner.__init__ 现在直接接收 split: ResolvedSplit | None(eval_runner.py),task_run_eval 模式下 split=None 直接抛 ValueError,eval_config_eval 模式传 split 也抛 ValueError——"接受了再丢掉"不可表达。
§3 任务 worker 计算了错误的条目宇宙
jobs/workers/eval.py 的 _dataset_filter_id() 回退到 eval.eval_set_filter_id(#1621 分支上非可选、evals_v2 上是 | None,合并后是类型错误);进度宇宙用 task.runs(readonly=True) 构建,对 EvalInput eval 恒为空。修复方向:resolve_split 一次调用同时服务 runner 的条目来源与进度宇宙,len(resolved_split) 对两种 backing 天然正确。jobs/api.py 还会在任务创建前预解析拆分,让坏拆分在请求期就 422 而不是变成一个注定失败的后台任务。
§4 "test 总是可解析"不再成立
#1621 的 filter_id_for_split() 与 split_filter_id_from_eval() 都假设 eval_set_filter_id 总是设置。在 evals_v2 上它对每个 EvalInput eval 都是 None,于是 test 的 422 分支以 "no test_set_filter_id" 消息触发——一个从未存在过的字段名。假设与诊断措辞都需要重写;最终 split_filter_id_from_eval 被整体删除。
§5 结果过滤用错了 id 做键
结果端点按 run_result.dataset_id in split_dataset_ids 过滤;EvalInput 支撑的 EvalRun 携带 dataset_id=None 而 eval_input_id 有值,因此 ?split= 对每个 EvalInput eval 都会返回零条结果——又一个静默错误。修复后(eval_api.py 的 get_eval_run_results):split 成为必填查询参数,先 resolved_split_or_422(task, eval, split) 再 eval_run_item_key(run_result) in resolved_split 过滤。
§6 golden 不在范围内——但"大声失败"有真实要求
golden 条目是匹配 eval_configs_filter_id 的 TaskRun,每个都带 output.rating(人工评分)。human_score_from_task_run 把 eval 的每个 output_scores 映射到该评分,judge 对比把 judge 分数与人工分数按 output score 做相关——相关性就是 judge 被选中的方式(回答"这个 judge 行不行",而 test/train/val 回答"这个模型行不行")。
EvalInput 在三个层面都无法参与:golden 运行用 eval_config_eval,复用条目存储的输出而不重跑任务(EvalInput 没有输出);EvalInput 没有评分存储;相关路径按 eval_run.dataset_id 查条目(对 EvalInput 为 None)。注意 EvalInput.reference 不是替代品:它是 judge 拿来比对输出的数据,人工评分是对 judge 的裁决——reference 让 judge 能打分,却不能告诉你 judge 打得好不好。
"大声"的覆盖范围(文档给出的粗略指引):golden 端点中当前对 null eval_set_filter_id 抛 400 的两个(get_eval_progress、get_eval_config_score_summary)与静默跳过的那个(get_eval_results_summary),各自变成错误、空集带原因、还是支持 EvalInput,是设计决策。
源码现状:runner 的 eval_config_eval 模式现在按 golden filter 收集且只会收集 TaskRun(collect_tasks_for_eval_config_eval 只遍历 self.task.runs(readonly=True)),run_job 中处理"EvalInput 上跑 eval_config_eval"的分支已被删除——这个状态不可达,自然也就没有"拒绝"可言。
§7 迁移无条件铸造 TaskRun 型 filter
migrate_train_set_filter_id 与新增的 migrate_val_set_filter_id 在每次加载时把 tag::train_{slug} / tag::val_{slug} 铸成 DatasetFilterId——包括 EvalInput 支撑的 eval(它们的数据根本不是 TaskRun)。此外,spec_utils 的 generate_spec_eval_tags / generate_spec_eval_filter_ids 被 #1621 扩成 4 元组后,需要明确每个源各自应做什么。源码现状:两条惰性迁移均被删除,splits 成为唯一归宿。
§8 filter-id 类型不可互换
DatasetFilterId 接受 multi_filter::…、high_rating、thinking_model;EvalInputFilterId 只接受 all 和 tag::…。任何跨源共享字段或 helper 的设计,都必须防止 TaskRun-only 的 filter 形式被存进 EvalInput 拆分——最终由类型系统结构性保证(见上文 SplitRef)。
§9 EvalProgress 对称性(在范围内)
EvalProgress 报告 train_dataset_size 并在 spec eval 页面渲染。加入 val_set_filter_id 后,val 也应报告计数,否则 train 有数字而 val 静默"不存在"。
源码现状(eval_api.py):
test_split = resolved_split_or_422(task, eval, "test") # 缺失 → 422
train_split = resolve_split(task, eval, "train")
val_split = resolve_split(task, eval, "val")
...
train_dataset_size=split_size(train_split), # 缺失 → 0
val_dataset_size=split_size(val_split), # 缺失 → 0
split_size(split) 用 is None 判断缺失(返回 0),与 ResolvedSplit.__len__ 的"空拆分是 falsy"陷阱明确区分。test 走 422、train/val 走 0 的差异是有意的:对缺失的 test 拆分报 0,会把"eval 已损坏"读成"测试集是空的"。
一个统一的规则:关于结果的一切响应都必须限定在单个拆分内
项目给出了一个贯穿性的铁律(functional spec §5.1):
每个关于 eval 结果的响应都限定在恰好一个拆分上——无论返回逐条记录还是聚合。任何端点都不得返回混合拆分的集合。
理由:把 split 参数设为可选会保留今天的"语法"却静默改变"语义"。现状里每个存储的 EvalRun 都是 test 集运行(因为 test 是唯一可运行的),"所有结果"与"test 结果"恰好相同,页面按巧合正确。一旦 val 可运行,同样的请求会返回混合表格且毫无提示——而该端点是对 agent 暴露的,agent 问"结果"也会静默拿到混合物。get_eval_run_results 的 split 因此是必填的(重新生成的 OpenAPI 客户端会把参数类型化为必填,漏传调用方是编译期错误而非运行时 422);运行 API 的 split 则保持可选、默认 test——因为"运行"有一目了然的默认(跑 eval 从来就是跑 test),而"读取"有三个同样有意义的答案、静默就是歧义,应当拒绝而非猜测。
拆分不设逐条结果标签(§5.2):调用方已在请求里指名拆分,整个响应就是这个拆分;而且拆分只按约定不相交(一个条目可合法匹配两个拆分的 filter),给每条结果一个单一拆分字段恰好在最需要时变得歧义。成员判定是标签的(§5.3):tag::val_x 在任一存储里都是合法选择器,字符串相同,决定读哪个存储的是记录在拆分上的 backing,而非 filter id 本身。
验证注意事项:什么最容易"安静地坏"
文档强调这些是阅读两条分支得来的观察,不是完整测试计划;实现代理需从合并后的树上重新推导受影响面。最容易静默破坏的领域:
- 拆分请求静默覆盖全集(§2):成功返回 200,只有断言"跑了哪些条目"才能抓住;
- 结果过滤对一种源为空、另一种不为空(§5);
- 进度总计与部分拆分运行的恢复行为,按源分别看(§3);
- 跨重叠拆分的增量缓存复用:项目声称条目粒度缓存使其安全,需确认第二个源出现后仍成立;
- 两种 eval 形态的迁移行为:加载/保存往返既不丢字段也不造字段(§7);
- "恰好一个源"不变式在新字段集上存活,且违反时有可理解的错误(§1);
- 跨源 filter-id 类型混淆(§8);
- golden 路径的失败大声且准确而非空(§6);
- 无拆分路径与今天逐字节相同:整个参数是 opt-in,既有 V1 行为绝不能移动。
源码中对应的高风险区域测试集中在 test_eval_model.py 的 TestEvalSplits 类:test_legacy_fields_migrate_into_splits(读一次即清空)、test_fresh_eval_has_populated_splits(迁移不限于文件加载)、test_splits_wins_over_a_legacy_field(splits 优先)、test_unknown_split_key_survives_a_round_trip("holdout" 这种未来拆分名可加载、可往返、可访问)、test_unknown_field_inside_a_split_survives_a_round_trip(SplitRef 上的未知字段因 extra="allow" 而保留)、test_dict_round_trip_keeps_the_migrated_splits 与 test_model_copy_keeps_the_migrated_splits(provenance 在 dump 重建与拷贝中存活)。runner 侧测试(test_eval_runner.py)则以 split=_test_split(...) 贯穿,断言针对"哪些条目"而非成功状态。
Git / PR 工作流与合流纪律
文档记录了完整的合流流程,且明确标注了中途被取代的步骤:
- 从
scosman/eval-api-improvements(45dd7b0)切出scosman/eval-splits-v1-v2; - 合入
scosman/evals_v2并解决冲突(merge base 为df0fd56,且 #1621 本身已相对main是 dirty 的,冲突会来自多个方向); - 实现拆分支持;
- 关闭 PR #1621,指向替代分支;
- 关闭 PR #1620(被取代,其
val_set_filter_id单一提交由本分支承载); - 打开新 PR:
scosman/eval-splits-v1-v2 → scosman/evals_v2,接受正式评审。
步骤 1–2 在构建后被取代:从 eval-api-improvements 分支意味着要携带 PR #1517(leonard/kil-686-eval-job,草稿未合并,且含显式合并阻塞标记),这些绝不能进入面向 main 的分支。项目最终直接在 origin/scosman/evals_v2 上重建为 claude/eval-splits-evals-v2,使步骤 2 的合并变得不必要。代价是 phase 5(jobs worker 相关)的代码面向 #1517 的 worker,不随分支带来,需等 #1517 合并后重新落地(详见 implementation_plan.md phase 5 条目)。
合流方向的纪律:冲突处偏向 evals_v2 的形态——eval_set_filter_id: DatasetFilterId | None、EvalInput 模型、V2 judge 类型都是保留方;而 filter_id_for_split、split_filter_id_from_eval、val_set_filter_id、eval_set_filter_id_override 全部被本设计删除。文档特别提醒:本分支是替换 #1621 而非扩展它,任何与本分支相遇且已携带 #1621 的树,diff 会读起来像"大规模删除已存在代码"——这是正确的,不是丢失的工作。
开放问题与下游对齐
文档收尾列出三个开放问题:
- 模型形态(§1,含方案 d):驱动其余大部分决策;
- 哪些端点学习 EvalInput 路径、哪些明确失败:鉴于 golden 不在范围内(§6);
中间分支:已作废,该合并从工作流中删除。agi-anyting_goes_into合并
此外,functional spec 第 11 条要求本项目的最后一个 phase 产出 specs/projects/eb_v2_splits_alignment/project_overview.md——为 eb-v2 对齐线撰写一份项目概览(只有 what,不是 spec)。它刻意不在本次 speccing 中设计:只有模型真正落地后,冲突面才可知(两条线已分叉 256 个提交,eb-v2 未评审且仍在移动)。那个项目才是对齐设计发生的地方;本项目的职责是交给它一份诚实、当下的问题描述,而非一份过期副本。
小结
train/val/test 拆分跨 V1/V2 的工作,最终在 Kiln 中沉淀为一套清晰的形态:类型化 SplitRef 联合体驱动的 splits 字典作为唯一存储归宿、单向迁移处理遗留字段、resolve_split / eval_run_item_key 作为唯一源感知缝、ResolvedSplit 作为跨层传递的不可变值、以及"结果响应严格限定单拆分"的 API 纪律。九个问题点中最危险的几处——拆分覆盖被静默忽略、结果过滤返回空、进度宇宙算错——都通过"让错误状态不可构造"而非"增加校验"来解决。对于想在 Kiln 上继续深入 eval 数据模型、或评估"增加第四个拆分/第三种数据源"成本的技术读者,这份文档与其配套的 functional_spec.md、architecture.md、implementation_plan.md 以及上述源码与测试,是理解该设计意图与实现边界的第一手材料。