快速上手

EvalScope 是一个为大模型设计的评测框架，旨在提供简单易用、功能全面的评测流程。本指南将引导您完成从简单到复杂的各类评测任务，帮助您快速上手。

开始第一次评测

您可以通过命令行或 Python 代码两种方式，在指定数据集上使用默认配置评测一个模型。

方式1：使用命令行

在任意路径下执行 evalscope eval 命令即可启动评测。这是最推荐的入门方式。

evalscope eval \
 --model Qwen/Qwen2.5-0.5B-Instruct \
 --datasets gsm8k arc \
 --limit 5

基本参数说明:

• --model: 指定模型的 ModelScope ID (如 Qwen/Qwen2.5-0.5B-Instruct) 或本地路径。

• --datasets: 指定一个或多个数据集名称，以空格分隔。支持的数据集请参考数据集列表。

• --limit: 每个数据集最多评测的样本数，便于快速验证。若不设置，则评测全量数据。

方式2：使用 Python 代码

通过调用 run_task 函数并传入 TaskConfig 配置，可以在 Python 环境中运行评测。配置可以是 TaskConfig 对象、Python 字典，或 yaml/json 文件路径。

使用 TaskConfig 对象

from evalscope.run import run_task
from evalscope.config import TaskConfig

task_cfg = TaskConfig(
    model='Qwen/Qwen2.5-0.5B-Instruct',
    datasets=['gsm8k', 'arc'],
    limit=5
)

run_task(task_cfg=task_cfg)

使用 Python 字典

from evalscope.run import run_task

task_cfg = {
    'model': 'Qwen/Qwen2.5-0.5B-Instruct',
    'datasets': ['gsm8k', 'arc'],
    'limit': 5
}

run_task(task_cfg=task_cfg)

使用 YAML 文件

config.yaml

model: Qwen/Qwen2.5-0.5B-Instruct
datasets:
  - gsm8k
  - arc
limit: 5

from evalscope.run import run_task

run_task(task_cfg="config.yaml")

使用 JSON 文件

config.json

{
    "model": "Qwen/Qwen2.5-0.5B-Instruct",
    "datasets": ["gsm8k", "arc"],
    "limit": 5
}

from evalscope.run import run_task

run_task(task_cfg="config.json")

查看评测结果

评测完成后，终端会打印出如下格式的得分报告：

+-----------------------+----------------+-----------------+-----------------+---------------+-------+---------+
| Model Name            | Dataset Name   | Metric Name     | Category Name   | Subset Name   |   Num |   Score |
+=======================+================+=================+=================+===============+=======+=========+
| Qwen2.5-0.5B-Instruct | gsm8k          | AverageAccuracy | default         | main          |     5 |     0.4 |
+-----------------------+----------------+-----------------+-----------------+---------------+-------+---------+
| Qwen2.5-0.5B-Instruct | ai2_arc        | AverageAccuracy | default         | ARC-Easy      |     5 |     0.8 |
+-----------------------+----------------+-----------------+-----------------+---------------+-------+---------+
| Qwen2.5-0.5B-Instruct | ai2_arc        | AverageAccuracy | default         | ARC-Challenge |     5 |     0.4 |
+-----------------------+----------------+-----------------+-----------------+---------------+-------+---------+

小技巧

您还可以通过可视化工具来深入分析评测结果：

pip install 'evalscope[service]'
evalscope service

服务启动后，访问 http://127.0.0.1:9000 即可打开可视化界面。详情参考：评测结果可视化

进阶用法

评测在线模型 API

EvalScope 支持评测兼容 OpenAI API 格式的模型服务。只需指定服务地址、API Key，并将 eval-type 设置为 openai_api。

示例1：直接评测 OpenAI API 兼容的云端服务（推荐入门方式，无需 GPU）

支持任意 OpenAI API 兼容的模型服务，只需配置 $OPENAI_API_BASE_URL 与 $OPENAI_API_KEY 即可：

evalscope eval \
 --model your-model-name \
 --api-url $OPENAI_API_BASE_URL \
 --api-key $OPENAI_API_KEY \
 --eval-type openai_api \
 --datasets gsm8k \
 --limit 10

示例2：评测自部署的模型服务

