参数说明

执行 evalscope eval --help 可获取全部参数说明。

环境变量

以下环境变量可在启动前设置，用于控制全局默认行为：

环境变量	说明	默认值
EVALSCOPE_CACHE	EvalScope 缓存根目录，用于存放数据集、评测中间文件等	~/.cache/evalscope
EVALSCOPE_LANGUAGE	全局默认语言，影响报告等输出语言（en 或 zh）	en
EVALSCOPE_HEARTBEAT_INTERVAL	评测进度心跳上报间隔（秒）	60
MODELSCOPE_CACHE	ModelScope 模型与数据集缓存根目录	~/.cache/modelscope/hub

模型参数

参数	类型	说明	默认值
--model	str	被评测的模型名称 • ModelScope模型ID（如Qwen/Qwen2.5-0.5B-Instruct） • 本地模型路径（如/path/to/model） • API服务的模型ID（如Qwen2.5-0.5B-Instruct）	-
--model-id	str	模型别名，用于报告展示	model的最后一部分
--api-url	str	模型API端点，支持OpenAI兼容格式和OpenAI Responses API根路径 示例：http://127.0.0.1:8000/v1 或 https://api.openai.com/v1	None
--api-key	str	模型API端点密钥	EMPTY
--model-args	str	模型加载参数，逗号分隔的key=value或JSON字符串 • revision: 模型版本 • precision: 模型精度 • device_map: 设备分配	revision=master precision=torch.float16 device_map=auto
--model-task	str	模型任务类型	text_generation （可选：image_generation）
--chat-template	str	模型推理模板，支持Jinja模板字符串（仅本地推理支持该参数）	None（使用transformers默认）

示例：

# key=value形式
--model-args revision=master,precision=torch.float16,device_map=auto

# JSON字符串形式
--model-args '{"revision": "master", "precision": "torch.float16", "device_map": "auto"}'

模型推理参数

--generation-config 参数支持以下配置项（逗号分隔的key=value或JSON字符串）：

参数	类型	说明	支持的后端
timeout	int	请求超时时间（秒）	所有
retries	int	重试次数，默认为5	OpenAI兼容
retry_interval	int	重试间隔时间（秒），默认10	OpenAI兼容
stream	bool	是否流式返回响应	所有
max_tokens	int	最大生成token数量	所有
top_p	float	Nucleus采样，考虑概率质量为top_p的token	所有
temperature	float	采样温度，范围0~2，越高越随机	所有
frequency_penalty	float	范围-2.0~2.0，正值惩罚重复token	OpenAI兼容
presence_penalty	float	范围-2.0~2.0，正值惩罚已出现token	OpenAI兼容
logit_bias	dict	token id到偏置值的映射（-100~100） 示例："42=10,43=-10"	OpenAI兼容
seed	int	随机种子	OpenAI兼容
do_sample	bool	是否采用采样策略（否则贪婪解码）	Transformers
top_k	int	从top_k最可能的词中采样	Anthropic, Google, HuggingFace, vLLM, SGLang
logprobs	bool	是否返回输出token的对数概率	OpenAI, Grok, TogetherAI, HuggingFace, llama-cpp-python, vLLM, SGLang
top_logprobs	int	返回概率最高的前N个token（范围0~20）	OpenAI, Grok, HuggingFace, vLLM, SGLang
parallel_tool_calls	bool	工具调用是否支持并行	OpenAI, Groq
max_tool_output	int	工具输出的最大字节数	所有（默认16*1024）
extra_body	dict	向OpenAI兼容服务发送的额外请求体	OpenAI兼容服务
extra_query	dict	向OpenAI兼容服务发送的额外查询参数	OpenAI兼容服务
extra_headers	dict	向OpenAI兼容服务发送的额外请求头	OpenAI兼容服务
height	int	图像生成模型专用，指定图像高度	图像生成模型
width	int	图像生成模型专用，指定图像宽度	图像生成模型
num_inference_steps	int	图像生成模型专用，推理步数	图像生成模型
guidance_scale	float	图像生成模型专用，指导尺度	图像生成模型

