> ## Documentation Index
> Fetch the complete documentation index at: https://opencompass-docs-preview-pr-335-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 选择 Benchmark

选择已注册的 Benchmark，并配置其完整参数结构。

Benchmark 定义评测内容。每个 Benchmark 负责自己的数据集、稳定任务 ID、任务准备、评分逻辑和聚合指标。将 Benchmark 作为 `agentcompass run` 的第一个位置参数：

```bash wrap theme={"system"}
agentcompass run <benchmark> <harness> "$MODEL_NAME"
```

## 查找 Benchmark

运行以下命令，查看当前安装的 AgentCompass 版本实际提供的 Benchmark：

```bash wrap theme={"system"}
agentcompass list benchmark
```

侧边栏提供已有独立文档的 Benchmark 入口，可查看任务、参数、兼容性和运行方式。

## 配置 Benchmark 参数

[运行参数参考](/zh/user_guide/using_agentcompass/cli/run#参数参考)介绍了 `--benchmark-params <json>`。其中 `<json>` 是一个 JSON 对象，包含所选 Benchmark 的完整参数覆盖：

```bash wrap theme={"system"}
agentcompass run \
  <benchmark> \
  <harness> \
  "$MODEL_NAME" \
  --benchmark-params '{
    "sample_ids": ["<task-id>"],
    "<benchmark-specific-field>": "<value>"
  }'
```

允许的对象由两套结构组合而成：

```text theme={"system"}
benchmark params
  ├─ RuntimeBenchmarkConfig 提供的共享字段
  └─ 所选 Benchmark config 定义的字段
```

### 共享 Benchmark 字段

所有继承 `RuntimeBenchmarkConfig` 的 Benchmark 配置都支持以下面向用户的字段。表中列出基类默认值，所选 Benchmark 可以覆盖这些值。

<table style={{width:'100%', tableLayout:'fixed'}}>
  <thead>
    <tr><th style={{width:'24%', whiteSpace:'nowrap'}}>字段</th><th style={{width:'25%'}}>类型</th><th style={{width:'18%'}}>基类默认值</th><th style={{width:'33%'}}>含义与调整场景</th></tr>
  </thead>

  <tbody>
    <tr><td style={{width:'24%', whiteSpace:'nowrap'}}><code>sample\_ids</code></td><td><code>list\[str] | null</code></td><td><code>null</code></td><td>仅运行列出的稳定任务 ID。适用于冒烟测试、失败任务重跑或受控子集；未知 ID 会在执行前报错。</td></tr>
    <tr><td style={{width:'24%', whiteSpace:'nowrap'}}><code>aggregation\_mode</code></td><td><code>"micro\_weighted" | "category\_mean"</code></td><td><code>"micro\_weighted"</code></td><td>未设置 <code>category\_hierarchy</code> 时，选择通用指标如何合并任务和类别。</td></tr>
    <tr><td style={{width:'24%', whiteSpace:'nowrap'}}><code>category\_hierarchy</code></td><td><code>object | null</code></td><td><code>null</code></td><td>使用显式类别聚合树，并优先于 <code>aggregation\_mode</code>。除非 Benchmark 文档已经定义，否则不要设置。</td></tr>
  </tbody>
</table>

多次尝试应在 <code>execution.attempts</code> 下配置，不属于该对象。尝试计划、Metric Contract，以及上述聚合字段如何合并任务结果，见[指标与聚合](/zh/user_guide/other_features/results/metrics_aggregation)。

model ID 不属于该 JSON 对象。它仍是 `agentcompass run` 的第三个位置参数，由 runtime 注入 Benchmark 配置。

每个 Benchmark 还会在共享结构上增加自己的字段。无论所选 Benchmark 是否有独立页面，都可以直接从当前安装代码查询其完整字段、类型、默认值和描述：

```bash wrap theme={"system"}
agentcompass config docs benchmark <benchmark-id>
```

如果有对应 Benchmark 页面，合法取值、推荐设置、所需凭证以及字段间关系以该页面为准。

### 构建 JSON 对象

例如，`swebench_verified` 将共享的任务选择和聚合字段，与自身的准备及评测器字段组合：

```json wrap theme={"system"}
{
  "sample_ids": ["astropy__astropy-12907"],
  "prepare_mode": "prebaked",
  "workspace_root": "/testbed",
  "eval_timeout": 1800
}
```

这个展开后的对象用于展示字段归属，并不建议在每个命令中重复默认值。只传递需要与所选 Benchmark 实际配置不同的字段。

`--benchmark-params` 必须是合法 JSON，因此键和字符串值都使用双引号。CLI 值会覆盖配置文件 `benchmark.params` 中的同名键。添加最终 CLI 覆盖前，可先检查内置值和配置文件合并后的结果：

```bash wrap theme={"system"}
agentcompass config show \
  --benchmark <benchmark-id> \
  --config <config-file>
```

## 镜像与 provider 设置

重量级 Benchmark 通常会把任务镜像、工作区根目录和资源提示附加到任务元数据。兼容的 [Recipe](/zh/user_guide/other_features/recipes) 会将这些要求转换给 Docker、Daytona 或 Modal。provider 镜像、资源和网络覆盖应放在 `--env-params` 中，它们不是 Benchmark 参数。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.