文档导航

评估 harness

laya.evals 把标注数据集变成一个可复现的分数,把基线变成一道通过/不通过的门,于是一次质量 改动就是一个可复核的 diff,而不是一次手工核对。

指标的数学和数据集解析器是纯 Python 加 numpy,从不 import torch,所以不需要权重就能跑。拿数据集 去跑某个 checkpoint 则需要那个 checkpoint,并要花它正常的加载时间。

快速开始

# check the format without a model
laya-evals validate research/evals/fixture.jsonl

# score a labelled set on one checkpoint, with thresholds and a baseline
laya-evals run data.jsonl --model english --device cpu \
    --min-accuracy 0.8 --max-ece 0.05 --score-within 0.25 --slice language \
    --json report.json --markdown report.md

# compare a saved report to a baseline
laya-evals compare report.json --baseline baseline.json --tolerance choice_accuracy=0.02

laya eval ... 是通过主 CLI 做同样的事,所以 laya eval validate data.jsonl 也能用。

退出码:成功为 0,某个阈值或基线容差不过为 1,用法错误为 2。run 把总体指标和请求的 切片打印到 stdout,给了 --json / --markdown 时还会写出完整报告和 Markdown 摘要。

用教师的重复决策比较一个学生

当同一个输入教师给出不同答案时,单独一份保存的答案并不能描述它的可重复性。compare_agreement 拿一个学生,和一次独立的教师重复,去对一次固定的参考教师观测做比较。它接受三份保存下来的运行, 不需要模型权重,也不需要教师服务:

laya-evals agreement reference.json repeat.json student.json \
    --bootstrap-samples 2000 --seed 0 --json agreement.json

不给 --json 时,命令把报告写到 stdout。--seed 只控制自助重采样(bootstrap),不控制模型 生成。成功退出 0;格式错误或未对齐的运行退出 2。这条命令不施加替换门或质量门。

每份输入都是一个 JSON 对象,形状如下:

{
  "schema": "laya-agreement-run/1",
  "run_id": "teacher-reference",
  "provenance": {
    "model": "teacher-checkpoint",
    "revision": null,
    "settings": {"temperature": 0.7, "prompt_template": "Choose one label."},
    "seed": 42
  },
  "cases": [{
    "id": "ticket-001",
    "state": "I was charged twice.",
    "questions": {"route": {
      "type": "choice",
      "instructions": "Select the team responsible for this request.",
      "criteria": ["billing", "support"]
    }},
    "answers": {"route": "billing"},
    "language": "en",
    "tags": ["duplicate-charge"]
  }]
}

每次观测运行都要用不同的 run_id。三次运行必须包含完全相同的唯一 case ID、state、问题定义、 语言和 tag;行的顺序可以不同。state 必须是非 null 的 JSON。问题定义保留选项顺序,并接受非空的 criteria 字典,或由互不相同的字符串标签组成的列表。答案必须覆盖每一个问题。学生的答案可以是 null 表示弃答;教师的答案必须是标签。缺失的 case、未知的标签、非有限的 JSON 值,以及 CLI 输入里重复的 JSON 对象键,都是错误,而不是被省略的样本。

两次教师运行必须声明相同的 model、revision 和 settings。把采样参数和提示词模板放进 settings, 把重复的种子放在它外面。其他元数据,比如数据集 revision 和生成脚本,都会被保留。有不可变的模型 revision 时就记录它;未知时就显式用 null。报告会标出未知的 revision,但无法核实记录下来的 来源是否准确,也无法核实那些教师调用是否相互独立。输入对象的顺序是有意义的,与 Laya 对结构化 state 和问题的序列化一致;请在三次运行之间保持它一致。

在校验完教师记录之后,跑一个本地的学生:

import json
import laya
from laya.evals import evaluate_agreement

with open("reference.json", encoding="utf-8") as handle:
    reference = json.load(handle)
with open("repeat.json", encoding="utf-8") as handle:
    repeat = json.load(handle)
