轻量入门方案
Demo 仓库 ↗Promptfoo + Gitee CI：搭建 Prompt 回归流水线
把 Promptfoo 评测接入 Gitee 的持续集成，在代码提交或合并请求时自动执行质量门禁。
技术栈：Promptfoo · Gitee CI · Node.js厂商绑定：无
适用场景
适合代码托管在 Gitee、希望不依赖厂商平台就完成 Prompt 回归的测试团队。流水线只负责调度和阻断，评测逻辑仍然由仓库里的 Promptfoo 配置管理。
前置依赖
- Gitee 仓库已启用 Gitee Go / CI。
- 仓库中存在
promptfooconfig.yaml、Prompt 文件和评测脚本。 - 在 Gitee 仓库变量中配置
OPENAI_API_KEY、OPENAI_BASE_URL、OPENAI_MODEL。 - Runner 能访问你的模型接口。
敏感变量只放在 Gitee 的加密变量中，不提交到仓库。
完整步骤
1. 固定目录结构
promptfoo-regression/
├─ promptfooconfig.yaml
├─ prompts/
│ ├─ baseline.txt
│ └─ candidate.txt
├─ tests/
│ └─ smoke.yaml
└─ scripts/
└─ check-gate.js
2. 本地先跑通
先执行 npx promptfoo eval -c promptfooconfig.yaml。本地失败时不要直接交给 CI 排查。
3. 添加 Gitee CI 配置
在仓库根目录创建 .workflow/promptfoo.yml，安装 Node 依赖、执行评测、上传结果并执行门禁脚本。
4. 配置触发条件
建议在 Prompt、测试数据、评测脚本变更时触发；普通文档变更无需消耗模型调用。
5. 处理失败
流水线失败后下载结果文件，优先定位失败用例和差异样本，再决定修改 Prompt、数据还是门禁规则。
代码 / 配置
.workflow/promptfoo.yml
name: promptfoo-regression
triggers:
push:
branches: [main, develop]
pull_request:
types: [open, update]
steps:
install:
image: node:20
commands:
- npm ci
eval:
image: node:20
commands:
- npx promptfoo eval -c promptfooconfig.yaml -o artifacts/results.json
- node scripts/check-gate.js artifacts/results.json
env:
OPENAI_API_KEY: $OPENAI_API_KEY
OPENAI_BASE_URL: $OPENAI_BASE_URL
OPENAI_MODEL: $OPENAI_MODEL
artifacts:
paths:
- artifacts/results.json
不同 Gitee 组织的 Runner 配置语法可能不同，提交前应以仓库实际的 Gitee Go 模板校验为准；核心命令保持不变。
结果解读
CI 结果分为三类：
- 通过：关键用例无失败，退化指标在允许范围内。
- 阻断：出现 P0/P1 失败、关键样本回归或候选版本显著退化。
- 需复核：裁判低置信度、接口超时或测试环境异常。
环境故障不能直接当成业务质量通过，应单独标记为 infrastructure_failure。
踩坑清单
- Gitee Runner 的 Node 版本和本地不一致。
- 加密变量名称与 YAML 中的变量名称不一致。
- 未创建 artifacts 目录导致结果无法上传。
- 重试机制把真实失败掩盖成成功。
- 评测超时没有设置合理的任务上限和并发数。
拓展优化
- 将冒烟集和完整回归集分成两个流水线。
- 对 Pull Request 只跑低成本样本，合并到主分支再跑完整集。
- 对模型返回做缓存，但缓存键必须包含 Prompt、模型和参数版本。
- 把结果摘要写入 CI 评论，把完整 JSON 作为构建产物保存。
- 逐步加入人工复核队列，不让不确定结果静默通过。