From b15d9611535b71a6bc8cf609129b7317bc983835 Mon Sep 17 00:00:00 2001
From: sora <2075279110@qq.com>
Date: Thu, 23 Jul 2026 07:00:08 +0000
Subject: [PATCH] Expand README.md with full CLI parameters, suite benchmark
 lists, timing, and output statistics

---
 README.md | 191 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 166 insertions(+), 25 deletions(-)

diff --git a/README.md b/README.md
index 818bdd9..d8b0b0c 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@
 │   └── test.sh                     # 本地测试脚本示例
 ├── config/
 │   └── dpv4-int8_nothinking.yaml   # benchmark 生成参数配置
-├── tools/docker/                   # Docker 构建上下文（仅构建产物，不含运行镜像）
+├── tools/docker/                   # Docker 镜像构建上下文
 │   ├── Dockerfile.py312
 │   ├── bash/
 │   ├── evalscope/
@@ -33,7 +33,7 @@
 
 ### 2.1 `bash/run.py`
 
-统一的 benchmark 启动入口，支持 suite、自定义 datasets、thinking 模式、输出目录组织等。
+统一的 benchmark 启动入口，支持 suite、自定义 datasets、thinking 模式、输出目录组织、断点续跑、自动汇总等。
 
 ```bash
 python bash/run.py \
@@ -45,17 +45,9 @@ python bash/run.py \
   --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`，汇总成：
+读取各 benchmark 的 `reports/{benchmark}.json`，汇总成：
 
 - `results/{folder_name}.xlsx`
 - `results/{folder_name}.csv`
@@ -74,39 +66,174 @@ python bash/run.py \
 
 根据数据集实例批量预拉 SWE-bench 评测所需的 Docker 镜像，支持：
 
-- `--dataset`：指定 `swe_bench_verified` / `swe_bench_lite` 等
+- `--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` 里的默认生成参数。
+各 benchmark 的 `temperature`、`top_p`、`max_tokens`、`subset_list`、`agent_config` 等参数。未在此文件中的 benchmark 会回退到 `run.py` 里的默认生成参数（`temperature=0.0, top_p=1.0, max_tokens=32768`）。
 
 ---
 
-## 3. 输出目录约定
+## 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}/
+    │   ├── seed_{seed}/            # 单次或 multi-run 第 1 次
     │   │   ├── predictions/
     │   │   ├── reviews/
     │   │   ├── reports/{benchmark}.json
     │   │   └── logs/
-    │   └── seed_{seed}_run_{n}/    # multi-run 数据集的第 n 次运行
-    └── active_time/                # 真实运行时间累计
+    │   ├── seed_{seed}_run_1/      # multi-run 第 2 次
+    │   ├── seed_{seed}_run_2/      # multi-run 第 3 次
+    │   └── ...
+    └── active_time/                # 每个 benchmark 的真实运行时间累计
 
 results/
-└── {folder_name}.xlsx
+└── {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}')
+"
 ```
 
 ---
 
-## 4. 快速开始
+## 7. 快速开始
 
-### 4.1 安装依赖
+### 7.1 安装依赖
 
 ```bash
 conda create -n evalscope python=3.12 -y
@@ -115,19 +242,32 @@ cd /data1/sora/evalscope
 pip install -e ./evalscope
 ```
 
-### 4.2 运行单个 benchmark
+### 7.2 运行单个 benchmark
 
 ```bash
 python bash/run.py --datasets gsm8k --limit 50
 ```
 
-### 4.3 运行 suite
+### 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
 ```
 
-详细参数见 `myread.md` 或：
+### 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
@@ -135,16 +275,17 @@ python bash/run.py --help
 
 ---
 
-## 5. 设计说明
+## 8. 设计说明
 
 - **模型无关**：`run.py` 通过 `--model` / `--api-url` 接入任意 OpenAI-compatible 服务。
 - **配置可覆盖**：YAML 配置 + 命令行参数，未配置的 benchmark 自动使用默认生成参数。
 - **可恢复**：基于 `perf_backup.py`，适合长时间评测任务在 kill/中断后继续。
 - **可汇总**：基于 `collect_results.py`，自动产出可对比的 Excel/CSV。
+- **可扩展**：新增 benchmark 只需在 YAML 配置参数，或在运行时依赖默认生成参数。
 
 ---
 
-## 6. 相关文档
+## 9. 相关文档
 
 - 详细使用手册：`myread.md`
 - Docker 构建说明：`DOCKER_BUILD.md`