revision = "YOUR_CHECKPOINT_COMMIT"
with laya.Router(device="cpu", revision=revision) as runner:
    report = evaluate_agreement(
        runner, reference, repeat, model="english",
        student_provenance={
            "model": "convaiinnovations/laya", "revision": revision,
            "settings": {"device": "cpu"},
        },
    )
print(report["overall"])

runner 使用与带标签 harness 相同的 predict(state, questions, model=...) 协议(例如 laya.Router)。输入在推理之前会被复制。runner 的失败会向外传播;无效或不完整的输出会抛出 EvalError。一个被标上 abstention="abstained" 的 choice 会变成一个 null 观测,而它底层的 choice 仍然必须是一个合法的标签。

另有一份 laya-agreement-report/1 报告,记录来源、输入哈希、逐个配对的决策,以及按问题 ID、 语言和 tag 切分的比率。对每个决策,教师重复一致率是 repeat == reference,学生一致率是 student == reference,配对差值是二者的差。所有比率都用完整的决策数:弃答贡献零一致,并会拉低 student_coverage。95% 百分位区间重采样整个 case ID,把它们的各个问题保持在一起,并重新计算 决策之和的比值。对固定的输入、种子和 bootstrap 次数(100–100000),它是确定性的。case 少于 两个时区间为 null。切片比率没有区间。

一致不是准确,教师的可重复性也不是理论天花板。两个模型可能在一个错误答案上一致。区间描述的 是在所提供案例及其保存观测上的变化;它不涵盖额外的教师生成。一个包含零的区间并不确立等价。 检查切片和单个决策是否有标签偏斜,而正确性或校准的主张请用带标签的评测。

examples/evals/teacher_agreement.py 把来自一个固定在 revision 的公开数据集的两份已发布教师观测,对着一个本地 Laya checkpoint 回放, 保存这三份运行及其报告。它那小小的固定样本演示的是工作流,不是可以上线的状态。

shortlist 错误的归因

对一个带标注、基数很高的 choice 集合,laya.evals_shortlist.evaluate_shortlist 走既有的 predict_shortlist 路径和常规的评估 harness。它回答两个各自独立的问题:检索有没有保住真值 标签,以及标签在的时候 Laya 有没有选中它?这是一个针对 choice 标签的可选启用的 Python API; 普通的 laya-evals run 报告不变。

import laya
from laya.evals import Dataset
from laya.evals_shortlist import evaluate_shortlist
from laya.shortlist import embed_fn_from_agent

agent = laya.load()
dataset_path = "intents.jsonl"
dataset = Dataset.from_jsonl(dataset_path)
report = evaluate_shortlist(
    agent, dataset, embed_fn_from_agent(agent), k=20,
    checkpoint_id="my-checkpoint@revision", embedder_id="my-encoder@revision",
    dataset_path=dataset_path,
)
print(report.overall)
print(report.cases[0]["shortlist_status"])

用与被测部署相同的嵌入函数和 checkpoint。这两个标识由调用方提供,应当指名不可变的 revision; 报告无法从任意一个 callable 推断出它背后的权重。dataset_path 把文件的 SHA256 和既有的问题 指纹一起记录下来。每个 case 保留实际的 shortlist 标签,以及 correct、retrieval_miss 或 decision_miss 之一。shortlist_recall_at_k 是保留下来的真值标签的比例。 shortlist_accuracy_on_recalled 是正确的决策数除以保留下来的 case 数;一个都没保留时它会被 省略。既有的 choice_accuracy 仍然是覆盖所有 case 的端到端准确率,包含检索未命中的。shortlist 指标出现在同样的 language、model、question 和 tag 切片里。请求延迟包含嵌入和那次决策调用; 报告不单独拆分各阶段的耗时。当 k >= n 时,原问题直接通过,检索召回率为 1,不调用嵌入器。

这不会复现 issue #102 里的 BANKING77 结果: 那些数字取决于它的数据集、checkpoint 和双编码器。这个 API 让同一种诊断在调用方自己的标注集 上可以重复。

评估 ONNX 导出

run --onnx PATH 通过 ONNXAgent 给导出的 ONNX 模型打分,而不是走 torch Router,于是一次 ONNX 部署(包括来自 scripts/export_onnx.py --quantize 的 INT8 副本)会被和 torch 路径一样的 阈值与基线卡住:

