> ## Documentation Index
> Fetch the complete documentation index at: https://base.bangwu.me/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 产品评测

> 从真实 trace 建立 AI 产品评测：发现失败模式、构造最小回归用例、校准 LLM 裁判，并区分 CI 回归测试、线上监控与运行时护栏。

# AI 产品评测

模型 benchmark 帮你选择起步模型；**产品 eval** 检查的是实际应用能否完成用户目标，包括提示词、检索、工具、权限和业务代码。回答流畅，不代表请求的操作真的成功了。

本页综合 Hamel Husain 的评测卡片、FAQ 与 OpenAI 官方评测指南，是 [Agent harness](/zh/env/agent-harness) 的实操补充：harness 控制执行，eval 提供行为是否正确的证据。

## 先看失败，再建看板

**Trace** 是从用户请求到最终结果的执行记录，包括消息、检索上下文、工具参数与结果，以及相关状态变化。多 Agent 流程应保留共同的 trace ID、事件来源和先后顺序。

1. **收集多样样本。** 混合随机抽样、不同工作流、负面反馈、重试和异常慢的请求。即使已知道要找什么错误，也保留一部分随机抽样。
2. **先写开放式笔记。** 让理解产品的人先看实例，再让自动评审器建议标签。记录用户遇到了什么问题，包括普通代码缺陷和设计问题，不只盯模型错误。
3. **归纳重复失败。** 把笔记整理成具体类别，例如“预约了不可用时段”“工具失败后仍声称成功”。再按相关标准标注 pass/fail，并保留证据。
4. **排序并持续复查。** 综合频次、影响和修复成本，继续看数据，直到新样本不再带来或改变失败类别；产品有重要变化后重新检查。

Hamel 建议准备约 100 条多样 trace，并先做一轮人工标注。这是起步经验，不是统计保证，也不意味着样本少时就不能开始。

**发现问题与估计发生率需要不同的采样方式。** 专挑重试请求能帮你找问题，但这批数据的失败率不等于生产失败率。记录采样方法；估计发生率时，使用有代表性的抽样或明确的加权方案。分享 trace 或交给外部裁判前，先去除密钥和不必要的个人信息。

## 把失败变成回归用例

阅读长对话时，先定位最上游的第一处失败，不要把它引发的后续连锁反应都当成独立问题。保留完整 trace 供排查，再缩小复现范围。

以一个虚构的预约 Agent 为例：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
用户：预约 10:00 的时段。
工具结果：10:00 不可用。
Agent：仍调用预约工具预订 10:00。  <-- 第一处失败
Agent：告诉用户预约已确认。
```

最小测试可能只需要用户请求和可用性查询结果。**N-1 测试**就是回放失败步骤之前的有效对话前缀，再检查系统下一步会做什么。预期行为放在输入之外，不要把原来的错误答案或评分标签喂给被测系统。

一份实用的测试记录可以包含：

| 字段 | 用途 |
| - | - |
| `case_id`、`source_trace_id` | 把回归用例关联到原始证据 |
| `input_prefix`、`tool_fixtures` | 重现相关对话与工具状态 |
| `criterion`、`expected_behavior` | 定义单项行为，而非模糊的质量总分 |
| `app_version`、`prompt_version`、`model` | 标识测了哪个系统版本 |
| `rubric_version`、`judge_version` | 标识用什么标准与裁判评分 |
| `result`、`evidence` | 保留结果及对应的工具事件或文本证据 |

在沙箱中使用模拟工具或隔离测试账号回放，不要调用真实预约、支付或删除接口。工作流或工具 schema 大幅变化后，重建过期 fixture。仍需保留端到端测试：单个“下一步”检查通过，不代表完整会话能成功。

## 选择最便宜且可信的检查

| 要检测的失败 | 优先方法 | 检查什么 |
| - | - | - |
| 输出 schema 不合法、字段缺失 | 代码断言 | 解析并校验实际输出 |
| 工具参数错误、越权操作 | 代码断言与运行时权限检查 | 在动作边界检查参数、身份和状态 |
| 工具结果不支持回答中的成功声明 | 人工审查，必要时使用已校准的 LLM 裁判 | 对照最终回答与相关执行证据 |
| 整体体验不好 | 人工审查与产品实验 | 先定位具体失败，再考虑自动化 |

先修提示词中明显漏写的要求和普通 bug；有价值时补便宜的回归测试。重要的语义错误需要反复衡量时，再投入 LLM 裁判。**已知安全要求不必等真实事故发生才测试**，例如授权检查和不可逆操作。

优先使用范围明确的 pass/fail，而不是未定义的“质量 4/5”。预约案例里，把“没有预约不可用时段”和“没有把未确认的预约说成成功”拆成两项，它们需要不同的证据。含义明确且经过验证时，数值评分或成对比较仍有价值；二元标签是实用默认值，不是普遍定律。

语义裁判可以返回一个简短的结构化结果：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "criterion": "no_false_confirmation",
  "verdict": "fail",
  "evidence": "预约工具返回冲突，但最终回答声称已确认。"
}
```

这是示意格式，不是某个厂商的 API。应让人能复查所引用的事件。缺少证据或裁判超时属于需要处理的评测错误，不能自动算作通过。

## 检查路径、完整会话与最终状态

LangChain 的 Agent 评测指南区分了多种评测范围。根据失败发生的位置，选择真正能发现它的检查范围：