示例：

# key=value形式
--generation-config do_sample=true,temperature=0.5

# JSON字符串形式（支持更复杂参数）
--generation-config '{"do_sample":true,"temperature":0.5,"extra_body": {"chat_template_kwargs":{"enable_thinking": false}}}'

数据集参数

参数	类型	说明	默认值
--datasets	list[str]	数据集名称列表，空格分隔 参考数据集列表	-
--dataset-dir	str	数据集下载路径	~/.cache/modelscope/datasets
--dataset-hub	str	数据集下载源	modelscope （可选：huggingface）
--limit	int/float	每个数据集最大评测数据量 • int：评测前N条数据 • float：评测前N%数据 示例：100或0.1	None（全部评测）
--repeats	int	重复推理一个样例多次	1
--dataset-args	str	数据集配置参数（JSON字符串），详见下表	{}

dataset-args 配置项

--dataset-args 为JSON字符串，每个数据集可配置以下参数：

参数	类型	说明
dataset_id	str	数据集modelscope id/本地路径
local_path	str	本地数据集路径，已废弃，请使用dataset_id
review_timeout	float	评测样本超时时间（秒），代码类任务建议设置
prompt_template	str	Prompt模板，示例：Question: {query}\nAnswer:
system_prompt	str	系统prompt
subset_list	list[str]	评测数据子集列表
few_shot_num	int	few-shot示例数量
few_shot_random	bool	是否随机采样few-shot数据
shuffle	bool	是否打乱数据
shuffle_choices	bool	是否打乱选项顺序（仅多选题）
metric_list	list[str|dict]	指标列表，默认支持acc
aggregation	str	评测结果聚合方式，默认mean。可选：mean_and_pass_at_k、mean_and_vote_at_k、mean_and_pass_hat_k（均需设置repeats=k）。 • pass_at_k：同一样例生成k次至少一次通过的概率（如humaneval设repeats=5） • vote_at_k：对同一样例k次结果投票后计分 • pass_hat_k：同一样例k次全部通过的概率（如tau2_bench设repeats=3）
filters	dict	输出过滤器 • remove_until: 过滤指定字符串之前的内容 • extract: 提取正则匹配的内容
force_redownload	bool	是否强制重新下载数据集
extra_params	dict	数据集相关的额外参数，具体参考各数据集说明，指定{<param_name>:<value>}即可, value的类型(type)和选择范围(choices)根据具体参数而定。SWE-bench agentic 等基准的扩展参数请参见 Agent 评测
sandbox_config	dict	Sandbox配置（详见下方Sandbox参数）

sandbox_config 配置项：

参数	类型	说明	默认值
image	str	Docker镜像名称	python:3.11-slim
network_enabled	bool	是否启用网络	true
tools_config	dict	工具配置字典	{'shell_executor': {}, 'python_executor': {}}

示例：

--datasets gsm8k arc ifeval hle \
--dataset-args '{
  "gsm8k": {
    "few_shot_num": 4,
    "few_shot_random": false
  },
  "arc": {
    "dataset_id": "/path/to/arc"
  },
  "ifeval": {
    "filters": {
      "remove_until": "</think>"
    }
  },
  "hle": {
    "extra_params": {
      "include_multi_modal": false
    }
  }
}'

评测参数

