> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 选择 Benchmark

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

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

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

## 查找 Benchmark

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

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

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

## 配置 Benchmark 参数

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

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

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

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

### 共享 Benchmark 字段

所有继承 `RuntimeBenchmarkConfig` 的 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>k</code></td><td><code>int</code></td><td><code>1</code></td><td>每个选中任务的最大尝试次数，必须为正整数。<code>k=1</code> 只运行一次；<code>k>1</code> 会保存多次完整尝试，是否提前停止由 <code>avgk</code> 决定。</td></tr>
    <tr><td style={{width:'24%', whiteSpace:'nowrap'}}><code>avgk</code></td><td><code>bool</code></td><td><code>true</code></td><td>仅在 <code>k>1</code> 时生效。<code>true</code> 会完成全部 <code>k</code> 次尝试并报告 <code>avg\@k</code>；<code>false</code> 会报告 <code>pass\@k</code>，并在任务首次成功后停止后续尝试。</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>micro\_weighted</code> 对任务等权；<code>category\_mean</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>覆盖分组指标层级。除非 Benchmark 文档定义了所需对象结构，否则不要设置。</td></tr>
  </tbody>
</table>

对于使用 AgentCompass 通用二元聚合的 Benchmark，`accuracy` 始终按第 1 次尝试计算；`avg@k` 是各次尝试正确率的平均值，`pass@k` 是至少一次成功的任务比例。Benchmark 使用自定义聚合器时，以对应页面的说明为准。

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

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

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

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

### 构建 JSON 对象

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

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

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

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

```bash 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 参数。