NiceEval 里的 Judge：评开放式输出

Judge 用独立裁判模型评估难以用精确 Match 表达的质量，例如事实一致性、摘要忠实度和说明是否清楚。它的三个 factory 从 niceeval/expect 导出，只构造 ScoreMatch。measurement 是 [0, 1] 内的有限数字。这个区间是统一的数据格式，不表示每个 factory 都会给任意连续分数。 check(subject, match) 登记 Assertion；handle 只配置同一条 entry。

import { closedQA } from "niceeval/expect";

const turn = await t.send("用两句话说明这项变更的风险。");
t.check(
  { input: turn.input, output: turn.message },
  closedQA("回答是否清楚说明了风险？").atLeast(0.8),
).gate().label("风险说明质量");

三个 factory

Factory	用途	当前可能的 measurement
`closedQA(question)`	判断输出是否满足一条开放式标准	`0` 或 `1`
`factuality(reference)`	判断输出是否与参考文本一致	`0`、`0.4`、`0.6` 或 `1`
`summarizes(source)`	判断输出是否忠实总结原文	`0` 或 `1`

factuality 的中间档位有固定含义：提交内容是参考答案的一致子集时为 0.4，是一致超集时为 0.6。它不是按事实条数计算覆盖率。只回答一个事实和回答两个事实，都可能落在同一个 0.4 档位。每次都显式把 Turn 的公开输入与输出组成材料：

t.check(
  { input: turn.input, output: turn.message },
  factuality("退款期限是 30 天。").atLeast(0.9),
).gate().label("退款事实");

跨轮、文件或其他自定义材料也用相同的 check(subject, match)：

const notes = await t.sandbox.readText("NOTES.md");
t.check({
  input: "安装服务并在 NOTES.md 中说明安装和回滚。",
  output: notes,
}, closedQA("文档是否说明了安装和回滚？").atLeast(0.8)).gate().label("操作说明");

文件先经公开 Sandbox API 读取成字符串。Judge factory 不接收路径、{ on }、隐式最后一条输入或单次模型覆盖。跨 session 的材料由作者显式组合。

一条标准对应一个 Judge

先判断评分标准能否独立成立。可以独立判断、独立计权或需要单独显示失败原因的要求，分别登记 Judge Assertion。

t.check({ input: turn.input, output: turn.message }, closedQA("回答是否说明了兼容性风险？").atLeast(1))
  .gate().label("兼容性风险");
t.check({ input: turn.input, output: turn.message }, closedQA("回答是否给出了回滚方法？").atLeast(1))
  .gate().label("回滚方法");

不要把独立要求合成“回答是否准确、完整、清楚，并说明风险和回滚？”。一个 closedQA 只会给这组要求一个 0 或 1，报告无法指出是哪一项失败，也无法给各项不同权重。只有标准描述同一个不可分割的整体质量时，才使用一个 Judge。例如“风险说明整体是否清楚”是一个维度；它的 measurement 可以作为这一项的结果。标准中出现“并且”不一定要拆，但如果其中一半可以成立、可以单独给分或失败后需要单独修复，就应该拆。能用确定性证据验证的条件不交给 Judge。命令是否成功、文件是否存在和工具是否调用，分别使用对应的 Match 或 scoped Assertion；Judge 只评价传入文本中的开放式语义。

声明 capability 和配置

只有评估用例声明了 judge 才能创建 Judge Assertion：

import { closedQA } from "niceeval/expect";

export default defineEval({
  judge: true,
  async test(t) {
    const turn = await t.send("总结需求。");
    t.check({ input: turn.input, output: turn.message }, summarizes("原始需求").atLeast(0.8))
      .gate().label("总结质量");
  },
});

judge: true 声明 capability，并从 Experiment 与项目配置继承字段。
judge: { ... } 同时声明 capability，并按字段覆盖 Experiment 与项目配置。
没有 judge 声明时创建 Judge Assertion 会立即报告作者错误。

