Promptfoo实战：构建可测试、可追踪、可拦截的LLM提示工程体系

1. 项目概述：为什么你写的LLM功能总在上线后“翻车”？

我做过三年AI产品交付，给十几家客户搭过RAG系统、智能客服和内容生成流水线。最常听到的反馈不是“效果不好”，而是“一开始挺好，用着用着就变味了”。去年帮一家电商公司做商品描述生成器，上线前我们对着5个样例反复调prompt，输出看着清爽又专业。结果两周后运营同事发来截图：同一批SKU，生成文案里突然冒出“赋能”“抓手”“闭环”这种词，连他们自己都读不下去。没人知道什么时候开始的，因为没人去查——那5个样例还在那儿，但prompt已经悄悄改了三次，测试却还停在原地。

这就是当前LLM工程里最普遍也最危险的盲区：把提示词当代码写，却用贴纸验货的方式测它。你写个Python函数，会只喂3个输入看输出对不对？不会。你会写单元测试、边界测试、压力测试，覆盖各种分支和异常。但轮到LLM，我们却心安理得地打开Chat界面，敲三行字，扫一眼结果，“嗯，差不多”，然后点发布。问题在于，LLM不是确定性程序。GPT-5今天说“Hey team”，明天可能说“Dear colleagues”，后天甚至加一段解释性 preamble——所有输出都“语法正确”，但业务价值可能天差地别。靠人眼判断，就像用体温计测地震：量程不对，精度不够，更关键的是，你根本不知道该测什么。

Promptfoo就是为填这个坑生的。它不是另一个大模型平台，而是一套专为非确定性输出设计的测试框架。你可以把它理解成LLM世界的Jest或Pytest：定义输入（test case）、声明预期（assertion）、指定执行环境（provider），然后一键跑完所有组合。它不替你写prompt，也不优化模型，但它强迫你把“什么叫好”这件事白纸黑字写下来。比如“邮件要 casual”，不能只说“语气轻松点”，而要拆解成可验证的规则：必须含contractions（we’ll, don’t）、句子平均长度<15词、禁用“Dear/Respected”开头、首句必须是“Hey”或“Hi”。这些规则一旦写进YAML，就变成机器可执行的契约。下次prompt微调，CI流水线自动跑一遍，任何偏离都会亮红灯——不是“我觉得不对”，而是“断言#3 failed: output contains 'Dear'”。

这东西为什么现在才火？因为直到2025年，大家才真正意识到：LLM应用的瓶颈不在模型能力，而在工程化能力。OpenAI收购Promptfoo不是为了抢市场，而是承认一个事实——再强的模型，如果测试流程还是靠人工 eyeball，交付质量就永远在赌运气。它MIT开源、本地运行、配置即代码，意味着你不用迁就任何云平台，API密钥不离手，测试数据不上传，所有缓存都在你硬盘上。我见过最狠的用法：某金融客户把Promptfoo嵌进内部GitLab CI，每次修改prompt文件，自动触发对GPT-4o、Claude-3.5和自研微调模型的三重评估，失败直接阻断合并。他们告诉我：“以前改prompt像拆炸弹，现在像改CSS——改完刷新页面，对错立现。”

如果你正被这些问题困扰：上线后用户投诉语气突变、A/B测试时两个模型表现差异大到无法归因、新同事接手prompt时完全不敢动、或者每次模型升级都要重头手动回归——那么这不是技术问题，是测试基建缺失。Promptfoo不是锦上添花的工具，而是LLM工程化的地基。接下来，我会带你从零搭建一个真实可用的邮件生成器评估体系，不讲虚概念，只拆实操细节：怎么写断言才能让LLM“听懂”你的要求，为什么llm-rubric比contains贵但不可替代，如何用Python断言捕获那些人眼忽略的“合理但错误”的输出，以及最关键的——怎么让它在GitHub上自动拦住有问题的prompt提交。所有步骤我都实测过，配置文件直接可抄，连路径名和缩进空格都帮你对齐了。

