Ai App Eval Builder

---
name: ai-app-eval-builder
description: Use when an LLM, RAG, agent, chatbot, copilot, extraction, classification, generation, or prompt/model change needs a risk-based eval dataset, reproducible graders, slice-level release gates, or an offline-to-production quality loop.
---

# AI 应用评测设计器

## 中文简介

**AI 应用评测设计器**把“回答看起来不错”转成可审查的质量工程：从用户任务、能力边界和失败后果拆解指标，建立版本化离线数据集和线上生产样本回流，组合确定性检查、人工评审与经校准的 LLM judge，并按高风险切片给出发布决定。它不把单一平均分、一次演示或未校准的主观评分当成上线证据。

## 使用背景

AI 应用会随模型、提示词、检索索引、工具、权限和真实用户分布而变化。只用静态黄金答案容易遗漏生产失败；只看生产指标又难以复现和回归。可靠评测需要离线数据集用于可重复比较，再把脱敏的线上失败、漂移和人工升级样本带回候选集，形成可追溯闭环。不同系统的错误也必须分层：RAG 的检索失败不能被“答案不错”掩盖，Agent 的越权工具调用不能被最终文本正确抵消。

## 核心原则

- 先将用户目标拆成 `C-*` 能力和 `R-*` 风险；每项写可观察成功、失败成本、受影响切片与不可接受结果。
- 数据集是版本化产品，不是一次性 prompt 列表：黄金集、生产失败、困难样本和对抗样本均记录来源、代表性、隐私、去重和纳入理由。
- 先使用可解释的确定性检查；语义质量再用人工或 LLM judge，三者可组合但不得相互替代。
- rubric 必须定义输入证据、评分等级、通过边界、正反例和冲突处理，使不同运行、评审者和版本可复现。
- 人工与 LLM judge 都需要校准集、盲评、分歧率和复核规则；judge 不能看到候选身份或先前分数来替代证据。
- 按风险切片、失败类型和置信区间比较 baseline 与 candidate；总体平均只能作摘要，不能覆盖任一阻断切片或硬性安全约束。
- 同时记录质量、成本、p50/p95 延迟、超时/重试率与稳定性；质量提升若突破预算或可靠性门槛，不能直接发布。
- 每次结论绑定 baseline、candidate、dataset、retrieval/index、grader/rubric、模型/提示词和运行环境版本；未运行、未知和失败保留原状。

## 适用场景

- 为聊天、提取、分类、摘要、生成、RAG 或 Agent 上线前建立离线回归套件和发布门禁。
- 比较模型、system prompt、工作流、检索器、chunking、reranker、工具 schema、权限策略或超时/预算策略。
- 将真实投诉、人工升级、失败 trace 和生产漂移转为脱敏、审核过的评测候选样本。
- 需要解释某个切片、故障类型、工具调用或检索阶段为何退化，而不是只报告一个准确率。

## 不适用场景

- 目标用户、任务成功定义、允许数据/工具或失败成本未知时，不编造阈值；先补 `C-*`/`R-*` 和停止条件。
- 只想用单一“准确率”或偏好分给开放式助手发布背书时，拒绝压缩质量维度；先按任务、风险和切片设计多个可观察判定。
- 需要修复某一已知线上事故时，先用 `bug-debugging-playbook` 建立原因证据；本 Skill 交付评测与门禁，不声称已修复系统。
- 需要直接实现评测平台、索引或 Agent 时，另建工程计划；本 Skill 不虚构 API、生产权限、日志或运行结果。

## 输入要求

将事实与不确定性标为 `[事实]`、`[推断]`、`[假设]` 或 `[未知]`，不可把示例、日志摘要或模型印象写成事实。

