AI Agent Guide 交互版
模块一 · LLM 工程基础 TypeScript + Zod + output_config.format 含 3 个交互实验台

Prompt 回归评测:把“我感觉变好了”变成可比较的数字

你把 Prompt 里一句“请简洁回答”改成“请详细分析”,或者把模型升级到新版本。接口依然返回 200 OK,JSON 也能正常解析,但代码评审助手开始把正常格式化函数判成高危漏洞,或者漏掉了真正的 SQL 注入。没有固定用例集和断言规则,你根本分不清这是模型抖动,还是新改动的退步。

30 秒核心脉络

一、什么叫“输出变差”:别急着上另一个模型打分

AI 工程里的回归测试,本质是把不完全确定的模型当成被测函数:固定输入 + 固定 Prompt + 固定检查规则 = 可比较的实验结果。

很多人一听说“评测”,第一反应就是再找一个更贵的模型当裁判。这当然有用,但顺序错了。工程上应该先把最容易确定、成本最低的硬问题用代码拦住,把变差拆成 4 个可观测维度:

维度 1 · 最硬指标
格式变差

新 Prompt 让模型多包了一层 Markdown 代码块,或者把数值字段 score 输出成了字符串,下游解析直接崩溃。

检查手段:output_config.format + Zod Schema 强约束
维度 2 · 核心业务
内容变差

JSON 格式完全合法,但原本能抓出的 SQL 注入被忽略,模型只泛泛地说“代码风格可以优化”。

检查手段:mustMention 关键词 + issueTypes 分类断言
维度 3 · 体验与克制
风格与边界变差

要求一句话总结却吐出 800 字,或者把一段完全正常的工具函数硬生生审出 3 条“安全风险”。

检查手段:字符上限 + 反例(clean-code)零误报检查
维度 4 · 生产成本
成本变差

Prompt 加长了 600 字规则后,通过率只涨了 2%,但单次调用的输入与输出 Token 成本直接翻倍。

检查手段:记录 usage.input_tokens / output_tokens 与耗时
固定输入集 cases.json (4 条) 3 条典型故障 + 1 条正常反例 L1 · 硬契约 output_config.format Zod 保证字段合法 失败即刻拦截 L2 · 语义断言 代码规则脚本 关键词 / 类型 / 分数 零额外调用成本 L3 · 门禁 版本对比 通过率 & P0 决定是否放行
图 1:先用 L1 Schema 和 L2 代码断言拦截 60 分的硬退步,再决定版本是否放行。
先猜后验
假如你的代码评审测试集里有 4 条用例,全部都是包含真实 Bug 或安全漏洞的代码。新版 Prompt 在这 4 条用例上拿到了 100% 通过率,能直接放心上线吗?
判断正确:只放有问题输入的测试集,会诱导你不断把 Prompt 改得越来越严厉。结果就是模型连正常代码也强行编造出“安全漏洞”和“性能隐患”。下方实验一可以直接看到真实模型输出。
交互实验台 01 · 真实输出溯源与反例诊断

为什么 review-v1 在“正常代码”上翻车了?

本实验展示 examples/core-methods/prompt-regression/run-eval.ts 在 qwen-plus(temperature: 0)上的真实运行报告。切换 Prompt 版本与 4 条用例,观察模型输出与断言结果的变化。 真实运行数据 · prompt-regression-report.md

