Run Aisbench Evaluation

---
name: run-aisbench-evaluation
description: 解析中文自然语言中的 AISBench 测评需求，检查 Python 与 AISBench 运行环境，通过分轮追问确认关键配置，将基准名称映射为仓库内的数据集任务，在用户最终确认后生成并执行 AISBench CLI，并返回精度指标和产物路径。适用于用户要求使用 AISBench 评测模型或运行数据集；不适用于实现新数据集或仅解释基准概念。
---

# 运行 AISBench 测评

将用户提出的测评需求转换为一次经过确认、可追溯的 AISBench 运行。保留用户指定的模型、推理后端、数据集、测评范围和输出位置。执行前主动找出会改变测评结果、成本或产物的模糊点，与用户形成共同理解。如果用户只要求提供命令或方案，则在确认必要细节后只生成对应内容，不启动测评。

## 按需读取资料

- 需要解析基准别名、任务名、提示词格式和数据文件要求时，读取 [references/benchmarks.md](references/benchmarks.md)。
- 只有当用户要求标准提示词、提示词模板或示例时，才读取 [references/prompt-examples.md](references/prompt-examples.md)。
- 如果目标基准不在映射表中，先在当前仓库的 `ais_bench/benchmark/configs/datasets/` 下搜索，并读取该基准的 README 和准备选用的配置文件，再确定任务。不得猜测任务名。

## 解析用户需求

提取用户提供的以下字段：

- 基准名称及其变体；
- AISBench 模型任务（`--models`），或足以确定模型任务的后端信息；
- API 服务字段：`host_ip`、`host_port`、`url`、`model_name`，以及可选的 `api_key`；
- 用户要求本地模型任务时对应的本地模型路径；
- 运行控制参数：`mode`、`work_dir`、`num_prompts`、`max_num_workers`、`max_out_len`、`batch_size`、`request_rate`、`retry`、`generation_kwargs`、`summarizer`、`reuse`、`debug` 和 `dry_run`。

解析常见写法时不区分大小写，并将空格、连字符和下划线视为可互换的分隔符。用户明确给出的 AISBench 任务名保持不变。

仅当用户没有指定对应值时使用以下默认值：

- `mode=all`，完成推理、评估和结果汇总；
- `summarizer=example`；
- 用户只提供基准别名时，使用映射表中首选的对话提示词任务；
- 用户提供 vLLM/OpenAI 兼容的对话服务地址但没有指定模型任务时，使用 `vllm_api_general_chat`。

如果既没有可用的模型任务，也没有可识别的后端信息，不得自行虚构后端。先检查用户提到的模型配置，或仓库中已经使用的模型配置。如果仍无法确定可运行的配置，只询问缺失的模型任务或后端信息。

## 分轮确认关键细节

把测评配置视为一棵决策树：上游决定会影响下游问题。例如，先确定服务化还是本地模型，才能确认模型任务以及对应的服务地址或模型路径；先确定基准及其提示词格式，才能判断模型任务是否兼容。

按照以下方式与用户确认：

1. 将用户已经明确表达的选择标记为已确定，不重复询问。
2. 区分“事实”和“决定”。任务名、配置文件位置、数据文件是否存在、CLI 支持哪些参数等事实，应通过当前仓库、环境和可用工具自行查明，不得转而询问用户。基准范围、模型选择、样本范围、资源消耗偏好等决定由用户作出。
3. 每轮找出所有上游条件已经明确、现在即可回答的未决问题，作为当前问题集合。一次性询问这一整组问题并等待用户回答，不要逐个来回追问。
4. 每个问题都应编号，解释该决定的实际影响，并提供一个结合当前上下文的建议答案。建议不等于默认替用户作出决定。
5. 收到回答后更新决策树：已确定的答案可能解锁新的下游问题。只询问新出现且会实质影响运行的问题。
6. 当关键分支已经全部明确时，展示最终测评配置和脱敏命令，请用户做一次最终确认。得到明确确认后才能启动真实测评。

问题轮次使用简洁的中文格式：

```text
❓ 问题1｜<标题>：<问题，以及不同选择对结果或成本的影响>
➡️ 建议：<推荐答案及简短理由>

❓ 问题2｜<标题>：<问题>
➡️ 建议：<推荐答案及简短理由>
```