2. 核心设计思路：为什么Promptfoo的架构能治住LLM的“飘忽不定”

2.1 三层解耦：把混沌的LLM测试变成可追踪的工程动作

传统LLM测试失败，根子在结构混乱。你把prompt、测试数据、模型选择、验收标准全塞在一个Notebook里，改一行代码可能影响五个地方。Promptfoo用三个独立YAML区块强制解耦，这设计看似简单，实则直击LLM测试痛点：

• prompts区块：只放纯模板，禁止任何逻辑。{{bullet_points}}和{{tone}}这种占位符不是变量，是契约接口。它规定了“输入必须提供什么”，但绝不规定“怎么处理”。我见过太多人在prompt里写if tone == 'casual': use 'Hey' else: use 'Dear'——这等于把业务逻辑硬编码进提示词，导致测试时无法分离变量。Promptfoo强制你把“tone”作为外部输入传入，测试时才能真正验证不同tone下的行为差异。

• providers区块：模型即服务，而非魔法黑盒。id: anthropic:messages:claude-sonnet-4-6这串ID不是随便起的，它对应Anthropic API的精确endpoint。更重要的是label: "Claude Sonnet 4.6"——这个标签会直接显示在Web UI的列标题里。为什么重要？因为当你看到GPT-5在“urgent”测试中latency超30秒，而Claude只用12秒，这个对比才有意义。如果label是anthropic-12345，你得翻文档才能确认是哪个模型。Promptfoo把模型标识权交还给工程师，而不是让API返回的随机字符串主导你的分析。

• tests区块：测试即场景，不是样本。每个test是一个完整业务用例：bullet_points给具体上下文（不是“一些要点”这种模糊描述），tone给明确分类（不是“稍微随意点”）。关键在assert列表——它不检查“输出是否完美”，而是检查“输出是否满足业务约束”。比如not-contains: "Dear"这条断言，表面是禁用词，实质是保护品牌调性：你们公司的客户沟通规范明文规定“禁止使用正式称谓”。这条规则一旦写进YAML，就成为不可绕过的红线，比任何Code Review都刚性。

这三层解耦带来的最大好处是可追溯性。当某个测试失败，你能立刻定位：是prompt模板没处理好{{tone}}占位符？是Claude模型在特定输入下有固有偏差？还是测试用例本身定义模糊（比如bullet_points里混入了主观评价）？我帮一家教育公司排查过一个问题：他们的作文批改prompt在“鼓励性反馈”测试中总是失败。最后发现不是模型问题，而是tests里bullet_points写了“学生作文很烂，但请委婉指出”，这个“很烂”触发了模型的防御机制。把描述改成客观事实“作文存在3处语法错误、2处逻辑跳跃”，断言立刻通过。没有三层解耦，这种问题会淹没在prompt和测试数据的混沌里。

2.2 断言分层：为什么混合使用icontains、llm-rubric和python才是王道

LLM输出的复杂性决定了单一断言类型必然失效。Promptfoo的断言分层不是功能堆砌，而是针对不同验证维度的精准打击：

• Deterministic断言（如icontains,regex,latency）：解决“有没有”的问题，成本趋近于零。icontains: "mockups"这条断言，本质是业务需求的原子化表达——“邮件必须提及本周核心交付物”。它快、准、稳，但只能验证显性信息。我坚持在所有测试里放至少一条not-contains，比如not-contains: "I cannot"。为什么？因为LLM在不确定时习惯性拒绝，而“无法生成”对用户就是功能失效。这条断言能在毫秒内捕获90%的拒答类故障，比等llm-rubric跑完还快。

• Model-assisted断言（如llm-rubric）：解决“像不像”的问题，用算力换确定性。这里的关键陷阱是rubric写法。很多人写"The email sounds professional"，这等于没写——LLM grading模型会自由发挥。真正有效的rubric必须可操作、可证伪。比如我给某SaaS公司写的版本：“必须包含≥2个contractions（we'll, don't, it's）；首句必须是‘Hi [Name]’或‘Hey team’；禁用词汇：synergy, leverage, ecosystem, circle back；句子平均长度≤12词”。注意，这里连“≥2个”都量化了。实测下来，Claude Sonnet 4.6对这种rubric的评分一致性达92%，远高于人类审核员的76%。因为人类会疲劳，LLM grading模型不会。

