在 PR 里拦住提示词回归,别等客户先发现
用 GitHub Actions 运行 promptfoo,在同一黄金数据集上对比新旧提示词,并把分数评论到 PR 上。
要点速览
- LLM 的输出有多种可接受的答案,精确匹配没有意义;需要黄金数据集加上加权断言。
- promptfoo action 会在每个改动提示词的 PR 上做前后对比并评论结果;它需要 pull-requests: write 权限和一个 API key secret。
- paths 过滤和 concurrency 分组确保评测只在必要时运行,不会因为重叠运行白白消耗 API 费用。
设想一个团队改了系统提示词里的一句话,想让聊天机器人回答得短一些。演示效果不错。两周后,客户反馈说机器人在回复中不再提到订单号,而他们的运营团队每天都要靠这个信息工作。
传统单元测试发现不了这类问题。普通软件函数对每个输入只有一个正确输出;而正如 Evidently AI 指出的,LLM 对同一个输入可能给出许多都可以接受的答案,所以精确匹配毫无用处。
上线到生产环境也不意味着测试结束:每次改动之后,仍然需要离线评测来做回归测试。前线部署工程师(FDE)直接在客户系统上修改提示词和模型,这张安全网必不可少。
本指南就来搭建这张网:一个 GitHub Actions 工作流,在每个改动提示词的 pull request 上运行 promptfoo。
要搭建什么,需要准备什么
最终效果:每当有人提交改动 prompts/ 目录内容的 PR,GitHub Actions 就会在同一个黄金数据集上运行评测,对比新旧提示词,并直接把结果评论到 PR 上。如果分数低于阈值,合并之前就能看到红色信号。
需要准备:一个你拥有管理员权限的 GitHub 仓库,一个模型服务商的 API key(下面的例子用 OpenAI),以及一个存放提示词的目录。你需要能读懂 YAML,并了解 pull request 的工作方式。
第 1 步:黄金数据集比 YAML 更重要
一组带有已认可输出的参考输入,通常称为“黄金数据集”,整套测试都围绕它展开。所以不要急着写工作流。先从 15-20 个真实问题入手,来源可以是日志,也可以是与客户的会议,每个问题都配上正确答案必须具备的特征。
以一家快递公司为例。“我的订单 DH-1042 在哪里?”这个问题没有唯一正确的答案。但每个好答案都必须复述订单号,不能编造送达日期,并且保持礼貌。这三个特征就成了三条断言。
本步检查:每个测试用例至少有一个机器可以验证的条件(包含某个字符串),以及一个需要判断的条件(语气、事实准确性)。
第 2 步:编写带加权断言的 promptfoo 配置
在 promptfoo 中,每条断言都会把 LLM 的输出与期望值或条件进行比较;通过与否取决于加权分数是否达到阈值。这个阈值就是 CI 中的通过/失败信号。下面的文件经过删减,只用于说明结构;使用前请对照 promptfoo 的 Assertions and Metrics 页面核对字段名。
# prompts/promptfooconfig.yaml(删减版)
prompts:
- file://support_prompt.txt
providers:
- openai:gpt-4o-mini
tests:
- vars:
question: "我的订单 DH-1042 在哪里?"
threshold: 0.75
assert:
- type: contains
value: "DH-1042"
weight: 1
- type: llm-rubric
value: "不编造具体的送达日期"
weight: 2
- type: llm-rubric
value: "语气礼貌、简洁"
weight: 1
简单算一下就能看出阈值如何起作用,这里假设分数按加权平均计算。总权重为 4。旧提示词三点全部满足:4/4 = 1.0,通过。
现在假设新提示词为了回答简短,编造了一个送达日期。输出仍然包含订单号(1 分),也仍然礼貌(1 分),但丢掉了权重最高那条断言的 2 分:2/4 = 0.5,低于 0.75 的阈值,测试失败。如果新提示词只是丢了礼貌,分数是 3/4 = 0.75,正好卡在阈值上。
| 断言(权重) | 旧提示词 | 编造送达日期的新提示词 |
|---|---|---|
| 包含“DH-1042”(1) | 通过:1 | 通过:1 |
| 不编造送达日期(2) | 通过:2 | 失败:0 |
| 礼貌、简洁(1) | 通过:1 | 通过:1 |
| 分数与 0.75 阈值对比 | 4/4 = 1.0,通过 | 2/4 = 0.5,失败 |
这张表说明了为什么一个在演示中看似无害的改动仍会被标红:一个严重错误就足以把分数拉到阈值以下。
本步检查:运行一个明知错误的用例,确认它会失败。一套从不变红的测试,等于什么都没测。
第 3 步:只在提示词变更时运行的工作流
每次评测都会产生计费的 API 调用,所以你不希望有人改个 README 也触发它。pull_request 事件上的 paths 过滤可以解决这个问题:只有至少一个变更文件匹配该模式时,工作流才会运行。
# .github/workflows/prompt-eval.yml
name: 提示词回归评测
on:
pull_request:
paths:
- 'prompts/**'
concurrency:
group: prompt-eval-${{ github.ref }}
cancel-in-progress: true
permissions:
contents: read
pull-requests: write
concurrency 块处理的是另一项成本来源。在同一个并发组内,任一时刻最多只运行一个 job 或工作流。当你向同一个 PR 连续推送三次 commit,较早的运行会被取消,而不是三次都去调用 API。
pull-requests: write 权限必不可少:promptfoo 需要它才能在 PR 上发评论。
第 4 步:添加 promptfoo action 和 secret
promptfoo action 承担了主要工作:在每个改动提示词的 PR 上,它会完整运行一次前后对比,并把结果发到 PR 上。如果使用 OpenAI,请在仓库中设置 OPENAI_API_KEY secret(Settings 下的 Secrets);其他服务商则使用对应的 key。
jobs:
evaluate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: promptfoo/promptfoo-action@v1
with:
# key/token 输入参数的名称:请查阅 promptfoo-action 的 README
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
github-token: ${{ secrets.GITHUB_TOKEN }}
prompts: 'prompts/**/*.txt'
config: 'prompts/promptfooconfig.yaml'
prompts(一个 glob)和 config(配置文件路径)这两个输入是 promptfoo 示例的核心。这里简化了 checkout 步骤和 key 的传递方式;请阅读 Testing Prompts with GitHub Actions 页面,获取你所用版本的完整配置。
本步检查:提交一个只改动 support_prompt.txt 中一个词的 PR。Actions 标签页应显示工作流正在运行,PR 上应出现一条带对比表的评论。再提交一个只改 README 的 PR:工作流不应运行。
关于范围的说明:本指南止步于 PR 上的红色信号,这还不等于阻止合并。在向客户承诺糟糕的提示词“进不了 main”之前,请在自己的仓库中验证:分数低于阈值时,这个 job 是否会报告失败。
让流水线空转的常见错误
最常见的错误是黄金数据集太简单。如果 20 个问题全是演示里的样例问题,评测会永远是绿色,而真实用户问的却是别的事情。把每一个曾经引发过事故的问题都加进去。
第二个:paths 中的 glob 与提示词的实际存放位置不匹配。很多团队把提示词写在 Python 文件里,改了之后工作流却毫无动静。测试方法是改动那个具体文件,看 Actions 是否运行。
第三个是忘了换模型也是一种改动。如果模型名写在 prompts/ 目录下的 promptfooconfig.yaml 中,切换模型会自动触发评测。如果它在另一个配置文件里,就把那个路径也加到 paths 中。
这项技能在客户现场是什么样子
回归测试的目的是证明新改动在改进系统的同时,没有破坏原本正常的功能,而最合理的位置是 CI/CD,在每次改动后运行。
它的价值在某些时刻格外明显,比如客户想换一个更便宜的模型:不必凭感觉争论,直接提交一个更换模型的 PR,把对比评论拿给他们看。
接手新客户时,第一件事是:和一线运营人员坐下来,请他们列出最担心的 20 个问题,并问清楚哪些错误不可接受。他们的回答决定了权重。这份问题清单连同权重,是你离开项目时最有价值的交付物。
如何写进简历、带进面试
阅读 FDE 岗位描述时,留意“evaluation”“LLM testing”和“CI/CD”这类字眼。然后对比简历上描述同一段经历的两种写法。
泛泛而谈
- 有 LLM 评测经验,熟悉 GitHub Actions。
- 为聊天机器人优化过提示词。
可以验证
- 为订单客服聊天机器人搭建回归评测,基于 20 个用例的黄金数据集,在 GitHub Actions 中运行,分数低于 0.75 时将 PR 标红。
- 按运营团队的优先级设置断言权重:编造送达日期的权重是风格错误的两倍。
第二种写法更有说服力,因为招聘方可以核实。附上一个公开 PR 的链接,里面有结果评论,最好是因为新提示词更差而被标红的那种。
面试时,如果被问到“换模型时,你怎么知道没有东西坏掉?”,准备好用上面 DH-1042 的例子和 2/4 的计算来回答。
也可以把问题抛回给雇主:“团队在部署给客户之前,如何对提示词做回归测试?”答案会告诉你,你是有机会搭建这张安全网,还是要把时间花在收拾它缺位留下的烂摊子上。
你离开项目后,提示词还会被改几十次。你留给客户的不是最好的提示词,而是每个未来的提示词都必须通过的测试,用来证明它没有破坏已经正常运行的东西。
这篇文章对你有帮助吗?
感谢你的反馈!