EvalScope 安装与使用说明

EvalScope 安装与使用说明一、项目简介EvalScope 是由魔搭社区ModelScope打造的一站式大模型评测框架支持全面的评测基准内置 MMLU、C-Eval、GSM8K 等 200 评测基准多模态支持LLM、VLM、Embedding、Reranker、AIGC 等推理性能测试TTFT、TPOT、吞吐量等指标交互式报告WebUI 可视化界面支持多维度模型对比二、安装步骤2.1 环境要求Python 3.10Windows / Linux / macOSGPU 环境推荐用于本地模型评测2.2 创建虚拟环境# 创建虚拟环境python-mvenv venv# 激活虚拟环境Windows PowerShell.\venv\Scripts\Activate.ps1# 激活虚拟环境Linux/macOSsourcevenv/bin/activate2.3 安装依赖# 切换到 evalscope 源码目录cdevalscope# 安装核心依赖使用清华镜像加速pipinstall-rrequirements/framework.txt-ihttps://pypi.tuna.tsinghua.edu.cn/simple --prefer-binary# 安装额外依赖可选pipinstalltorch accelerate-ihttps://pypi.tuna.tsinghua.edu.cn/simple --prefer-binary2.4 配置项目路径重要由于 editable install 模式在 Windows 下存在 namespace package 问题需要通过.pth文件配置# 创建 .pth 文件指向项目源码目录echoE:\project\evalscope\evalscopeE:\project\evalscope\venv\Lib\site-packages\evalscope.pth2.5 验证安装# 验证模块路径应输出 __init__.py 的路径而非 Nonepython-cimport evalscope; print(evalscope.__file__)# 验证注册表所有数值应大于 0python-cimport evalscope; from evalscope.api.registry import BENCHMARK_REGISTRY, MODEL_APIS, METRIC_REGISTRY, AGGREGATION_REGISTRY; print(Benchmarks:, len(BENCHMARK_REGISTRY), Model APIs:, len(MODEL_APIS), Metrics:, len(METRIC_REGISTRY), Aggregators:, len(AGGREGATION_REGISTRY))三、快速开始3.1 方式一命令行评测# 评测本地模型自动从 ModelScope 下载evalscopeeval\--modelQwen/Qwen2.5-0.5B-Instruct\--datasetsgsm8k arc\--limit5# 评测 OpenAI API 兼容的在线模型evalscopeeval\--modelyour-model-name\--api-url$OPENAI_API_BASE_URL\--api-key$OPENAI_API_KEY\--eval-type openai_api\--datasetsgsm8k\--limit53.2 方式二Python 代码创建demo1.pyfromevalscope.runimportrun_task task_cfg{model:Qwen/Qwen2.5-0.5B-Instruct,datasets:[gsm8k,arc],limit:5}run_task(task_cfgtask_cfg)运行python demo1.py E:\project\evalscope\venv\Scripts\python.exe E:\project\evalscope\demo1.py3.3 方式三配置文件创建config.yamlmodel:Qwen/Qwen2.5-0.5B-Instructmodel_args:revision:masterprecision:torch.float16datasets:-gsm8k-arcgeneration_config:max_tokens:2048temperature:0.7limit:5运行python-cfrom evalscope.run import run_task; run_task(task_cfgconfig.yaml)四、配置说明4.1 核心参数参数说明默认值model模型名称ModelScope 或 HuggingFace 地址无datasets评测数据集列表如[gsm8k, arc, mmlu]无limit每个数据集评测样本数用于快速测试无eval_type评测类型llm_ckpt本地模型、openai_apiAPI 模型llm_ckptwork_dir输出目录./outputs/{timestamp}4.2 模型参数task_cfg{model:Qwen/Qwen2.5-0.5B-Instruct,model_args:{revision:master,precision:torch.float16,device_map:auto},generation_config:{max_tokens:2048,temperature:0.7,top_p:0.95,do_sample:False}}4.3 数据集参数task_cfg{dataset_args:{gsm8k:{few_shot_num:4,few_shot_random:False,subset_list:[main]}}}五、支持的数据集5.1 LLM 基准部分数据集类型描述gsm8k数学推理Grade School Math 8Karc科学问答AI2 Reasoning Challengemmlu多任务Massive Multitask Language Understandingceval中文评测Chinese Evaltruthful_qa真实性Truthful QAhumaneval代码生成HumanEval Code5.2 VLM 基准部分数据集类型描述mmmu多模态MMMU Benchmarkai2d图表理解AI2D Diagram Understandingmathvista数学视觉MathVistavqav2视觉问答VQA v2.05.3 查看全部支持的数据集python-cimport evalscope; from evalscope.api.registry import BENCHMARK_REGISTRY; print(sorted(BENCHMARK_REGISTRY.keys()))六、评测结果6.1 输出目录结构outputs/20260728_100401/ ├── configs/ │ └── task_config.yaml # 任务配置 ├── reports/ │ ├── Qwen2.5-0.5B-Instruct/ │ │ ├── gsm8k.json # 数据集报告 │ │ └── arc.json │ └── report.html # 可视化 HTML 报告 └── predictions/ └── Qwen2.5-0.5B-Instruct/ └── gsm8k_main_preds.json # 预测结果6.2 示例输出gsm8k report table: ┌───────────────────────┬───────────┬──────────┬──────────┬───────┬─────────┬─────────┐ │ Model │ Dataset │ Metric │ Subset │ Num │ Score │ Cat.0 │ ├───────────────────────┼───────────┼──────────┼──────────┼───────┼─────────┼─────────┤ │ Qwen2.5-0.5B-Instruct │ gsm8k │ mean_acc │ main │ 5 │ 0.4 │ default │ └───────────────────────┴───────────┴──────────┴──────────┴───────┴─────────┴─────────┘6.3 启动可视化服务# 安装服务依赖pipinstallevalscope[service]# 启动服务evalscopeservice访问http://127.0.0.1:9000查看可视化报告。七、常见问题Q1: Benchmark ‘gsm8k’ not found原因evalscope/__init__.py未被执行导致注册表为空。解决方案使用.pth文件配置方式详见 2.4 节。Q2: litellm 安装失败缺少 Rust解决方案使用预编译版本pipinstalllitellm1.55.0 --prefer-binary-ihttps://pypi.tuna.tsinghua.edu.cn/simpleQ3: editdistance 编译错误解决方案安装预编译替代包pipinstalleditdistance-sQ4: 模型下载速度慢解决方案配置 ModelScope 镜像pipinstallmodelscope-ihttps://pypi.tuna.tsinghua.edu.cn/simple设置环境变量exportMODEL_SCOPE_ENDPOINThttps://www.modelscope.cnQ5: CUDA 内存不足解决方案task_cfg{model_args:{device_map:auto,load_in_4bit:True# 或 load_in_8bit}}八、进阶功能8.1 性能压测# 单模型性能测试evalscope perf--modelQwen/Qwen2.5-0.5B-Instruct--concurrency124# 多模型对比evalscope perf--modelQwen/Qwen2.5-0.5B-Instruct Qwen/Qwen2.5-7B-Instruct8.2 竞技场模式模型对战evalscope arena\--model-list Qwen/Qwen2.5-0.5B-Instruct Qwen/Qwen2.5-7B-Instruct\--datasetsgsm8k\--limit108.3 Agent 评测evalscopeeval\--modelQwen/Qwen2.5-0.5B-Instruct\--datasetsgsm8k\--agent-config{strategy: function_calling}\--limit5九、参考文档官方文档支持的数据集列表参数说明自定义数据集指南十、项目结构evalscope/ ├── evalscope/ # 核心代码 │ ├── benchmarks/ # 评测基准适配器 │ ├── models/ # 模型 API 接口 │ ├── metrics/ # 评测指标 │ ├── evaluator/ # 评测执行器 │ ├── report/ # 报告生成 │ ├── run.py # 主入口 │ └── config.py # 配置管理 ├── requirements/ # 依赖文件 ├── docs/ # 文档 ├── tests/ # 测试 └── pyproject.toml # 项目配置