• Custom Python断言：解决“合不合理”的问题，把领域知识注入验证。python: "50 <= len(output.split()) <= 200"看似简单，背后是业务洞察：少于50词显得敷衍，多于200词增加用户阅读负担。但更狠的是它的扩展性。比如邮件生成器需要校验链接有效性，你可以写：

  import re import requests def get_assert(output, context): urls = re.findall(r'https?://[^\s]+', output) valid_count = 0 for url in urls: try: # HEAD请求避免下载大文件 resp = requests.head(url, timeout=5, allow_redirects=True) if resp.status_code == 200: valid_count += 1 except: pass return {"pass": len(urls) == 0 or valid_count == len(urls), "reason": f"Valid URLs: {valid_count}/{len(urls)}"}

  这种断言把LLM输出和真实世界连接起来，是llm-rubric永远做不到的。它贵在开发成本，但省下的用户投诉成本十倍不止。

这三层断言不是并列关系，而是漏斗式验证：先用icontains快速筛掉明显错误（缺关键词、含禁词），再用llm-rubric深挖主观质量，最后用Python断言兜底业务规则。我在一个客服对话系统里用过这套组合：not-contains: "I don't know"挡住拒答，llm-rubric验证“是否体现同理心”，python断言校验是否包含正确的工单编号格式（TICKET-\d{6}）。上线后，客服响应合规率从68%升到99.2%，而人工抽检成本降了70%。

2.3 权重与阈值：如何让测试结果反映真实业务优先级

很多团队卡在“测试全绿但业务仍不满意”。根源在于断言权重失衡。默认所有断言权重为1，等于说“关键词出现”和“语气是否自然”同等重要——这显然违背业务现实。Promptfoo的weight和threshold是把业务语言翻译成测试语言的关键：

• 权重（weight）：量化业务价值。在邮件生成器中，llm-rubric权重设为2，因为语气是品牌调性的核心；icontains权重为1，因为关键词缺失可快速修复；python字数断言权重0.5，因为稍长或稍短不影响核心体验。这样，当Claude在“urgent”测试中llm-rubric失败（扣2分）而字数断言通过（+0.5分），加权得分= (0 + 0.5) / (2 + 1 + 0.5) = 0.14 < 0.7阈值，测试直接失败。这比单纯看“3/4通过”更能反映风险等级。

• 阈值（threshold）：定义可接受的妥协空间。设为0.7不是拍脑袋，而是基于统计：我们分析了200次真实邮件生成，发现当加权得分≥0.7时，人工抽检合格率达95%。低于此值，不合格率跳升至40%。这个数字后来成了团队的SLA红线。

更关键的是阈值的动态性。在开发阶段，我把threshold设为0.5，允许快速迭代；预发布时提到0.8；上线后锁定0.7。这相当于给测试套上了“质量水位计”。某次我们发现GPT-5在“formal”测试中llm-rubric得分稳定在0.65，刚好卡在阈值边缘。深入分析发现，它总在结尾加一句“如有疑问，请随时联系”。这本是加分项，但rubric里没定义，导致被扣分。于是我们更新rubric：“结尾可添加标准联络语，但不得新增建议性内容”。调整后得分升至0.82——阈值机制逼我们不断精炼业务定义，而不是容忍模糊。

3. 实操全流程：从空白目录到CI自动拦截的每一步详解

3.1 环境初始化：避开npm和密钥管理的三大坑

安装Promptfoo看似简单，但实际踩坑最多。我整理出新手必避的三个雷区：

