6.1 Promptfoo：本地回归与红队

6.1 Promptfoo：本地回归与红队

本节摘要：Promptfoo 是开源评测框架（CLI 与库双形态），官方定位三个关键词：本地优先——评测数据与 API Key 不出机器，适合公司内网与敏感数据；配置即评测——一个 yaml 声明 prompts（考题模板）、providers（被测系统：模型或自定义 HTTP）、tests（测试用例 + 断言）三件套，promptfoo eval 一条命令跑完整张回归卷；内建红队——自动生成提示注入、越狱等攻击样本并给安全分，把第 3.3 节的四攻击面变成可自动化的日常检查。它与本书前五章的关系是"执行器"：tests 就是第 3 章回归集的 yaml 化身，asserts 就是第 2.3 节判定分流的第一层（规则），llm-rubric 断言就是第 5 章的裁判。本节走完 init → eval → view → 阈值退出码的完整 CLI 工作流，并给出红队配置示例；所有配置均标注「写法示意，以官方文档为准」。

学习目标

阅读完本节，你应当能够：

1. 写出包含 prompts / providers / tests / asserts 的最小配置并本地跑通。
2. 把第 3 章回归集的分层标签映射进测试用例的组织方式。
3. 说明常用断言类型与第 2.3 节三种判定方式的对应。
4. 跑通红队生成与安全跑分，并把它挂进发布前检查。

一、定位：为什么先讲它

与手写脚本（第 3~5 章的做法）相比，工具换来三样东西：可比性（同一配置反复跑，结果结构一致）、可视化（Web UI 看逐条对错）、协作（yaml 进仓库，第 9.1 节评测即代码的抓手）。代价是多一层抽象——先有考卷再上工具的顺序不能反（第 0.2 节的警告在此兑现）。

二、最小配置：三件套 + 断言

# promptfooconfig.yaml（写法示意，以官方文档为准）
prompts:
  - "你是客服助手。请回答用户问题：{{question}}"
providers:
  - id: openai:gpt-4o-mini          # 被测系统 A
    label: mini
  - id: openai:gpt-4o               # 被测系统 B：同卷对比两个模型
    label: pro
defaultTest:                        # 全部用例共享的底线断言
  assert:
    - type: latency
      threshold: 5000               # 毫秒（示意）
tests:
  - description: 退款时限-标准问法
    vars:
      question: 退款多久到账？
    assert:
      - type: contains
        value: 工作日                # 规则断言：硬标准
      - type: similar
        value: 退款一般 5 个工作日原路退回
        threshold: 0.6              # 语义相似度（示意阈值）
  - description: 退款时限-情绪化问法   # 同知识点换表述，测稳健性
    vars:
      question: 钱到底什么时候退！！！都三天了
    assert:
      - type: llm-rubric            # 裁判断言：开放式质量（第 5 章 rubric）
        value: 回答安抚情绪且给出准确时限，不得编造政策
  - description: 格式契约-JSON 输出
    vars:
      question: 请以 JSON 输出订单状态
    assert:
      - type: is-json               # 结构校验（第 2.3 节规则判定）
​

三处与本书概念的对应：

1. tests ↔ 回归集：vars 是输入，description 承担分层标签（3.1 节的场景 × 难度建议写进 description 或单独字段，便于报告分层统计）；
2. assert ↔ 判定分流第一层：contains / is-json / latency 等规则断言免费且确定；判不了的交给 llm-rubric——第 2.3 节"规则先行、裁判兜底"在断言体系里原样重现；
3. providers ↔ 被测系统：多个 provider 同卷对比，天然支持第 4.4 节的延迟成本质量三角（报告含延迟与 token 用量）。

💡 断言可以组合权重（加权通过率，第 4.1 节），可以对输出做 transform 后再断言；阈值类断言（latency、相似度）把"多差算差"写进配置而非写进代码。

三、CLI 工作流：从 init 到退出码

# workflow.sh（写法示意，以官方文档为准）
npx promptfoo@latest init          # 生成配置骨架，改成上面的三件套
promptfoo eval -c promptfooconfig.yaml   # 跑完整张考卷
promptfoo view                     # 打开本地 Web UI：逐条对错、并排对比、历史记录
promptfoo eval -c promptfooconfig.yaml --threshold 0.85
                                   # 及格线 85%（示意）：低于则退出码非 0 → CI 门禁（第 9.2 节）
​

四条工程纪律：

1. 配置进仓库：promptfooconfig.yaml 与回归集数据文件（可被 file:// 引用）一起走 PR（第 9.1 节）；
2. 版本对齐：配置里记录数据集版本与模型快照标识，跑分报告才能对齐到确切版本（第 3.4 节数据卡纪律）；
3. 及格线分层：主集一条线（如 85%）、hard 子集另一条（如 50%，示意），别用一把尺子量所有层（第 3.3 节两列分数）；
4. 非确定性报告：temp > 0 的 provider 建议配置多次重复，看均值 ± 波动（第 4.1 节 pass@k）。

四、红队：把对抗面自动化

第 3.3 节的四个攻击面（注入、越狱、格式破坏、对抗变形）过去靠人工构造；Promptfoo 的 red-teaming 能力按策略（官方称 plugins/strategies）自动生成攻击样本并跑分：

# redteam.yaml（写法示意，以官方文档为准）
redteam:
  purpose: 客服助手，可查询订单、退款与账户信息   # 描述被测系统，供生成器定向
  numTests: 40                      # 生成样本数（示意）
  plugins:
    - prompt-injection             # 提示注入：指令夹带与覆盖
    - pii-leakage                  # 隐私泄露探测
    - excessive-agency             # 越权行为（自称能做做不到的事）
  strategies:
    - basic                        # 基础变形
    - multilingual                 # 多语言绕过
​

# redteam.sh（写法示意，以官方文档为准）
promptfoo redteam generate -c redteam.yaml   # 生成攻击样本
promptfoo redteam eval -c redteam.yaml       # 跑安全分：多少攻击被攻破
​

三个使用要点：

1. 红队分不是安全证明：自动生成覆盖已知模式，攻破率 0% 只说明"这批攻击没打穿"（观点）；
2. 攻破的样本入库：自动红队发现的成功攻击，人工确认后原样进 hard 子集（第 3.3 节），成为永久回归题——红队是采样的上游，不是终点；
3. 发布前必跑：安全子集（人工积累）+ 红队生成（自动扩展）各跑一遍，前者守已知、后者探未知。

五、适用与不适用

本节要点回顾

1. 三件套：prompts（考题）/ providers（被测系统）/ tests（用例 + 断言）——配置即评测，本地优先。
2. 断言即分流：规则断言先行，llm-rubric 兜底语义质量；阈值与权重把"多差算差"写进配置。
3. CLI 闭环：init → eval → view；--threshold 的非零退出码是 CI 门禁的执行原语（第 9.2 节）。
4. 红队定位：自动生成攻击扩展覆盖，攻破样本回流入库；红队分不是安全证明。

离线端就位。但回归集再全，也照不到线上——真实用户的长尾、真实分布的漂移，需要另一套设施：把每次请求记录成 trace，再对 trace 打分。下一节接入 Langfuse。