至少确认以下会影响本次运行的分支；用户已明确或能够从现有配置中唯一确定的项目除外：

- 目标基准、子集和对应数据集任务；
- 模型运行方式、模型任务，以及服务地址或本地模型路径；
- 完整评测还是限制样本数，以及运行模式；
- 输出目录和是否复用历史结果；
- 会显著影响资源消耗或结果可比性的并发数、最大输出长度和生成参数；
- API 密钥来自哪个已配置的安全来源，不得要求用户在对话中直接粘贴密钥。

不要为了形式而追问无关偏好。如果用户已经给全所有必要信息，可以跳过中间问题轮次，直接展示最终配置和脱敏命令，请用户确认。如果用户回答“其余使用建议值”或同等表达，可以据此一次性确定尚未明确的非敏感选项，但仍需进行最终确认。

## 检查 AISBench 运行环境

在执行任务搜索、生成最终命令或启动测评前，先在准备运行 AISBench 的 Python 环境中检查解释器、包和 CLI。优先使用 `python -m pip`，确保检查的是当前 Python 对应的环境：

```bash
command -v python
python --version
python -m pip --version
python -m pip list
command -v ais_bench
```

AISBench 支持 Python 3.10、3.11 和 3.12。如果版本不在该范围内，报告当前版本并停止后续运行检查。检查 `python -m pip list` 中是否存在 `ais-bench-benchmark`（显示名称可能按 pip 规则规范化），并确认 `ais_bench` 命令来自同一个环境；两者都满足时，再运行 `ais_bench -h` 验证 CLI 能够正常加载。

如果当前环境没有安装 AISBench，或者包已安装但找不到或无法加载 `ais_bench` 命令，不得自行选择、激活或修改其他 Python 环境。要求用户告知该项目应使用的准确环境激活命令，例如 `conda activate ais_bench` 或 `source <venv路径>/bin/activate`。后续检查和测评必须在激活后的同一 shell 中进行；如果每次命令使用新的非持久 shell，则每次都要先执行用户提供的激活命令。

同时向用户提供与当前仓库相符的安装指南，但未经用户明确授权不得执行安装：

```bash
# 在 AISBench 仓库根目录进行源码安装（首选）
python -m pip install -e . --use-pep517

# 或从 PyPI 安装基本功能
python -m pip install ais_bench_benchmark
```

评测 vLLM、Triton 等服务化模型且源码安装未包含所需依赖时，可补充提示：

```bash
python -m pip install -r requirements/api.txt
python -m pip install -r requirements/extra.txt
```

用户完成环境激活或明确授权安装后，重新执行 `python -m pip list`、`command -v ais_bench` 和 `ais_bench -h`。只有全部通过，才能继续任务搜索和真实测评。

## 定位并检查测评条件

在 AISBench 仓库根目录运行命令。仓库根目录应同时包含 `setup.py` 和 `ais_bench/` 包。启动真实测评前：

1. 使用已经通过运行环境检查的 `ais_bench` 可执行命令，并记录其实际路径。
2. 使用 `ais_bench --models <模型任务> --datasets <数据集任务...> --search` 定位模型和数据集任务文件。该命令只用于发现配置，不能视为已经完成测评。
3. 从选定的数据集配置中确认所需的本地数据路径，并检查对应文件是否存在。
4. 确认模型任务支持所有数据集任务的提示词格式。对话提示词数据集需要支持对话格式的模型任务；字符串提示词数据集需要支持字符串格式的模型任务。
5. 确认 API 服务或本地模型配置可用。对于所选 API 模型配置中已经存在的字段，优先通过 CLI 参数覆盖。

除非用户另行明确要求，否则不得自动下载数据集、修改共享模型配置、启动推理服务或安装依赖。如果缺少前置条件，报告具体缺失的路径或配置，并给出满足条件后原本要执行的命令。

## 生成命令

完整精度测评使用以下命令结构：

```bash
ais_bench \
  --models <模型任务> \
  --datasets <数据集任务> [<数据集任务> ...] \
  --mode all \
  --summarizer example \
  [已检查的覆盖参数]
```

只将已经解析出的字段映射到 AISBench 支持的 CLI 参数：

