promptfoo 与 Agent 评测工具链：把 evals 装进 CI

为什么需要评测工具链：手工测不可持续

Agent 的改动频率远高于传统软件（提示词、模型版本、工具集、温度——任何一个都会改变行为），手工测试不可持续：改一行提示词，要人工把 20 个场景重测一遍？没人会做，于是回归以「上线后用户发现」的方式发生（本库企业采用篇的缺口一：没有评测 = 盲飞）。评测工具链的职责：把「测试场景、期望结果、评分标准」代码化/配置化，让「每次改动自动跑全部场景」像单元测试一样运行——evals 就是 LLM 应用的单元测试，这个类比是理解整个工具链的钥匙。

promptfoo 的核心抽象：测试定义、断言与评分器

promptfoo（开源，LLM 评测框架的事实标准之一）的核心抽象三件。测试定义（YAML）：场景集的结构化描述——输入（用户消息/变量）、提供者（要测的模型/Agent——多提供者对比是 promptfoo 的招牌：同一套测试跑 GPT/Claude/开源模型，一张对比表）、以及断言。断言（assert）的类型学是精髓所在——按「判定的确定性」分层：确定性断言（contains/equals/regex/JSON schema 校验——零成本、零歧义，能用它的绝不迷信 LLM 评分）、语义相似度断言（embedding 相似度阈值——答案不唯一但语义应相近的场景）、LLM-as-judge 断言（用另一个模型按 rubric 打分——开放性回答的质量判定，本库 LLM-as-judge 篇的原则在此落地：judge 的 rubric 要具体、判分要抽查校准）。评分与报告：跑完输出通过率、逐 case 的对比视图、CI 友好的退出码（不通过则 CI 失败）。

evals 进 CI 的工程模式：三级防线的部署

evals 进 CI 的三级模式，按成本与覆盖递进。一级：冒烟集（每次 PR）。精选 20–50 个核心 case（覆盖主路径 + 易碎场景），跑时几分钟、成本几块钱——PR 级的回归防线（提示词/模型的改动在合并前拦截退化）。二级：全量集（每日/每次发版）。完整场景集（数百 case、含边界与对抗样本），夜间跑——发现长尾退化（本库回归测试的完整版）。三级：生产影子评测（真实流量抽样，本库 ai-frontier 篇的影子评测）——线上流量的 A/B 对比与漂移检测。三个工程细节决定成败。细节一：失败的可归因——评测失败要能快速定位「是提示词、模型版本、还是工具坏了」——工具链的 trace 集成（本库可观测性篇）让失败 case 一键看轨迹。细节二：基线的锁定与更新——评测集与基线分数要版本化（改测试集等于改卷子——卷子与成绩要一起管理），「分数的提升」要对照「测试集是否也被放宽」。细节三：成本的预算——LLM 断言与全量集都是真金白银（数千 case × 数次调用的月账单）——确定性断言优先、LLM 断言抽样的成本纪律要写进评测设计。

从 evals 到质量文化：评测工具链的组织面

工具链只是起点，评测要长成组织文化。评测集的治理：评测集是团队最重要的资产之一（比代码更能定义「这个 Agent 该做什么」）——它要有 owner、有版本、有变更评审（谁都可以往里加 case，但改期望结果要走评审——防止「改测试凑答案」）。失败 case 的入库纪律：每一个线上发现的 bad case，修复前先变成评测 case（bug → 回归测试的经典纪律在 LLM 时代的翻版）——评测集随事故生长，防线的覆盖随时间变密。评测与产品指标的连接：evals 的通过率要与产品指标（用户满意度、任务完成率）校准对齐（evals 全绿但用户骂声一片 = 测试集偏离真实分布——评测集要定期用真实流量刷新）。组织的成熟度曲线：手工测 → 脚本测 → CI 防线 → 影子评测 → 评测驱动的开发（改任何东西之前先写测试 case）——每个阶段都是一次工程文化的跃迁。Agent 工程的终极形态，大概就是「评测驱动」四个字——模型与提示词都会过时，测试集才是组织关于「什么是对的」的长期记忆。

promptfoo 实战：为一个客服 Agent 建立评测集

promptfoo（正文框架）的实战：为一个客服 Agent 建立评测集的完整过程。评测集的设计。场景矩阵的覆盖（查询类/投诉类/操作类 × 简单/复杂——本库 SFT 篇的矩阵法迁移到评测）、每个 case 的结构（用户输入 + 断言——断言的选择见下）、对抗样本（注入尝试、越权请求——本库安全篇的对抗测试）。断言的选型实践。能确定性的用确定性（转人工的判断 → contains「人工」断言；输出格式 → JSON schema 断言）、语义断言的 rubric 设计（「回答是否包含退款政策要点」——rubric 列出必含要点而非「回答得好」）、LLM-as-judge 的校准（抽 10 个 case 人工判 vs judge 判——一致率 <80% 就改 rubric——本库 LLM-as-judge 篇的校准纪律）。CI 的接入。GitHub Actions 的集成（PR 触发冒烟集、每日全量）、失败的处理策略（阻塞合并 vs 告警不阻塞——按风险分级）、成本的控制（确定性断言优先、LLM 断言的模型选择（judge 用中档模型）、评测集的规模纪律）。评测集的运营（本库评测篇的治理）：bad case 入库的纪律、评测集的版本管理、与产品指标的校准对齐（evals 全绿但用户不满 = 测试集偏了）。这个实战的元意义：promptfoo 把「评测」从研究活动变成工程活动——YAML 一写、CI 一接，Agent 的质量就有了回归防线；评测驱动开发的门槛，从来没这么低过。