Prompt 版本:
测试用例:
用例:missing-null-check 使用 review-v1.md

            
预期断言(cases.json)
当前版本总通过率:3 / 4 (75%) PASS
断言检查清单 模型评分:30
    qwen-plus 实际返回 JSON
    
              
    诊断结论

    二、从失败用例里长出 Prompt 规则

    review-v2.md 里的约束不是拍脑袋写出来的,而是从失败 case 里长出来的。

    在上面的实验里,review-v1 面对一段普通的 Intl.NumberFormat 价格格式化函数,硬是编造了三条问题:把未校验的 currency 参数说成“安全漏洞(信息泄露)”,又批评它缺少 JSDoc 注释,最终只给了 72 分。

    定位到“过度评审”这个失败模式后,review-v2.md 针对性地增加了三条护栏:

    1. 明确评审优先级:运行时错误 > 安全风险 > 性能问题 > 可维护性。
    2. 明确零问题出口:如果代码整体没有明显问题,issues 输出空数组,score 应在 80 到 100 之间。
    3. 划定安全与性能的判定边界:没有看到外部输入、数据库、文件或网络边界时,不要默认判定为安全漏洞;不要把普通对象创建或格式化函数判定为性能问题。

    加完规则后重跑同一批 4 条 case,clean-code 通过了(评分 95,issues: []),同时前 3 条故障用例没有出现退步。这就是回归测试的核心价值:修掉一个已知失败模式,并证明没有破坏已有能力。

    三、把断言规则与版本门禁接进工作流

    不要只盯着总通过率。如果一个 P0 高危用例从通过变成失败,即使总通过率看起来没怎么掉,这个版本也必须被门禁拦住。

    同时,真实项目里只有“关键词 + 类型 + 分数”还不够,工程上通常会逐步补上两道防线:第一道是输出长度/格式冗余检查(防止模型突然变得极其啰嗦,撑爆界面或预算);第二道是关键用例多次重复运行(即使 temperature: 0,不同服务端版本仍可能出现轻微波动)。

    交互实验台 02 · 断言沙盒与发布门禁

    调整检查规则与模拟抖动,看门禁何时拦截发布

    在真实 run-eval.ts 骨架上叠加输出长度上限与重复运行策略,观察版本门禁的放行/拦截判定,右侧代码块会同步更新对应的 TypeScript 实现。 门禁规则与抖动为教学模拟

    待评测 Prompt
    JSON 长度上限(maxChars) 1000 字符
    稳定性策略与 P0 门禁
    用例 ID 优先级 输出字符数 语义断言 长度检查 门禁状态
    发布门禁:BLOCKED(拦截发布)
    3 / 4 通过
    查看同步生成的 TypeScript 评测脚本(run-eval.ts 片段)
    evaluateCase + 长度门禁 + 重复运行

    四、不要神化最小脚本:5 个工程局限

    自己写几十行 TypeScript 断言能解决 60 分的问题,但它不是完整的评测平台。

    1. 关键词检查很粗糙:模型可能提到了“SQL 注入”,但给出的修复建议是错的;也可能换了同义词描述同一个风险,导致关键词误杀。
    2. 分数不是绝对标准:不同 Prompt 对 60 分的定义完全不同,必须配合清晰的评分标准说明使用。
    3. 单次运行不够稳定:即便设置 temperature: 0,服务端升级或浮点非确定性仍会带来波动,关键用例需要多次重复运行。
    4. 没有 LLM-as-Judge:对于“解释是否清晰”“建议是否可执行”这类软指标,代码规则很难覆盖,需要另一个模型按 Rubric 打分。
    5. 没有统计 Token 成本:生产脚本应该把 response.usage.input_tokens 和 output_tokens 写入报告,避免质量涨了 2%、账单翻倍。
    交互实验台 03 · 三阶段评测演进模拟

    从 60 分脚本到生产评测:每加一层得到什么、付出什么

    点击切换不同评测成熟度,对比缺陷拦截能力、单次运行成本与可解释性。工程上的原则永远是:先把硬规则铺好,再按需引入模型裁判。 成本与覆盖度为示意对比

    阶段 1:Schema + 代码规则断言 额外评测调用:0 次 / 用例

    硬退步拦截
    75%
    软质量识别
    25%
    评测时间/成本
    低 (1x)

    五、现成工具怎么选与日常开发流程

    自己写脚本是为了看懂 eval 的骨架;当用例突破几十条、需要接入 CI 或团队协作时,再切换到成熟工具。

    Promptfoo Prompt 对比 & CI

    最接近本章主线。通过 YAML 配置组织 Prompts、Providers 与断言,自带 Web 对比界面,适合在 CI 里跑多模型、多 Prompt 版本回归。

    官方文档:promptfoo.dev →
    DeepEval Python / RAG / Agent

    类似 Pytest 的 LLM 测试框架,内置 Faithfulness、Answer Relevancy 等指标,适合进入 RAG 检索与 Agent 评测阶段后使用。

    官方文档:deepeval.com →
    LangSmith 团队 Trace & 数据集

    平台化方案,适合系统上线后把真实用户的失败 Trace 一键沉淀回测试数据集,做跨版本的线上线下联动对比。

    官方文档:LangSmith Evaluation →
    DSPy 编程式 Prompt 优化

    定位是“programming, not prompting”,根据你定义的 Metric 自动优化指令与 Few-shot。前提是先拥有稳定的测试集与评测指标。

    官方文档:dspy.ai →

    把回归评测放进日常开发闭环

    脚本能跑只是起点,真正有价值的是把它固定成 4 步习惯:改 Prompt 前先跑基线保存报告;改 Prompt 后用同一批 case 重跑对比;线上或手测发现离谱输出时,先把输入加进 cases.json 再动手改 Prompt;每次发布不只看总通过率,还要盯住高优先级用例是否退步。

    任务类型 先做什么 AI 适合做什么 工程师必须盯什么 验收方式
    AI 功能迭代 准备正例与反例 case 调 Prompt、写解析和重试逻辑 输出质量、Token 成本、失败兜底 用固定 case 做版本对比
    Bug 修复 复现离谱输出 读日志、定位规则冲突 根因是否成立、是否误伤其他用例 先加回归用例,再验证修复
    Agent 能力 定义工具与权限边界 生成执行循环和工具封装 越权、死循环、不可恢复失败 看工具调用轨迹与最终状态
    完整可运行源码
    示例位于仓库 examples/core-methods/prompt-regression/(包含 cases.json、prompts/review-v1.md、prompts/review-v2.md 与 run-eval.ts),使用阿里云百炼 Qwen(支持 output_config.format)可直接运行 npx tsx --env-file=.env examples/core-methods/prompt-regression/run-eval.ts。

    Prompt 回归评测本质上是一种工程判断习惯,而不是工具堆砌。测试 case 远比 eval 框架值钱:先有几条真实、带反例的代表性数据,再谈自动化评测才有意义。进入后续的 RAG 知识库与 Agent 实战后,你会看到完全相同的闭环在更大的链路上复现,只不过检查对象从一段 JSON 输出,扩展到了检索召回率、引用忠实度以及工具调用的执行轨迹。