Promptfoo + 火山引擎 Ark Coding Plan 搭建实战

如果你用过 LLM 做产品，一定遇到过这个场景：改了一行 prompt，效果变好还是变差？没有数据，全靠感觉。

Promptfoo 是目前社区最活跃的开源 prompt 评测框架。它支持矩阵测试（多个 prompt × 多个模型 × 多个用例），内置断言引擎，能告诉你每次改动到底提升了还是回退了。但多数教程假设你用 OpenAI 的付费 API——对于个人开发者，每月几十美金的测试成本并不友好。

火山引擎 Ark 的 Coding Plan 提供了免费额度，包含 DeepSeek V4 Pro 等推理模型。本文记录从零搭建的全部过程，以及三个实际踩过的坑。

一、Promptfoo 是什么

一句话：Promptfoo 是一个用 YAML 配置驱动的 LLM 评测工具。你定义好 provider（模型）、prompt（模板）、tests（用例+断言），它跑完给你一份可视化报告。

核心概念：

概念	说明	示例
`providers`	要测试的模型 API	DeepSeek V4 Pro, GPT-4o-mini
`prompts`	要对比的 prompt 模板	简单翻译指令 vs 专业翻译指令
`tests`	测试用例 + 断言规则	输入 "Hello"，输出应包含 "你好"
`assert`	断言类型	`contains`、`not-contains`、`is-json`、`llm-rubric` 等

组件	层级	职责
`promptfooconfig.yaml`	配置层	定义 provider、prompt、tests
Promptfoo CLI	执行层	并发调用 API，收集结果
Promptfoo View	展示层	Web UI 可视化报告
断言引擎	验证层	对每次输出执行断言检查

二、安装——brew 比 npm 快 10 倍

第一个坑来得很快。

尝试 1：npm 全局安装（失败）

npm install -g promptfoo@latest

120 秒超时，没装完。挂了代理重试，180 秒超时，还是没装完。在项目目录本地安装 npm install --save-dev promptfoo，600 秒超时，包下载了 508 个但 .bin 目录没生成——安装中断。

原因： promptfoo 的依赖树很大（npm 安装后 23,830 个文件、172.6MB），npm 在下载和链接阶段容易超时。

尝试 2：brew 安装（成功）

brew install promptfoo

30 秒搞定。Homebrew 用预编译的 bottle，下载即用，不需要 npm install 的依赖解析和链接过程。

$ promptfoo --version
0.121.19

结论：macOS 上优先用 brew。

三、配置——接入 Ark Coding Plan

3.1 获取 API 凭证

火山引擎 Ark Coding Plan 控制台 → API Key 管理，获取 ark-* 格式的 key。

关键点：Coding Plan 的 endpoint 是 https://ark.cn-beijing.volces.com/api/plan/v3，不是标准 Ark 的 /api/v3。用错 endpoint 会直接 401。

3.2 配置文件

# promptfooconfig.yaml
description: "Promptfoo Demo - 翻译对比 (Ark Coding Plan)"

providers:
  - id: openai:chat:deepseek-v4-pro
    label: "DeepSeek V4 Pro"
    config:
      apiBaseUrl: https://ark.cn-beijing.volces.com/api/plan/v3
      apiKey: ark-xxx
      temperature: 0.0
      max_tokens: 16384    # 推理模型需要 3-5x 输出 token

  - id: openai:chat:deepseek-v4-flash
    label: "DeepSeek V4 Flash"
    config:
      apiBaseUrl: https://ark.cn-beijing.volces.com/api/plan/v3
      apiKey: ark-xxx
      temperature: 0.0
      max_tokens: 16384

prompts:
  - label: "简单翻译指令"
    raw: |
      将以下英文翻译成中文，只输出译文：
      {{text}}

  - label: "专业翻译指令"
    raw: |
      你是专业翻译。将以下英文翻译成地道中文，注意文化适配，只输出译文：
      {{text}}

tests:
  - vars:
      text: "Hello, how are you today?"
    assert:
      - type: contains
        value: "你好"

  - vars:
      text: "The quick brown fox jumps over the lazy dog."
    assert:
      - type: contains
        value: "狐狸"
      - type: contains
        value: "狗"

  - vars:
      text: "Machine learning is transforming every industry."
    assert:
      - type: contains
        value: "机器"
      - type: contains
        value: "学习"

  - vars:
      text: "Break a leg at your performance tonight!"
    assert:
      - type: contains
        value: "演出"

  - vars:
      text: "It's raining cats and dogs outside."
    assert:
      - type: contains
        value: "大"

3.3 三个关键配置

① Provider ID 格式：openai:chat:<model-name>

Promptfoo 的 openai: 前缀默认走 OpenAI 官方 API。必须用 openai:chat: 前缀才能指定自定义 apiBaseUrl。直接用 openai:deepseek-v4-pro 会报 "API key is not set"。

② max_tokens 至少 16384

DeepSeek V4 Pro 是推理模型，API 返回的结构是：

{
  "message": {
    "content": "你好，你今天好吗？",
    "reasoning_content": "我们需要理解用户的要求……直接翻译即可。"
  }
}

reasoning_content 消耗的 token 计入 max_tokens。设置为 1024 时，推理过程吃掉全部配额，content 返回空字符串。实测翻译任务需要 4096-16384。

③ 模型名用小写

Ark Coding Plan 的模型名是 deepseek-v4-pro，不是 DeepSeek-V4-Pro。大小写不匹配会返回 "model not found"。

四、跑测试——三次迭代到 100%

第一次：0/20（API key 错误）

Provider ID 用了 openai:deepseek-v4-pro，Promptfoo 试图调 OpenAI 的 API，报 "API key is not set"。