参数	类型	说明	默认值
--eval-type	str	评测类型 • llm_ckpt: 本地模型推理（transformers） • openai_api: OpenAI兼容Chat Completions API服务 • openai_responses_api: OpenAI官方Responses API服务 • anthropic_api: Anthropic Claude API服务 • litellm: LiteLLM多厂商路由（支持100+ LLM服务商） • text2image: 文本转图像模型（diffusers） • image_editing: 图像编辑模型 • mock_llm: 模拟推理（功能验证） • custom: 自定义评测类型	None（自动判断）
--eval-batch-size	int	评测批量大小，作用于以下阶段： • 推理阶段：并发请求数（service模式）或批量大小（checkpoint模式） • LLM-judge 评审阶段：并发线程数 • batch_calculate_metrics 阶段：每批次处理的样本数	1（service模式为8）
--eval-backend	str	评测后端 • Native: 默认后端 • OpenCompass: 大语言模型评测 • VLMEvalKit: 多模态模型评测 • RAGEval: RAG/Embedding/Reranker/CLIP评测 • ThirdParty: 特殊任务评测	Native
--eval-config	str	非Native后端的配置文件路径	-

Judge参数

LLM-as-a-Judge评测参数，使用裁判模型判断正误：

参数	类型	说明	默认值
--judge-strategy	str	裁判模型策略 • auto: 根据数据集自动决定 • llm: 总是使用裁判模型 • rule: 只使用规则判断 • llm_recall: 规则失败后使用裁判模型	auto
--judge-worker-num	int	[已废弃] 请使用 --eval-batch-size 代替，将在 v2.0.0 中移除	1
--judge-model-args	dict	裁判模型配置（JSON字符串），详见下表	-
--analysis-report	bool	是否生成分析报告（自动判断语言）	false

judge-model-args 配置项

参数	类型	说明	默认值
api_key	str	API密钥	从MODELSCOPE_SDK_TOKEN读取，默认EMPTY
api_url	str	API端点	从MODELSCOPE_API_BASE读取， 默认https://api-inference.modelscope.cn/v1/
model_id	str	模型ID	从MODELSCOPE_JUDGE_LLM读取， 默认Qwen/Qwen3-235B-A22B
system_prompt	str	系统prompt	-
prompt_template	str	Prompt模板	根据score_type自动选择
generation_config	dict	生成参数（同--generation-config）	-
model_args	dict	裁判模型加载参数（同--model-args），例如{"default_headers": {"X-API-KEY": "your-api-key"}}	{}
score_type	str	打分方式 • pattern: 判断与参考答案是否相同 • numeric: 无参考答案打分（0-1）	pattern
score_pattern	str	解析输出的正则表达式	pattern模式：(A|B) numeric模式：\[\[(\d+(?:\.\d+)?)\]\]
score_mapping	dict	pattern模式的分数映射	{'A': 1.0, 'B': 0.0}

参见

关于ModelScope模型推理服务，请参考ModelScope API推理服务

pattern 模式默认prompt模板

Your job is to look at a question, a gold target, and a predicted answer, and return a letter "A" or "B" to indicate whether the predicted answer is correct or incorrect.

[Question]
{question}

[Reference Answer]
{gold}

[Predicted Answer]
{pred}

Evaluate the model's answer based on correctness compared to the reference answer.
Grade the predicted answer of this new question as one of:
A: CORRECT
B: INCORRECT

Just return the letters "A" or "B", with no text around it.

numeric 模式默认prompt模板

Please act as an impartial judge and evaluate the quality of the response provided by an AI assistant to the user question displayed below. Your evaluation should consider factors such as the helpfulness, relevance, accuracy, depth, creativity, and level of detail of the response.

Begin your evaluation by providing a short explanation. Be as objective as possible.

After providing your explanation, you must rate the response on a scale of 0 (worst) to 1 (best) by strictly following this format: "[[rating]]", for example: "Rating: [[0.5]]"

[Question]
{question}

[Response]
{pred}

Sandbox参数

EvalScope 使用嵌套的 --sandbox 配置（对应 SandboxTaskConfig）统一管理沙箱设置。

--sandbox 配置项

