Promptfoo 上手：先用本地输出检查评测规则，再连接模型

评测第一次报错，可能是模型答错，也可能是变量、模板或断言写错。Promptfoo 的 Echo provider 会原样返回渲染后的输入，适合先排除第二类问题。本文用一份正确标签和一份故意写错的标签演示配置检查，不需要模型 API 密钥，也不声称已经运行测试。

这个资源解决什么问题，适合谁？

Promptfoo是用于提示词和模型输出评估的开源工具，可将输入、provider 与断言写成配置。适合已经有固定任务样本、希望保存回归证据的开发者；如果任务目标尚未定义，先整理答案标准，装工具不会自动得到可信评分。

本文介绍可本地安装的 CLI，因此归入资源，而不是在线工具卡片。先前站内的提示词表达讨论可以提供写法思路，本资源负责验证这些改动，不能替任何表达策略预先背书。

从哪里下载，怎样确认运行环境？

官方下载渠道是 Promptfoo 安装文档，源码见 promptfoo/promptfoo。开源代码与托管服务是不同交付，使用云服务、模型 API 或商业功能前应另查费用和条款；下载 CLI 不等于获得免费的模型额度。

2026-10-06 核查的安装文档要求 Node.js 至少 22.22.0，并推荐 Node.js 24 LTS。macOS、Linux 和 Windows 均应先确认本机 Node/npm；Windows 下使用 PowerShell 执行下面逐行命令。不要为了省事把未审查安装脚本与真实 API 密钥放在同一环境。

如何在独立目录安装并固定版本？

以下命令在新的练习目录执行，不要直接放进生产仓库。--save-exact 将本次解析到的版本写入依赖，锁文件用于以后复装；它不代表本文已经验证了该版本。首次安装需要网络，安装后应记录命令输出和系统版本。

mkdir promptfoo-lab
cd promptfoo-lab
node --version
npm --version
npm init -y
npm install --save-dev --save-exact promptfoo
npx --no-install promptfoo --version

如果 Node 版本不满足要求，先按官方渠道升级再重试，不使用强制忽略引擎检查掩盖问题。团队复用配置时可参考统一 AI 配置的工作流，同时提交锁文件，密钥则应留在环境变量或密钥管理器里。

怎样写一份故意包含失败的最小配置？

在练习目录创建 promptfooconfig.yaml，内容如下。第一条应通过，第二条预期失败，用于证明断言没有把所有输出都判为正确。它是两个合成样本，不是模型准确率测试。

prompts:
  - '{{answer}}'
providers:
  - echo
tests:
  - description: correct-label
    vars:
      answer: billing
    assert:
      - type: equals
        value: billing
  - description: deliberately-wrong-label
    vars:
      answer: technical
    assert:
      - type: equals
        value: billing

运行 npx --no-install promptfoo eval 查看结果，再用 npx --no-install promptfoo view 打开本地报告。报告服务只用于本机检查，不应暴露到公网。第二条失败是预期设计，不要为了得到全绿把断言删除；改正它时应明确是在修样本还是在改合同。

如何分辨配置问题、网络调用和模型错误？

Echo 官方文档明确说明它不发起模型调用，但模型评分型断言仍可能调用裁判或嵌入 provider。本文仅使用 equals，不加入 llm-rubric、similar 或自定义外部脚本。软件安装、遥测等网络行为与模型调用仍是不同问题，敏感环境需要单独审查相关设置。

如果两条都通过，先核对加载的配置文件和实际断言；如果均未执行，检查 YAML 缩进与 CLI 错误。接入真实模型后，把请求失败、空输出和标签错误分开记录，再计入总样本分母，不能只展示成功返回的条目。

什么时候值得接入生产回归，替代方案是什么？

先完成“正确样本通过、错误样本失败”，再将 provider 换成经核查的目标接口，并设置预算和权限边界。真实样本用脱敏副本，输出报告也可能包含输入文本，发布前同样要检查。不要上传未审查的客户日志。

只有几条固定 JSON 校验时，普通单元测试足够；需要多提示、多模型对照和人工看表时，再考虑完整评测工具。可结合生产级 Agent 工程原则把失败处理接到业务流程。本篇未安装或运行 Promptfoo，读者执行后的版本、结果与日志才是可引用的测试证据。

FAQ

问：Echo 会调用大模型吗？ 答：Echo 本身不会，但某些评分断言仍可能调用外部模型。

问：第二条失败意味着安装坏了吗？ 答：不是，它是故意设置的负例，应当失败。

问：本地 CLI 免费就代表评测免费吗？ 答：不是，模型接口、托管服务等可能另行收费。

参考来源

核查日期：2026-10-06；命令未执行，负例结果为预期而非实测。

• 安装与运行环境
• Echo provider
• 确定性断言
• 官方源码及许可证