把 eval 从平台搬回仓库：Promptfoo 配置、断言和能验收的标准 · Skills

写在前面：这次迁移没有导出功能。官方指南原话是它覆盖”在 Promptfoo 里手动重建一个 eval”，不依赖 OpenAI Evals 的导出。所以别去找一键迁移，直接照着旧 eval 抄。

第一步：装 CLI，先跑通一个空配置

npm install -g promptfoo@latest
promptfoo init eval-suite
cd eval-suite

promptfoo init 会生成一个能直接跑的目录。先跑一次确认环境没问题：

promptfoo eval -c promptfooconfig.yaml --no-cache
promptfoo view

view 会在本地打开结果页，一屏看到每条样本的通过情况。配置改坏了就先验证再重跑：

promptfoo validate config -c promptfooconfig.yaml

第二步：四段配置，把旧 eval 拆进去

一份 promptfooconfig.yaml 就四块，跟 OpenAI Evals 的构建块一一对应——测试数据、prompt、模型、打分标准。

description: 客服邮件分类回归集

prompts:
  - file://prompt.txt

providers:
  - openai:gpt-5.6-terra

tests:
  - vars:
      email: "我上周下的订单还没发货，订单号 88213"
    assert:
      - type: contains
        value: "物流"
      - type: llm-rubric
        value: "回答里必须给出下一步动作，不能只道歉"
  - vars:
      email: "你们的产品真好用，谢谢"
    assert:
      - type: not-contains
        value: "订单号"

要点：

prompts 指向文件而不是内联字符串，prompt 才能进 git、才能 diff。
providers 用 openai: 前缀，走 OPENAI_API_KEY。要对比两个模型就并列写两行，一次跑出对比结果。
tests 里每条样本自带断言，比”一批样本配一套全局规则”好维护。

第三步：把 grader 翻译成断言

OpenAI 平台上的 grader 大致对应这几类断言：

原来的 grader	写法
字符串匹配 / 包含	`contains` / `not-contains` / `equals`
JSON 结构校验	`is-json` 加 `javascript` 取值判断
相似度阈值	`similar` （注意：跨系统的分数不可直接比）
模型打分	`llm-rubric`，把评分标准写成一句话

llm-rubric 这类模型打分的断言，重建之后必须重新校准。 官方明确提醒：基于相似度的评分在不同系统里不会给出完全相同的数字，任何手工重建的 grader——尤其是 LLM-as-a-judge——在拿来当回归门槛之前要先验证。做法是拿旧平台上跑过的一组样本，在新配置里跑一遍，对比通过率；差超过 10 个百分点就把阈值调回原来的通过率水平，而不是照抄数值。

第四步：接进 CI

最小可用的 GitHub Actions 步骤：

- run: npx promptfoo@latest eval -c promptfooconfig.yaml --no-cache
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

跑法以官方 CI 集成文档为准，有现成的 action 可以省掉手写步骤。CI 里建议把 --no-cache 带上，否则缓存会把模型的真实波动盖掉，回归集就失去意义了。

怎么知道自己做对了

供应商只出现在一个文件里。 promptfooconfig.yaml 里的 providers 是唯一出现模型名的地方；改它一行就能整体换供应商，业务代码一行不动。做不到说明适配层还没抽出来。
30 条以上真实样本全部跑通，且断言不是全绿。 全绿通常意味着断言写得太松。健康的回归集里应该有 2 到 3 条是”已知会失败、正在修”的。
通过率和旧平台对齐。 同一批样本，新旧两侧的通过率差在 10 个百分点以内。超了先查 grader 翻译，别急着改阈值。
CI 里能复现。 本地跑一次、CI 跑一次，两次结果一致，且任意一次提交能让 CI 变红（手动改坏一条断言验证一次）。

泼冷水

回归集搬回家之后，维护成本就完全落在你身上了——样本要更新、断言会过时、模型升级会让一批断言突然变红。以前这些至少有个界面帮你点。所以样本别贪多，30 到 60 条覆盖主要分支就够，堆到几百条只会让它彻底停更。

还有一层：eval 解决的是”改动有没有搞坏东西”，不解决”这个东西本身对不对”。一套跑得飞绿的回归集，完全可能建立在一个错误的产品判断上。

原文：https://developers.openai.com/cookbook/examples/evaluation/moving-from-openai-evals-to-promptfoo CI 集成：https://www.promptfoo.dev/docs/integrations/ci-cd/