Promptfoo 工具详细使用指南Promptfoo 是一款开源的 LLM 应用评测与红队测试工具核心定位是将大模型 Prompt 调优、效果验证从“人工凭感觉”转化为标准化、可量化、可重复的工程化流程。它支持多 Prompt、多模型并行对比内置丰富的断言体系与安全测试能力可无缝集成到 CI/CD 流水线是 AI 测试团队落地自动化评测的主流工具之一。一、环境安装与初始化1. 前置依赖需要 Node.js 18 及以上版本支持 Windows、macOS、Linux 全平台运行。2. 安装方式全局安装推荐npminstall-gpromptfoo国内用户可使用镜像加速npminstall-gpromptfoo--registryhttps://registry.npmmirror.com免安装运行适合临时试用场景无需全局安装npx promptfoolatest3. 项目初始化生成带示例的入门项目promptfoo init--examplegetting-started交互式空白项目初始化promptfoo init执行后可选择评测场景、目标模型自动生成核心配置文件promptfooconfig.yaml。4. 配置模型密钥通过环境变量配置对应大模型平台的 API Key常用配置示例# OpenAIexportOPENAI_API_KEYsk-xxx# AnthropicexportANTHROPIC_API_KEYsk-ant-xxx# 国内模型如智谱AIexportZHIPU_API_KEYyour-key国内模型也可直接在配置文件中通过headers字段指定密钥适配自研或私有化部署的模型接口。二、核心概念与配置文件结构Promptfoo 的所有评测逻辑都由promptfooconfig.yaml定义核心包含四大模块1. prompts待测提示词模板定义发送给大模型的提示词支持变量插值、文件引用、动态生成三种形式直接内联文本用{{变量名}}做占位符加载本地文本/JSON文件file://prompts/customer_service.txt通过 JS/Python 脚本动态生成file://generate_prompt.js支持多轮对话格式JSON 数组结构的聊天消息示例prompts:-你是专业客服助手请回答用户问题{{user_question}}-file://prompts/service_v2_prompt.txt2. providers被测模型提供商指定评测调用的大模型内置支持 20 主流平台包括 OpenAI、Anthropic、Google Gemini、Azure OpenAI、Ollama、智谱AI、百度千帆等。通用格式提供商:类型:模型名示例providers:-openai:chat:gpt-4o-mini-anthropic:messages:claude-3-5-sonnet-20241022-ollama:chat:qwen2.5:7b同时支持自定义 API 接口通过配置endpoint、headers适配私有化部署的大模型。3. tests测试用例集每个测试用例由**变量值vars和断言规则assert**组成是评测的最小执行单元。支持三种用例管理方式内联编写适合小规模测试导入本地 CSV/JSON 文件对接 HuggingFace、云存储等外部数据集示例tests:-description:退款咨询场景vars:user_question:如何申请订单退款assert:-type:containsvalue:退款流程-type:llm-rubricvalue:回答清晰步骤明确语气友好threshold:0.84. defaultTest全局默认配置所有测试用例共享的断言、超时、评分模型等配置避免重复编写。defaultTest:assert:-type:latencythreshold:3000# 所有用例响应耗时不超过3秒-type:costthreshold:0.002# 单次调用成本不超过0.002美元options:provider:openai:gpt-4o-mini# 指定统一的评分模型三、基础使用完整流程1. 执行评测在配置文件所在目录执行命令启动批量评测# 使用默认配置文件 promptfooconfig.yamlpromptfooeval# 指定自定义配置文件promptfooeval-cmy-eval-config.yaml# 输出结果到指定文件支持 json、csv、htmlpromptfooeval-oresults.json# 评测不通过则返回非0退出码适合CI流水线promptfooeval--fail-on-error执行完成后终端会直接输出核心统计总用例数、通过率、平均耗时、总调用成本等信息。2. 可视化查看结果执行以下命令启动本地 Web 服务自动打开浏览器展示详细评测报告promptfoo view可视化报告支持逐条查看每个用例的输入、模型输出、断言详情横向对比不同 Prompt、不同模型的表现差异按通过率、耗时、成本等维度排序筛选导出 HTML、JSON、CSV 格式的报告文件四、核心断言类型详解断言是 Promptfoo 评测的核心能力分为确定性断言和模型评分断言两大类覆盖从规则校验到主观质量评估的全场景。1. 确定性断言无需额外调用模型无需二次调用大模型基于规则精准校验零额外成本、结果无偏差断言类型功能说明contains/not-contains校验输出包含/不包含指定文本equals校验输出完全等于预期值适合客观题场景regex校验输出匹配指定正则表达式is-json/is-yaml校验输出为合法的 JSON/YAML 格式latency校验接口响应耗时不超过阈值单位毫秒cost校验单次调用成本不超过阈值单位美元javascript执行自定义 JS 脚本实现复杂逻辑校验levenshtein基于编辑距离校验文本相似度2. 模型评分断言LLM-as-a-Judge核心为llm-rubric类型通过大模型作为“评委”按照自定义评分标准对输出进行 0~1 分的主观打分适配事实准确性、逻辑合理性、风格符合度等难以用规则校验的场景。示例assert:-type:llm-rubricvalue:回答必须完全基于给定上下文不得捏造事实语言简洁专业threshold:0.8# 得分≥0.8视为通过可单独指定评分模型通常用低成本小模型担任评委控制评测成本支持自定义评分维度可适配业务专属的质量标准五、高级功能与专项评测1. 自动化红队安全测试Promptfoo 内置完整的 LLM 红队测试能力可自动生成对抗性 Prompt批量检测模型的安全漏洞覆盖 Prompt 注入、敏感内容生成、偏见歧视、越权回答等常见风险点。常用命令# 执行全量红队扫描promptfoo redteam run# 指定攻击插件类型promptfoo redteam run--pluginsinjection,hate-speech,misinformation# 查看红队测试报告promptfoo redteam view适合上线前的安全合规校验自动发现人工难以覆盖的对抗性场景。2. RAG 系统专项评测可直接用于 RAG 检索增强生成系统的全链路效果评测注入检索上下文变量校验答案的上下文忠实度支持检索准确率、事实幻觉率、无关信息占比等专项维度可对接真实业务知识库批量验证 RAG 链路的整体效果3. 代码生成沙箱评测针对代码生成场景支持在 Docker 隔离沙箱中执行生成的代码通过单元用例验证代码正确性同时规避恶意代码风险。需配合epicbox和 Docker 使用支持自定义运行环境镜像适配 Python、Java、JavaScript 等多语言。4. 外部数据集对接测试用例无需全部手动编写支持多种数据源一键导入本地 CSV/JSON 文件tests: file://test_cases.csvHuggingFace 公开数据集tests: huggingface://datasets/rajpurkar/squad云存储文件Azure Blob、AWS S3 等适合企业沉淀内部黄金评测集实现标准化回归测试。5. 动态脚本扩展支持通过 JavaScript、Python 脚本动态生成 Prompt、测试用例甚至自定义断言逻辑可对接业务数据库、线上 bad case 回流系统适配复杂定制化场景。六、工程化与 CI/CD 集成Promptfoo 原生支持嵌入研发流水线实现 Prompt 变更、模型迭代后的自动回归评测落地质量门禁。1. 流水线集成示例在 GitHub Actions / GitLab CI 中加入以下步骤# 执行基准评测npx promptfoolatesteval-cpromptfooconfig.yaml-oresults.json --fail-on-error# 执行安全红队扫描核心业务必跑npx promptfoolatest redteam run--pluginsinjection,pii-leakage配合--fail-on-error参数评测不通过则阻断发布将 AI 质量校验纳入标准发布流程。2. 与现有测试框架融合可通过 CLI 调用 JSON 结果解析的方式将 Promptfoo 集成到 Pytest、JUnit 等传统测试框架中统一测试报告与管理流程降低团队转型成本。七、最佳实践与避坑建议评测分层推进优先用确定性断言覆盖基础规则校验再逐步补充llm-rubric覆盖主观维度避免一开始全靠大模型评分导致成本高、结果波动大。控制评测成本评分任务优先选用低成本小模型如 gpt-4o-mini批量评测前先小范围试运行避免产生意外高额 API 费用。沉淀黄金数据集持续将线上 bad case、边界场景、极端案例加入测试集形成业务专属评测基准每次模型/Prompt 迭代必跑回归。人工校准机制核心高风险业务场景必须保留人工抽样复核定期校准大模型评委的评分偏差避免自动评分与真实业务感受脱节。避免过度玄学化评测指标必须锚定业务价值不要堆砌无意义的评分维度优先保障核心场景的质量可控。