以 vLLM 为例，启动一个模型服务：

# 请先安装 vLLM: pip install vllm
export VLLM_USE_MODELSCOPE=True
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-0.5B-Instruct \
  --served-model-name qwen2.5 \
  --trust-remote-code \
  --port 8801

使用以下命令评测该 API 服务：

evalscope eval \
 --model qwen2.5 \
 --api-url http://127.0.0.1:8801/v1 \
 --api-key EMPTY \
 --eval-type openai_api \
 --datasets gsm8k \
 --limit 10

如需评测 OpenAI 官方 Responses API，请设置 --eval-type openai_responses_api，并将 --api-url 指向 API 根路径：

evalscope eval \
 --model gpt-4.1-mini \
 --api-url https://api.openai.com/v1 \
 --api-key $OPENAI_API_KEY \
 --eval-type openai_responses_api \
 --datasets gsm8k \
 --limit 10 \
 --generation-config '{"stream": true, "max_tokens": 512}'

自定义评测参数

示例1. 调整模型加载和推理生成参数

您可以通过传入 JSON 格式的字符串来精细化控制模型加载、推理生成和数据集配置。

evalscope eval \
 --model Qwen/Qwen3-0.6B \
 --model-args '{"revision": "master", "precision": "torch.float16", "device_map": "auto"}' \
 --generation-config '{"do_sample":true,"temperature":0.6,"max_tokens":512}' \
 --dataset-args '{"gsm8k": {"few_shot_num": 0, "few_shot_random": false}}' \
 --datasets gsm8k \
 --limit 10

常用参数说明:

• --model-args: 模型加载参数，例如 revision (版本), precision (精度), device_map (设备映射)。

• --generation-config: 推理生成参数，例如 do_sample (采样), temperature (温度), max_tokens (最大长度)。

• --dataset-args: 数据集专属参数，以数据集名称为键。例如 few_shot_num (少样本数量)。

示例2. 调整结果聚合方式

对于需要多次生成的任务（如数学题），可以通过 --repeats 参数指定重复生成次数k，并使用 dataset-args 调整结果聚合方式，例如 mean_and_vote_at_k、mean_and_pass_at_k、mean_and_pass^k。

evalscope eval \
 --model Qwen/Qwen2.5-0.5B-Instruct \
 --datasets gsm8k \
 --limit 10 \
 --dataset-args '{"gsm8k": {"aggregation": "mean_and_vote_at_k"}}' \
 --repeats 5

参见

查看所有可配置项，请参考：全部参数说明

使用裁判模型进行评估

对于某些主观或开放式任务（如 simple_qa），可以指定一个强大的“裁判模型”来评估目标模型的输出。

import os
from evalscope import TaskConfig, run_task
from evalscope.constants import JudgeStrategy

task_cfg = TaskConfig(
    model='qwen2.5-7b-instruct',
    api_url='https://dashscope.aliyuncs.com/compatible-mode/v1',
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    eval_type='openai_api',
    datasets=['chinese_simpleqa'],
    limit=5,
    judge_strategy=JudgeStrategy.AUTO,
    judge_model_args={
        'model_id': 'qwen2.5-72b-instruct',
        'api_url': 'https://dashscope.aliyuncs.com/compatible-mode/v1',
        'api_key': os.getenv('DASHSCOPE_API_KEY'),
    }
)

run_task(task_cfg=task_cfg)

参见

关于裁判模型的详细配置，请参考：裁判模型参数

使用 Hugging Face 数据集

EvalScope 默认从 ModelScope 加载数据集。如需改用 Hugging Face Hub，将 --dataset-hub 设置为 huggingface 即可。当某个数据集在 Hugging Face 与 ModelScope 上的仓库 ID 不一致时，再通过 --dataset-args 覆盖该数据集的 dataset_id。

以 ocr_bench 为例，其默认 ID 为 ModelScope 上的 evalscope/OCRBench，对应 Hugging Face 仓库为 echo840/OCRBench：

evalscope eval \
 --model Qwen/Qwen2.5-VL-7B-Instruct \
 --datasets ocr_bench \
 --dataset-hub huggingface \
 --dataset-args '{"ocr_bench": {"dataset_id": "echo840/OCRBench"}}' \
 --limit 5

