PromptFoo 源码分析与工程实战：LLM 测试框架的架构与最佳实践
大模型应用上线前如何保证输出质量？单元测试管不了语义，人工评估又慢又不一致。PromptFoo（promptfoo.dev）是目前社区最成熟的 LLM 测试框架之一，被 OpenAI 和 Anthropic 内部使用，在 GitHub 上已积累 23k+ star。这篇文章从架构设计和工程实践两个维度拆解这个框架。
核心架构：三个层次
PromptFoo 的架构可以分三层理解：
| 层次 | 组件 | 职责 |
|---|---|---|
| CLI/Config 层 | promptfoo eval | YAML/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)）
直接字符串/正则/数值比较，不走 LLM：
assert: - type: equals value: "Hello" - type: contains value: "error" provider: openai:gpt-4o-mini # 可选转发给 LLM 做语义判断 - type: is-json - type: latency threshold: 5000 # ms2. 模型辅助断言（LLM-as-Judge）
llm-rubric类型用另一个 LLM 做裁判，评估输出的语义质量。这是最强大的评估方式，框架内部会构造一个 grader prompt：
assert: - 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(f'Passed: {passed}/{total}') assert passed / total >= 0.8, f'Pass 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-rubric | 2m 45s | $0.42 | 38 |
| + 自定义 Python | 12s | 无关 | 19 |
结论：llm-rubric 虽然慢且贵，但缺陷发现能力是纯确定性断言的 3 倍。平衡方案是 put 便宜模型（gpt-4o-mini）做预筛，贵的模型做全量评估。
进阶：自定义 Provider
PromptFoo 允许注册自定义 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（断言引擎）。