Diagnosis Eval Data Schema

这份文档记录评测基准里的数据结构。口语化理解就是：

用例文件说“我要考什么”
trace 文件说“Agent 实际做了什么”
评测结果说“这次有没有跑偏”
汇总报告说“整体稳定性怎么样”

当前这套评测是代码规则判断，不是再调用一个 LLM 来打分。

1. 用例定义

文件：mvp/eval/cases/diagnosis-cases.json

每一条 case 是一个固定考题，告诉评测器“这个问题应该看哪些点、需要哪些证据、哪些结论可以接受”。

{
  "id": "payment-timeout",
  "title": "Payment API timeout",
  "question": "支付接口最近出现超时，请结合知识库、日志和指标判断可能原因，并给出修复建议。",
  "traceFixture": "payment-timeout-pass.json",
  "expectedRootCauseKeywords": ["支付", "超时", "连接池"],
  "minKeywordMatches": 2,
  "requiredEvidenceTools": ["lookup_knowledge", "query_logs", "query_metrics"],
  "allowedVerdicts": ["PASS", "LOW_CONFID"],
  "forbiddenAnswerKeywords": ["无证据确定"]
}

字段说明：

字段	意思	评测器怎么用
`id`	这条用例的唯一名字	出现在报告里，方便定位是哪条 case 挂了
`title`	给人看的标题	出现在结果里，方便快速理解场景
`question`	要问 Agent 的问题	fixture 模式下不会真的发送给 Agent，但它记录了这条 case 的原始输入
`traceFixture`	对应的 trace 文件名	评测器会去 `fixtures/` 目录加载这个文件
`expectedRootCauseKeywords`	最终回答里希望看到的关键点	评测器会在 `session.answer` 里做关键词命中检查
`minKeywordMatches`	至少要命中几个关键词	命中数低于这个值，就认为根因覆盖不够
`requiredEvidenceTools`	这条 case 至少应该用到哪些证据工具	评测器会检查 trace 里是否出现这些工具
`allowedVerdicts`	Verifier 允许给出的结论	比如 `PASS` 或 `LOW_CONFID`，不在列表里就失败
`forbiddenAnswerKeywords`	回答里不应该出现的危险说法	命中这些词，说明回答可能过度自信或不符合降级策略

2. Trace Fixture

目录：mvp/eval/fixtures/*.json

trace fixture 是一次 Agent 运行后的“留痕快照”。评测器不会关心整个 trace 的所有字段，只读取当前能支撑基准判断的字段。

当前会读取这些字段：

Trace 字段	意思	评测器怎么用
`session.answer`	Agent 最终给用户的回答	用来检查根因关键词和禁用词
`session.totalDurationMs`	这次运行耗时	进入报告，帮助观察性能是否明显变差
`session.selfEvaluation.verifier_evaluation.verdict`	Verifier 对最终回答的判断	必须存在，并且要落在 case 的 `allowedVerdicts` 里
`session.selfEvaluation.verifier_evaluation.tool_trace_summary[*].tool_name`	Verifier 总结里看到的工具证据	用来补充判断证据工具是否出现
`toolInvocations[*].toolName`	Agent 实际调用过的工具名	用来检查 `requiredEvidenceTools` 是否满足
`toolInvocations[*].success`	工具调用是否成功	当前主要保留在 trace 里，后续可以升级成更严格的成功率检查

简单说，trace 里最重要的是三类信息：

最终回答：它说了什么
工具证据：它查了什么
Verifier：它自己有没有承认这个结论可靠

3. 单条评测结果

Java 类型：DiagnosisEvalResult

这是每条 case 跑完之后的判断结果。

字段	意思
`caseId`	对应的 case id
`title`	case 标题
`passed`	这条 case 是否通过
`failedChecks`	没通过的具体原因，比如缺工具、关键词不够、verdict 不允许
`verdict`	从 trace 里读出来的 Verifier verdict
`matchedKeywordCount`	最终回答命中的关键词数量
`requiredKeywordCount`	case 定义里一共有多少个关键词
`evidenceCoverage`	每个必需工具是否出现，例如 `{ "query_logs": true }`
`toolCallCount`	本次 trace 里工具调用总数
`durationMs`	本次 trace 的耗时

判断通过的口语化规则：

回答要说到关键点
该查的证据工具要查到
Verifier 的结论要在可接受范围内
回答不能出现危险的过度自信表达
如果是 REJECT，就必须走降级模板

4. 汇总报告

Java 类型：DiagnosisEvalReport

这是整个基准集跑完之后的总结果。

字段	意思
`totalCases`	总共评测了多少条 case
`passedCases`	通过了多少条
`passRate`	通过率，范围是 `0.0` 到 `1.0`
`verdictDistribution`	Verifier verdict 的分布，比如有几个 `PASS`、几个 `LOW_CONFID`
`averageToolCallCount`	平均每条 case 调用了多少次工具
`averageDurationMs`	平均耗时
`results`	每条 case 的详细结果列表

5. 怎么看这个基准

这套结构不是为了证明 Agent 永远正确，而是为了在每次改 prompt、工具、检索、Verifier 之后，有一个固定尺子能回答：

以前能过的诊断题，现在还过不过？
它是不是少查了某些证据？
它是不是变得更自信但证据不足？
它是不是开始输出不该说的话？
它是不是明显变慢了？

所以面试里可以这样讲：

我没有只看一次 demo 效果，而是把典型诊断场景固化成 case。
每条 case 都定义预期关键点、必需证据工具和可接受的 verifier 结论。
Agent 每次运行会留下 trace，评测器用代码规则读取 trace，输出结构化报告。
这样我改 Agent 的时候，可以用同一套基准判断有没有行为回退。

5.7 KiB Raw Blame History