| 用户字段 | CLI 参数 |
| --- | --- |
| 主机地址/IP | `--host-ip` |
| 端口 | `--host-port` |
| 自定义服务 URL | `--url` |
| 服务端模型名 | `--model-name` |
| API 任务的分词器或模型路径覆盖值 | `--path` |
| 最大输出 token 数 | `--max-out-len` |
| 请求并发数 | `--batch-size` |
| 请求发送速率 | `--request-rate` |
| 重试次数 | `--retry` |
| 生成参数 | `--generation-kwargs '<JSON 对象>'` |
| 测评样本数 | `--num-prompts` |
| AISBench 并行任务数 | `--max-num-workers` |
| 输出根目录 | `--work-dir` |
| 已有运行的时间戳 | `--reuse` |

### vLLM Chat URL 约束

选择 `vllm_api_general_chat` 或其他使用 `VLLMCustomAPIChat` 的模型任务时，`--url` 必须传服务基地址，不能传完整的 Chat Completions 端点。该模型类会在基地址后自动拼接 `v1/chat/completions`。

如果用户提供的地址以 `/v1/chat/completions` 或 `/v1/chat/completions/` 结尾，生成命令前必须移除这一结尾，同时保留它之前可能存在的网关路径前缀：

```text
用户地址：http://127.0.0.1:8080/v1/chat/completions
--url：http://127.0.0.1:8080
实际请求：http://127.0.0.1:8080/v1/chat/completions

用户地址：https://gateway.example.com/openai/v1/chat/completions
--url：https://gateway.example.com/openai
实际请求：https://gateway.example.com/openai/v1/chat/completions
```

不得把完整端点原样传给 `--url`，否则该实现会形成类似 `/v1/chat/completions/v1/chat/completions` 的重复路径。展示最终配置时，同时列出规范化后的 `--url` 基地址和预计实际请求端点。若 warm-up 返回 `NOT FOUND` 或 HTTP 404，先根据模型类的 URL 拼接逻辑检查实际请求路径是否重复；能够据此唯一确认时，视为允许进行一次纠正性重试的命令参数错误。

以上约束只适用于 `VLLMCustomAPIChat`。选择其他 API 模型任务时，应读取对应模型类的 URL 构造逻辑后再决定 `--url` 是基地址还是完整端点，不得直接套用本规则。

严格区分 `--batch-size` 与 `--max-num-workers`：前者控制单个 API 模型任务内的请求并发数，后者控制并行执行的 AISBench 任务数。只有用户要求时才加入 `--debug` 或 `--dry-run`。只有用户明确要求相应模式，或正在继续某个已指定的历史运行时，才使用 `--mode infer`、`eval`、`viz` 或其他受支持模式。

安全引用所有来自用户的 shell 参数值，检查数值范围，并把 `generation_kwargs` 作为合法 JSON 传入。不得使用 `eval` 拼装或执行命令。不得打印 API 密钥；如果密钥已保存在环境变量中，执行命令时引用该环境变量，对用户展示命令时使用脱敏占位符。

执行前，简要展示规范化后的测评配置和脱敏命令，并明确说明即将开始真实测评。用户最初说“运行”“执行”或“开始测评”表示其目标是实际运行，但不能替代分轮澄清后的最终确认。只有用户确认最终配置后才能执行命令。

## 执行并返回结果

获得用户对最终配置的明确确认后，从仓库根目录执行命令并等待进程退出。记录 AISBench 输出的结果根路径。如果终端没有输出该路径，只能使用本次命令执行期间新建且能够唯一确定的时间戳目录；存在并发运行、无法唯一归属时，不得直接选择无关的“最新”目录。

进程退出码为 0 时，读取 `<结果根路径>/summary/` 下生成的文件，优先读取 Markdown，其次读取文本或 CSV，并返回：

- 模型任务和数据集任务；
- 脱敏后的执行命令；
- 完成状态和主要指标，保留数据集名称及指标单位；
- 实际存在的结果根路径，以及 summary、predictions、results 和 logs 路径。

不能因为进程已经启动就宣称测评成功。如果命令失败，说明失败阶段、退出状态、精简错误信息和相关日志路径。最多进行一次纠正性重试，而且仅限于能够根据仓库文档明确修正的命令语法或任务名错误。数据文件缺失、服务不可用、鉴权失败或资源耗尽时不得自动重试。