# EvalScope 评测脚本与配置

本仓库包含一组基于 [EvalScope](https://github.com/modelscope/evalscope) 的评测脚本、配置和辅助工具，用于通过 OpenAI-compatible API 统一运行各类 LLM benchmark。

代码本身与具体模型无关，当前默认配置以 `DeepSeek-V4-Flash-INT8` 为例，可通过命令行参数或配置文件切换到其他模型。

---

## 1. 代码组成

```
/data1/sora/evalscope/
├── bash/                           # 可执行脚本
│   ├── run.py                      # 统一 benchmark 入口
│   ├── collect_results.py          # 汇总分数到 Excel/CSV
│   ├── perf_backup.py              # 断点续跑：备份与恢复 predictions/perf
│   ├── pull_swe_bench_images.py    # 预拉 SWE-bench Docker 镜像
│   └── test.sh                     # 本地测试脚本示例
├── config/
│   └── dpv4-int8_nothinking.yaml   # benchmark 生成参数配置
├── tools/docker/                   # Docker 镜像构建上下文
│   ├── Dockerfile.py312
│   ├── bash/
│   ├── evalscope/
│   └── tau2-bench/
├── myread.md                       # 详细使用手册
└── DOCKER_BUILD.md                 # Docker 镜像构建说明
```

---

## 2. 核心脚本

### 2.1 `bash/run.py`

统一的 benchmark 启动入口，支持 suite、自定义 datasets、thinking 模式、输出目录组织、断点续跑、自动汇总等。

```bash
python bash/run.py \
  --model DeepSeek-V4-Flash-Int8 \
  --api-url http://localhost:30000/v1 \
  --dataset-dir /data1/sora/evalscope \
  --output-dir /data1/sora/evalscope/output \
  --suite official \
  --limit none
```

### 2.2 `bash/collect_results.py`

读取各 benchmark 的 `reports/{benchmark}.json`，汇总成：

- `results/{folder_name}.xlsx`
- `results/{folder_name}.csv`

由 `run.py` 在每个 benchmark 结束后自动调用，也可单独运行。

### 2.3 `bash/perf_backup.py`

实现断点续跑：

- 每次 benchmark 完成后把 `predictions/` 和 report JSON 备份到 durable 目录。
- 再次运行同一 benchmark 前自动恢复到 `work_dir`，避免重复推理。
- 记录 `active_time`，kill 后重启不会重复计算等待时间。

### 2.4 `bash/pull_swe_bench_images.py`

根据数据集实例批量预拉 SWE-bench 评测所需的 Docker 镜像，支持：

- `--dataset`：指定 `swe_bench_verified` / `swe_bench_lite` 等，支持逗号分隔多数据集
- `--max-workers`：控制并发数
- 国内源加载数据集元数据

### 2.5 `config/dpv4-int8_nothinking.yaml`

各 benchmark 的 `temperature`、`top_p`、`max_tokens`、`subset_list`、`agent_config` 等参数。未在此文件中的 benchmark 会回退到 `run.py` 里的默认生成参数（`temperature=0.0, top_p=1.0, max_tokens=32768`）。

---

## 3. `bash/run.py` 完整参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--model` | `DeepSeek-V4-Flash-Int8` | 模型名，传给 OpenAI API 的 `model` 字段 |
| `--api-url` | `http://localhost:30000/v1` | 模型服务地址 |
| `--dataset-dir` | `/data1/sora/evalscope` | 数据集父目录，evalscope 会自动找其下的 `datasets/` |
| `--output-dir` | `/data1/sora/evalscope/output` | 评测输出根目录 |
| `--folder-name` | `model_name` 或 `model_name_THINKING` | 顶层输出文件夹名 |
| `--config` | `config/dpv4-int8_nothinking.yaml` | YAML 配置文件路径 |
| `--tokenizer-path` | `/data1/models/DeepSeek-V4-Flash-INT8` | 本地 tokenizer 路径，用于长文本 middle-truncation |
| `--suite` | `full` | 预置套件：`full` / `lite` / `mid` / `group1` / `group2` / `group3` / `official` |
| `--datasets` | `None` | 逗号分隔自定义 benchmark 列表，覆盖 `--suite` |
| `--exclude` | `None` | 从当前 suite 中排除的 benchmark |
| `--limit` | `None` | 每数据集最多跑几条；`none` / `all` 表示全量 |
| `--seed` | `42` | 随机种子 |
| `--batch-size` | `4` | 评测并发 |
| `--thinking` | `False` | 开启 thinking 模式 |
| `--no-thinking` | - | 关闭 thinking 模式 |
| `--thinking-max-tokens-scale` | `1.0` | thinking 开启时，max_tokens 乘以该系数 |
| `--max-tokens-add` | `0` | 每个 benchmark 的 max_tokens 额外增加的值 |
| `--judge-model` | `DeepSeek/DeepSeek-V4-Pro` | LLM-as-judge 模型名 |
| `--judge-api-url` | Vectron 地址 | 裁判模型 API 地址 |
| `--judge-api-key` | 内置 key | 裁判模型 API key |
| `--judge-max-tokens` | `10240` | 裁判模型最大输出长度 |
| `--truncation-tokens` | `131072` | 长文本 middle-truncation token 上限 |
| `--no-summary` | - | 跳过每次 benchmark 后的汇总 Excel/CSV |

---

## 4. 套件与 Benchmark 覆盖

### 4.1 `full` 全量套件

覆盖全部 benchmark，含 multi-run：

- **multi-run**：`humaneval`, `live_code_bench`, `aime24`, `aime25`, `aime26`, `hmmt26`, `imo_answerbench`, `gpqa_diamond`
- **single-run**：`bigcodebench`, `bfcl_v3`, `competition_math`, `gsm8k`, `hle`, `super_gpqa`, `arc`, `bbh`, `cmmlu`, `drop`, `hellaswag`, `mmlu`, `mmlu_pro`, `simple_qa`, `trivia_qa`, `winogrande`, `openai_mrcr`, `longbench_v2`
- **agent**：`tau2_bench`, `general_fc`

预计时间：约 **75h**（已含 multi-run，基于 CSV 实测）。

### 4.2 `official` 官方对比套件

对齐腾讯入库标准对比表核心子集：

| 类型 | Benchmark |
|------|-----------|
| multi-run | `aime25`, `aime26`, `live_code_bench` |
| single-run | `hle`, `mmlu_pro`, `gpqa_diamond`, `longbench_v2` |
| agent | `tau2_bench` |

> `swe_bench_verified` 默认注释掉，如需启用可修改 `bash/run.py` 的 `official` suite。

预计时间：视模型速度和是否启用 swe 而定，通常 **数小时到数十小时**。

### 4.3 `lite` 快速冒烟

- multi：`aime24`, `humaneval`
- single：`gsm8k`, `arc`, `longbench_v2`
- agent：`general_fc`

预计时间：约 **5h**。

### 4.4 `mid` 平衡套件

- multi：`aime24`, `humaneval`
- single：`live_code_bench`, `bigcodebench`, `competition_math`, `gsm8k`, `gpqa_diamond`, `mmlu_pro`, `simple_qa`, `longbench_v2`, `openai_mrcr`
- agent：`general_fc`, `tau2_bench`

预计时间：约 **25h**。

### 4.5 `group1/2/3` 多机组分组

用于多机并行，合计覆盖 `full` 全部 benchmark：

| 套件 | multi | single | agent | 预计时间 |
|------|-------|--------|-------|----------|
| `group1` | `live_code_bench`, `aime24`, `aime25`, `aime26`, `hmmt26`, `imo_answerbench`, `humaneval` | `bigcodebench`, `competition_math`, `gsm8k`, `drop`, `arc`, `hellaswag`, `winogrande` | - | ~22h |
| `group2` | - | `hle`, `mmlu_pro`, `trivia_qa` | - | ~26h |
| `group3` | `gpqa_diamond` | `openai_mrcr`, `longbench_v2`, `bfcl_v3`, `mmlu`, `cmmlu`, `bbh`, `simple_qa` | `tau2_bench`, `general_fc` | ~27h |

---

## 5. Multi-run 配置

以下 benchmark 默认会重复跑多次再取平均，次数在 `bash/run.py` 的 `MULTI_RUN_CONFIG` 中定义：

| Benchmark | 次数 | 说明 |
|-----------|------|------|
| `aime24` / `aime25` / `aime26` / `hmmt26` | 12 | 样本少，多次采样稳定结果 |
| `live_code_bench` | 5 | 约 100 样本 |
| `imo_answerbench` | 4 | 约 120 样本 |
| `humaneval` | 3 | 约 164 样本 |
| `gpqa_diamond` | 2 | 约 198 样本 |

---

## 6. 输出目录与统计

### 6.1 目录结构

```
output/
└── {folder_name}/                  # 默认 model_name，thinking 时默认 model_name_THINKING
    ├── {benchmark}/
    │   ├── seed_{seed}/            # 单次或 multi-run 第 1 次
    │   │   ├── predictions/
    │   │   ├── reviews/
    │   │   ├── reports/{benchmark}.json
    │   │   └── logs/
    │   ├── seed_{seed}_run_1/      # multi-run 第 2 次
    │   ├── seed_{seed}_run_2/      # multi-run 第 3 次
    │   └── ...
    └── active_time/                # 每个 benchmark 的真实运行时间累计

results/
└── {folder_name}.xlsx              # 汇总表格
```

### 6.2 汇总表格字段

Excel / CSV 通常包含：

| 字段 | 说明 |
|------|------|
| `benchmark` | benchmark 名 |
| `score` | 最终分数 |
| `num` | 样本数 |
| `active_time(h)` | 真实运行时间（小时） |
| `latency(s)` | 平均推理延迟 |
| `ttft(s)` | 首 token 时间 |
| `tps` | 每秒 token 数 |
| `input_tokens` / `output_tokens` | 平均输入/输出 token 数 |

### 6.3 查看单个 benchmark 分数

```bash
cat output/{folder_name}/aime25/seed_42/reports/aime25.json
```

### 6.4 查看汇总分数

```bash
python3 -c "
import json, glob
for f in sorted(glob.glob('output/{folder_name}/*/seed_*/reports/*/*.json')):
    data = json.load(open(f))
    score = data.get('score', data.get('mean_acc', 'N/A'))
    print(f'{f}: {score}')
"
```

---

## 7. 快速开始

### 7.1 安装依赖

```bash
conda create -n evalscope python=3.12 -y
conda activate evalscope
cd /data1/sora/evalscope
pip install -e ./evalscope
```

### 7.2 运行单个 benchmark

```bash
python bash/run.py --datasets gsm8k --limit 50
```

### 7.3 运行 suite

```bash
# 官方对比套件
python bash/run.py --suite official --limit none

# thinking 模式
python bash/run.py --suite official --thinking --thinking-max-tokens-scale 2.0

# 自定义输出文件夹
python bash/run.py --suite official --folder-name my_exp --limit none
```

### 7.4 预拉 SWE-bench 镜像

```bash
python bash/pull_swe_bench_images.py --dataset swe_bench_verified --max-workers 4
```

详细参数见：

```bash
python bash/run.py --help
```

---

## 8. 设计说明

- **模型无关**：`run.py` 通过 `--model` / `--api-url` 接入任意 OpenAI-compatible 服务。
- **配置可覆盖**：YAML 配置 + 命令行参数，未配置的 benchmark 自动使用默认生成参数。
- **可恢复**：基于 `perf_backup.py`，适合长时间评测任务在 kill/中断后继续。
- **可汇总**：基于 `collect_results.py`，自动产出可对比的 Excel/CSV。
- **可扩展**：新增 benchmark 只需在 YAML 配置参数，或在运行时依赖默认生成参数。

---

## 9. 相关文档

- 详细使用手册：`myread.md`
- Docker 构建说明：`DOCKER_BUILD.md`
- 上游 EvalScope：https://github.com/modelscope/evalscope