1. 产品和能力：用户/调用方、任务、成功与失败结果、输出/引用格式、非目标和发布决定。
2. 风险：安全、合规、资金、隐私、错误行动、拒答、时效、品牌与可恢复性，以及各风险影响的用户切片。
3. 系统与版本：baseline/candidate 的模型、提示词、参数、代码、检索/index/chunking、工具 schema/权限、部署环境和可复现运行配置。
4. 数据：黄金集、生产失败/升级、困难和对抗候选，采样窗口、来源分布、许可/脱敏、保留期和真实用户分布的代表性证据。
5. 评分与资源：已有 rubric/标注、确定性契约、人工 reviewer、LLM judge、预算、p50/p95 延迟、吞吐、可用性和运行频率。
6. 线上观测：事件/trace、用户反馈、人工覆盖、告警、漂移信号、回流 owner 及禁止收集的数据。

## 信息不足时的处理

- **成功或风险未知：** 只交付澄清问题、候选 `C-*`/`R-*`、可观察信号和停止条件；不设“95%”之类任意阈值。
- **生产样本不可用：** 先声明离线代表性限制，使用经领域审核的合成/历史黄金集，并规定取得脱敏失败样本后的回流条件；不声称已代表生产。
- **参考答案不唯一：** 写行为 rubric、允许答案集合或 pairwise 规则；不要以字符串完全一致给开放式任务判错。
- **人工或 judge 资源不足：** 优先确定性硬门禁和风险最高切片，抽样人工校准；未校准的 LLM judge 只能探索，不得单独做发布结论。
- **版本、日志、成本或延迟未知：** 标为 `GAP-*`；不比较未知版本，也不以质量结果掩盖运行预算或稳定性缺口。
- **敏感数据不能进入评测：** 去标识、最小化字段、访问控制和保留期先获批准；无法安全处理时只记录聚合指标或合成替代，并降级结论。

## 工作流

1. **建立评测卡。** 记录发布决定、基线、候选、事实/未知、范围和停止条件；将用户可见能力编号为 `C-*`、不可接受失效编号为 `R-*`。
2. **拆能力、风险与切片。** 为每个 `C-*` 写成功观察、失败成本、风险等级、用户/语言/任务/权限/上下文/数据新鲜度切片；不要从总体分反推风险。
3. **构建版本化数据集。** 将黄金集、生产失败、困难和对抗样本分别标为 `D-*`，记录来源、采样窗口、代表性、隐私、难度、风险、预期行为和 dataset version。用语义/文本近似、来源和时间窗口检查训练/提示/索引泄漏与重复，并将相近 case 成组后拆分到同一集合。
4. **定义分层期望。** RAG 分开记录 query、候选文档、检索相关性/召回、证据覆盖、回答忠实性/完整性/引用；Agent 分开记录初始状态、允许工具/权限、每步轨迹、工具选择、参数、结果、循环/终止和最终任务结果。
5. **设计 grader 与 rubric。** 每个 `G-*` 指明输入、版本、方法、确定性程度、等级、阈值、正反例、失败代码和不适用条件。先放 schema、JSON、引用存在、权限、工具参数、禁止调用、步骤/预算等确定性检查；再补人工和 LLM judge。
6. **建立失败分类与处置台账。** 为每种可行动失效分配稳定 `Failure-*` 代码，记录定义、RAG/Agent/其他层、受影响切片、频率/严重性、可能修复与 owner、关联生产样本和回归 case。每个失败的 `G-*` 判定与 `E-*` 运行记录必须回链一个 `Failure-*`；新现象先登记再聚合，不用自由文本替代。
7. **校准人工与 LLM judge。** 用冻结的校准集让至少两名 reviewer 独立盲评，记录一致率/分歧与裁决。LLM judge 固定模型/提示词/参数/输出 schema，随机化候选顺序、交换 A/B 位置、限制或归一化长度、隐藏候选名称和先前分数，并与人工金标比较偏差；不通过校准不得进入主门禁。
8. **运行可重复比较。** 固定或记录随机 seed、并发、重试、超时、地区和依赖版本；对同一 `D-*` 同时运行 baseline/candidate，保存输入、输出、trace、grader 结果、token/成本、p50/p95 延迟、失败/波动和时间戳为 `E-*`。失败结果回链 `Failure-*`，并聚合其频率、严重性与切片分布。
9. **按切片判定与诊断。** 同时报总体和每个高风险切片、`Failure-*`、RAG 阶段或 Agent 轨迹指标；计算样本量/置信限制。硬门禁、最差关键切片、回归幅度、成本/延迟/稳定性任一失败即阻断，不用平均分抵消。
10. **发布与线上回流。** 输出通过/有条件通过/不通过及 owner、监控、灰度、回滚和复跑条件。上线后按窗口把经隐私审查的生产失败、人工升级、投诉、分布漂移和成功对照转为候选 `D-*`，去重、标注、版本化并关联 `Failure-*` 后才加入下轮离线集。