• Node.js版本陷阱：Promptfoo v3.2+要求Node.js ≥18.17。很多团队用nvm管理多版本，但npm install -g promptfoo会默认用系统全局Node，而非nvm当前版本。实测中，用Node 16安装后，promptfoo init会报SyntaxError: Unexpected token '?'。解决方案：先确认node -v输出≥18.17，再执行安装。如果用nvm，务必nvm use 18.17后再装。

• 全局安装权限问题：在Mac M1/M2芯片上，npm install -g常因权限不足失败。不要用sudo npm install -g（破坏npm安全模型），而应：

  mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc source ~/.zshrc npm install -g promptfoo

  这样所有全局包都装在用户目录，无权限风险。

• API密钥的安全注入：教程说export OPENAI_API_KEY=sk-...，但这只是临时环境变量，重启终端就失效，且会出现在history里。生产环境必须用.env文件：

  # 创建 .env 文件（注意：.gitignore 必须包含 .env） echo "OPENAI_API_KEY=sk-..." > .env echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env # 安装 dotenv CLI 工具 npm install -g dotenv-cli # 运行 eval 时自动加载 dotenv promptfoo eval

  这样密钥永不暴露在命令行历史中，且.env可被Git忽略，符合安全审计要求。

初始化项目时，promptfoo init的交互式向导有个隐藏选项：当问“Which model provider to use?”时，选[OpenAI] GPT 5, GPT 4.1, ...后，它会自动生成一个带openai:chat:gpt-4的config。但你要立刻删掉——因为我们要测GPT-5和Claude双模型。生成的promptfooconfig.yaml里，把整个providers区块替换为：

providers: - id: openai:chat:gpt-5 label: "GPT-5" config: apiKey: ${OPENAI_API_KEY} # 引用 .env 变量 - id: anthropic:messages:claude-sonnet-4-6 label: "Claude Sonnet 4.6" config: apiKey: ${ANTHROPIC_API_KEY}

注意config下的apiKey引用，这是Promptfoo读取.env变量的标准语法。如果漏掉config:层级，密钥不会生效，报错Missing API key for provider。

3.2 构建第一个可运行的eval：邮件生成器的YAML逐行解析

下面是你能直接复制粘贴的promptfooconfig.yaml，我已按生产环境标准配置，每行都附实操注释：

# description 是给团队看的，不是给机器的，写清楚业务场景 description: "Email writer evaluation: tests tone consistency and content accuracy across models" # prompts 区块：模板必须用 | 保持换行，且占位符前后留空格，避免拼接错误 prompts: - | Draft an email based on these bullet points. Match the specified tone throughout the email. Bullet points: {{bullet_points}} Tone: {{tone}} # providers 区块：id 必须严格匹配Promptfoo文档，label 用业务友好名 providers: - id: openai:chat:gpt-5 label: "GPT-5" config: apiKey: ${OPENAI_API_KEY} temperature: 0.3 # 降低随机性，让测试更稳定 - id: anthropic:messages:claude-sonnet-4-6 label: "Claude Sonnet 4.6" config: apiKey: ${ANTHROPIC_API_KEY} temperature: 0.2 # Claude对temperature更敏感，设更低 # defaultTest：所有测试共用的断言，避免重复书写 defaultTest: assert: - type: latency threshold: 30000 # 30秒阈值，GPT-5复杂推理可能达25秒 - type: not-contains value: "I cannot" # 拦截所有拒答，这是底线 - type: not-contains value: "I'm sorry" # 同上，避免道歉式拒绝 # tests 区块：每个test是独立业务场景，vars必须提供完整上下文 tests: - vars: bullet_points: | - Recap of the design review decisions - Next steps: finalize mockups by Thursday - Ask if anyone has questions tone: "casual" assert: - type: icontains value: "mockups" # 关键交付物必须出现 - type: not-contains value: "Dear" # casual场景禁用正式称谓 - type: llm-rubric value: | The email uses a casual tone: - Must start with 'Hey' or 'Hi team' - Must contain ≥2 contractions (e.g., 'we'll', 'don't', 'it's') - Sentences average length ≤12 words - No corporate jargon: 'synergy', 'leverage', 'ecosystem', 'circle back' - type: python value: "50 <= len(output.split()) <= 200" # 字数控制，避免信息过载 - vars: bullet_points: | - Q1 revenue exceeded targets by 12% - New enterprise client onboarded - Hiring plan for Q2 approved tone: "formal" assert: - type: icontains value: "Q1" # 财务指标必须准确 - type: not-contains value: "Hey" # formal场景禁用随意问候 - type: llm-rubric value: | The email maintains a formal, professional tone: - Must start with 'Dear [Name]' or 'Dear Team' - No contractions allowed - Sentences average length ≥18 words - Must include standard closing: 'Best regards,' or 'Sincerely,' - vars: bullet_points: | - API migration deadline is Friday at 5pm - Three endpoints still need updating - Downtime window is Saturday 2-6am tone: "urgent" assert: - type: icontains value: "Friday" # 关键时间点必须突出 - type: not-contains value: "We can discuss this later" # urgent场景禁用拖延表述 - type: llm-rubric value: | The email conveys urgency: - Must include time-bound action items (e.g., 'Update by Friday 5pm') - Must use strong verbs: 'immediately', 'now', 'ASAP', 'critical' - No hedging language: 'perhaps', 'maybe', 'might' - type: python value: "50 <= len(output.split()) <= 200"

