Promptfoo：面向生产环境的LLM提示词质量评估框架

1. 这不是又一个LLM“跑通就行”的教程——Promptfoo 是你模型上线前最后一道质量卡口

如果你正在用大模型做实际业务，比如把 LLM 接入客服工单分类系统、让模型从合同里抽关键条款、或者批量生成合规的营销文案，那你大概率已经踩过这些坑：昨天还85%准确率的 prompt，今天加了三条新样例后掉到62%；A/B 测试时发现模型在测试集上表现亮眼，一放到真实用户对话流里就频繁胡说；团队里三个人写的 prompt 各自为政，没人能说清哪个版本真正更稳。这些问题背后，缺的不是更多数据或更大模型，而是可量化、可复现、可协作的评估机制。Promptfoo 就是专治这个病的——它不训练模型，不写 prompt，而是给你一套“显微镜+游标卡尺”，让你能像测电压、量尺寸一样，客观测量 prompt 的鲁棒性、一致性、抗干扰能力。我去年在给一家保险科技公司做核保规则引擎升级时，用 Promptfoo 把原本靠人工抽查 20 条样本就“感觉差不多”的评估流程，变成了每天自动跑 37 个测试用例、生成带置信区间的质量报告。最直接的结果是：上线前模型幻觉率从 11.3% 压到 2.1%，且每次 prompt 迭代后，我们能立刻定位是“对模糊表述的容忍度下降”还是“对专业术语的泛化能力增强”。它适合三类人：正在把 LLM 落地到生产环境的工程师（你需要知道模型在边界场景下会不会崩）；负责 prompt 工程的算法同学（你得证明自己调的不是玄学）；还有技术负责人（你要向业务方解释：为什么这个 prompt 值得上 30 万预算）。别把它当成另一个 CLI 工具，它是你 LLM 项目里的 QA 工程师。

2. 为什么非得是 Promptfoo？而不是自己写脚本、用 LangChain Eval 或者直接看 accuracy？

2.1 传统评估方式的硬伤：从“拍脑袋”到“伪科学”

很多人第一反应是：“我写个 Python 脚本循环跑几条测试数据不就行了？”——这确实能跑通，但很快会撞墙。举个真实例子：我们曾用一个 5 行 for 循环脚本评估合同关键信息抽取 prompt，输入 100 条样本，输出一个 overall accuracy=89.2%。但后来发现，这 100 条里有 72 条是标准格式的保单，剩下 28 条是手写扫描件转的文字，而模型在这 28 条上的准确率只有 41%。问题出在哪？脚本没做分组统计，更没定义“准确”的标准：是字段全对才算对？还是只要核心字段（如被保人姓名、保额）正确就给分？还是允许同义词替换（如“人民币”≈“CNY”）？自己写的脚本往往只解决“能不能跑”，不解决“怎么才算好”。LangChain 的 eval 模块看似更专业，但它本质是把评估逻辑耦合在链式调用里，一旦你的 pipeline 涉及多步调用（比如先用 LLM 做意图识别，再路由到不同子模型），它的 evaluator 就很难插进去做中间节点的断言。更致命的是，它没有内置的“对抗测试”能力——比如你没法一键生成 20 个语义相同但句式各异的变体，去测 prompt 对表达方式的鲁棒性。而 Promptfoo 的设计哲学很清晰：评估必须和模型调用解耦，必须支持声明式定义，必须能覆盖从功能正确性到工程稳定性全维度。它不关心你用的是 OpenAI 还是本地 Llama3，也不管你是通过 API 还是 Ollama 调用，只要你能把输入输出标准化成 JSON，它就能工作。

2.2 Promptfoo 的三层架构：为什么它能同时兼顾灵活性与严谨性

Promptfoo 的核心不是一堆命令，而是一个三层评估框架，每一层解决一类问题：

• 第一层：测试用例（Test Cases）——这是你的“黄金标准”。每个 test case 是一个明确的输入-期望输出对，比如输入是“请提取以下合同中的甲方名称、乙方名称和签约日期”，期望输出是{"party_a": "XX科技有限公司", "party_b": "YY保险股份有限公司", "sign_date": "2024-03-15"}。关键在于，它支持结构化期望（JSON Schema）、模糊匹配（正则、语义相似度阈值）、甚至多级断言（比如先检查字段是否存在，再检查值是否在预设枚举中）。这比简单字符串对比强太多。