## 专业判断规则

### 数据集、代表性与泄漏

- 黄金集用于稳定回归，不等于真实分布；生产失败应按影响和频率采样，困难样本验证边界，对抗样本验证鲁棒/安全。每一类都写目标比例、当前覆盖和不能代表的群体。
- 数据集切分以用户、会话、文档族、时间窗口、模板和近重复簇为单位，避免同一答案、文档、问题改写或泄漏到训练、few-shot、prompt、索引和评测两侧。记录检测方法、阈值和人工复核。
- 生产 trace 进入离线集前移除直接标识符、秘密和不必要上下文，保留来源类别与时间窗；未经审批的原始内容不能复制到 prompt、示例或 judge。

### Grader、rubric 与校准

- 确定性 grader 适合 schema、字段、允许枚举、数值、引用 ID、工具/权限、参数范围、状态转换、终止和预算；它不证明开放式有用性或事实正确性。
- rubric 每级使用可观察条件而非“优秀/合理”，注明证据优先级、错误严重度、允许不确定/拒答方式和正反例。评分规则、标注指南和 grader prompt 都有独立版本。
- 人工校准应记录盲评者、样本、分歧矩阵、裁决和复训触发。高风险失败、judge 与人工不一致、低置信和新切片优先人工复核。
- LLM-as-judge 需要检测并缓解顺序、自偏、长度和位置偏差：候选匿名化；随机/反转顺序与位置；长度上限或等长摘要；禁止用 judge 同源候选身份作为优势；固定版本/温度/schema；用人工金标、反转一致性和错误样本校准。对校准外任务不外推发布结论。

### 失败分类与处置

- `Failure-*` 是跨 dataset、grader、baseline 和 candidate 版本稳定的失败代码；格式使用 `Failure-<DOMAIN>-<CAUSE>`，已发布代码不改义、不复用。定义必须给出纳入/排除边界，避免把不同根因混入“回答错误”。
- 层级至少区分 RAG 检索/排序、RAG 答案/引用、Agent 工具选择/参数/权限/循环/副作用，以及其他模型/格式/安全/运行时。每项记录受影响切片、运行频率、严重性、可能修复、责任 owner、关联生产样本 `D-*` 和回归 case `D-*`。
- `G-*` 的每个 fail label 必须映射一个 `Failure-*`；`E-*` 的失败数、样本和 trace 必须回链相同代码。无法分类的失败先记为带 owner 和截止条件的稳定 `Failure-OTHER-UNCLASSIFIED`，完成复核后新增具体代码，不回写改变历史结果。

### RAG、Agent 与运行指标

- RAG 必须将检索与答案分层：先看候选集合是否包含必要证据、排序是否让证据可用，再看回答是否忠实、完整、正确引用和在无证据时正确拒答。回答分数不能抵消关键证据漏检或伪造引用。
- Agent 必须保存可审查轨迹：状态、工具候选、实际选择、参数、返回、权限决策、重试、循环计数、终止理由、最终副作用和补偿。最终答案正确也不能抵消越权、错误工具、危险参数、无限循环或不可逆副作用。
- 对每个版本收集总成本及 token/工具成本、p50/p95/p99 延迟、超时、错误、重试、成功波动和 run-to-run 稳定性；比较必须在相同负载和时间窗口说明差异。

### 门禁、版本与闭环

- 发布表必须列 baseline version、candidate version、dataset version、grader/rubric version、模型/提示词、retrieval/index、工具 schema/权限和运行环境。任一改变使比较不可解释时，重跑或降级结论。
- 门禁区分硬约束（安全、权限、schema、关键引用、工具副作用）、关键切片下限、总体非回归、成本/延迟/稳定性预算和人工复核。每项写样本量、阈值、允许回归、owner 和阻断动作。
- 线上信号只在脱敏、去重、标注和版本化后回流。发布后仍需监控对应切片、告警阈值、灰度暂停/回滚条件和下一次数据集冻结日期。

