promptfoo/promptfoo · 上手攻略

  • 仓库：promptfoo/promptfoo
  • 链接：https://github.com/promptfoo/promptfoo
  • 分类：ai
  • 作者：Tom
  • 更新：2026-07-09

是什么

Promptfoo 是一个用于评估（Evaluation）和红队（Red Teaming）LLM 应用的 CLI + 库工具。它解决的核心问题是：在 Prompt 工程和 AI 应用迭代过程中，你怎么知道你的改动真的变好了？靠"感觉不错"是不够的。

核心功能三件事： 1. 自动化评估（Eval）：用声明式 YAML 配置，自动跑测试用例、对比多个模型的输出，给出 pass/fail 和量化分数 2. 红队渗透测试：自动扫描 50+ 种 LLM 漏洞类型（jailbreak、injection、RAG poisoning 等） 3. 模型对比：一键对比 GPT、Claude、Gemini、DeepSeek、Ollama 等 60+ 模型的表现

已被 OpenAI 和 Anthropic 官方使用，现在是 OpenAI 旗下产品（保持 MIT 开源许可）。

解决什么问题

AI 应用上线最大的风险不是功能错，而是安全漏洞和 Prompt 退化：

  • Prompt 改了个词，可能让安全护栏失效
  • 换了新模型，老 Prompt 效果下降 30%
  • RAG 系统的检索质量没有客观指标
  • 上线后没有回归测试，迭代全凭感觉

Promptfoo 把 AI 质量保障变成可自动化、可复现的流程——像 Jest 之于 JavaScript，只是测试的是 LLM 输出而不是代码。

快速安装

环境要求

  • Node.js：^20.20.0 或 >= 22.22.0
  • ⚠️ Node.js 20 将于 2026-07-30 停止维护，届时 promptfoo 将要求 Node.js 24 LTS
  • 支持 npm、npx、brew、pip 安装

安装命令

# 全局安装
npm install -g promptfoo

# 或用 npx（无需安装）
npx promptfoo@latest

# 或用 brew（macOS/Linux）
brew install promptfoo

# 或用 pip
pip install promptfoo

⚠️ 注意：pip 安装仅包含 CLI，不含 Node.js 原生的核心评估引擎能力。

快速上手（Eval）

Step 1：初始化示例项目

promptfoo init --example getting-started
# 或用 npx
npx promptfoo@latest init --example getting-started

这会创建一个 getting-started/ 目录，包含： - promptfooconfig.yaml — 配置文件 - prompts.txt — 待测试 Prompt 模板 - README.md — 说明文档

Step 2：配置模型 providers

编辑 promptfooconfig.yaml，指定要对比的模型：

providers:
  - openai:chat:gpt-5.4
  - openai:chat:gpt-5.4-mini
  - anthropic:messages:claude-opus-4-6
  - google:gemini-3.1-pro-preview

⚠️ 注意：模型 ID 格式各 provider 不同，OpenAI 用 provider:model 格式（冒号），而 Mastra 用 provider/model（斜杠），此处是 promptfoo 的格式。

Step 3：编写测试用例

prompts:
  - 'Translate to {{language}}: {{input}}'

tests:
  - vars:
      language: French
      input: Hello world
    assert:
      - type: contains
        value: 'Bonjour'

  - vars:
      language: Spanish
      input: Where is the library?
    assert:
      - type: icontains
        value: 'biblioteca'

Step 4：运行评估

cd getting-started
promptfoo eval
# 查看结果
promptfoo view

promptfoo view 会打开 Web 界面，在浏览器中直观对比各模型输出。

核心用法进阶

断言类型（Asserts）

tests:
  - vars:
      question: "What is 2+2?"
    assert:
      # 简单包含
      - type: contains
        value: '4'
      # 不包含（安全护栏）
      - type: not-contains
        value: 'sorry'
      # LLM 裁判（用另一个模型评分）
      - type: llm-rubric
        value: 'Answer is mathematically correct'
      # 延迟阈值（ms）
      - type: latency
        threshold: 3000
      # 成本控制（美元）
      - type: cost
        threshold: 0.002

模型对比示例

# 直接在命令行覆盖配置中的模型
npx promptfoo@latest eval -r google:gemini-3.1-pro-preview google:gemini-2.5-pro

RAG 评估

npx promptfoo@latest init --example eval-rag