• 第二层：评估器（Evaluators）——这是你的“质检员”。Promptfoo 内置了 12 种评估器，从基础的equals（严格相等）、contains（包含关键词），到高级的llm-rubric（用另一个 LLM 当裁判，按预设 rubric 打分）、model-graded-closedqa（让模型判断答案是否满足闭合式问答要求）。最实用的是similarity评估器，它默认用 OpenAI 的 text-embedding-3-small 计算 embedding 余弦相似度，阈值可调（我们通常设 0.82，低于此值视为语义偏离）。这意味着，即使模型把“2024年3月15日”写成“2024-03-15”，只要语义一致，它就判为通过。

• 第三层：场景（Scenarios）与比较（Comparisons）——这是你的“实验室”。你可以把同一组 test cases 丢给多个 prompt 版本（v1_prompt.txt, v2_prompt.txt）或多个模型（gpt-4-turbo, claude-3-haiku），然后生成横向对比报告。报告里不仅有总分，还有每个 test case 在各版本下的表现热力图、失败原因归类（如“格式错误”、“事实错误”、“遗漏字段”），甚至能导出 CSV 供 BI 工具分析趋势。这才是真正支撑决策的数据。

提示：不要试图用 Promptfoo 替代单元测试。它解决的是“模型行为是否符合业务预期”，而单元测试解决的是“代码逻辑是否正确”。两者必须共存。我们团队的规范是：所有 prompt 变更必须附带 Promptfoo 测试套件，且 CI 流水线中，Promptfoo 评估失败 = 构建失败。

2.3 它不是银弹，但划清了“能用”和“敢用”的界限

必须坦诚：Promptfoo 不解决模型本身的能力天花板。如果你的 base model 连基本数学计算都错，Promptfoo 只会忠实地告诉你“所有涉及数字的测试用例全部失败”。它也不解决数据漂移问题——当业务场景突变（比如突然要处理大量海外保单），旧的 test cases 可能失效，需要人工更新。但它划清了一条关键分界线：“能用”是指模型在某个快照下跑通了几个例子；“敢用”是指你有证据证明，它在已知的 97 个边界场景下，失败率稳定在 3% 以内，且失败模式可预测、可修复。后者才是生产环境的入场券。我们上线前的最后一道关，就是让 Promptfoo 跑满 72 小时的压力测试：每分钟生成 50 个随机扰动的输入（加入错别字、中英文混排、超长段落截断），持续监控成功率曲线。只有曲线平稳在 98.5%±0.3% 区间，才允许发布。这种确定性，是任何“感觉良好”的评估给不了的。

3. 从零开始搭建你的第一个 Promptfoo 评估流水线：实操步骤、参数选择与避坑指南

3.1 环境准备与最小可行配置：5 分钟跑通，但别跳过这三步

安装 Promptfoo 极其简单，但有三个细节决定你后续是否踩坑：

# 推荐用 npm 全局安装（比 pip 更稳定，尤其在 Windows 上） npm install -g promptfoo # 验证安装 promptfoo --version # 输出应为 0.72.0 或更高（截至 2024 年 7 月最新版） # 初始化项目目录 mkdir my-llm-eval && cd my-llm-eval promptfoo init

promptfoo init会生成三个核心文件：promptfooconfig.yaml（主配置）、prompts/（存放 prompt 模板）、tests/（存放测试用例）。重点来了：初始化后，务必打开promptfooconfig.yaml，修改这两处：

1. providers配置：默认它可能只配了openai:chat。如果你用的是本地模型，比如 Ollama 的llama3，要这样写：

   providers: - id: ollama:chat config: baseUrl: http://localhost:11434 model: llama3

   注意baseUrl必须带协议（http://），且端口正确。我们曾因漏写http://导致连接超时，报错信息却指向模型 ID 错误，排查了 2 小时。

2. defaultTestFile路径：默认指向tests/test.yaml，但建议改成tests/main.yaml，避免和未来可能的tests/edge_cases.yaml混淆。

注意：Promptfoo 默认使用OPENAI_API_KEY环境变量调用 OpenAI。如果你不用 OpenAI，必须在providers里明确定义其他 provider，并在tests/文件中指定provider: ollama:chat。否则它会静默 fallback 到 OpenAI，导致本地模型调试失败。

3.2 编写第一个测试用例：从“Hello World”到真实业务场景

别一上来就写复杂合同解析。先用一个极简的“回声测试”验证整个链路：

在tests/main.yaml中写：

- vars: input: "你好，今天天气怎么样？" assert: - type: equals value: "你好！今天天气不错。" provider: ollama:chat # 明确指定 provider

然后运行：