python scripts/export_onnx.py --model convaiinnovations/laya --output laya.onnx --quantize
laya-evals run data.jsonl --onnx laya.int8.onnx --max-ece 0.05

--model 指定导出所来自的 checkpoint —— Hub id 或本地路径,而不是 english 这样的 Router 短名,因为这条路径上没有 Router(默认 convaiinnovations/laya)。它的配置和 tokenizer 从那里 加载。Agent 只服务一个 checkpoint,所以某个数据集行的 model 字段指名了另一个 checkpoint 时 会报一个清晰的错,而不是被错误的模型静默作答;--device 不适用。--batch-size 在 Agent 有 batch API 时用它,否则回退为每个状态一次调用;--sort-by-length 会被转发给那个 batch API; 每个状态一次的回退没有可以重排的分组。传 --calibration PATH 把一个拟合好的校准映射加载到 ONNXAgent 上,于是 --max-ece 这样的校准门会针对校准后的概率评估。报告的 config 块记录 onnx 路径和 calibration 路径(设置了的话)。

在 research/evals/fixture.jsonl 上测得(12 个标注行,英文 checkpoint,CPU):

runner choice_acc noul_acc score_mae ece mean_conf p50 ms
torch Router 0.75 1.00 1.3418 0.1596 0.7304 116.8
--onnx fp32 0.75 1.00 1.3418 0.1596 0.7304 66.3
--onnx int8 0.75 1.00 1.3512 0.1658 0.7304 46.3

fp32 导出精确复现了 torch 的数字,量化副本让 score_mae 变动 0.009、ece 变动 0.006 —— 正是 compare --tolerance 用来卡的那种漂移。

数据集格式

每行一个 JSON 对象(JSONL)。空行和以 # 开头的行会被忽略。

字段 必填 含义
state 是 要据以决策的文本、邮件、工单或 JSON 文档
questions 是 一个 Laya 问题 dict,和 Router.predict 接受的完全一样
expected 是 按问题 id 建的标注真值:choice 是标签,score 是数字,noul 是 true/false
tags 否 用来切片的字符串
language 否 用来切片的语言代码
model 否 强制这一行用某个 checkpoint;--model 会覆盖它。什么都不强制的行会标上 Router 实际作答所用的那个 checkpoint

research/evals/dataset.template.jsonl 里有一个带注释的示例。

指标

每个指标在适用之处按答案计算,再在整个数据集上聚合:

指标 适用于 含义
choice_accuracy choice 所选标签命中的比例
noul_accuracy noul 布尔值(概率 >= 0.5)命中的比例
score_mae score 平均绝对误差
score_within_<tol> score 落在某个绝对容差内的比例
ece 任何带置信度和已知标签的答案 期望校准误差,15 个分箱,在 laya.evals._answer_confidence 读取的那一列上计算 —— 答案带 answer["answer_confidence"] 时就用它,不带时用回退值;见一个指标读哪个置信度
brier 任何带置信度和已知标签的答案 把置信度当作 P(正确) 的 Brier 分数,mean((confidence - correct)**2);越低越好
aurc 任何带置信度和已知标签的答案 风险-覆盖率曲线下的面积:每个不同置信度水平一个风险值,各按该水平覆盖的答案数加权;越低越好,并且奖励那种把对与错排序排对的置信度,而不仅仅是校准良好
selective_accuracy@50、selective_accuracy@80 任何带置信度和已知标签的答案 在 50% / 80% 覆盖率点上的置信度阈值所接受的答案上的准确率 —— 也就是在最不自信的尾部弃权所买到的东西。阈值无法拆开一组置信度相等的答案,所以这可能覆盖超过所点名比例的部分;见覆盖率切点
mean_confidence 任何带置信度的答案 同一列的均值 —— 答案带 answer["answer_confidence"] 时就用它
latency_p50_ms、latency_p95_ms 每请求 每个请求等待的墙钟时间,仅供参考 —— 见批处理与计时
cost_per_decision_p50_ms、cost_per_decision_p95_ms 每决策 一次调用的墙钟时间除以它承载的行数,仅供参考