等价的 Python 写法：

from evalscope import TaskConfig, run_task

task_cfg = TaskConfig(
    model='Qwen/Qwen2.5-VL-7B-Instruct',
    datasets=['ocr_bench'],
    dataset_hub='huggingface',
    dataset_args={
        'ocr_bench': {
            'dataset_id': 'echo840/OCRBench',
        },
    },
    limit=5,
)

run_task(task_cfg=task_cfg)

小技巧

若数据集在 Hugging Face 与 ModelScope 上的仓库 ID 相同，只需设置 --dataset-hub huggingface，无需再传 dataset_id。

离线评测

在无网络环境下，您可以使用本地缓存的模型和数据集进行评测。

1. 准备本地数据集

数据集默认托管在ModelScope上，加载需要联网。如果是无网络环境，可以使用本地数据集和模型，流程如下：

1. 首先查看想要使用的数据集在modelscope上的ID：在支持的数据集列表中查找到需要使用的数据集的数据集ID，例如mmlu_pro的ID为 modelscope/MMLU-Pro。

2. 使用modelscope命令下载数据集：点击“数据集文件”tab -> 点击“下载数据集” -> 复制命令行

# 下载数据集
modelscope download --dataset modelscope/MMLU-Pro --local_dir ./data/mmlu_pro

3. 使用目录./data/mmlu_pro作为local_path参数的值传入即可。

2. 准备本地模型

模型文件托管在ModelScope Hub端，需要联网加载，当需要在离线环境创建评测任务时，可提前将模型下载到本地：

例如使用modelscope命令下载Qwen2.5-0.5B-Instruct模型到本地：

modelscope download --model modelscope/Qwen2.5-0.5B-Instruct --local_dir ./model/qwen2.5

参见

更多下载选项，请参考 ModelScope下载指南。

3. 运行离线评测

在评测命令中，将 --model 指向本地模型路径，并通过 --dataset-args 指定数据集的 local_path。

evalscope eval \
 --model ./model/qwen2.5 \
 --datasets mmlu_pro \
 --dataset-args '{"mmlu_pro": {"local_path": "./data/mmlu_pro"}}' \
 --limit 10

从已有/中断的评测结果继续评测

如果之前的评测任务中断，或者您想基于已有的评测结果继续进行评测，可以使用 --use-cache 参数指定之前的输出目录。这将跳过已完成的样本，只评测剩余样本。此外，还可以通过 --rerun-review 参数强制对所有样本重新执行评分步骤。

evalscope eval \
 --model Qwen/Qwen2.5-0.5B-Instruct \
 --datasets gsm8k \
 --limit 10 \
 --use-cache outputs/20230101_123456 \
 --rerun-review

跳过评测出错的样本

在某些情况下，模型可能会因为输入过长、超时、模型服务崩溃等原因导致推理失败，或评测过程中出现了未知错误。这时程序会抛出异常并中断评测流程。您可以通过 --ignore-errors 参数跳过这些出错样本，继续评测剩余样本。在评测报告中，这些样本会被忽略，也就是说最终评测的样本数量会减少。

evalscope eval \
 --model Qwen/Qwen2.5-0.5B-Instruct \
 --datasets gsm8k \
 --limit 10 \
 --ignore-errors

从 v0.1.x 迁移

如果您之前使用的是 v0.1.x 版本，升级到 v1.0+ 后请注意以下主要变化：

1. 本地数据集：不再支持 zip 压缩包格式。请参考离线评测指引，使用 local_path 参数加载本地数据集。

2. 可视化兼容性：v1.0 的输出报告格式已更新，旧版报告与新版可视化工具不兼容。

3. 推理参数：模型推理参数 n 已被移除，请改用 repeats 参数来控制重复生成次数。

4. 评测流程控制：stage 参数已移除。新增 rerun_review 参数，用于在 use_cache=True 时强制重新执行评分步骤。

5. 数据集名称：gpqa 数据集已更名为 gpqa_diamond，且不再需要手动指定 subset_list。

常见问题

在评测过程中遇到问题？我们为您整理了一份常见问题列表，希望能帮助您解决问题。

参见

参考：常见问题解答