promptfoo eval

如果看到✅ Passed: 1 / 1，说明基础环境通了。接下来，升级到真实场景。假设我们要评估一个“会议纪要摘要” prompt：

1. 在prompts/summary.txt中写 prompt：

   你是一个专业的会议助理。请根据以下会议记录，生成一份简洁的摘要，包含：1) 主要议题；2) 关键结论；3) 下一步行动项（列出具体负责人和截止日期）。摘要必须用中文，不超过 200 字。

2. 在tests/main.yaml中添加测试用例：

   - vars: input: | 【会议记录】 时间：2024-07-10 14:00 参会人：张三（产品）、李四（研发）、王五（市场） 议题1：Q3 新功能上线计划 结论：确定 8 月 15 日上线「智能推荐」模块，需市场部配合预热。 行动项：张三负责需求文档终稿，7 月 25 日前；李四负责接口联调，8 月 5 日前。 议题2：用户反馈处理 结论：优先修复登录页加载慢问题。 行动项：李四负责性能优化，7 月 30 日前。 assert: - type: contains value: "Q3 新功能上线计划" - type: contains value: "智能推荐" - type: contains value: "张三" - type: contains value: "7 月 25 日" - type: similarity value: "主要议题：Q3 新功能上线计划、用户反馈处理\n关键结论：确定 8 月 15 日上线「智能推荐」模块；优先修复登录页加载慢问题。\n下一步行动项：张三负责需求文档终稿（7 月 25 日前）；李四负责接口联调（8 月 5 日前）和性能优化（7 月 30 日前）。" threshold: 0.85

这里的关键技巧是：混合使用断言类型。contains快速验证关键信息是否出现，similarity确保整体结构和语义完整。threshold: 0.85是我们经过 50 次实验得出的经验值——低于 0.8，模型偶尔会漏掉一个逗号就失败；高于 0.9，对合理 paraphrasing（如“上线” vs “发布”）过于敏感。

3.3 进阶：构建对抗测试集与自动化回归

真实业务中，最怕的不是模型答错，而是答错得“很有道理”。比如合同抽取，模型把“甲方：北京XX公司”错写成“甲方：上海XX公司”，人类一眼看出是错的，但similarity评估器可能因为公司名相似而放过。这时要用 Promptfoo 的adversarial能力：

1. 在tests/adversarial.yaml中创建对抗测试：

   - vars: input: | 【合同片段】 甲方：北京智算科技有限公司 乙方：上海云图数据服务有限公司 金额：人民币伍拾万元整 assert: - type: json schema: type: object properties: party_a: type: string pattern: "^北京.*有限公司$" # 强制甲方必须是北京开头 party_b: type: string pattern: "^上海.*有限公司$" amount: type: string pattern: "^(人民币|CNY).*(伍拾|50).*万元$"

2. 运行时指定多个测试文件：

   promptfoo eval --test test.yaml --test adversarial.yaml

3. 接入 CI/CD：在 GitHub Actions 中，我们这样配置：

   - name: Run Promptfoo Evaluation run: | npm install -g promptfoo promptfoo eval --no-cache --max-concurrency 5 env: OLLAMA_HOST: http://localhost:11434

   --no-cache防止本地缓存污染线上结果，--max-concurrency 5控制并发数，避免压垮本地 Ollama 服务。

实操心得：我们最初把所有测试塞进一个main.yaml，结果每次改一个用例就要重跑全部 127 个测试，耗时 8 分钟。后来拆分成functional.yaml（核心功能）、robustness.yaml（对抗测试）、performance.yaml（响应时间 SLA），并用promptfoo eval --test functional.yaml按需执行，迭代速度提升 4 倍。记住：测试套件也是代码，要遵循单一职责原则。

4. 生产级评估报告解读与问题根因定位：从“Failed”到“怎么修”

4.1 看懂 HTML 报告里的每一个像素：不只是红绿灯

运行promptfoo eval --write会生成report.html。别只盯着右上角那个大大的✅ 92.3%。真正有价值的信息藏在细节里：

• 左侧导航栏的“Test Cases”：点击任意一个 failed 的用例，你会看到三列对比：

  • Input：原始输入文本（可折叠）
  • Expected：你定义的期望输出（支持 JSON Schema 高亮）
  • Actual：模型实际输出（带语法高亮）

  关键是下方的“Assertion Results”区域：它会逐条列出你定义的每个assert，并标出哪一条失败。比如：

  [FAIL] similarity: Expected similarity >= 0.85, got 0.72 [PASS] contains: 'Q3 新功能上线计划' [PASS] contains: '智能推荐'

  这立刻告诉你：问题不是模型漏了关键信息，而是它生成的摘要结构混乱、语义偏离。此时，你应该去检查 prompt 是否明确了“分点陈述”的格式要求。