| 范围 | 检查示例 | 需要的证据 |
| - | - | - |
| 单步 | 工具拿到的日期是不是用户要求的？ | 工具参数与当前请求 |
| 最终回复 | 确认消息是否符合预约结果？ | 最终消息与工具结果 |
| 完整会话 | 最终预约是否体现了几轮之前的改期要求？ | 按会话／thread ID 汇总的有序轮次 |
| 环境状态 | 是否只存在预期的那笔测试预约？ | 运行后隔离测试系统中的记录 |

每一轮看起来都合理，整体任务仍可能失败。反过来，不同的工具调用顺序也可能得到同样正确的结果。应断言必要约束，例如写入前经过审批、不重复预约；除非顺序本身就是需求，否则不要只接受一条固定轨迹。

对于会改变状态的任务，每次评测都从干净、已知的 fixture 开始，运行后检查真实状态。编码任务可以检查仓库测试和最终 diff，而不是只读 Agent 的“已完成”。将可信评分检查放在 Agent 可修改的工作产物之外，不要只依赖 Agent 自己写或改过的测试判定成功。

容器是隔离这类任务的一种方式，不是所有 benchmark 的定义，本身也不是完整的安全边界。按测试需要限制凭证、网络、挂载和运行时间。记录 fixture 版本、工具配置、评分结果与 trace；必要时重复运行随机性较强的用例，报告尝试次数与通过次数。基础设施错误和超时单独记录，不要悄悄排除或算作成功。

## 用人工标签校准裁判

第二个模型的意见不是标准答案。为同一项标准收集人工标注的通过与失败样本；定义有歧义时，先澄清，再调裁判。

按用途隔离样本：

* **训练／示例集：** 从中选择裁判提示词里的 few-shot 示例。
* **开发集：** 修改评分规则，分析裁判与人的分歧。
* **留出测试集：** 检查泛化，不根据这里的标签调参。同源 trace 及其改写版本应放在同一分组，避免跨集合泄漏。

不存在通用切分比例或合格分数。Hamel 的卡片给了示例比例，FAQ 则强调应按漏检与误报的代价选择目标。

先明确正类。本页约定：**正类代表实际存在失败**。

* **TPR／失败召回率** = `TP / (TP + FN)`：人工标为失败的样本中，裁判抓住了多少。
* **TNR／特异度** = `TN / (TN + FP)`：人工标为通过的样本中，裁判正确放行了多少。

如果 100 个样本中 95 个合格，永远输出“通过”的裁判也有 95% accuracy，但**失败召回率为 0%**。同时报告两项指标及其样本数；某类没有样本时，对应指标是未定义，不是 100%。小样本仍会带来很大的不确定性。

裁判模型、评分规则或应用数据分布变化后，重新检查人机一致性。看具体误报与漏检，而不只是优化总分。将应用模型／提示词与评分器配置一起版本化，才能解释分数为什么变化。

## 区分回归测试、监控和护栏

| 位置 | 数据与时机 | 目标 | 失败后做什么 |
| - | - | - | - |
| CI／发布前 | 合并或发布前运行精选回归用例 | 发现已知问题回归 | 按明确验收标准阻止变更 |
| 线上监控 | 抽样真实 trace，通常异步执行 | 发现新失败、跟踪漂移 | 告警、调查、补充用例 |
| 运行时护栏 | 对受保护的每个请求或动作同步检查 | 阻止特定有害操作或响应 | 拦截、请求审批或安全降级 |

回答后的检查可以发现一次错误购买，却不能阻止那次购买。必须在**副作用发生前**、模型之外执行权限控制。护栏还需要延迟和误报预算；检查失败时，不要盲目重试付款等写操作，参见[购买审批边界](/zh/env/agent-harness#把候选查询与购买审批分开)。

CI 通过率不是用户满意度的估计：回归集会故意增加已知失败的占比。同样，全绿只证明覆盖范围内的检查通过。持续加入经过独立审查的生产失败与有针对性的边界用例，并在代码、提示词、模型、检索或工具变化时重跑相关评测。

## 最小起步清单

* 和产品／领域专家一起审查一小批多样样本。
* 命名一个重要失败，保留对应 trace 证据。
* 用最小、安全的 fixture 复现，写清断言或评分规则。
* 用人工标注的通过与失败样本验证自动裁判。
* 在同一批版本化用例上比较当前系统与候选系统。
* 明确失败由谁处理，把新的生产案例回流到测试集。

## 参考资料

* [meng shao：Agent Evals 常见问题](https://x.com/shao__meng/status/2110585984564039900) — 2026-10-15 的 Folo 线索

* [LangChain：The Most Common Questions About Agent Evals, Answered](https://www.langchain.com/blog/common-questions-about-agent-evals) — 单步、完整会话、执行轨迹与环境终态评测

* [meng shao：Pocket Guide to AI Evals](https://x.com/shao__meng/status/2109445747133579381) — 2026-10-12 的 Folo 线索，指向 Hamel 原始卡片

* [Hamel Husain：Evals flashcards](https://hamel.dev/notes/llm/evals/flashcards/) — 重点参考错误分析、裁判验证、trace 用例与部署卡片

* [Hamel Husain：AI Evals FAQ](https://hamel.dev/blog/posts/evals-faq/) — 采样、评估器选型、校准与多轮调试

* [Hamel Husain：Your AI Product Needs Evals](https://hamel.dev/blog/posts/evals/) — 以范围明确的测试和人工审查打基础

* [OpenAI：Evaluation best practices](https://platform.openai.com/docs/guides/evaluation-best-practices) — 任务专属评测、人工校准、边界情况与持续评测


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.