# 在 PR 里拦住提示词回归，别等客户先发现

> 用 GitHub Actions 运行 promptfoo，在同一黄金数据集上对比新旧提示词，并把分数评论到 PR 上。

原文: https://fdetimes.net/zh/guides/promptfoo-regression-evals-github-actions/

设想一个团队改了系统提示词里的一句话，想让聊天机器人回答得短一些。演示效果不错。两周后，客户反馈说机器人在回复中不再提到订单号，而他们的运营团队每天都要靠这个信息工作。

传统单元测试发现不了这类问题。普通软件函数对每个输入只有一个正确输出；而正如 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 页面核对字段名。

```yaml
# 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` 过滤可以解决这个问题：只有至少一个变更文件匹配该模式时，工作流才会运行。

```yaml
# .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。

```yaml
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”这类字眼。然后对比简历上描述同一段经历的两种写法。

第二种写法更有说服力，因为招聘方可以核实。附上一个公开 PR 的链接，里面有结果评论，最好是因为新提示词更差而被标红的那种。

面试时，如果被问到“换模型时，你怎么知道没有东西坏掉？”，准备好用上面 DH-1042 的例子和 2/4 的计算来回答。

也可以把问题抛回给雇主：“团队在部署给客户之前，如何对提示词做回归测试？”答案会告诉你，你是有机会搭建这张安全网，还是要把时间花在收拾它缺位留下的烂摊子上。

你离开项目后，提示词还会被改几十次。你留给客户的不是最好的提示词，而是每个未来的提示词都必须通过的测试，用来证明它没有破坏已经正常运行的东西。

**本周动手试试:**

- 从手头的 LLM 项目中挑出 15-20 个真实问题，记录已认可的输出，作为黄金数据集保存到仓库中。
- 添加一个 promptfoo 工作流，用 paths 过滤指向提示词目录，提交一个改动提示词的 PR，阅读结果评论。
- 故意写一个更差的提示词，确认 PR 被标红，然后保存这个 PR 的链接，作为作品集里的证据。

## 信源

- [LLM evaluation: a beginner's guide (Evidently AI)](https://www.evidentlyai.com/llm-guide/llm-evaluation)

- [Watch the language: A tutorial on regression testing for LLMs](https://www.evidentlyai.com/blog/llm-regression-testing-tutorial)

- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions)

- [Testing Prompts with GitHub Actions | Promptfoo](https://www.promptfoo.dev/docs/integrations/github-action/)

- [Assertions and Metrics - LLM Output Validation | Promptfoo](https://www.promptfoo.dev/docs/configuration/expected-outputs/)
