SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场agent-regression-evals

agent-regression-evals

测试与质量

查看项目

更新于 10-24 09:22

技能介绍

Agent Regression Evals 用于在智能体、提示词、模型或工具发生变更时，证明变更没有让智能体变差。它解决的核心问题是：智能体具有非确定性，单次试验无法区分回归与随机波动；最终答案正确也不代表过程正确，例如调用了本不该调用的工具。

用途

该工具用于搭建回归评估套件、判断通过率变化是否超出噪声、对工具调用路径进行评分，并在变更导致真实退化时阻止合并。它不调用 API 或 LLM，由用户自行运行智能体，脚本只负责评分、计数和门禁。

主要能力

  • 轨迹检查：scripts/trajectory_checker.py 按 strict、unordered、subset、superset 等匹配模式检查工具调用路径，支持参数模式、禁用工具和调用次数上限。默认使用 superset，即要求步骤出现，允许无害探索；除非顺序是硬性要求，否则评估结果而非路径。禁用工具在所有模式下都会拦截。
  • 不稳定用例检测：scripts/flake_detector.py 将每个用例标记为 STABLE_PASS、STABLE_FAIL 或 FLAKY，计算 Wilson 置信区间、pass@k（k 次中至少成功一次）和 pass^k（k 次全部成功），并生成隔离存根。关键用例永远不会成为隔离候选。
  • 回归门禁：scripts/regression_gate.py 先对每个用例的多次试验取平均，再对用例间配对差异进行 t 检验 95% 置信区间和单侧精确 McNemar 检验。当下降真实但样本量不足时，会提示需要多少用例才能检出。

使用方式

工作流分为三步： 0. 在干净环境中对基线和候选各运行每个用例 k 次（k >= 3），每次试验写入一行 JSONL，例如 {"case_id": "refund-lookup", "trial": 1, "passed": true, "critical": true, "cost_usd": 0.012, "trajectory": [{"tool": "get_order", "args": {...}}]}。

  1. 在路径重要的场景（安全、必需查询）评分路径：python scripts/trajectory_checker.py --spec cases.json --results candidate.jsonl
  2. 在信任任何比较之前，区分不稳定用例与稳定用例：python scripts/flake_detector.py --results candidate.jsonl --k 3 --quarantine-out q.json
  3. 门禁：与基线进行逐用例配对比较，退出码 4 阻止合并：python scripts/regression_gate.py --baseline baseline.jsonl --candidate candidate.jsonl --quarantine q.json

所有脚本支持 --sample 和 --output json。

门禁阻止条件

  • 统计显著下降（置信区间上界低于零，或 McNemar p < 0.05）。
  • 关键用例在基线所有试验中通过，但在候选任何试验中失败。
  • 基线用例在候选运行中缺失。删除用例是最廉价的假修复。
  • 隔离条目没有负责人或有效期，或覆盖关键用例。
  • 出现禁用工具调用（轨迹检查器，退出码 4）。 对于超过 --tolerance 但统计功效不足的下降，或超过 --max-cost-increase 的成本上升，门禁会发出警告，由人工决定。

适用场景

适用于智能体、提示词、模型或工具变更后的回归验证，尤其关注安全关键路径、必需工具调用、通过率波动和成本变化。建议从真实失败开始构建套件（20-50 个用例），在“应该做”和“不应该做”之间保持平衡。

限制与硬性规则

  • 绝不比较单次试验。每个用例少于 3 次试验时，不稳定检测器会拒绝（退出码 4）。
  • 绝不将试验汇总为独立样本。先按用例取平均，再比较用例。
  • 绝不在没有负责人和有效期的情况下隔离。过期条目会自动重新进入门禁。
  • 绝不删除失败用例来变绿。门禁会统计缺失项。
  • 绝不在 8 个用例上把“无显著下降”称为通过。报告结论时需附上统计功效说明。

脚本与退出码

  • scripts/trajectory_checker.py：评分工具调用路径，支持匹配模式、参数模式、禁用工具、调用上限。退出码：0、2 偏差、3 输入错误、4 禁用工具。
  • scripts/flake_detector.py：按用例标记 STABLE_PASS / STABLE_FAIL / FLAKY，计算 Wilson 置信区间、pass@k、pass^k，生成隔离存根。退出码：0、2 不稳定、3、4 试验次数过少。
  • scripts/regression_gate.py：配对置信区间、精确 McNemar、关键用例、缺失用例、隔离有效性、成本。退出码：0 PASS、2 WARN、3、4 BLOCK。

参考资料与资产

  • references/eval_statistics.md：pass@k 与 pass^k、按用例平均、配对置信区间、McNemar、统计功效（7 个来源）。
  • references/trajectory_grading.md：结果与路径、匹配模式、评分器类型（6 个来源）。
  • references/flaky_cases_and_quarantine.md：不稳定原因、带有效期的隔离、干净试验（6 个来源）。
  • assets/eval_case_spec.example.json：步骤 1 的轨迹规范。
  • assets/sample_baseline.jsonl、assets/sample_candidate.jsonl：结果格式。
  • assets/ci_eval_gate.example.yml：运行门禁并在退出码 4 时失败的 CI 任务。