// niceeval.config.ts
export default defineConfig({
  judge: {
    model: "judge-model",
    baseUrl: "https://gateway.example.com/v1",
    apiKeyEnv: "JUDGE_GATEWAY_KEY",
    timeoutMs: 180_000,
  },
});

字段优先级是评估用例对象、Experiment、项目配置。未指定时，baseUrl 为 OpenAI 兼容端点，apiKeyEnv 为 OPENAI_API_KEY，timeoutMs 为 180000 毫秒。运行器把解析结果冻结一次，并将同一份配置用于指纹、预检和实际 evaluator。

阈值与分数

通过制评估先用 ScoreMatch.atLeast(n) 形成 threshold，再用无参 .gate() 把 Judge measurement 纳入 failed。每个必须成立的开放式要求使用一条独立 Judge。这样任何一项失败都会使 Attempt 失败，报告也会保留各自的理由。

const quality = t.check(
  { input: turn.input, output: turn.message },
  closedQA("回答是否准确且完整？").atLeast(0.8),
).gate().label("回答质量");
await quality.orStop();

.orStop() 是同一 handle 的 async barrier。低于阈值时它停止当前 continuation；正常 stop 后 Attempt 仍得到 failed Verdict。计分制评估直接调用 .score(n)：measurement m 贡献 m * n。这里的 n 是这一评分项的权重，不是评估的固定总分。多个独立要求分别调用 .score(n)，各项 contribution 再累加。

t.check({ input: turn.input, output: turn.message }, closedQA("回答是否说明了兼容性风险？"))
  .score(8).label("兼容性风险");
t.check({ input: turn.input, output: turn.message }, closedQA("回答是否给出了回滚方法？"))
  .score(12).label("回滚方法");

上例两项各自得到 0 或 1，因此分别贡献 0/8 和 0/12。如果评价的是一个整体维度，也可以只登记一条 Judge，再用 .score(n) 乘这一项的 measurement。例如 factuality 得到 0.4 且该项 .score(20) 时贡献 8 分。这个 0.4 表示固定的“一致子集”档位，不表示完成了 40% 的独立要求。 .atLeast(n) 在登记前形成 threshold Match；它不会改变 contribution，也不会让计分制评估产生 failed Verdict。两种配置都只运行一次 Judge evaluator，写一条 AssertionResult。没有配置 .score() 的 Judge Assertion 默认只保存 evaluation。

配置、预检与失败

没有模型或 key 时，NiceEval 不发网络预检。Judge Assertion 为 unavailable，并保留 judge-model-unresolved 或 judge-key-unresolved 原因。配置了 score 或 .orStop() 的 Assertion 不可用时，Score grading 不可排名；Pass Attempt 为 errored。模型和 key 都存在时，运行器在派发前检查端点。真实预检失败是 setup error，不伪造 AssertionResult。模型请求开始后发生的传输失败是普通 unavailable。无效响应、非有限分数和区间外分数是 errored，NiceEval 不把它们裁剪成可用分数。 Judge 给出的理由写入通用 explanation。evidence 只保存裁剪、脱敏后的判分材料。

结果读取

niceeval view、固定 query operation 和失败反馈从同一份已封口的断言结果生成摘要：失败或不可用项优先显示，已配置的 measurement 显示实际值与 required threshold。Judge 没有专用的断言结果或展示分支。

核心模型

交互与评分

执行模型

NiceEval 里的 Judge：评开放式输出

三个 factory

一条标准对应一个 Judge

声明 capability 和配置

阈值与分数

配置、预检与失败

结果读取

相关阅读

​三个 factory

​一条标准对应一个 Judge

​声明 capability 和配置

​阈值与分数

​配置、预检与失败

​结果读取

​相关阅读

三个 factory

一条标准对应一个 Judge

声明 capability 和配置

阈值与分数

配置、预检与失败

结果读取

相关阅读