「已知标签」指的是 _correct 能评判的那种:choice 答案对一个字符串标签,或 noul 答案对 一个布尔值。score 答案在任何容差下都没有 correct 值,所以它被排除在那五个指标之外 —— ece 也算在内,因为 ece、brier、aurc 和两个 selective_accuracy@* 读的是同一列 (confidence, correct)。因此一个只有 score 的数据集不会发布任何 ece,无论它的答案多有 把握;对它跑 --max-ece 会以 metric 'ece' is not in the report 失败,而不是拿一个从未被算出 来的数字通过。

一个指标读哪个置信度

上面每一行取置信度的指标(ece、brier、aurc、两个 selective_accuracy@*、 mean_confidence)都从 laya.evals._answer_confidence 取它的列,这个函数优先用 answer["answer_confidence"] —— 也就是答案被报告出来的概率,温度缩放所拟合的那个量。这并不是 在声称这个数字按交付状态就是对的:两个基础 checkpoint 都过度自信,而 laya-multilingual 干脆 没有自带任何已拟合的温度 —— 见 README 的 校准 —— 而这正是 ece 要去测量、而不是去 假定的东西。

一个不带 answer_confidence 的答案会按顺序回退到 confidence,然后对 noul 回退到 max(p, 1 - p),再回退到 max(probabilities)。这些是不同的量。在 choice 和 score 上, confidence 字段是归一化熵,它跟着选项数(#394)变,而不是跟着答案有多对变; max(probabilities) 是顶格选项上的质量,只有当被报告的答案是 argmax 时才等于那个被报告答案的 概率。

真正会不带这个字段到达的形状是严格的 Jev 线上契约:LAYA_JEV_STRICT 会从每个答案里丢掉 answer_confidence(laya/serve.py::_project_jev_strict,以及该 flag 在 HTTP API 页里的那一行),所以对着记录下来的严格响应跑的报告,校准的是那个熵 数字。在三行带标签的数据上测得 —— choice 带着 answer_confidence 0.95,而熵 confidence 是 0.7887;score 0.90 对 0.6410;noul 0.87 —— 同一数据集在完整载荷上得分 mean_confidence 0.9067、ece 0.0900,在严格投影上是 0.7666 和 0.1707。两份报告只有在它们的答案带同一个字段时 才可比;tests/test_evals.py 把两条路径都钉住,所以那条回退顺序的任何改动都必须是刻意做出的。

覆盖率切点与并列

两个覆盖率指标都在一个置信度阈值上切,而一个阈值会接受每一个处于其自身置信度的答案。所以 一次切分绝不会拆开一组共享同一置信度的答案:当 coverage * n 落进这样一组内部时,组里每个成员 都被接受。因此这个数字背后的答案数是该组的上沿,而不是所点名的比例 —— 在一个置信度全都相等的 切片上,selective_accuracy@50 就是那个切片自身的准确率,而不是它较好的那一半。门打印的计数 (规则失败消息里的 n=)是切片的大小,而不是被接受的大小,所以一个非常宽的组单从这条消息是 看不出来的。

并列是常态而非边角情况:一个拟合出的温度可能让某个分箱报告一个点质量(point mass), laya.common.answer_confidence 就记录到已发布的 choice:11+ 上有这种情况,而一个真实的 checkpoint 在十二个答案里产生了一个恰好都在 1.0 的六行组。改为在行下标上切,会让两个指标都 取决于数据集到达的顺序 —— 同样的行,打乱之后,把 selective_accuracy@50 在 0.000 和 1.000 之间移动。

aurc 对每个不同的水平积一个风险值,各按该水平覆盖的答案数加权,所以它仍然是风险-覆盖率曲线 下的面积,而不是大小不一的点的平均。

有两个值得提前规划的结果:

  • 一个数字可能朝任一方向移动,幅度超过重排序能造成的。 当一组横跨切点时,阈值读数和同一份 数据的每一种行下标读数都不同:在 400,001 个并列形状的数据集上测得,selective_accuracy@50 最多差 0.500,aurc 最多差 0.351。在上面那个十二答案的形态上 —— 六个正确,全都在置信度 1.0 —— aurc 移动 0.327(0.173 到 0.500)。一道原本通过的门可能失败,一道原本失败的门可能通过; 先前的判定取决于行顺序,对绝对的 min 或 max 上限也一样,而后者没有被任何东西拒绝,因为 它读的是单次运行。
  • 重新生成已提交的基线。 config.coverage_metric_definition 记录了一份报告是由哪种定义 产生的。跨两种定义比较一个覆盖率指标会被拒绝,在两处要减去基线的门上 —— --baseline --tolerance(EvalReport.compare)和 --gate-policy 下的相对规则 (max_drop / max_increase)—— 而且只要任一侧过期就会被拒,不只是基线:一个由更老的 laya 产生的候选带有一个行顺序的伪影,可能读起来比真相更好,所以拿它去和一份正确重新生成 的基线做门,会让一份正确打分的报告本应失败的回归通过。没有那道拒绝,一条过期基线就会藏起一个 真实的回归:一个在老定义下记录为 0.033 的切片,在这个定义下读作 0.517,于是一个真正下降了 0.217 的候选会通过 0.05 的 max_drop。ece 和 brier 不切,保持可比。

数据里没有并列时,每个答案就有一个水平,两个指标就恰好是它们一直以来的样子 —— 逐位相同,而不 只是接近。

把 ScoreWithin(0.25) 加进评估器列表就得到一个容差指标;默认评估器集合是 choice_accuracy、 noul_accuracy、score_mae 和 mean_confidence。置信度指标不是评估器,也不由你选用:ece、 brier、aurc、selective_accuracy@50 和 selective_accuracy@80 会在每一次至少有一个答案 同时带置信度和已知标签的运行上被计算,无论给它的是哪个评估器列表。从 CLI 看同样的事就是一个 flag:laya-evals run data.jsonl --score-within 0.25 在默认指标旁边报告 score_within_0.25, 而且这个 flag 可以重复,所以 --score-within 0.25 --score-within 0.5 会两个都报告。

容差指标需要一个带数值标签的 score 答案,所以在没有它的数据集上它没有值:run 会点名它算 不出来的那个指标,而不是发布一个静默的零;而点名该指标的 --min / --max 门会以缺失失败。 一次运行被要求了哪些容差会记在报告的 config 块里,所以一份经过复核的基线会说明它预期哪些列。

批处理与计时

--batch-size N 在一次调用里给最多 N 个共享同一 checkpoint 和同一问题 schema 的连续行打分。 两个计时指标来自同一批测量,回答不同的问题:一个批次的每一行都在该批次完成时返回,所以它的 latency 是整次调用,而它的 cost_per_decision 是这次调用的 1/N。因此在决策集合不变的情况 下,批处理会抬高 latency_*、压低 cost_per_decision_*,而 --max latency_p50_ms=... 问的是请求是否被快速服务,不是这次运行是否便宜。不给 --batch-size 时两者一致。

compare 会忽略任何 *_ms 指标,除非有容差点名它,所以这些指标永远不会因为计时的噪声让基线 失败。harness 实际做了什么 —— 请求的批大小、它解析成的 runner 形状、多少个行共享一次调用、最大 的块 —— 记录在报告的 config.timing 里,因为光看 flag 说不清到底有没有批处理。这些计数器记录 的是发出的调用,不是返回的调用:在 laya-evals run --on-error skip 下,一次调用抛了异常的那个 块仍然计入 rows_grouped 和 max_chunk,和它在 config.errored 里的条目并列。默认是 --on-error fail,它会重新抛出异常,而不是发布一份指标只覆盖返回了的调用的报告。两个 *_ms 指标只计返回了的调用,所以一次失败的调用绝不会贡献一个它没测到的延迟。

把批次内的行分组

--sort-by-length 把大小相近的行分进同一次前向传播,于是每一趟都填充到一个较短的最大值, 而不是填充到其中最长的那一行。它改变的是调用的形状,不是答案:结果以同样的顺序返回,得分 完全相同,所以 research/ 可以在 10,000 张工单上报出 2.15x,而没有任何决策发生变化。

要重排序必须不止一趟,所以它只在 --batch-size N 小于这次运行所分组的行数时才生效。 config.timing 把两项声明分开记:sort_by_length 是命令行上说的,sort_by_length_sent 是 实际到达 runner 的。不带 --batch-size 的运行请求的是一件不可能发生的事,并用 sent: false 说明这一点;而一个 predict_batch 早于这个开关的 runner 会以未排序的方式打分,而不是在一次 长运行跑到一半时抛出 TypeError。

阈值上的弃权门

--min-confidence T 把 core 的可选启用弃权阈值(#361)转发给这次运行发出的每一次调用,所以 Router 和 ONNXAgent 会在 harness 看到之前,把 answer_confidence 低于 T 的答案标记为 low_confidence: True 和 abstention: "abstained"。这道门是一个报告控制,不是打分控制: apply_confidence_gate 让 answer["choice"] / ["noul"] / ["score"] 保持原始 argmax 不变,而 _aggregate 只读那些键,所以每一个准确率、校准和覆盖数字 —— ece、brier、aurc、 selective_accuracy@NN —— 在 T=0 和 T=0.7 下都相同。变的是报告的 config.timing.min_confidence 和 config.timing.min_confidence_sent,以及在 harness 下游对 那个 flag 采取行动的调用方。

接受的范围是 core 的 laya.confidence.check_min_confidence —— [0.0, 1.0],有限,不是 bool —— 而不是这里的一份副本,所以一个门自己都会拒绝的值会在任何 checkpoint 加载之前以用法错误 (退出码 2)失败。0.0 是一个合法的请求:它是弃权扫描的对照组,也是 flag_low_confidence 视为空操作的那个值,所以一个把它丢掉的检查会藏起究竟是哪个对照组跑了。

一个 predict(或者对批处理运行而言是 predict_batch)早于这道门的 runner 会被以一个具名的 EvalError 拒绝,而不是在没有阈值的情况下运行。静默丢掉它会让 report.config["timing"]["min_confidence"] 点名一个 harness 从未施加过的阈值 —— 正是这个 harness 存在的意义所要防止的那类谎言,即便指标数字保持不变。config.timing 把请求和事实都 记录下来:min_confidence 是被请求的阈值,min_confidence_sent 说明这次运行发出的任何调用 是否真的带上了它。

切片

compare 和 run 报告总体数字;给 --slice language|model|qid|tag 时,还按每个切片值报告同样 的指标,于是一种语言或一个问题上的回归不读聚合值也能看见。model 切片保存每一行的作答 checkpoint:Router 每个请求自己的选择,或者对一个不路由的 runner 而言是 runner 的 model。

可选启用的切片门

总体的基线门可以通过,而一个更小的语言或问题切片却在回归。要把一个经过复核的切片变成一项 CI 要求,保存一份 JSON 策略,比如 gates.json:

{
  "version": 1,
  "rules": [
    {"slice": {"language": "zh"}, "metric": "choice_accuracy",
     "min_count": 50, "max_drop": 0.05},
    {"slice": {"qid": "intent"}, "metric": "ece",
     "min_count": 50, "max": 0.10}
  ]
}
laya-evals run data.jsonl --baseline baseline.json --tolerance choice_accuracy=0.02 \
    --gate-policy gates.json --json report.json
laya-evals compare report.json --baseline baseline.json \
    --tolerance choice_accuracy=0.02 --gate-policy gates.json

每条规则恰好选择 language、model、qid 或 tag 的一个值,并按该指标在切片报告里出现的 样子精确点名它。它有一个正的 min_count 和恰好一个上限:min 或 max 检查候选值;max_drop 允许相对基线最多下降那么多;max_increase 允许最多上升那么多。后两者需要 --baseline。计数 是所选切片里该指标的已打分答案数,对相对规则而言,是两份报告里的。对 ece 而言,它是带 有限置信度和布尔 correct 值的答案数。缺失的切片或指标、已打分答案太少、或者有跳过/出错的 case,都会让这个可选启用的门失败。相对规则还要求两份报告带有匹配的运行身份,所以缺失的证据 不能表现为通过。一次测得的回归会报告切片、指标、计数、值和上限。非法的策略语法会在 checkpoint 加载之前以退出码 2 退出;质量失败以退出码 1 退出。策略记录在 run --json 报告的 config.gate_policy 里。compare --gate-policy 把该命令行上提供的策略施加到已保存的测量上。 如果它和报告记录的策略不同,compare 会说明;在一次新策略下做显式的重新检查,不会改变最初 那次运行所处的策略。

常规的总体比较仍然适用,包括它的容差和旧基线行为。不给 --gate-policy 时,切片报告和比较的 行为和以前一样。

运行身份

run 把它测到的东西记进报告的 config 块,所以复核者读到的这份产物本身就可复核:

键 含义
schema 报告形状,laya-evals-report/1,这样消费者可以拒绝一个它读不懂的
dataset 输入时写下的路径 —— 是一个名字,不是一个哈希
dataset_sha256 被解析的数据集字节的 sha256
questions_sha256 问题 schema 的指纹:整个数据集上每个问题的 id、类型、instructions 和 criteria
laya_version 算出这些数字的 laya
coverage_metric_definition 是哪一种 aurc / selective_accuracy@* 定义产生了这份报告(见覆盖率切点)。对其中任一指标的相对门规则会拒绝一份在另一种定义下记录的基线,而不是去减那些含义不同的数字
gate_policy run --gate-policy 所施加的可选切片门策略
thresholds 这次运行所施加的门:min、max 和 baseline_tolerance
revisions 每个作答过的 checkpoint 所加载自的那个 commit(见下文)

dataset 是一条路径,而路径不是身份:数据集可能被就地编辑、被移动,或者以同一个名字被重新 拉取,而一个 CI 缓存可能把同一个文件名、不同的字节交给两次运行。questions_sha256 覆盖的是 被问了什么,而不是有多少行,所以往一个没变的问题集里加状态不会动这个指纹 —— dataset_sha256 仍然会变,而加一行是对数据的改动,不是对问题的改动。

它也覆盖 instructions,因为指令文本就是提示词。build_sequence 会把 "<type> question: <instructions>" 渲染进被 tokenize 的 head,Agent 会拒绝一个没有指令的 问题(「加上模型应当回答的文本」),而 Laya 自己的问题身份早就在算它: Router._question_schema 和这个 harness 的批分组都以整个 questions dict 为键, tests/test_router_batch.py 固定住了「单单改写 instructions 就会把一行移进它自己的批分组」 这件事。那么一段改写过的话还算和基线相等吗?不算 —— 而这就是重点。「判断一笔退款是否正当」 和「保守一些,只批准明确的退款请求」问的是不同的问题,而指标门只有在差异刚好把一个数字推得 超过你指定的容差时才能察觉。给一个 choice 选项命名也是同样的道理:criteria 是决策空间, 而 research/eval/metamorphic.py 里的蜕变检查之所以存在,就是因为重命名一个标签会翻转答案。

指令文本里没有任何东西被归一化,只有引擎自己施加的那一步:非字符串的 instructions 会按 json.dumps(ins, ensure_ascii=False) 做哈希,与 Agent._to_internal 一致。所以空白和措辞都 算数,一段在人类看来只是复制编辑的改写会被当作一次新实验。这是诚实的默认值 —— 替代方案是在 一次运行和它的基线之间横一个相似度启发式,而常见使用的评估系统里没有谁有这种东西。

没有任何带时间的东西被记录下来,所以对固定的 runner 而言报告仍然字节级可复现。

REPORT_SCHEMA、questions_fingerprint(dataset) 和 file_fingerprint(path) 是公开的,所以 直接驱动 laya.evals.evaluate 的调用方拿到和一次 CLI 运行相同的身份。

基线与 CI 门

  • 把数据集、一份基线报告(你复核过的 --json 输出)和容差放在一起,提交进仓库,于是一次改动 就是一个可复核的 diff。--tolerance METRIC=VALUE 是该指标允许的最大绝对漂移。
  • laya-evals run ... --baseline baseline.json --tolerance ... 漂移时以非零退出,所以它原样 就能放进 CI。laya.evals.EvalReport.compare 和 assert_regression 为测试暴露了同样的逻辑。

指标门回答的是「数字动没动」。它回答不了「这些是不是同一批数字」,因为 compare 读的是 overall,而且只读 overall —— 所以一份针对某个数据集记录下来的基线,会让另一个数据集上 打分的候选以完全相同的算术通过。EvalReport.comparable_to 补上这一点:它比较 schema、 dataset_sha256 和 questions_sha256,而 run --baseline 和 compare 仍然打印每一个增量, 然后以非零退出失败,点名那个键和两个值:

FAIL: baseline is not comparable: dataset_sha256 (dataset bytes): baseline is <sha>, this run is <sha>

某一侧缺失的键是未知,不是冲突,所以在身份存在之前写下的每一份报告都保持和原来一模一样的 比较行为。这包括下面那个定时门的基线,它来自 research/eval/,完全没有 config.schema。

有两个 CI 场景用到它:

  • .github/workflows/ci.yml 里一个免权重的 job 运行 tests/test_evals.py 和 tests/test_evals_api.py,所以指标数学、数据集解析和 CLI 在每个 PR 上都被覆盖,不用下载 checkpoint;
  • .github/workflows/evals.yml 每周运行一次,发布前和按需运行:它在 MASSIVE 英文套件上评估 英文 checkpoint,并用 research/evals/thresholds.json 里的容差与 research/results/eval_english_51_languages.json 比较。它把报告作为 artifact 上传,不阻塞 PR。

对固定的 checkpoint 版本,harness 是确定性的,所以一份报告可复现。run 会把数据集、模型和 设备,以及这次运行的计时事实,记进报告的 config 块,还有 revisions:每个作答的 checkpoint 实际是从哪个 commit 加载的。--revision <SHA> 为这次运行 加载的每个 checkpoint 固定那个 commit,--revision english=<SHA> 固定某一个 checkpoint(可 重复)—— 这正是自动路由的运行想要的形式,因为三个 checkpoint 是三个仓库,一个 commit 不可能 同时存在于三者之中。不固定时,运行取 checkpoint 的默认分支,报告仍然会说明是哪个 commit 作答, 于是一次基线漂移可以归因到权重或归因到代码。laya/revisions.py 在 PINNED_REVISIONS 里发布 经过复核的 commit SHA,供想主动选用的调用方使用。用 --onnx 时,只有裸的 --revision <SHA> 适用,作用于配置和 tokenizer 的下载。

加入真正的标注集

往 research/evals/ 里放一个 JSONL,旁边放一份复核过的基线,然后把一个 workflow(或 research/evals/check_regression.py)指向这两者。格式和 fixture 一样;harness 里没有任何 东西知道 MASSIVE。

证据检查

evidence 读取 —— 从不写入 —— 一次微调/评测运行已经持久化的产物,并说明存在什么证据、缺了 什么、什么不充分。它不加载模型权重,也不需要 torch。

laya-evals evidence --checkpoint ./my-checkpoint [--report report.json]

一个 checkpoint 目录必须包含 rl_agent_config.json。校准证据来自持久化的 training.laya_train_calibration 块:一个没有训练元数据的旧 checkpoint 是 UNKNOWN;一个 条目数为零的问题类型是 MISSING;一个条目里记录了任何上游 issues 文本(未拟合、低于 MIN_TYPE_N/CALIB_WARN_N、被钳制、拟合后无变化)的类型是 INSUFFICIENT;一次干净的拟合是 PRESENT。这个 helper 信任由 #933 写入的持久化 issues,而不是再维护第二个数值阈值来源。

评测报告的身份字段(schema、dataset_sha256、questions_sha256、laya_version)以与 run 相同的语义报告。checkpoint↔报告 的关系只作为一种确定性冲突来主张:如果两个产物暴露了 相同的 dataset_sha256/questions_sha256 但值不同,它就是 INCOMPARABLE。其他一切都是 UNKNOWN —— 单单 laya_version 匹配从不证明匹配,单单 laya_version 不同也从不证明冲突。