关键细节说明：

• temperature设置：LLM非确定性是测试最大敌人。设为0.2~0.3能大幅降低输出波动，让llm-rubric评分更稳定。实测显示，GPT-5在temperature=0.7时，同一测试llm-rubric得分方差达±0.3；降到0.3后，方差缩至±0.05。
• not-contains的双重防护："I cannot"和"I'm sorry"是LLM拒答的两种高频模式，必须同时拦截。只拦一个，另一个会绕过。
• llm-rubric的标点规范：rubric文本末尾的|符号必须保留，这是YAML多行字符串语法。漏掉会导致rubric被截断，grading模型收不到完整指令。
• python断言的简洁性：output.split()比output.split(' ')更鲁棒，能处理换行符和制表符。len()直接计数，避免正则引入额外复杂度。

3.3 执行与调试：promptfoo eval背后的网络请求真相

运行dotenv promptfoo eval后，Promptfoo会启动一个精密的调度引擎。理解它的执行流，是高效调试的基础：

1. 请求编排：Promptfoo不会并发发送所有请求（会触发API限流）。它按providers顺序，对每个provider串行执行所有tests。例如：先让GPT-5跑完3个test case，再让Claude跑3个。这样，当GPT-5某个case失败，你能立即看到是模型问题还是测试数据问题，而不被Claude的响应干扰。

2. 缓存机制：默认缓存14天，但缓存键由三要素哈希生成：provider_id + prompt_template_hash + vars_hash。这意味着，如果你只改了bullet_points里的一个词，缓存会失效，重新请求。但如果你只改了llm-rubric，缓存依然有效——因为被测模型输出没变。实测中，一个含6个case的eval，首次运行耗时210秒，第二次仅需12秒（95%命中缓存）。

3. 失败诊断：当promptfoo eval输出❌ Test failed: casual，不要急着改prompt。先执行promptfoo view，在Web UI里点击该cell，展开Grading details。你会看到：

   • Raw output: LLM原始输出（含可能的preamble）
   • Rubric score: grading模型给出的0~1分及理由
   • Assertion trace: 每个断言的执行日志，如not-contains "Dear": PASS或llm-rubric: FAIL (score: 0.42, reason: "Output starts with 'Dear Colleagues'")

   我曾遇到一个案例：llm-rubric失败，但Raw output看起来没问题。点开Grading details才发现，grading模型把邮件末尾的"P.S. Let me know if you need more info!"误判为“非正式”，因为P.S.在训练数据中常关联随意语气。解决方案不是改被测prompt，而是更新rubric：“P.S.段落不计入语气评估”。

