# AI Eval Suite

> 当用户需要搭建 AI 评估、运行 benchmark、对比模型表现、或排查评估失败时使用。

- Skill: `tencentblueking/ai-eval-suite` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add tencentblueking/ai-eval-suite`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tencentblueking/ai-eval-suite/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tencentblueking (https://skillmd.com/u/tencentblueking)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tencentblueking/ai-eval-suite

---


# AI 评估闭环套件

基于 [promptfoo](https://promptfoo.dev) 的 AI 能力评估闭环流程编排。

**核心价值**：不是"写一个 eval 配置"，而是驱动完整的闭环——从构建评测集到最终达标，
包括失败分析、调优建议、用户确认后执行修改、重评估对比。

**推荐搭配使用**：初始化 suite（SOP 1）时，优先使用官方
[promptfoo-evals](https://github.com/promptfoo/promptfoo/tree/main/.claude/skills/promptfoo-evals)
skill 来搭建 config / tests / assertions 框架——它是 promptfoo 团队维护的语法知识库，
对配置编写、断言选择、provider 模式等覆盖最全面。

本 skill 在官方能力的基础上补全**评估优化闭环**：分析失败原因、提出调优建议、
驱动重评估直到达标。两者分工互补，官方负责"写得对"，本 skill 负责"跑到过"。

如果用户环境中没有官方 skill，本 skill 的 SOP 1 和 `references/project-structure.md`
中也包含了足够的模板和指引来独立完成初始化。

## SOP 五步闭环

```
SOP 1        SOP 2        SOP 3        SOP 4        SOP 5
初始化  ──→  运行评估  ──→  分析评估  ──→  调优  ──→  重评估
  │                                       ↑            │
  │                                       └────────────┘
  │                                        未达标时循环
  └─ 通过率阈值（用户设定）                  达标 → 归档
```

每个 SOP 的详细操作指南在 `references/` 目录下，按需读取：


| SOP          | 文件                          | 何时读取         |
| ------------ | --------------------------- | ------------ |
| 1. 初始化 Suite | `references/sop-init.md`    | 用户要创建新的评估套件时 |
| 2. 运行评估      | `references/sop-run.md`     | 需要执行评估时      |
| 3. 分析评估      | `references/sop-analyze.md` | 评估完成后需要分析结果时 |
| 4. 调优        | `references/sop-tune.md`    | 分析发现问题需要修复时  |
| 5. 重评估       | `references/sop-reeval.md`  | 调优后需要验证效果时   |

**子 agent 使用建议**：

| SOP | 步骤 | 子 agent | 原因 |
|-----|------|----------|------|
| SOP 2 | 运行评估 | ✅ 强烈推荐 | 耗时长，无需交互 |
| SOP 3 | 跑分析脚本 | ❌ 主 agent | 任务耗时较长建议后台执行并检查进展 |
| SOP 3 | 根因分析 | ❌ 主 agent | 需要理解业务上下文 |
| SOP 4 | 调优 | ❌ 主 agent | 需要与用户交互 |
| SOP 5 | 运行+对比 | ✅ 推荐 | 同 SOP 2+3 |

辅助参考：


| 文件                                | 内容                           |
| --------------------------------- | ---------------------------- |
| `references/project-structure.md` | 目录约定、promptfooconfig 模板、命名规范 |
| `references/checklist.md`         | 发布前自检清单                      |


内置脚本：


| 文件                           | 用途                                                                   |
| ---------------------------- | -------------------------------------------------------------------- |
| `scripts/bk_llm_provider.py` | 蓝鲸 LLM 网关 provider（OpenAI 标准协议），可作为 LLM-as-Judge grader 或独立 provider |
| `scripts/analyze_results.py` | 评估结果分析：失败分类、两轮纵向对比、多模型横向对比 |


## 快速判断：用户处于哪个阶段？


| 用户说的话                           | 对应 SOP  | 动作                 |
| ------------------------------- | ------- | ------------------ |
| "给 XX 能力搭建评估" / "创建评测套件"        | SOP 1   | 读 `sop-init.md`    |
| "跑一下评估" / "运行 benchmark"        | SOP 2   | 读 `sop-run.md`     |
| "评估结果怎么样" / "哪些用例失败了"           | SOP 3   | 读 `sop-analyze.md` |
| "怎么修" / "调一下 prompt" / "换个模型试试" | SOP 4   | 读 `sop-tune.md`    |
| "加个模型对比一下" / "用 XX 模型也跑一下"     | SOP 4   | 读 `sop-tune.md`（优先级 3） |
| "改完了再跑一次" / "对比一下前后"            | SOP 5   | 读 `sop-reeval.md`  |
| "评估不通过" / "通过率太低" / "评估挂了"      | SOP 3   | 读 `sop-analyze.md` |
| "还是不行" / "通过率没变"                | SOP 3→4 | 重新分析 + 调优          |
| "从头到尾跑一遍"                       | SOP 1-5 | 按顺序执行              |


## 公共 Provider 体系

评估中有两类 provider 需要区分：

```
evals/providers/            ← 公共 provider（跨 suite 复用）
  bk_llm_provider.py        ← 蓝鲸 LLM 网关（LLM-as-Judge / 独立调用）

evals/<suite>/providers/    ← 业务 provider（走完整业务链路）
  provider.py               ← 调用真实业务接口
```

- **业务 provider** 每个 suite 自己编写，直接调用业务 API，走完整链路
- **公共 provider** 放在 `evals/providers/`，各 suite 通过 `python:../providers/xxx.py` 引用
- 使用 `llm-rubric` 等模型辅助断言时，必须通过 `defaultTest.options.provider` 指定 grader，
避免依赖 promptfoo 默认的 OpenAI key

蓝鲸项目初始化时，可将本 skill 内置的 `scripts/bk_llm_provider.py` 复制到 `evals/providers/`
作为 LLM-as-Judge 的 grader provider。详见 `references/sop-init.md` Step 3。

## 核心约束

这些规则贯穿所有 SOP，不可违反：

1. **环境变量无敏感默认值** — 用户名、密钥等必须从环境变量获取，不允许硬编码
2. **不自建 wrapper 脚本** — 直接使用 `npx promptfoo` CLI，避免额外抽象层增加调试复杂度
3. **每个环节产出必须持久化** — 评估结果（JSON/HTML）、分析结论（conclusion.md）、调优决策（README 调优记录）、迭代进展（README 进展表）都要落地到文件，不能只停留在对话中

## 断言选择速查

```
确定性断言
  contains / icontains / regex / is-json / python / javascript
    ↓ 
语义相似度断言
  similar / rouge-n / bleu
    ↓ 
模型辅助断言
  llm-rubric / factuality / context-faithfulness
  ⚠️ 必须通过 defaultTest.options.provider 指定 grader provider
```