defineEval 是编写评估用例的主要入口。每个评估用例文件调用一次,传入描述和 test(t),并默认导出结果。
业务判据、证据和分值怎么组织,见 NiceEval Taste。
不要提供
id 或 name。NiceEval 根据文件路径生成评估用例 ID。defineEval 选项
description
niceeval list 和 view 里;纯说明,不影响调度或打分。
tags
--tag 过滤和 view 分类;与 id 前缀过滤是两套独立的筛选维度。
sandbox
plugins
judge
timeoutMs
metadata
diff
ignore 在默认清单上追加排除;include 优先级最高,把匹配路径显式加回。
合成规则固定为「默认 ∪ ignore,再被 include 打洞」,清单在分类账锚点时冻结。
test
Test context: t
t.note(label, value) 记录供结果审阅使用的 JSON 值或 Quantity,例如 t.note("延迟", ms(512))。
它不登记 Assertion,不影响 Verdict、score 或 coverage。null 显示为 unavailable。
同一 Attempt 的 label 必须唯一,最多 64 项,每项 JSON 不超过 64 KiB;违规时抛出 TypeError。
show @<locator> 和 View 在 Assertions 后展示 Notes;show --json 的 Attempt 结果包含 notes。
show exp:<experiment-id> 按 label 和单位聚合数值,展示 count、min、median、p90、max。
t(TestContext)是评估用例作者在 test(t) 里拿到的上下文。每调用一次检查方法,就登记一条断言。
t.check(subject, match)用匹配条件检查你显式传入的值。t.check(contextualMatch)不传值,由 NiceEval 把当前的只读 ctx 交给匹配条件去读取。t.judge(material, match)把材料交给 Judge 打分,走的是和t.check同一条登记路径。
judge 都要求显式传入材料。官方提供四个现成裁判,它们构造好匹配条件后同样交给 check。closeQA(selector, question) 先用 selector 选出一组材料,再让 Judge 回答一个验收问题。Agent 场景另有 closeQA(question),默认读取当前作用域的完整历史,也可以传入 EventMatch 或 ToolMatch 只看部分事实。
断言默认怎样影响结果,取决于评估的类型:
- 通过制评估里,Boolean 断言默认决定 Attempt 的判定;计分制评估里,Boolean 断言默认只记录,不影响结果。
- 打分类的断言(measurement)默认不会让评估失败。两种评估里,加上
.gate(minimum)后,分数低于下限才算失败。计分制里,同一条断言可以同时加.gate()和.score()。 .orStop()让断言失败时停止后续步骤。Boolean 断言直接用自己的结果;measurement 写.orStop(minimum),或者在.gate(minimum)后面写不带参数的.orStop(),沿用 gate 的下限。
t.score(ratio, { weight: 50 }).label("完成耗时") 登记。ratio 是 0 到 1 之间的数,weight 是非负的有限数。结果里会保留 ratio、对应的分值和实际得分。依据的数值材料拿不到时,这一项的得分记为未知。
defineScoreEval 的 ScoreTestContext 还提供 t.score(n),直接登记一项得分;已有的断言用 .score(n) 计入分数。两处的 n 都必须是不小于零的有限数,写 0 也算一项明确的得分。工具调用的匹配与计数规则见 匹配工具调用。全部成员如下:
simulatedUser
note
evaluationKind
send
sendFile
requireInputRequest
respond
respondAll
reply
sessionId
events
eventOccurrences
newSession
signal
model
reasoningEffort
flags
progress
diagnostic
log
skip
group
check
agentJudge
judge
toolCalls
sandbox
observability
usage
succeeded
toolOrder
eventOrder
usedNoTools
maxToolCalls
noFailedActions
event
notEvent
elapsedMs
maxTokens
maxCost
closeQA
closeQA
closeQA
Judge 打分
先用defineJudge 声明评分标准,再直接交给 t.check 或 t.judge:
judgeImage() 生成的图片,登记时就会保存一份快照。
Judge 用哪个模型按顺序决定:先取项目配置的 judgeProvider,再应用评估用例的 judge,最后应用 Experiment 的 judge。后一层给的是完整 Provider 时,会整体替换服务和执行配置;只给模型字符串时,只换掉已选 Provider 的模型。评估用例的 judge 只决定这道题用哪个模型或 Provider,不限制能用哪些匹配条件。
通过制和计分制都可以调用 .gate(minimum)。计分制还可以调用 .score(n),gate 失败时仍保留这一项的得分。
二值裁判
只需判断满足或不满足时,从niceeval/expect 导入 binaryJudge:
binaryJudge(options: BinaryJudgeOptions) 返回普通 ScoreMatch。BinaryJudgeOptions 是不含 anchors 的 JudgeOptions:
rubric 必填,maxCalls 与 maxMaterialBytes 可选,校验和预算与 defineJudge 相同。
它只分类为 satisfied 或 not-satisfied,分别得到 1 或 0。.score(n) 因而只给满分或零分;必须满足时使用 .gate(1)。
非法输出、预算不足或服务故障保留错误或不可用状态,不计作零分。审计保留类别、理由和映射结果,供 show @<locator> assertions 查看。
图片材料
从niceeval/judge 导入 judgeImage,它会立即复制一份原图数据。限制如下:
- 格式只支持 PNG 和 JPEG。
- 每张最多 4 MiB、16,777,216 像素。
- 每条断言、每次模型请求最多引用 4 次图片,合计不超过 8 MiB。同一张图重复引用也会计数。
- 每个 Attempt 最多保存 32 MiB 图片。
OpenAIProvider、VercelProvider 和 OpenRouterProvider 默认不发送图片,需要显式设置 supportsImages: true,并选一个同时支持图片和工具调用的模型。TypesafeProvider 不支持图片。不支持时返回 judge-capability-unavailable,不会把图片换成文字描述再评分。
judgeImage
JudgeImageInput
body
mediaType
现成裁判与自定义 Match
defineJudge 和现成裁判都返回 ScoreMatch,可以直接交给 t.check。t.judge 只是同一条路径的简写,所以登记、快照、预算、打分、审计和结果保存都只发生一次。
例如,直接使用
instructionFollowing() 的实例:
faithfulness 先从输出里提取事实,再逐项判断,最后由代码算比例。提取不完整时没有有效得分。TypeSafe 不支持 extract,所以在 TypesafeProvider 上结果为 unavailable,不会改成整体估一个分。
pairwisePreference 按固定顺序比较一次,适合一个候选和一个参考之间的比较。
closeQA 把选中的全部材料按原顺序一次交给 Judge,Judge 只根据这些材料回答验收问题。
Agent 场景可以用 turn.closeQA(question)、session.closeQA(question) 和 t.closeQA(question)。传入 EventMatch 时只看匹配的事件,传入 ToolMatch 时看匹配的工具调用的完整信息。
材料的情况会影响结果:选中的材料完整但为空时,得分为 0,不调用模型;材料不完整、无法判断或超出上限时,结果为 unavailable,不会截掉一部分再评分。
需要把多个模型步骤组合起来时,用 defineScoreMatch 的 score(value, context) 自己写评分逻辑。context.llm 提供 score、classify、extract 和 batchClassify,都返回 Effect。
它们和现成裁判共用调用预算、超时设置和审计记录。
- 静态的配置校验不会发网络请求。Provider、模型或 key 缺失时,也不会发请求。
- 聊天类服务用强制函数调用(forced-function)请求,TypeSafe 用
/systemone接口,两者都会严格校验响应。 - 网络传输出错或超时,结果为 unavailable;HTTP 400 或协议不兼容,结果为 errored。
Turn 返回类型
t.send(...) 返回一个 TurnHandle。它包含从事件流整理出来的常用字段,以及一整套只针对这一轮的断言。
calledTool 和 notCalledTool 也是 Turn 上的断言,匹配和计数规则见 匹配工具调用。Turn 只检查当前轮,Session 检查调用处之前的全部轮次;根 t 检查调用时已启动 Session 的各自前缀。之后发生的调用不进入已登记的断言。
turn.inputRequests 是本轮事件里全部 input.requested 请求的只读、深冻结投影,顺序与事件流一致;没有请求时为 []。
它适合读取任意数量的请求,已有 requireInputRequest 仍要求恰好一个匹配请求。
input
events
inputRequests
toolCalls
eventOccurrences
status
reply
data
usage
check
agentJudge
judge
succeeded
toolOrder
usedNoTools
maxToolCalls
noFailedActions
event
notEvent
eventOrder
elapsedMs
maxTokens
maxCost
closeQA
closeQA
closeQA
测试集导出
file/0000、file/0001,依此类推。
已经有稳定的业务 key 时,也可以默认导出 Record<string, EvalDef>。例如 swelancer.eval.ts 里的 key 15193 会生成 swelancer/15193。key 必须是非空的单段路径,不能是 . 或 ..,不能包含 /、\\ 或控制字符。评估用例按 key 的字典序排列。
从 ctx 读取材料,以及官方用量统计
defineMaterialMatch<C,T>({ name, read, match, capture? }) 定义一组从 ctx 读取的材料,可以从 niceeval 或 niceeval/expect 导入。Adapter 的 create 提供应用自己的 ctx。在 check 或 closeQA 登记时,NiceEval 把当前的只读 ctx 传给 read。
read 返回 { state: "complete", items: [{ id, value }] },或者返回带 reason 的 partial 或 unavailable 状态。每项的 id 在本组内不能重复,最长 128 个 UTF-8 字节。
capture 控制保存多少材料,默认最多 256 项、48 KiB,最高可以调到 16384 项、4 MiB。
check(materialMatch) 返回 Boolean 断言,默认至少有一项满足条件才算通过。closeQA(materialMatch, question, options?) 返回 Judge 打分的断言:question 不能为空,最长 8 KiB;options 的类型是 JudgePresetOptions。选中的全部材料按原顺序一次交给 Judge。材料完整但为空时,得分为 0,不调用模型。
Agent 场景的 read 从 AgentMatchContext<Scope> 读取 NiceEval 整理好的工具调用(toolCalls)或事件(eventOccurrences),再分别用 ToolMatch 或 EventMatch 匹配。
defineContextMatch<C,T>({ name, read, match, capture? }) 从 ctx 读取单个小的值。read 返回 { state: "available", value } 或 { state: "unavailable", reason }。配 BooleanMatch 时得到 Boolean 断言,配 ScoreMatch 时得到打分类断言。值拿不到时,不会调用评分逻辑。
t.usage 读取 NiceEval 官方记录的用量,读取时就固定下来。失败和重试的调用、缓存的分桶以及费用的计算依据都会保留。
- 普通 Adapter 的用量依据是记录下来的每一次调用(
recorded-calls)。 - Agent 的用量依据是每次发送时上报的数字(
reported-sends),可以按 Turn、Session 或 Attempt 查看。 usage.totalTokens等字段是 NumericMaterial。不知道的值保持未知,不会补成 0。
t.maxTokens(max) 限制 token 总量。t.maxCost(usd) 按美元成本限制:优先用实际扣费金额,扣费为 0 也算;没有实际扣费时,才用你显式配置的价格算出的估算。
t.elapsedMs 是从 Attempt 开始到读取这一刻经过的毫秒数,可以交给 t.check(..., atMost(limit))。业务里“第一次完成”的时间点仍要用业务自己的匹配条件判断。
Sandbox 结果断言
这组方法检查 agent 在每次发送窗口两端之间产生的工作区变化,返回只能配置 key、label、group、optional 和 gate 的 post-run 断言句柄。changedPaths(["src/a.ts"]) 要求恰好修改这个文件;changedOnlyWithin(["src"]) 允许不改文件,也允许只改 src 内的部分文件。后者按路径组件匹配,agents 不覆盖 agents-old;至少提供一个范围,空数组请改用 noChanges()。
路径含 * 或 ? 时抛出 TypeError:不支持 glob,目录前缀直接写目录名。
unchangedWithin(["agents", "niceeval.config.ts"]) 保护运行配置,允许修改其余文件;它与 changedOnlyWithin 不是逻辑取反。路径组件、glob 和空数组的拒绝规则与允许范围检查相同。
只关心文件路径时,两种检查都使用 { content: "none" }。它只拿正则表达式与 agent 变化路径比较,不读取变化行。binary 或 oversized 内容省略不影响结果;归因材料采集失败或不完整时仍为 unavailable。默认的 both 会同时扫描变化行,所选内容被省略时可能无法判定。
inDiff 不扫描未变化上下文。没有命中且所选内容被省略时,结果为 unavailable;路径或已知变化行命中时仍可确定满足。匹配的证据保留首个命中路径与有界预览。只想匹配内容时,pattern 应避免命中路径。
这些断言沿用 diff.ignore 和发送窗口归因。作者自己写入的 Fixture 不算 agent 变化;同一次发送内恢复原状没有端点变化,不同发送间修改后还原仍会保留变化。材料采集失败或不完整时为 unavailable;内容被省略时,仅依赖该内容的匹配无法判定,不会伪装成匹配。