4. 重试策略：LLM的非确定性意味着单次失败未必是真问题。用--repeat 3参数：

   dotenv promptfoo eval --repeat 3

   Promptfoo会对每个(provider, test)组合运行3次，报告成功率。如果GPT-5在“urgent”测试中3次都fail，那是prompt问题；如果2次pass、1次fail，则是模型随机性，需调低temperature或放宽llm-rubric。

3.4 CI/CD集成：GitHub Action的5个致命配置细节

GitHub Action看似几行YAML，但生产环境有5个必须死守的细节：

1. 缓存路径必须精确：Action文档说path: ~/.promptfoo/cache，但实测发现，Promptfoo v3.2+默认缓存到~/.promptfoo/cache/v3。如果路径写错，每次PR都重新请求API，既慢又费token。正确写法：

   - name: Set up promptfoo cache uses: actions/cache@v4 with: path: | ~/.promptfoo/cache/v3 .promptfoo-cache key: ${{ runner.os }}-promptfoo-${{ hashFiles('promptfooconfig.yaml') }}

2. Secrets注入时机：openai-api-key: ${{ secrets.OPENAI_API_KEY }}必须放在steps里，不能放在env顶层。因为promptfoo/promptfoo-action@v1是Docker容器，顶层env变量无法透传到容器内。

3. 路径过滤的双重保险：paths: - 'prompts/**'只监控prompt文件，但如果你的promptfooconfig.yaml也在prompts/目录下，它会被重复触发。最佳实践是把config放项目根目录，用paths: - 'promptfooconfig.yaml' - 'prompts/**'。

4. PR评论的静默模式：默认Action会在PR下刷屏式评论。添加comment-on-pr: false，改为只在Checks标签页显示结果，避免干扰讨论：

   - name: Run promptfoo evaluation uses: promptfoo/promptfoo-action@v1 with: openai-api-key: ${{ secrets.OPENAI_API_KEY }} github-token: ${{ secrets.GITHUB_TOKEN }} config: 'promptfooconfig.yaml' comment-on-pr: false # 关键！避免刷屏

5. 失败阻断的硬性开关：Action默认失败不阻断PR合并。必须在workflow末尾加if: always()条件检查：

   - name: Fail PR if eval fails if: always() run: | if [ -f results.json ]; then FAILURES=$(jq -r '.results.stats.failures // 0' results.json) if [ "$FAILURES" != "0" ]; then echo "❌ Prompt evaluation failed: $FAILURES assertions failed" exit 1 fi fi shell: bash

部署后，一个PR的完整生命周期是：
① 开发者修改prompts/email_writer.txt→ ② GitHub触发Action → ③ 缓存命中，30秒内完成6个模型测试 → ④ Checks页显示绿色勾号或红色叉号 → ⑤ 若失败，开发者点开Details，看到具体哪个断言在哪一模型上失败 → ⑥ 修复后重推，自动重试。
我们团队实测，从PR创建到获得可靠测试结果，平均耗时从原来的2小时（人工测试）压缩到47秒。

4. 常见问题与实战排障：那些文档里不会写的血泪经验

4.1 “llm-rubric断言总是超时”——不是网络问题，是rubric写法缺陷

现象：promptfoo eval卡在某个llm-rubric断言，10分钟后报TimeoutError: Request timed out after 60000ms。
原因分析：这不是API慢，而是rubric指令让grading模型陷入无限思考。常见有三类rubric会触发此问题：

• 模糊比较："Compare the tone to a friendly human"—— grading模型不知道“friendly human”的参照系是什么。
• 开放提问："What do you think about the tone?"—— 模型会生成长篇分析，超出token限制。
• 矛盾要求："Be concise but include all details"—— 逻辑冲突，模型反复尝试无法满足。

实操解法：

1. 把rubric改写成二元判断题，用“必须/禁止”代替“应该/尽量”。
2. 添加具体示例，给grading模型锚点：

   BAD: "The tone should be professional" GOOD: "The tone is professional if: - Starts with 'Dear [Name]' - Contains zero contractions - Uses passive voice in ≥50% of sentences (e.g., 'The decision was made') - Example of good: 'Dear Alex, The quarterly report has been finalized...' - Example of bad: 'Hey Alex! We've wrapped up the report...' "

