选择 Benchmark

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

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

agentcompass run <benchmark> <harness> "$MODEL_NAME"

​

查找 Benchmark

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

agentcompass list benchmark

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

​

配置 Benchmark 参数

运行参数参考介绍了 --benchmark-params <json>。其中 <json> 是一个 JSON 对象，包含所选 Benchmark 的完整参数覆盖：

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

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

benchmark params
  ├─ RuntimeBenchmarkConfig 提供的共享字段
  └─ 所选 Benchmark config 定义的字段

​

共享 Benchmark 字段

所有继承 RuntimeBenchmarkConfig 的 Benchmark 配置都支持以下面向用户的字段：

字段	类型	默认值	含义与调整场景
sample_ids	list[str] | null	null	仅运行列出的稳定任务 ID。适用于冒烟测试、失败任务重跑或受控子集；未知 ID 会在执行前报错。
k	int	1	每个选中任务的最大尝试次数，必须为正整数。k=1 只运行一次；k>1 会保存多次完整尝试，是否提前停止由 avgk 决定。
avgk	bool	true	仅在 k>1 时生效。true 会完成全部 k 次尝试并报告 avg@k；false 会报告 pass@k，并在任务首次成功后停止后续尝试。
aggregation_mode	”micro_weighted” | “category_mean"	"micro_weighted”	micro_weighted 对任务等权；category_mean 对类别级结果等权。应与官方指标定义一致。
category_hierarchy	object | null	null	覆盖分组指标层级。除非 Benchmark 文档定义了所需对象结构，否则不要设置。

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

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

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

agentcompass config docs benchmark <benchmark-id>

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

​

构建 JSON 对象

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

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

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

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

agentcompass config show \
  --benchmark <benchmark-id> \
  --config <config-file>

​

镜像与 provider 设置

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