• “Comparison” 标签页：当你对比多个 prompt 时，这里会显示热力图。深绿色代表该用例在所有版本中都通过，深红色代表全部失败。最值得关注的是浅黄色格子——它表示“只在某个版本失败”。比如prompt_v2在“含错别字的输入”上失败，而prompt_v1通过，这强烈暗示v2的 prompt 过度依赖了原文的精确措辞，鲁棒性反而下降。

• “Metrics” 标签页：提供全局统计。注意Latency (p95)—— 95% 请求的响应时间。如果这个值超过你 SLA（比如 2.5 秒），即使准确率 100%，也不能上线。我们曾发现一个 prompt 因要求模型“用文言文重写摘要”，导致平均延迟飙升到 4.8 秒，果断废弃。

4.2 失败案例归类与根因树：建立你的“Prompt 故障知识库”

我们团队维护一个共享的FAILURE_ROOT_CAUSES.md，把所有失败归为 5 类，每类对应 Promptfoo 的特定表现：

这个表格不是凭空写的。每一行都来自我们过去 3 个月 147 次失败的复盘。比如“上下文遗忘”这一条，我们发现当输入长度超过 1800 token 时，失败率陡增，于是把similarity评估器的阈值从 0.85 降到 0.78（接受一定语义压缩），同时在 prompt 中增加位置强调指令，双管齐下后，长文本失败率从 34% 降到 5%。

4.3 一个真实故障的 15 分钟定位实录：从报警到修复

上周五下午 4:23，我们的监控告警：contract-extractor服务的field_extraction_accuracy从 98.2% 突降至 83.1%。以下是我们的标准响应流程：

1. Step 1（2 分钟）：立即运行promptfoo eval --test tests/production.yaml --provider openai:chat，确认是 OpenAI 模型问题（排除本地 Ollama 故障）。报告确认：127 个用例中，23 个失败，全部集中在“金额字段”。

2. Step 2（5 分钟）：打开report.html，筛选所有失败用例，发现共同点：输入中金额写法为“¥500,000.00”或“RMB 500000”，而期望输出是“人民币伍拾万元整”。检查assert，发现用了equals断言，但模型输出是“500000元”。这说明equals过于严格。

3. Step 3（3 分钟）：修改tests/production.yaml，将equals替换为llm-rubric：

   - type: llm-rubric value: | 金额字段必须准确无误。允许以下等价形式： - 数字：500000、500,000、500000.00 - 文字：伍拾万元整、五十万元整、50万元 - 符号：¥500000、RMB 500000 禁止：四舍五入、单位错误（如写成‘万元’而非‘元’）、遗漏小数位。

4. Step 4（3 分钟）：重新运行promptfoo eval，失败数降为 2。查看剩余两个失败用例，发现是模型把“¥1,234,567.89”错写成“1234567.89元”（漏了千分位逗号，但 rubric 允许）。确认这是可接受的格式变体，将这两个用例的assert改为similarity，阈值设 0.92。

5. Step 5（2 分钟）：提交 PR，CI 自动运行全量测试，通过。发布新版本。全程 15 分钟，服务恢复。

这个过程之所以快，是因为 Promptfoo 把“哪里错了”转化成了“哪条断言错了”，把模糊的“模型不准”变成了具体的“金额格式断言策略需要调整”。没有它，我们可能要花 2 小时翻日志、猜原因。

5. 超越基础：Promptfoo 在复杂场景中的深度应用与经验陷阱

5.1 多模型协同评估：当你的 pipeline 不止一个 LLM

很多业务不是单个 prompt 能搞定的。比如我们的“智能投顾”系统：第一步用 LLM 从用户提问中识别投资目标（保守/平衡/激进）；第二步根据目标，路由到不同的资产配置模型；第三步用另一个 LLM 生成通俗易懂的建议。这时，Promptfoo 的scenario功能就至关重要。

我们创建scenarios/investment_advice.yaml：