修复： 改为 openai:chat:deepseek-v4-pro。

第二次：14/20（推理内容污染）

6 个失败用例中有两组规律：

失败用例	断言	失败原因
"Break a leg..."	`not-contains: "断腿"`	推理内容解释了"直译是'摔断腿'"
"raining cats and dogs"	`not-contains: "猫和狗"`	推理内容解释了"字面意思是猫和狗"

推理模型的 reasoning_content 会解释习语的字面含义，而这些解释恰好包含我们在 assert 中要排除的词。not-contains 断言在推理模型上基本不可用。

第三次：20/20（全通过）

去掉所有 not-contains 断言，只保留正向 contains。

┌────────────────────────┬────────────────────────┬────────────────────────┬────────────────────────┬────────────────────────┐
│ text                   │ DeepSeek V4 Pro        │ DeepSeek V4 Pro        │ DeepSeek V4 Flash      │ DeepSeek V4 Flash      │
│                        │ 简单翻译指令           │ 专业翻译指令           │ 简单翻译指令           │ 专业翻译指令           │
├────────────────────────┼────────────────────────┼────────────────────────┼────────────────────────┼────────────────────────┤
│ Hello, how are you     │ PASS                   │ PASS                   │ PASS                   │ PASS                   │
│ The quick brown fox... │ PASS                   │ PASS                   │ PASS                   │ PASS                   │
│ Machine learning...    │ PASS                   │ PASS                   │ PASS                   │ PASS                   │
│ Break a leg...         │ PASS                   │ PASS                   │ PASS                   │ PASS                   │
│ It's raining cats...   │ PASS                   │ PASS                   │ PASS                   │ PASS                   │
└────────────────────────┴────────────────────────┴────────────────────────┴────────────────────────┘

✓ 20 passed (100%)
0 failed (0%)
0 errors (0%)
Duration: 20s (concurrency: 4)

Token 消耗：共 2,894 tokens，其中 2,179 是 reasoning tokens（占比 75%）。推理模型虽然"想得多"，但翻译质量确实不差。

五、踩坑复盘

#	坑	现象	根因	解法
1	npm 安装超时	多次超时，依赖下载中断	依赖树大（172MB），npm 链接阶段慢	用 brew 安装
2	API key 错误	"API key is not set"	`openai:` 前缀路由到 OpenAI 官方 API	用 `openai:chat:` 前缀
3	content 为空	输出只显示 "Thinking:..."	推理 token 耗尽 max_tokens，content 返回空	max_tokens 设为 16384+
4	not-contains 误判	中文译文本不该含英文词，但断言失败	推理内容包含原文/解释，污染了输出	只用正向 `contains` 断言
5	doubao 模型 404	`doubao-1.5-pro-32k` 返回 "model does not support"	Coding Plan 未包含该模型	仅用 deepseek 系列

六、Promptfoo 断言选型指南

基于本次实测，推理模型下的断言可用性：

断言类型	推理模型可用？	说明
`contains`	✅	正向包含，稳定可靠
`icontains`	✅	大小写不敏感，同上
`not-contains`	❌	推理内容会包含原文/解释，易误判
`equals`	❌	推理内容混入输出，无法精确匹配
`is-json`	✅	结构校验，不受推理内容影响
`llm-rubric`	⚠️	需要额外配置 grading provider，且推理内容可能干扰评分
`cost`	✅	成本断言，与输出内容无关
`latency`	✅	延迟断言，与输出内容无关

建议： 在推理模型上，优先使用 contains、is-json、cost、latency 四类断言。需要否定语义时，用 contains 正向验证期望行为，而非 not-contains 排除不希望的行为。

七、扩展：可以做什么

这套配置可以轻松扩展：

1. 对比更多模型

providers:
  - id: openai:chat:deepseek-v4-pro
  - id: openai:chat:deepseek-v4-flash
  - id: openai:chat:gpt-4o-mini          # 需要 OpenAI key
  - id: openai:chat:claude-3.5-haiku    # 需要 Anthropic key

2. 增加更多 prompt 变体

prompts:
  - label: "零-shot"
    raw: "翻译：{{text}}"
  - label: "Few-shot"
    raw: |
      英文：Hello → 中文：你好
      英文：{{text}} → 中文：

3. 接入 CI/CD

# .github/workflows/prompt-eval.yml
- name: Run promptfoo eval
  run: npx promptfoo eval --no-cache

每次 PR 改 prompt 时自动跑回归测试，任何断言失败都会阻止合并。

八、结论

Promptfoo + Ark Coding Plan 是一套零成本的 prompt 评测方案。对于个人开发者和小团队，不需要任何付费 API 就能建立 prompt 回归测试。

但推理模型引入了独特的挑战：reasoning_content 混入输出导致传统断言策略失效。这本质上是 prompt 评测工具的设计假设（输出 = 最终答案）与推理模型的实际行为（输出 = 推理过程 + 最终答案）之间的不匹配。

我们的建议：

macOS 用 brew 安装，不要跟 npm 的死锁较劲
Provider ID 用 openai:chat: 前缀，否则 API key 传不过去
推理模型 max_tokens 设 16384 以上，给推理留够空间
断言用正向 contains，别用 not-contains，推理内容会污染否定断言
把 promptfoo eval 放进 CI，prompt 改动不再靠感觉

参考资料

Promptfoo 官方文档 — Configuration guide
Promptfoo GitHub — 开源仓库
火山引擎 Ark 平台 — Coding Plan 控制台
Ark API 文档 — API 参考
Homebrew promptfoo formula — Brew 安装信息