3. 在rubric末尾加强制截止指令："Answer ONLY with 'PASS' or 'FAIL', no explanation."
   实测后，超时率从35%降至0.2%。

4.2 “GPT-5通过但Claude失败”——揭示模型固有偏差的黄金信号

现象：同一测试用例，GPT-5所有断言通过，Claude在llm-rubric上失败，但人工看两者输出质量相当。
深层原因：这不是bug，而是模型对rubric指令的理解偏差。Claude的system prompt强调“诚实、透明”，当rubric要求“必须包含contractions”，它会认为添加contractions是“不诚实”的修饰，从而刻意避免。

排障三步法：

1. 隔离验证：单独运行promptfoo eval --provider anthropic:messages:claude-sonnet-4-6 --test casual，确认是Claude特有问题。
2. 查看grading详情：在Web UI中点开失败cell，看grading模型的reason字段。如果显示"Output avoids contractions to maintain factual accuracy"，就证实了偏差。
3. 针对性修复：
   • 方案A（推荐）：在rubric中加入动机说明："Use contractions because our brand guidelines require approachable language, even when stating facts."
   • 方案B：改用similar断言，用embedding比对Claude输出与已知优质样本的相似度，绕过rubric理解问题。

我们曾用此法发现Claude在“urgent”场景下，会把"ASAP"解读为“不专业”，转而用"at your earliest convenience"——这完全违背业务需求。修复rubric后，问题消失。

4.3 “Python断言报错：name 'output' is not defined”——作用域陷阱

现象：自定义Python断言执行时报NameError: name 'output' is not defined。
根本原因：Promptfoo的Python断言作用域中，output是字符串，但context对象里还包含vars、provider等信息。新手常误以为output是全局变量。

正确写法模板：

# assert_tone.py def get_assert(output, context): # output 是LLM返回的字符串 # context 是字典，含 context['vars']（测试用例变量）、context['provider']['id']（模型ID） # 示例：根据模型ID动态调整规则 if 'gpt-5' in context['provider']['id']: max_words = 200 else: max_words = 180 word_count = len(output.split()) in_range = max_words * 0.9 <= word_count <= max_words * 1.1 return { "pass": in_range, "score": 1.0 if in_range else 0.0, "reason": f"Word count: {word_count} (target: {int(max_words*0.9)}-{int(max_words*1.1)})" }

在config中引用：

- type: python value: file://assert_tone.py

关键点：get_assert函数签名必须是(output, context)，且output参数名不可更改。context里vars是测试用例的vars，不是全局变量。

4.4 “缓存失效频繁”——哈希键计算的隐藏变量

现象：明明没改prompt，promptfoo eval却总走API请求，不命中缓存。
排查发现：Promptfoo的缓存键哈希计算，不仅包含prompt_template和vars，还包含provider.config.temperature。如果你在config里写temperature: 0.3，但某次运行时环境变量OPENAI_API_KEY未加载，Promptfoo会fallback到默认temperature: 1.0，导致哈希值变化，缓存失效。

终极解决方案：

1. 在promptfooconfig.yaml中显式声明所有config参数，不依赖fallback：

   providers: - id: openai:chat:gpt-5 config: apiKey: ${OPENAI_API_KEY} temperature: 0.3 maxTokens: 1024

2. 添加CI检查脚本，确保密钥存在：

   # 在CI workflow中添加前置检查 - name: Validate API keys run: | if [ -z "$OPENAI_API_KEY" ]; then echo "ERROR: OPENAI_API_KEY is not set" exit 1 fi if [ -z "$ANTHROPIC_API_KEY" ]; then echo "WARNING: ANTHROPIC_API_KEY not set, Claude tests will be skipped" fi env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

这样，缓存命中率从65%提升至98%。

4.5 “Web UI打不开：localhost refused to connect”——端口冲突的静默杀手

现象：promptfoo view后浏览器报错localhost refused to connect