evalstone/HOWTO_EVAL_NEW_MODEL.md

# 如何评测新模型

> 本指南假设模型已通过 sglang/vllm 等部署为 OpenAI 兼容 API，只需修改配置即可用本框架评测。

---

## 目录

1. [最小改动：只换模型名和 API 地址](#最小改动只换模型名和-api-地址)
2. [推荐做法：复制一份配置文件](#推荐做法复制一份配置文件)
3. [配置参数说明](#配置参数说明)
4. [运行命令](#运行命令)
5. [结果收集](#结果收集)

---

## 最小改动：只换模型名和 API 地址

如果新模型能力和 `DeepSeek-V4-Flash-INT8` 接近，只想换个名字和 API 地址：

```bash
cd /data1/sora/evalscope
python bash/run.py \
  --model Your-Model-Name \
  --api-url http://your-api:30000/v1 \
  --dataset-dir /data1/sora/evalscope \
  --output-dir /data1/sora/evalscope/output_your_model \
  --limit none
```

> `--limit none` 跑完整数据；测试时用 `--limit 2` 或 `--limit 20`。

---

## 推荐做法：复制一份配置文件

不同模型的最佳 `temperature` / `max_tokens` 可能不同，建议为每个模型单独维护一个 YAML。

### 1. 复制默认配置

```bash
cd /data1/sora/evalscope/bash
mkdir -p config
cp config/dpv4-int8_nothinking.yaml config/your-model.yaml
```

### 2. 按需修改 `config/your-model.yaml`

下面是重点需要改的字段：

```yaml
# 示例： reasoning 模型可能需要 temperature=1.0 多测几次求平均
aime24:
  generation_config:
    temperature: 1.0      # 多测 benchmark 用 1.0；只测一次用 0.0
    top_p: 1.0
    stream: true
    max_tokens: 32768     # 根据模型输出长度能力调整

# 示例：知识类 benchmark 通常 greedy decoding
mmlu_pro:
  generation_config:
    temperature: 0.0
    top_p: 1.0
    stream: true
    max_tokens: 8192

# 示例：Agent benchmark 的 judge model
# 如果你不想改 judge model，保持默认 deepseek-v4-pro 即可
tau2_bench:
  generation_config:
    temperature: 0.0
    top_p: 1.0
    stream: true
    max_tokens: 16384
  dataset_args:
    extra_params:
      user_model: deepseek-v4-pro
      api_key: sk-9ed86ef546ca47e3afa7c3b014dea268
      api_base: https://api.deepseek.com/v1
      generation_config:
        temperature: 0.0
        max_tokens: 4096
  agent_config:
    mode: native
    strategy: react
    max_steps: 50
```

### 3. 修改 `run.py` 中的截断/tokenizer 配置（长上下文模型必看）

打开 `bash/run.py`，找到下面几行：

```python
MODEL_PATH = '/data1/models/DeepSeek-V4-Flash-INT8'
```

如果你的新模型本地有 tokenizer 目录，改成对应路径；如果通过 API 跑，这条基本不影响运行，但建议保持和模型一致。

再找到：

```python
TRUNCATION_CONFIG = {
    'longbench_v2': 32768*4,
    'openai_mrcr': 32768*4,
}
```

这表示长上下文 benchmark 最多保留 **131072 tokens**（头尾各一半）。
- 如果新模型 context length 更大且显存足够，可以调大（如 `32768*8`）。
- 如果显存紧张，可以调小（如 `32768*2` = 65536）。

### 4. 修改 judge model（可选）

如果 tau2_bench 需要换 judge：

```python
JUDGE_MODEL_ARGS = {
    'model_id': 'deepseek-v4-pro',
    'api_url': 'https://api.deepseek.com/v1',
    'api_key': 'sk-9ed86ef546ca47e3afa7c3b014dea268',
    ...
}
```

如果不需要 judge（例如只跑非 Agent benchmark），可以忽略。

---

## 配置参数说明

| 参数 | 作用 | 建议 |
|------|------|------|
| `temperature` | 采样温度 | 需要多次采样求平均的 benchmark（aime/hmmt/imo/live_code_bench/humaneval/gpqa）用 `1.0`；其余 greedy `0.0` |
| `max_tokens` | 最大输出长度 | 短输出知识题 `8192`；推理/代码 `32768`；Agent `16384`；具体看模型能力和任务 |
| `top_p` | nucleus sampling | 一般保持 `1.0` |
| `stream` | 流式输出 | 建议 `true`，兼容性好 |
| `agent_config.max_steps` | Agent 最大步数 | 默认 `50`；复杂任务可调大，简单任务可调小 |
| `TRUNCATION_CONFIG` | 长上下文截断 | 根据模型 context length 和显存调整 |

---

## 运行命令

### 全量跑

```bash
cd /data1/sora/evalscope
python bash/run.py \
  --config bash/config/your-model.yaml \
  --model Your-Model-Name \
  --api-url http://your-api:30000/v1 \
  --dataset-dir /data1/sora/evalscope \
  --output-dir /data1/sora/evalscope/output_your_model \
  --limit none
```

### 只跑某个分组

```bash
python bash/run_group1.py \
  --config bash/config/your-model.yaml \
  --model Your-Model-Name \
  --api-url http://your-api:30000/v1 \
  --dataset-dir /data1/sora/evalscope \
  --output-dir /data1/sora/evalscope/output_your_model_group1 \
  --limit none
```

### Docker 方式

```bash
docker run -it --rm \
  --network host \
  -v /data1/sora/evalscope/datasets:/opt/evalscope/datasets \
  -v /data1/sora/evalscope/output_your_model:/opt/evalscope/output_your_model \
  -v /var/run/docker.sock:/var/run/docker.sock \
  evalscope-complete-py312:latest \
  bash -c "
    cd /opt/evalscope && \
    python bash/run.py \
      --config bash/config/your-model.yaml \
      --model Your-Model-Name \
      --api-url http://localhost:30000/v1 \
      --dataset-dir /opt/evalscope \
      --output-dir /opt/evalscope/output_your_model \
      --limit none
  "
```

---

## 结果收集

评测完成后，结果在 `--output-dir` 目录下：

```
output_your_model/
├── humaneval/seed_42/reports/Your-Model-Name/humaneval.json
├── aime24/seed_42/reports/Your-Model-Name/aime24.json
└── ...
```

汇总分数：

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

或者用 `bash/update_excel.py`（如果有）把结果写入 Excel。