Promptfoo：提示词测试评估框架

为什么需要 Promptfoo：LLM 输出随机 → 自动化回归测试

LLM 应用与传统软件最大的不同在于输出不固定：同样的提示词（Prompt），同一模型每次返回的文本都可能不同；提示词一个标点符号的改动，可能让对话质量大幅下降，也可能让格式化输出直接失效。传统做法是人工把几十条用例逐条粘贴进聊天窗口比对，费时费力，且无法沉淀成可重复执行的测试资产；当团队同时维护多套提示词、多个模型时，回归验证更是难以持续。

Promptfoo 把“测试提示词”这件事工程化：用 promptfooconfig.yaml 声明测试集，命令行一键执行，自动判断每条用例是否通过预设的断言（Assertion），并输出通过率、耗时、成本等指标。它支持 OpenAI、Anthropic、Azure、Ollama 等数十种模型提供方，同一套测试可在不同提示词、不同模型之间横向对比。改动提示词后重新运行即可确认无回归，从而把提示词迭代变成可度量的工程流程。

与同类工具相比，Promptfoo 的气质是“配置即代码”：不依赖特定平台或框架，纯 CLI 操作，既能跑在本地，也能直接接入 CI 流水线，MIT 协议下没有额外锁定，测试资产完全自持。

安装与环境配置：3 步就绪

第一步安装：Promptfoo 以 npm 包形式分发，要求 Node.js 18 及以上。全局安装后可随时调用 promptfoo 命令；不想全局安装时，用 npx 临时运行亦可，两者命令等价。

第二步配置：执行 promptfoo init 在当前目录生成示例 promptfooconfig.yaml 与说明，随后把模型密钥写入环境变量。Promptfoo 会自动读取项目根目录的 .env 文件（如 OPENAI_API_KEY=sk-xxx），无需手动逐条导出。

第三步验证：运行 promptfoo --version 确认安装成功；随后在已配置好密钥的目录执行 promptfoo eval，有配置即直接出评估结果，无配置则提示先初始化。

npm install -g promptfoo# 不想全局安装时：npx promptfoo@latestpromptfoo --version# 生成示例配置promptfoo init# 在 .env 中填写 OPENAI_API_KEY 后运行示例评估promptfoo eval

快速上手：10 分钟跑通第一个评估

最小可用流程的核心思路：写一份配置文件 → 运行评估 → 打开报告。配置文件同时承担“测试用例”与“断言”两个角色，是 Promptfoo 唯一的必写资产。

步骤一：在项目目录创建 promptfooconfig.yaml，声明要评测的提示词模板、模型提供方与测试用例。提示词中用 {{变量名}} 引用用例变量，用例写在 tests 字段。步骤二：在 .env 文件中写入 OPENAI_API_KEY。步骤三：执行 promptfoo eval，CLI 输出每条用例的通过与整体通过率。步骤四：执行 promptfoo view 启动本地 Web 界面，可逐条查看输入输出与断言详情，对比多个提示词或模型的差异。

下面是一份可直接运行的翻译场景配置：

运行结果中，contains 断言要求输出包含 "Bonjour"，latency 断言要求响应不超过 5000ms，全部通过则该用例通过。进阶技巧：在 prompts 中并列多段提示词、在 providers 中并列多个模型，即用同一份测试集横向 PK——这是做模型选型最常用的姿势。

# promptfooconfig.yamlprompts:  - "将下面这句话翻译成法语：{{text}}"providers:  - openai:gpt-4o-minitests:  - vars:      text: "你好，世界"    assert:      - type: contains        value: "Bonjour"      - type: latency        threshold: 5000

promptfoo evalpromptfoo view   # 浏览器打开本地报告，默认端口 15500

核心能力详解：4 大支柱

支柱一 · 多 Provider 适配。内置 40+ 模型提供方接入（OpenAI、Anthropic、Azure OpenAI、Google Gemini、Ollama 本地模型、私有网关等），providers 字段直接写 provider:model 格式，同一测试集可跨厂商执行；也支持 eval 时通过 --providers 参数在命令行覆盖配置，无需改动文件。

支柱二 · 断言系统。断言是判定输出是否符合预期的规则，分两类：确定性断言（deterministic，如 contains 包含、regex 正则、javascript/python 脚本、latency 延迟、cost 成本）由本地计算，稳定可复现；模型评分断言（如 llm-rubric，由另一个 LLM 按标准打分）适合主观质量评估；此外支持 webhook 对接自建裁判逻辑。

支柱三 · 对比评估报告。eval 结果自动生成结构化报告：promptfoo view 打开 Web 界面可逐条展开输入、输出、断言详情；promptfoo share 将结果上传生成在线链接，方便团队评审与缺陷留档；CLI 同时支持输出 JSON/HTML/CSV 报告，可沉淀到制品库。

支柱四 · Red Teaming 安全测试。v1.0 正式发布的红队模块可自动生成攻击性测试用例，覆盖提示注入、越狱（jailbreak）、敏感信息泄露、恶意内容等场景。promptfoo redteam setup 生成安全测试配置，redteam run 执行攻击矩阵并产出漏洞报告，把安全测试并入日常评估流程。

生产部署与监控：从上线到运维

CI 集成是 Promptfoo 最常见的生产用法：在 GitHub Actions 等流水线中安装 promptfoo 后执行 promptfoo eval --no-cache --threshold 90，通过率低于 90% 时进程以非零退出码结束、流水线即失败——提示词回归被拦截在合并之前，无需人工盯屏：

程序化调用方面，Promptfoo 同时提供 Node.js 库 API（import { evaluate } from "promptfoo"），可在自有测试框架、数据处理管道中按批次调用评估并解析结果，适合把评估嵌入更复杂的质检链路。

可观测性上，建议关注三类指标：通过率（断言通过比例，核心回归信号）、单次响应延迟与成本（通过 latency/cost 断言设上限）、失败用例的分布（是固定一条失败还是随机波动）。配合 --cache 可复用相同请求组合的结果以显著降本，但要注意缓存与配置变更的关系（见下方避坑）。分享链接可作为评审证据，形成提示词变更的审计轨迹。

<p class="para-label">避坑清单：</p>

<ul class=“dash-list“><li>缓存导致结果不更新：Promptfoo 以”提示词+提供方+测试用例”组合为缓存键，改动断言或环境变量不会自动失效，需要全量重跑时加 --no-cache；</li><li>Node 版本过低安装失败：npm 安装报引擎不兼容时先升级 Node 至 18+，而不是绕过低版本约束；</li><li>llm-rubric 结果不稳定：模型评分存在随机性，关键用例优先用 contains/regex 等确定性断言，裁判模型建议设为 temperature=0；</li><li>API Key 未生效：.env 文件必须与 promptfooconfig.yaml 同目录，格式为 OPENAI_API_KEY=sk-xxx，不要加引号与多余空格；</li></ul>

- uses: actions/checkout@v4- run: npm install -g promptfoo- run: promptfoo eval --no-cache --threshold 90  env:    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

版本迭代

Promptfoo 从 2023 年 6 月的单文件 CLI 起步，核心演进主线是“评估能力增强 → 生态扩展 → 安全能力并入”。2024 年密集补齐 Provider 适配与断言类型，2025 年 1 月发布的 v1.0 将 Red Teaming 从预览转为正式能力，标志着安全测试成为框架的一等公民（截至训练数据，可能已有更新版本）。

AI 应用场景

常见误区

面试题