modelscope/evalscope · 上手攻略

  • 仓库：modelscope/evalscope
  • 链接：https://github.com/modelscope/evalscope
  • 分类：llm-evaluation · benchmark
  • 作者：Jay
  • 更新：2026-08-11

这是什么

EvalScope 是魔搭社区（ModelScope）打造的一站式大模型评测框架，用一行命令即可对 LLM、VLM、Embedding、Reranker、AIGC 等多类型模型进行能力评估、推理性能压测和结果可视化。

核心场景：评测模型效果（能力基准）、压测推理性能（TTFT/TPOT 等指标）、Agent 轨迹回放、多模型对战（Arena）。

⚠️ EvalScope 版本号建议以 pip 安装时拉取的版本为准，截至 2026-07-21 最新功能包括 Claw-Eval、ResearchRubrics、Toolathlon（Agent）、TVBench 等新基准。

解决什么问题

大模型评测存在三大痛点：

  1. 工具碎片化：能力评测用 OpenCompass，性能压测用另一套工具，结果分散无法统一可视化。
  2. 评测口径不统一：不同 benchmark 对同一个模型的排名差异极大，缺乏统一的 Agent 评测标准和轨迹回放能力。
  3. 多模态支持弱：VLM、AIGC 等非纯文本模型的评测工具稀缺。

EvalScope 通过多后端集成（OpenCompass、VLMEValKit、RAGEval）、统一 Pydantic 配置、交互式 WebUI 一次性解决这三个问题。

快速安装

pip install evalscope

最低依赖：Python 3.10+，pip / uv。

验证安装：

evalscope --version   # 输出版本号即安装成功

如需完整依赖（含 WebUI、perf 等）：

pip install "evalscope[all]"

核心用法

1. 基础能力评测（最常用）

# 评测 OpenAI 兼容 API 模型
evalscope eval \
  --model your-model-name \
  --api-url $OPENAI_API_BASE_URL \
  --api-key $OPENAI_API_KEY \
  --eval-type openai_api \
  --datasets gsm8k \
  --limit 5

# 评测本地 HuggingFace 模型
evalscope eval \
  --model ./your-model-path \
  --eval-type hf \
  --datasets mmlu c-eval \
  --limit 10

# 评测 Anthropic Claude API
evalscope eval \
  --model claude-3-5-sonnet \
  --eval-type anthropic_api \
  --api-key $ANTHROPIC_API_KEY \
  --datasets gsm8k

--datasets 支持多选，如 mmlu c-eval gsm8k。--limit 控制每数据集采样数量，生产评测去掉此参数。

2. 推理性能压测

# 标准性能压测
evalscope perf \
  --model your-model-name \
  --api-url $OPENAI_API_BASE_URL \
  --api-key $OPENAI_API_KEY \
  --eval-type openai_api \
  --concurrency 10 \
  --max-tokens 512 \
  --num-requests 200

# 多轮对话压测
evalscope perf \
  --model your-model-name \
  --api-url $OPENAI_API_BASE_URL \
  --api-key $OPENAI_API_KEY \
  --num-rounds 5 \
  --duration 300   # 墙钟时间预算（秒）

关键性能指标：TTFT（首批 Token 时间）、TPOT（每输出 Token 时间）、TPM（每分钟 Token 数）、TPS（每秒 Token 数）。

3. Agent 评测模式

# 通过 Docker 沙箱运行 Agent 基准
evalscope eval \
  --model your-model-name \
  --api-url $OPENAI_API_BASE_URL \
  --api-key $OPENAI_API_KEY \
  --eval-type openai_api \
  --datasets swe-bench_agentic \
  --runtime docker \
  --limit 5

# 公共 Agent CLI 评测（Claude Code / Codex）
evalscope eval \
  --model claude-code \
  --eval-type external_agent \
  --datasets gaia \
  --runtime docker

⚠️ Agent 评测依赖 Docker 沙箱，首次运行需拉取镜像（约 GB 级）。--runtime local 可用本地环境替代（需自行配置工具链）。

4. WebUI 可视化

# 启动 Web Dashboard（默认 http://localhost:7860）
evalscope webui

# 指定端口
evalscope webui --port 8080

支持：多模型对比仪表盘、报告概览、逐条 Agent Trace 回放、预测详情查阅。

5. Arena 竞技场模式