## 输出契约

按 `references/templates.md` 交付，缺失信息必须保留 `GAP-*`：

1. 评测卡：发布决定、`C-*`/`R-*`、事实/未知、baseline/candidate 及停止条件。
2. 数据集与代表性账本：`D-*`、来源类型、版本、切片、难度、泄漏/重复检查、隐私和覆盖缺口。
3. 分层评测设计：RAG 的检索/证据/答案，或 Agent 的轨迹/工具/参数/权限/循环/副作用。
4. `G-*` grader 与 rubric：确定性、人工、LLM judge 的输入、版本、正反例、偏差缓解、校准和升级规则。
5. `Failure-*` 失败分类与处置台账：稳定失败代码、定义、RAG/Agent/其他层、受影响切片、频率/严重性、可能修复/责任 owner、关联生产样本和回归 case，以及关联 `G-*`/`E-*`。
6. `E-*` 比较结果：版本、命令/配置、时间、样本、切片、质量、成本、延迟、稳定性、`Failure-*` 回链和限制。
7. 发布决定与回流：硬门禁、切片门槛、通过/有条件通过/不通过、监控/回滚、owner、线上回流与下轮 dataset version。

## 质量门槛

- 每个发布结论至少回链 `C-*`、`R-*`、`D-*`、`G-*`、`Failure-*` 和真实 `E-*`；未运行或版本不明不能写为通过。
- 每个失败的 `G-*` 标签和 `E-*` case/trace 必须回链一个定义完整的 `Failure-*`；缺失稳定代码、owner、生产样本或回归 case 关联时不能关闭该失败。
- 高风险切片、硬安全/权限/工具副作用、关键 RAG 证据和数据泄漏检查必须独立通过；总体平均不得覆盖它们。
- 开放式任务不只靠字符串、准确率或未校准 LLM judge；必须有适用的确定性检查、可复现 rubric 和人工/judge 校准证据。
- baseline/candidate/dataset/grader 及相关模型、检索、工具和环境版本必须可比较；变化未登记时结果仅作探索。
- 成本、p95 延迟、超时/错误和稳定性必须在预算内；质量提高不自动抵消可靠性或成本回归。
- 生产样本回流必须经过隐私、去重、标注和版本冻结；不能把原始生产数据直接当成永久黄金集。

## 常见失败与修正

| 失败 | 修正 |
|---|---|
| 只用 50 条黄金问答和平均准确率发布 | 增加生产失败、困难、对抗和风险切片；为每个关键切片设独立下限与阻断动作。 |
| 同一 FAQ、文档或改写题同时在 few-shot、索引与 test | 以文档/会话/近重复簇切分，登记泄漏检测和人工复核，再重新冻结版本。 |
| LLM judge 给长答案、先出现答案或同源模型更高分 | 匿名、随机/反转顺序、长度控制、固定 judge 配置，并用人工金标和反转一致性校准。 |
| RAG 只评最终答案 | 分别测必要证据召回/排序、忠实性、完整性、引用和无证据拒答，定位到检索或生成。 |
| Agent 最终答对但调用了错误或无权限工具 | 将工具选择、参数、权限、循环、预算和副作用作为独立硬门禁并保存 trace。 |
| 离线全绿后不看线上失败 | 设灰度监控、升级/投诉回流窗口、去重标注 owner 和下一个 dataset version；出现新高风险簇即复跑。 |

## 参考资料

- `references/usage-guide.zh.md`：准备材料、调用方式、阅读结果与离线-线上衔接。
- `references/templates.md`：评测卡、数据集、grader/rubric、校准、运行、门禁与回流模板。
- `references/checklists.md`：输入、数据、评审、RAG/Agent、版本、门禁和回流检查。
- `references/examples.md`：RAG、Agent 和单一准确率请求的三个 V1/V2 场景。