322 lines
18 KiB
Markdown
322 lines
18 KiB
Markdown
# 参数说明
|
||
|
||
执行 `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` | 被评测的模型名称<br>• ModelScope模型ID（如`Qwen/Qwen2.5-0.5B-Instruct`）<br>• 本地模型路径（如`/path/to/model`）<br>• API服务的模型ID（如`Qwen2.5-0.5B-Instruct`） | - |
|
||
| `--model-id` | `str` | 模型别名，用于报告展示 | `model`的最后一部分 |
|
||
| `--api-url` | `str` | 模型API端点，支持OpenAI兼容格式和OpenAI Responses API根路径<br>示例：`http://127.0.0.1:8000/v1` 或 `https://api.openai.com/v1` | `None` |
|
||
| `--api-key` | `str` | 模型API端点密钥 | `EMPTY` |
|
||
| `--model-args` | `str` | 模型加载参数，逗号分隔的`key=value`或JSON字符串<br>• `revision`: 模型版本<br>• `precision`: 模型精度<br>• `device_map`: 设备分配 | `revision=master`<br>`precision=torch.float16`<br>`device_map=auto` |
|
||
| `--model-task` | `str` | 模型任务类型 | `text_generation`<br>（可选：`image_generation`） |
|
||
| `--chat-template` | `str` | 模型推理模板，支持Jinja模板字符串（仅本地推理支持该参数） | `None`（使用transformers默认） |
|
||
|
||
**示例：**
|
||
```bash
|
||
# 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）<br>示例：`"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 努力程度，可选 `low` / `medium`（默认）/ `high` | OpenAI o1 系列 |
|
||
| `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` | 图像生成模型专用，指导尺度 | 图像生成模型 |
|
||
|
||
**示例：**
|
||
```bash
|
||
# 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]` | 数据集名称列表，空格分隔<br>参考[数据集列表](./supported_dataset/llm.md) | - |
|
||
| `--dataset-dir` | `str` | 数据集下载路径 | `~/.cache/modelscope/datasets` |
|
||
| `--dataset-hub` | `str` | 数据集下载源 | `modelscope`<br>（可选：`huggingface`） |
|
||
| `--limit` | `int`/`float` | 每个数据集最大评测数据量<br>• int：评测前N条数据<br>• float：评测前N%数据<br>示例：`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`）。<br>• `pass_at_k`：同一样例生成k次至少一次通过的概率（如`humaneval`设`repeats=5`）<br>• `vote_at_k`：对同一样例k次结果投票后计分<br>• `pass_hat_k`：同一样例k次全部通过的概率（如`tau2_bench`设`repeats=3`） |
|
||
| `filters` | `dict` | 输出过滤器<br>• `remove_until`: 过滤指定字符串之前的内容<br>• `extract`: 提取正则匹配的内容 |
|
||
| `force_redownload` | `bool` | 是否强制重新下载数据集 |
|
||
| `extra_params` | `dict` | 数据集相关的**额外参数**，具体参考[各数据集说明](./supported_dataset/index.md)，指定`{<param_name>:<value>}`即可, `value`的类型(`type`)和选择范围(`choices`)根据具体参数而定。SWE-bench agentic 等基准的扩展参数请参见 [Agent 评测](../user_guides/agent/native.md#swe-bench-agentic-基准) |
|
||
| `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': {}}` |
|
||
|
||
**示例：**
|
||
```bash
|
||
--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` | 评测类型<br>• `llm_ckpt`: 本地模型推理（transformers）<br>• `openai_api`: OpenAI兼容Chat Completions API服务<br>• `openai_responses_api`: OpenAI官方Responses API服务<br>• `anthropic_api`: Anthropic Claude API服务<br>• `litellm`: LiteLLM多厂商路由（支持100+ LLM服务商）<br>• `text2image`: 文本转图像模型（diffusers）<br>• `text2speech`: 文本转语音模型服务<br>• `image_editing`: 图像编辑模型<br>• `mock_llm`: 模拟推理（功能验证）<br>• `custom`: 自定义评测类型 | `None`（自动判断） |
|
||
| `--eval-batch-size` | `int` | 评测批量大小，作用于以下阶段：<br>• 推理阶段：并发请求数（service模式）或批量大小（checkpoint模式）<br>• LLM-judge 评审阶段：并发线程数<br>• batch_calculate_metrics 阶段：每批次处理的样本数 | `1`（service模式为`8`） |
|
||
| `--eval-backend` | `str` | 评测后端<br>• `Native`: 默认后端<br>• `OpenCompass`: 大语言模型评测<br>• `VLMEvalKit`: 多模态模型评测<br>• `RAGEval`: RAG/Embedding/Reranker/CLIP评测<br>• `ThirdParty`: 特殊任务评测 | `Native` |
|
||
| `--eval-config` | `str` | 非Native后端的配置文件路径 | - |
|
||
|
||
## Judge参数
|
||
|
||
LLM-as-a-Judge评测参数，使用裁判模型判断正误：
|
||
|
||
| 参数 | 类型 | 说明 | 默认值 |
|
||
|------|------|------|--------|
|
||
| `--judge-strategy` | `str` | 裁判模型策略<br>• `auto`: 根据数据集自动决定<br>• `llm`: 总是使用裁判模型<br>• `rule`: 只使用规则判断<br>• `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`读取，<br>默认`https://api-inference.modelscope.cn/v1/` |
|
||
| `model_id` | `str` | 模型ID | 从`MODELSCOPE_JUDGE_LLM`读取，<br>默认`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` | 打分方式<br>• `pattern`: 判断与参考答案是否相同<br>• `numeric`: 无参考答案打分（0-1） | `pattern` |
|
||
| `score_pattern` | `str` | 解析输出的正则表达式 | `pattern`模式：`(A\|B)`<br>`numeric`模式：`\[\[(\d+(?:\.\d+)?)\]\]` |
|
||
| `score_mapping` | `dict` | `pattern`模式的分数映射 | `{'A': 1.0, 'B': 0.0}` |
|
||
|
||
```{seealso}
|
||
关于ModelScope模型推理服务，请参考[ModelScope API推理服务](https://modelscope.cn/docs/model-service/API-Inference/intro)
|
||
```
|
||
|
||
<details><summary>pattern 模式默认prompt模板</summary>
|
||
|
||
```text
|
||
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.
|
||
```
|
||
</details>
|
||
|
||
<details><summary>numeric 模式默认prompt模板</summary>
|
||
|
||
```text
|
||
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}
|
||
```
|
||
</details>
|
||
|
||
## 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` |
|
||
|
||
完整使用方法（含本地与远端管理器配置示例）请参考 [沙箱环境使用](../user_guides/sandbox.md)。
|
||
|
||
## Agent 参数
|
||
|
||
`--agent-config` / `agent_config` 用于启用 [Agent 评测](../user_guides/agent/index.md)：当设置后，所有基于 `DefaultDataAdapter` 的基准会改用 [内置 AgentLoop](../user_guides/agent/native.md) 进行推理，或通过 [外部 Agent Bridge](../user_guides/agent/bridge.md) 转交给 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` | `{}` |
|
||
|
||
```{seealso}
|
||
完整使用说明、用例与 Trace 可视化请参见 [Agent 评测](../user_guides/agent/index.md)。
|
||
```
|
||
|
||
## 其他参数
|
||
|
||
| 参数 | 类型 | 说明 | 默认值 |
|
||
|------|------|------|--------|
|
||
| `--work-dir` | `str` | 评测输出路径（详见下方目录结构） | `./outputs` |
|
||
| `--no-timestamp` | `bool` | 是否不在工作目录中添加时间戳 | `false` |
|
||
| `--use-cache` | `str` | 复用本地缓存路径（如`outputs/20241210_194434`）<br>重用推理结果和评测结果 | `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 目录结构示例
|
||
|
||
```text
|
||
./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` 文件格式示例：
|
||
|
||
```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"
|
||
}
|
||
```
|