参数	类型	说明	默认值
enabled	bool	是否启用沙箱	false
engine	str	沙箱引擎，可选 docker、volcengine 等	docker
default_config	dict	任务级沙箱配置，将与 BenchmarkMeta.sandbox_config 合并；同时作为 Agent 模式中每个样本环境的默认配置	{}
manager_config	dict	转发给 ms_enclave manager 构造函数的参数（如远端 docker daemon 的 base_url、volcengine 凭证等）	{}
pool_size	int | None	池化执行的预热池大小，None 时与 eval_batch_size 对齐	None

完整使用方法（含本地与远端管理器配置示例）请参考 沙箱环境使用。

Agent 参数

--agent-config / agent_config 用于启用 Agent 评测：当设置后，所有基于 DefaultDataAdapter 的基准会改用 内置 AgentLoop 进行推理，或通过 外部 Agent Bridge 转交给 Claude Code / Codex 等成品 CLI。AgentLoopAdapter 子类（如 swe_bench_*_agentic）会忽略该全局配置，改用 dataset_args.extra_params。

参数	类型	说明	默认值
--agent-config	dict | NativeAgentConfig	Agent 全局配置，详见下表	None（关闭 Agent 模式）

agent-config 配置项

字段	类型	说明	默认值
strategy	str	策略名称：function_calling / react / swe_bench_toolcall / swe_bench_backticks	function_calling
tools	list[str]	工具白名单：bash / python_exec（submit 由策略自动注入）	[]
environment	str | None	工具运行环境：local（子进程）/ docker（隔离沙箱）	None
max_steps	int	循环迭代硬上限	10
extra	dict	策略构造参数，例如 {'system_prompt': '...'}	{}
environment_extra	dict	环境构造参数。local 支持 working_dir/env_vars；docker 支持 image/timeout/environment	{}

参见

完整使用说明、用例与 Trace 可视化请参见 Agent 评测。

其他参数

参数	类型	说明	默认值
--work-dir	str	评测输出路径（详见下方目录结构）	./outputs
--no-timestamp	bool	是否不在工作目录中添加时间戳	false
--use-cache	str	复用本地缓存路径（如outputs/20241210_194434） 重用推理结果和评测结果	None
--rerun-review	bool	配合 --use-cache 使用：删除已有 reviews 缓存并重跑评测/打分阶段，但仍复用 predictions 缓存	false
--enable-progress-tracker	bool	是否开启进度追踪，将层级评测进度实时写入progress.json，可通过服务接口查询	false
--collect-perf	bool	采集每次推理请求的性能指标（延迟、TTFT、Token 用量），汇总后写入评测报告。采集 TTFT 需开启 --generation-config stream=true；使用 --no-collect-perf 可禁用	true
--seed	int	随机种子	42
--debug	bool	是否开启调试模式	false
--ignore-errors	bool	是否忽略生成过程中的错误	false
--dry-run	bool	预检参数，不执行推理，只打印参数	false

work-dir 目录结构示例

./outputs/{timestamp}/
├── configs/
│   └── task_config_b6f42c.yaml      # 任务配置
├── logs/
│   └── eval_log.log                 # 评测日志
├── predictions/
│   └── {model_id}/
│       └── {dataset}.jsonl          # 模型推理结果
├── reports/
│   └── {model_id}/
│       └── {dataset}.json           # 评测报告
├── reviews/
│   └── {model_id}/
│       └── {dataset}.jsonl          # 评测结果详情
└── progress.json                    # 进度追踪文件（启用--enable-progress-tracker时生成）

progress.json 文件格式示例：

{
  "status": "running",
  "pipeline": "eval",
  "total_count": 14042,
  "processed_count": 5200,
  "percent": 37.03,
  "stage": {
    "name": "Evaluating", "label": "mmlu",
    "current": 1, "total": 3, "status": "running",
    "children": [
      {"name": "Predicting", "label": "mmlu@test", "current": 1000, "total": 1000, "status": "completed", "children": []},
      {"name": "Reviewing",  "label": "mmlu@test", "current": 320,  "total": 1000, "status": "running",  "children": []}
    ]
  },
  "updated_at": "2026-03-09T10:05:42Z"
}