RAG 评估会自动检验：事实准确性、答案相关性、上下文召回率、上下文忠实度。

Agent 评估

npx promptfoo@latest init --example openai-agents-basic
npm install
npx promptfoo@latest eval

测试 Agent 的工具调用、多轮对话轨迹、任务完成率。

红队渗透测试（Red Teaming）

Promptfoo 红队功能不是用来攻击别人的系统，而是用来发现你自己 AI 应用的安全漏洞。

初始化红队项目

npx promptfoo@latest redteam setup
# 或跳过 GUI
npx promptfoo@latest redteam init --no-gui

向导会要求填写： 1. 应用描述（Purpose）：越具体，生成的测试用例越精准 2. 目标配置：API 端点 URL、认证方式等 3. 插件选择：选 50+ 漏洞类型插件（Jailbreak、Injection、RAG Poisoning 等） 4. 攻击策略：微软/ Meta 等机构研究的先进对抗方法

目标类型示例

HTTP API：

targets:
  - id: https
    label: 'my-api'
    config:
      url: 'https://example.com/generate'
      method: 'POST'
      headers:
        'Content-Type': 'application/json'
      body:
        myPrompt: '{{prompt}}'
    purpose: 'A customer service chatbot that helps users track orders.'

直接测模型：

prompts:
  - 'You are a helpful assistant. {{query}}'
targets:
  - id: openai:gpt-5-mini

运行红队扫描

npx promptfoo@latest redteam run
# 生成红队报告
npx promptfoo@latest redteam report

报告包含： - 漏洞分类（prompt injection、context poisoning、越狱等） - 严重程度评级 - 原始输入/输出日志 - 修复建议

典型适用场景

场景 适用原因
Prompt 迭代 每次改 Prompt 都能跑自动化回归，不会改坏
多模型选型 在真实测试用例上对比 60+ 模型，不靠广告
CI/CD 集成 每次 PR 自动跑 Eval，防止 Prompt 退化
RAG 质量保障 量化检索+生成的端到端质量
LLM 安全审计 扫描 50+ 漏洞，上线前发现风险
合规要求（OWASP/NIST/EU） 内置合规检查项，满足监管要求
多租户 API 对每个客户场景跑独立评估

坑与注意

  1. Node.js 版本 deadline：2026-07-30 后 promptfoo 将要求 Node.js 24 LTS，Node.js 20 用户必须升级。

  2. Provider API Key 必须设置：不设 API Key 的话多数 Provider 无法工作，常见错误就是 OPENAI_API_KEY not set。

  3. 红队测试仅限自有应用：文档明确说明只能测试你自己有权限的系统，不要用来扫描别人。

  4. Eval 本地运行，API Key 不外传：LLM 调用在本地执行，Prompt 不会离开你的机器（但模型响应取决于 Provider 政策）。

  5. 断言不是银弹：LLM-as-judge（llm-rubric）本身依赖模型，有幻觉风险，重要场景建议配合人工复审。

  6. 配置文件路径：promptfooconfig.yaml 必须和 promptfoo eval 同目录运行，不能指定其他路径（可以用 --no-cache 调试）。

  7. Ollama 本地模型：需要本地先跑 ollama serve，promptfoo 通过 HTTP 接口连接，速度比 API Key 方式快且免费。

与同类对比

Promptfoo LangSmith Helicone GPT Pilot
用途 Eval + Red Team Eval + Tracing Tracing + 成本分析 AI 测试生成
红队能力 ✅ 50+ 漏洞类型 ❌ ❌ ❌
多模型对比 ✅ 60+ ⚠️ 限单一平台 ❌ ⚠️
CI/CD 集成 ✅ ✅ ⚠️ ⚠️
本地/离线 ✅ ❌ ❌ ✅
开源 ✅ MIT ❌ 付费 ❌ 付费 ✅
上手难度 低 低 低 中

一句话总结：Promptfoo 是目前开源世界里最完整的 LLM 质量保障工具链——如果你在认真做 AI 产品而不是玩票，它应该成为你 CI/CD 的一部分。

一句话推荐结论

Promptfoo 把"我觉得这个 Prompt 改好了"变成"这个 Prompt 在 100 个测试用例上通过率从 72% 升到 91%"——做 AI 产品，这是你和拍脑袋之间的最大差距。