# 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
```

主要特性：

- `--suite`：预置 `full` / `lite` / `mid` / `group1` / `group2` / `group3` / `official`
- `--datasets`：覆盖 suite，逗号分隔自定义 benchmark
- `--thinking` / `--thinking-max-tokens-scale` / `--max-tokens-add`：支持 thinking 模型
- `--folder-name`：自定义输出顶层文件夹名
- 自动生成汇总 Excel 到 `results/{folder_name}.xlsx`

### 2.2 `bash/collect_results.py`

读取 `output/{folder_name}/{benchmark}/seed_{seed}/reports/*.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` 里的默认生成参数。

---

## 3. 输出目录约定

```
output/
└── {folder_name}/                  # 默认 model_name，thinking 时默认 model_name_THINKING
    ├── {benchmark}/
    │   ├── seed_{seed}/
    │   │   ├── predictions/
    │   │   ├── reviews/
    │   │   ├── reports/{benchmark}.json
    │   │   └── logs/
    │   └── seed_{seed}_run_{n}/    # multi-run 数据集的第 n 次运行
    └── active_time/                # 真实运行时间累计

results/
└── {folder_name}.xlsx
```

---

## 4. 快速开始

### 4.1 安装依赖

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

### 4.2 运行单个 benchmark

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

### 4.3 运行 suite

```bash
python bash/run.py --suite official --limit none
```

详细参数见 `myread.md` 或：

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

---

## 5. 设计说明

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

---

## 6. 相关文档

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