evalstone/evalscope/docs/zh/get_started/parameters.md

参数说明

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

环境变量

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

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

模型参数

参数	类型	说明	默认值
--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/float	请求超时时间（秒）	所有
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，越高越随机	所有
stop_seqs	list[str]	触发停止生成的序列列表，返回文本不包含该序列	所有
frequency_penalty	float	范围-2.0~2.0，正值惩罚重复token	OpenAI兼容
presence_penalty	float	范围-2.0~2.0，正值惩罚已出现token	OpenAI兼容
repetition_penalty	float	对已生成token施加指数惩罚，1.0 表示不惩罚	OpenAI兼容、HuggingFace、vLLM
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兼容、HuggingFace、llama-cpp-python
top_logprobs	int	返回概率最高的前N个token（范围0~20）	OpenAI兼容、HuggingFace
parallel_tool_calls	bool	工具调用是否支持并行	OpenAI、Groq
response_schema	dict	请求结构化输出（JSON Schema），仍需对输出做校验	OpenAI、Google、Mistral
reasoning_effort	str	reasoning 努力程度，原样透传给服务端（如 none / minimal / low / medium / high / xhigh / max），合法取值由具体模型和服务端决定	OpenAI兼容
reasoning_tokens	int	reasoning 最大 token 预算（thinking budget）	Anthropic Claude
reasoning_summary	str	reasoning 摘要级别，可选 concise / detailed / auto	OpenAI reasoning 系列
reasoning_history	str	多轮对话中如何编码上一轮 assistant 的 reasoning_content。可选值：reasoning_field（默认，作为独立顶层字段透传，适配 DeepSeek V4 thinking、Qwen3 thinking 等）、think_tag（编码为 <think>...</think> 塞进 content 字符串，兼容旧版 Together / Groq 等部署）、none（完全剥离，DeepSeek R1 等禁止回传 reasoning_content 的 legacy 模型必须显式设此值）	OpenAI兼容
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]	指标列表。应使用 accuracy 等规范名称；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） • text2speech: 文本转语音模型服务 • image_editing: 图像编辑模型 • mock_llm: 模拟推理（功能验证） • custom: 自定义评测类型	None（自动判断）
--eval-batch-size	int	评测批量大小，作用于以下阶段： • 推理阶段：并发请求数（远程 API 模式）或批量大小（llm_ckpt模式） • LLM-judge 评审阶段：并发线程数 • batch_calculate_metrics 阶段：每批次处理的样本数	1（openai_api、openai_responses_api、anthropic_api、litellm 等远程 API 模式为8）
--eval-backend	str	评测后端 • Native: 默认后端 • OpenCompass: 大语言模型评测 • VLMEvalKit: 多模态模型评测 • RAGEval: RAG/Embedding/Reranker/CLIP评测 • ThirdParty: 特殊任务评测	Native
--eval-config	str	非Native后端的配置文件路径	-

Judge参数

Native LLM Judge 通过一个 typed judge 对象配置：Python/YAML 使用 judge={...}，CLI 使用 --judge '<JSON object>'。

TaskConfig(
    model='MODEL',
    datasets=['simple_qa'],
    judge={
        'strategy': 'llm',
        'models': {
            'model_id': 'JUDGE_MODEL',
            'api_url': 'OPENAI_COMPATIBLE_URL',
            'api_key': 'JUDGE_API_KEY',
            'generation_config': {'temperature': 0.0, 'retries': 3},
        },
        'repeats': 1,
        'position_swap': 'auto',
        'aggregation': 'mean',
        'min_valid_judges': 1,
    },
)

models 可传单个对象或对象列表。列表表示独立 Judge；重复的 model_id 必须显式指定不同的 judge_id，唯一 model_id 默认同时作为 judge_id。

字段	类型	说明	默认值
strategy	auto|rule|llm|llm_recall	auto 遵循 benchmark 策略；llm_recall 仅复核规则漏判，并取 max(rule, judge)。	auto
models	object|list[object]	一个或多个 Judge 模型配置；为保证 review cache 可复现，必须给出 model_id。	[]
repeats	int >= 1	每个 Judge 的独立判分观测次数，不等同于 transport retry。	1
position_swap	auto|on|off	auto 保持 benchmark 官方的位置交换策略。	auto
aggregation	mean|median|majority_vote	普通指标的跨观测聚合方式。	mean
min_valid_judges	int >= 1	一个指标所需的最少有效 Judge verdict 数。	1

models 的每项支持 judge_id、model_id、api_key、api_url、eval_type、model_args 与 generation_config。provider 私有的模型初始化参数放入 model_args；transport 重试放入 generation_config.retries。

judge.contract 仅配置通用单 verdict Judge：system_prompt、prompt_template、score_mapping 和 score_type。pattern 要求 Judge 在 JSON 中返回 score_mapping 之一；numeric 要求 JSON 分数位于 [0, 1]。框架会在 prompt 中追加 JSON 格式要求，只解析一次普通模型回复；不使用 constrained decoding、 正则提分或纠正性追问。无效回复显示为 unavailable，并从指标中排除，而非记为 0。

对于经过 LLM 判定的样本，报告包含 JudgeSummary：覆盖率、失败计数与分歧。当 adapter 通过确定性的 Judge 短路直接判定样本时，得分 metadata 会记录 judge_skipped=true 和 judge_skip_reason；Web review 面板会将其标为规则直接判分，而非 LLM verdict。native 评测复用 prediction 和 review 前要求缓存的评测身份完全匹配。 设置 rerun_review=True 可复用 prediction 并重算 review，新的 review 文件只有成功后才原子替换旧文件；它也是身份 不匹配时唯一的显式覆盖开关，生成的配置会在当前评测版本下记录 prediction 来源。

旧 judge_strategy 和单个 mapping judge_model_args 仅保留一轮输入迁移并会告警。已删除的 judge_worker_num 和 score_pattern 会明确报错。

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）保留 benchmark 默认值，同时接受其支持的显式覆盖，例如策略、步数和工具。

参数	类型	说明	默认值
--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	Agent 命令执行环境，例如 local 或 docker	None
environment_extra	dict	Agent 环境构造参数；Docker 镜像放在 sandbox_config.image	{}
max_steps	int	循环迭代硬上限	10
kwargs	dict	策略构造参数，例如 {'system_prompt': '...'}	{}

完整使用说明、用例与 Trace 可视化请参见 [Agent 评测](../user_guides/agent/index.md)。

其他参数

参数	类型	说明	默认值
--work-dir	str	评测输出路径（详见下方目录结构）	./outputs
--no-timestamp	bool	是否不在工作目录中添加时间戳	false
--use-cache	str	复用本地缓存路径（如outputs/20241210_194434） 重用推理结果和评测结果	None
--rerun-review	bool	配合 --use-cache 使用：基于 predictions 缓存重跑评测/打分，并仅在成功后原子替换 reviews 缓存	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"
}