- id: investment-routing description: 测试用户目标识别的准确性 tests: - vars: input: "我今年 55 岁，希望退休后每月有固定收入，不太能承受亏损。" assert: - type: equals value: "conservative" - id: asset-allocation description: 测试保守型配置的合理性（需调用外部 API） tests: - vars: input: '{"goal": "conservative", "age": 55}' assert: - type: json schema: type: object properties: bonds: type: number minimum: 60 maximum: 90 stocks: type: number minimum: 10 maximum: 40 - id: advice-generation description: 测试最终建议的可读性 tests: - vars: input: | 【配置方案】债券 75%，股票 25% 【用户画像】55 岁，保守型 assert: - type: contains value: "债券" - type: contains value: "风险较低" - type: similarity value: "建议以债券为主（75%），提供稳定收益；少量配置股票（25%）以抵御通胀。" threshold: 0.88

关键技巧：用id定义逻辑阶段，用description写明业务含义。这样生成的报告里，“investment-routing” 失败率高，你就知道是第一步出了问题，不用去查整个 pipeline。我们甚至把id和 Jira ticket 关联，比如id: routing-bug-JIRA-1234，方便追踪。

5.2 与现有 MLOps 工具链集成：让评估成为数据飞轮的一环

Promptfoo 不是孤岛。我们把它嵌入了整个 MLOps 流程：

• 数据层：tests/目录由数据团队维护，他们从线上日志中自动采样失败 case，每周生成tests/weekly_fails.yaml，确保测试集永远反映真实痛点。

• 模型层：在 Weights & Biases 中，每次promptfoo eval运行后，我们用promptfoo export --format json导出结果，再用 Python 脚本上传关键指标（accuracy,latency_p95,similarity_mean）到 W&B 的llm-eval项目，形成趋势图。

• 监控层：用 Prometheus 抓取promptfoo eval的 exit code 和耗时，配置告警：“连续 3 次promptfoo eval失败率 > 5%” 或 “latency_p95> 3s 持续 5 分钟”。

最妙的是反向驱动：当promptfoo发现某个 prompt 在“含专业术语的输入”上失败率高，我们会把这个信号传给数据团队，触发专项数据增强——专门收集 200 条含金融术语的合同，加入训练集。评估不再只是“验收”，而成了“需求输入”。

5.3 你必须避开的五个经验陷阱：那些文档里不会写的坑

1. 陷阱一：similarity评估器的 embedding 模型选型
   默认用text-embedding-3-small是为了快，但如果你的领域极度专业（如法律、医疗），它的 embedding 质量不够。我们试过用text-embedding-3-large，相似度计算更准，但成本高 3 倍。最终方案是：对核心 20 个高价值用例，用large模型；其余用small。通过promptfoo eval --test critical.yaml --evaluator large-similarity单独跑。

2. 陷阱二：llm-rubric的 prompt 注入风险
   llm-rubric本质是让另一个 LLM 当裁判，但它会把你的 rubric 文本作为 prompt 输入。如果 rubric 里写了“请勿幻觉”，裁判模型自己可能就幻觉出一个错误结论。我们的解法是：rubric 必须原子化、无歧义。比如把“请确保专业”改成“输出中必须出现‘甲方’、‘乙方’、‘违约责任’三个词”。

3. 陷阱三：并发数设置不当导致 Ollama 崩溃
   本地 Ollama 默认最大并发是 1。如果你在promptfooconfig.yaml中设maxConcurrency: 10，所有请求会排队，latency_p95爆表。解决方案：ollama serve启动时加参数OLLAMA_NUM_PARALLEL=4，再在 Promptfoo 配置中设maxConcurrency: 4。

4. 陷阱四：promptfoo init生成的默认 prompt 太弱
   它生成的prompts/default.txt是 “You are a helpful assistant.”。这在评估中毫无意义。必须删除它，从你的第一个真实业务 prompt 开始。我们有个检查清单：每个prompts/*.txt文件名必须体现业务场景（如insurance-underwriting.txt），且文件开头必须有# CONTEXT: ...注释说明适用范围。

5. 陷阱五：忽略--no-cache在 CI 中的必要性
   本地开发时 cache 很方便，但在 CI 中，cache 会跨 PR 污染。比如 PR#123 的测试通过了，但它的 cache 里存了旧 prompt 的结果，PR#124 运行时可能误用。CI 脚本里必须加--no-cache，且在promptfooconfig.yaml中禁用cache: true。

最后分享一个小技巧：我们把promptfoo eval的常用命令 alias 成pe（prompt eval），并写了个pe-watch脚本，监听prompts/和tests/目录变化，自动重跑。一行命令pe-watch --test functional.yaml，改完保存就看到结果刷出来。这种即时反馈，才是 prompt 工程该有的手感——不是写完等 10 分钟，而是改一个字，秒级看到影响。