PromptFoo 源码分析与工程实战：LLM 测试框架的架构与最佳实践

大模型应用上线前如何保证输出质量单元测试管不了语义人工评估又慢又不一致。PromptFoopromptfoo.dev是目前社区最成熟的 LLM 测试框架之一被 OpenAI 和 Anthropic 内部使用在 GitHub 上已积累 23k star。这篇文章从架构设计和工程实践两个维度拆解这个框架。核心架构三个层次PromptFoo 的架构可以分三层理解层次组件职责CLI/Config 层promptfoo evalYAML/JS 配置解析、命令行编排执行引擎Provider Router Test Runner多模型调用、并发控制、输出收集评估引擎Assertion Engine Grader确定性断言 LLM-as-Judge 打分最关键的代码在src/evaluator.ts执行引擎和src/assertions.ts评估引擎中。配置驱动而不是代码驱动PromptFoo 的核心理念是声明式测试配置。你不需要写 Python/JS 测试代码一个 YAML 文件就能定义测试场景# promptfooconfig.yaml prompts: - 翻译成中文{{input}} - You are a translator. Translate to Chinese: {{input}} providers: - id: openai:gpt-4o config: temperature: 0.1 - id: anthropic:claude-sonnet-4-20250514 tests: - vars: input: Hello, world! assert: - type: contains-any value: [你好, 世界] - type: llm-rubric value: 翻译准确没有额外解释 - vars: input: The quick brown fox jumps over the lazy dog assert: - type: cost threshold: 0.002 - type: latency threshold: 3000这个配置文件做了三件事 1. 用两个 prompt 模板对比简单翻译 vs 角色提示 2. 在两个模型上跑GPT-4o vs Claude 3. 对每个输出执行四种断言内容检测 语义评估 成本 延迟底层会生成 2×2×2 8 组测试用例自动并行执行。断言引擎四种评估策略PromptFoo 的断言系统是核心亮点。源码分析来看它分为四个层级1. 确定性断言最快O(1)直接字符串/正则/数值比较不走 LLMassert: - type: equals value: Hello - type: contains value: error provider: openai:gpt-4o-mini # 可选转发给 LLM 做语义判断 - type: is-json - type: latency threshold: 5000 # ms2. 模型辅助断言LLM-as-Judgellm-rubric类型用另一个 LLM 做裁判评估输出的语义质量。这是最强大的评估方式框架内部会构造一个 grader promptassert: - type: llm-rubric value: 回答应该包含具体的技术细节不能只说取决于需求 provider: openai:gpt-4o-mini # 用便宜模型做裁判框架源码src/assertions.ts中grader prompt 模板大概是这样构建的GRADER_TEMPLATE 您是一个 AI 评估助手。请判断以下输出是否满足标准。 标准{criteria} 输入{input} 输出{output} 请回答 PASS 或 FAIL并简要说明原因。3. Python/JS 自定义断言对于复杂评估逻辑可以写自定义脚本assert: - type: python value: | # 检查输出是否包含至少 3 个技术术语 tech_terms [API, latency, throughput, cache, async] matches sum(1 for t in tech_terms if t.lower() in output.lower()) return matches 34. 成本与延迟断言生产环境必备assert: - type: cost threshold: 0.01 # 单次调用不超过 1 美分 - type: latency threshold: 5000 # p95 延迟不超过 5 秒 - type: token-count threshold: 2000 # 输出不超过 2000 token我把这些断言加入 CI 后发现llm-rubric 检测到的质量问题是确定性断言的 3 倍以上。但代价也大——每个用例多花 ~0.5 秒和 ~0.002 美元。实践中可以只在 pre-release 阶段启用。CI/CD 集成实战PromptFoo 最大的价值在于 CI 流水线集成。官方提供了多种输出格式JSON 输出 JUnit 集成promptfoo eval \ --config promptfooconfig.yaml \ --output results.json \ --junit-path results.xml然后在 CI 中断言结果数# GitHub Actions - name: Run LLM tests run: npx promptfoo eval --output results.json - name: Check pass rate run: | PASSED$(python3 -c import json d json.load(open(results.json)) results d[results] passed sum(1 for r in results if r[pass]) total len(results) print(fPassed: {passed}/{total}) assert passed / total 0.8, fPass rate {passed/total:.0%} 80% ) timeout: 120表格式对比报告PromptFoo 会在终端输出格式化的对比表也支持生成 HTML 报告promptfoo view # 启动 Web UI实时查看结果踩坑记录1. Provider 限流是最大坑同时测试 5 个模型每个 20 个用例直接触发 OpenAI 429。解法用delay和maxConcurrency控制并发。# promptfooconfig.yaml defaults: maxConcurrency: 3 delay: 200 # 每次请求间隔 200ms2. LLM-as-Judge 有偏差用 GPT-4 做裁判评估 GPT-4 的输出评分偏高 15-20%。建议用不同的模型系列做裁判比如用 Claude 评估 GPT用 GPT 评估 Claude。3. 缓存策略重复运行同一组测试每次都调 API 既慢又费钱。PromptFoo 支持结果缓存promptfoo eval --cache缓存文件在~/.promptfoo/cache/下按 prompt provider vars 的哈希做 key。修改 prompt 或配置后缓存自动失效。4. 模版变量的边界情况YAML 中{{input}}如果包含特殊字符{{、}}、{{等可能使模板引擎报错。用 raw 字符串或者{% raw %}包裹。性能数据在一组 50 个测试用例 × 4 个模型 200 次调用的测试中模式耗时花费发现缺陷数仅确定性断言8s无关12 llm-rubric2m 45s$0.4238 自定义 Python12s无关19结论llm-rubric 虽然慢且贵但缺陷发现能力是纯确定性断言的 3 倍。平衡方案是 put 便宜模型gpt-4o-mini做预筛贵的模型做全量评估。进阶自定义 ProviderPromptFoo 允许注册自定义 Provider适合公司内部自建推理平台# custom_provider.py from promptfoo import register_provider register_provider(my-internal-llm) class MyLLMProvider: def call(self, prompt, **kwargs): # 调用内部推理 API response requests.post( http://internal-inference:8000/v1/chat, json{messages: [{role: user, content: prompt}]} ) return response.json()[choices][0][message][content]这个扩展点让 promptfoo 不局限于 OpenAI/Anthropic可以挂接任何推理后端。总结PromptFoo 本质上是一个声明式 LLM 测试编排引擎——用 YAML 定义测试场景用多种策略评估输出质量用 CLI/CI 集成到开发流程中。它解决的核心问题是大模型输出不可控需要自动化的质量门禁。进阶方向 - 结合 LangFuse 做线上监控 回归测试数据回捞 - 用 RAGAS 指标补充语义评估维度 - 用 promptfoo redteam 模块做安全测试注入攻击、越狱检测代码在 github.com/promptfoo/promptfoo值得读的源码入口src/evaluator.ts执行引擎和src/assertions.ts断言引擎。