评测工具链的对比：promptfoo 与它的竞品们

评测工具链（正文 promptfoo 为主角）的竞品对比，选型地图值得画出。工具的阵营。开源评测框架：promptfoo（CLI/CI 友好、多提供者对比、YAML 定义——工程团队的首选）、deepeval（pytest 风格——Python 团队的习惯语法、与测试框架的深度整合）、OpenAI evals（官方但偏向研究）。平台型产品：LangSmith（LangChain 生态的评测+观测+数据集管理——一体化但绑定）、Arize Phoenix / Langfuse（观测为主评测为辅——本库可观测性篇的兄弟功能）、Braintrust（商业化的评测+数据管理平台）。选型的维度。技术栈匹配（Python 团队 → deevel/promptfoo、LangChain 用户 → LangSmith 顺滑）、CI 优先 vs 平台优先（promptfoo 的 CLI 哲学 vs LangSmith 的平台体验）、成本（开源自托管 vs 平台订阅）、以及与可观测工具的协同（评测与 trace 的数据打通——本库可观测篇的联动）。工具链的组合建议：一个评测框架（promptfoo）+ 一个观测平台（Langfuse）+ 自建评测集治理——评测、观测、数据三件套齐了，Agent 的质量工程就有完整的驾驶舱。工具链选择的元原则：评测工具的价值 80% 来自「你真的在用」（CI 里跑、bad case 入库），20% 才来自工具的功能差异——工具选哪个都行，用起来才是一切。

evals 的进阶设计：Agent 轨迹的评测（不只看答案）

evals（正文断言）的进阶设计：Agent 轨迹的评测——不只看最终答案，要看「过程对不对」。轨迹评测的必要性：答案正确的 Agent 可能过程错误（猜对的、碰巧的——过程错误是未来失败的定时炸弹：这次蒙对下次翻车）；过程正确但答案错误的（工具调用全对、最终生成偏差——这是可修的）。轨迹评测的维度。工具选择（该用的工具用了吗、不该用的用了吗——本库 Agentic RAG 篇的路由评测）、调用参数（参数的正确性——检索词的质量、SQL 的正确性）、顺序与效率（步骤的冗余——绕了三步才到答案的效率问题）、安全合规（过程中有没有越权操作、敏感暴露）。轨迹评测的实现。promptfoo 的 trace 断言（工具调用的序列断言）、基于 LLM-as-judge 的轨迹评分（把完整轨迹喂给 judge 按 rubric 评「过程质量」——judge 评轨迹的 rubric 设计：步骤合理性、效率、安全三维度）。轨迹评测的成本：轨迹数据大（judge 的 token 消耗高）——抽样的策略（全量轨迹评测贵，抽样 + 答案全量的混合）。轨迹评测的收束：答案评测告诉你 Agent 「行不行」，轨迹评测告诉你 Agent 「为什么行/不行」——前者是验收，后者是改进的地图；成熟的 Agent 团队两者都要。

evals 的进阶话题：评测集的污染与动态更新

evals（正文运营）的进阶话题：评测集的污染与动态更新——评测集自身会「过期」和「被污染」。评测集的污染源。训练数据的泄漏（评测 case 进了模型的训练数据——模型「背题」——本库评测篇的污染问题在私有评测集同样发生：你的 case 如果在网上公开过，前沿模型可能见过）；评测集的过拟合（针对评测集调优提示词——分数涨了、真实能力没涨——为评测集优化的提示词泛化性差）；评测集的老化（业务演进后评测场景不再代表真实分布——测试集与业务分布的漂移）。动态更新的机制。评测集的滚动更新（定期从真实流量抽新 case 替换旧 case——像 GRE 的题库轮换，本库 ai-frontier 篇的动态评测）、保留集的制度（一小部分 case 永不公开、永不在开发中使用——只在关键决策时启用）、污染的检测（新旧模型在同 case 上的「异常跃升」检测——跃升可能是能力也可能是背题）。动态更新的收束：评测集是会过期与被投毒的活资产——滚动更新、保留集、污染检测三件套，让评测的公信力持续在线；评测集的治理水平，就是 Agent 质量保障体系的真实水平。

小结

评测工具链把「手工测不可持续」变成「evals 即单元测试」：promptfoo 的三件套（YAML 测试定义、分层断言——确定性优先、多提供者对比）是开源代表，evals 进 CI 的三级防线（PR 冒烟集、每日全量、生产影子）是部署模式。成败在三个细节：失败可归因（trace 集成）、基线版本化（改卷子要留痕）、成本纪律（确定性断言优先）。组织面上，评测集要有 owner 与变更评审、bad case 先入测试再修复、evals 与产品指标校准——评测工具链的终点不是工具，是「评测驱动」的工程文化：测试集是组织关于「什么是对的」的长期记忆。