# 多模型对战（Pairwise Battle）
evalscope arena \
  --models gpt-4o claude-3-5-sonnet qwen-2.5 \
  --api-urls $OPENAI_BASE_URL $ANTHROPIC_BASE_URL $DASHSCOPE_BASE_URL \
  --api-keys $OPENAI_API_KEY $ANTHROPIC_API_KEY $DASHSCOPE_API_KEY \
  --datasets alpaca_eval

内置基准速查

类别 基准 说明
通用能力 MMLU、C-Eval、GSM8K 业界标准
Agent GAIA、SWE-bench_Pro、τ³-bench、BigCodeBench 多轮推理 + 工具调用
代码 BigCodeBench、SWE-bench Multilingual 代码生成与修复
多模态 CharXiv、BabyVision、ERQA、WorldVQA、TVBench VLM 评测
长上下文 LoCoMo QA、LongMemEval 128K+ 上下文
RAG MTEB 2.x、RAGAS 0.4.x RAG 评测
图像质量 SSIM、PSNR（全参考） AIGC 图像
Perf SWE-smith Agentic 推理吞吐
Vendor k2_verifier、kimi_verifier、minimax_verifier API 部署一致性验证

⚠️ 基准列表持续更新（最近更新：2026-07-21），建议以 官方文档支持的基准页 为准。

典型适用场景

  1. 模型选型：用同一套基准对比 GPT-4o、Claude 3.5、Qwen-2.5 等模型的中文能力（C-Eval）、数学（GSM8K）、代码（SWE-bench）表现，输出统一报告。
  2. API 部署验证：用 Vendor Verifier 验证第三方 API 是否忠实复现官方模型行为，避免「换名降质」。
  3. 推理优化基准：用 SWE-smith 对比自研推理引擎（如 TokenSpeed）的单 GPU TPM 和 TPS。
  4. Agent 能力评测：用 Docker 沙箱评测 Code Agent 的真实多步任务能力，录制完整轨迹。
  5. 第三方模型 API 质量审计：用竞技场模式对多个 API 提供商做盲测排名。

坑与注意

  1. API Key 安全：--api-key 建议用环境变量而非明文传递，敏感场景不要把 key 写在脚本里。
  2. Docker 镜像首次拉取慢：Agent 评测默认从 DockerHub 拉镜像，企业内网环境需提前配置 registry mirror。
  3. Perf 压测需控制 --concurrency：并发过高可能触发 API 限流，建议从低并发逐步加压。
  4. 多后端基准覆盖不同：OpenCompass 基准子集 ≠ VLMEValKit 基准子集，部分基准只能通过特定后端运行。
  5. --limit 参数仅用于快速验证：正式评测需去掉 --limit，否则结果不具统计意义。
  6. RAG 评测模块已重构：v2026.06.02 起 RAG 评测使用 MTEB 2.x + RAGAS 0.4.x，旧版配置文件需迁移。
  7. 外部 Agent Bridge（Claude Code/Codex）：需要评测对象 CLI 已在 PATH 中，且通过 --eval-type external_agent 指定，不支持代理模式。

与同类对比

工具 覆盖范围 Agent 评测 WebUI 多后端集成
EvalScope LLM/VLM/Embedding/Reranker/AIGC ✅ Docker 沙箱 + 轨迹回放 ✅ ✅ OpenCompass/VLMEvalKit/RAGEval
OpenCompass LLM 为主 有限 ❌ ❌
LLM EVAL 轻量 LLM 评测 ❌ ❌ ❌
HELM 全面但偏英文 ❌ ❌ ❌
SWE-bench 仅代码 ✅ 但非统一框架 ❌ ❌

EvalScope 的核心差异化：一个框架同时搞定能力评测 + 性能压测 + Agent 轨迹回放 + 可视化，且由 ModelScope 社区维护，对中文基准（C-Eval）原生支持好。

一句话结论

需要对大模型做中文能力评测、推理性能压测或 Agent 轨迹分析？EvalScope 一行命令搞定，WebUI 可视化开箱即用，是目前最接近「LLM 评测一站式解决方案」的开源框架。

来源与引用

  • 仓库 README（多语言）：https://github.com/modelscope/evalscope
  • 中文文档：https://evalscope.readthedocs.io/zh-cn/latest/
  • 英文文档：https://evalscope.readthedocs.io/en/latest/
  • PyPI：https://pypi.org/project/evalscope
  • 最新功能更新（2026-07）：https://github.com/modelscope/evalscope/releases
  • Agent 评测指南：https://evalscope.readthedocs.io/en/latest/user_guides/agent/native.html
  • 外部 Agent Bridge：https://evalscope.readthedocs.io/en/latest/user_guides/agent/bridge.html