> ## 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.

# 指标与聚合

AgentCompass 使用同一套指标流水线处理二元、标量和混合型 Benchmark：Benchmark 声明每次尝试测量什么，运行配置决定如何执行和归约多次尝试，结果报告则为每个指标序列分别保存数值与覆盖计数。

```text theme={"system"}
attempt.metrics → Metric Contract → Attempt Strategy → Metric Reducer → 任务级数值 → Benchmark 聚合 → MetricReport
```

## 配置多次尝试

多次尝试属于执行控制，不是 Benchmark 参数。可以使用 CLI 参数，也可以在配置文件的 `execution.attempts` 下设置：

```bash theme={"system"}
agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --k 3 \
  --attempt-strategy avg
```

```yaml theme={"system"}
execution:
  attempts:
    k: 3
    strategy: avg
```

| 字段 | 默认值 | 含义 |
| - | - | - |
| `k` | `1` | 每个任务最多执行多少次相互独立的评测尝试。 |
| `strategy` | `avg` | 内置 `avg` 完整收集多次观测；内置 `pass` 在 Benchmark 的二元主指标首次成功后停止。 |

## 理解 Metric Contract

每个 Benchmark 都会声明一个 Metric Contract，为 `attempts.<N>.metrics` 中的每个键指定类型：

| 类型 | 单次尝试的值 | 支持的多次尝试 reducer |
| - | - | - |
| `binary_success` | JSON `true` 或 `false` | `avg@k` 和 `pass@k` |
| `scalar` | 有限 JSON 数字 | 仅 `avg@k` |

`binary_success` 表示由 Benchmark 明确定义的“成功 / 不成功”条件，例如验证器是否通过；不能因为某个数字字段当前恰好只出现 0 和 1，就把它当作二元成功指标。标量表示数量或程度，也可以表达部分分。

每个 Contract 必须声明且只能声明一个主指标。二元主指标统一使用 `correct`，标量主指标统一使用 `score`，这两个 ID 不能作为辅助指标；Benchmark 特有的 `reward`、`f2p` 等名称只能作为辅助指标。混合型 Benchmark 可以同时声明二元和标量观测，但执行策略始终由它固定的主指标决定。

AgentCompass 会在任务开始前检查 Contract。如果标量主指标的 Benchmark 选择 `strategy: pass`，即使 `k=1` 预检也会报错，因为普通数值分数没有“成功”语义。只有主指标为 `correct` 的 Benchmark 才能使用 `pass`。

## 确认会产生哪些指标序列

| 计划 | 执行方式 | 能够精确输出的序列 |
| - | - | - |
| `k=1` | 执行一次。 | 所有已声明指标的原生值。 |
| `k>1`、`strategy=avg` | 完成全部 `k` 次尝试。 | 所有兼容二元或标量指标的 `avg@k`，以及所有二元指标的 `pass@k`。 |
| `k>1`、`strategy=pass` | 二元主指标首次成功后停止，否则执行到第 `k` 次。 | 仅主指标的 `pass@k`。 |

`k>1` 时不再展示第 1 次尝试或 `first` 指标。二元主指标采用 `avg` 策略时，其 `avg@k` 和 `pass@k` 都属于重点结果；Contract 中的其他指标会作为辅助序列保留在完整报告中。

各 reducer 的定义如下：

* `native@1`：唯一一次有效观测的值。
* `avg@k`：恰好 `k` 个有效观测的算术平均值；二元指标中 `true` 记为 `1`，`false` 记为 `0`。
* `pass@k`：任一有效二元观测为 `true` 时立即得到 `1`；只有 `k` 个观测均有效且均为 `false` 时才能得到 `0`。

## 明确处理失败与缺失尝试

任一逻辑 attempt 最终 FATAL 使整题失效。ERROR 和 WARNING 保留 Benchmark 的有效观察；reducer 不为缺失指标补 false／0。

* `avg@k` 只有在 `k` 个观测全部有效时才有值。
* 一旦已有成功观测，`pass@k=1` 就是精确结果，即使后续尝试无需执行。
* 只有 `k` 个有效观测全部为 `false` 时，`pass@k=0` 才是精确结果。

计数包含 total、evaluated、unavailable、invalidated 和独立诊断 error；evaluated + unavailable + invalidated = total。

INVALIDATED 无有效值；ERROR 表示必需 attempt 缺失或最终 ERROR 且无法得出值；UNAVAILABLE 表示没有上述错误但观察不足。

## 执行、重试与复用

`execution.task_concurrency` 是单次运行唯一的并发上限，统计的是实际执行的 attempt（包括 retry），不会把同一任务的全部 `k` 次尝试合并成一个并发槽位。通过 `agentcompass run` 启用的内联 analysis 也共享这个上限；独立的 `agentcompass analysis` 命令按自身的 task concurrency 调度。

使用 `strategy: avg` 时，只有 Benchmark 和 Harness 都声明各次尝试的状态相互隔离，同一任务的多次尝试才可以并发；否则 AgentCompass 会串行执行它们。用户仍然只需设置一个并发参数。

复用按当前 plan 逐逻辑 attempt 判断。已解决失败保留为历史，旧次数不扣新预算；none／fresh 可通过评测快照避免重复推理。

## 聚合任务与类别

多次尝试 reducer 与 Benchmark 聚合器解决的是两个不同问题：reducer 负责合并同一任务的 `k` 次观测；得到任务级数值后，runtime 再调用 `Benchmark.aggregate_metrics()` 应用该 Benchmark 的官方跨任务定义。

派生指标计算分子、分母和权重前排除同一组失效 task ID。固定基线奖牌指标保留基线分母，已选适用题缺观察时不发布该指标。

默认 Benchmark 实现会为每个序列分别应用以下共享策略：

| 设置 | 运行级计算方式 |
| - | - |
| `micro_weighted` | 平均有效任务值，每个任务权重相同。 |
| `category_mean` | 平均有效类别均值，每个类别权重相同。 |
| 非空 `category_hierarchy` | 使用显式聚合树，并优先于 `aggregation_mode`。 |

每个类别和层级节点都会保存与总体结果相同的四种序列专属计数。缺失子节点使用 `value: null`，不会借用其他序列的计数。层级节点采用 `unweighted`、显式 `weighted` 或 `weighted_by_count` 时，只在有有效值的子节点之间重新归一化。

如果官方结果不是任务级数值的平均值，Benchmark 会覆盖默认 hook。例如，SciCode 的子问题准确率是 `正确子问题总数 / 子问题总数`，DeepResearch FACT 按已检查引用数加权引用准确率，GDPVal 使用语料总得分除以总分上限，Frontier Engineering 则根据参考表派生 medal 与 rank 结果。这些公式在选定的任务级 reducer 之后执行，因此能够同时处理 `native@1` 和完整的 `avg@k` 观测。

`metrics.json` 中的每个序列都会通过 `aggregation` 记录实际公式：共享序列使用 `micro_weighted`、`category_mean` 或 `category_hierarchy`，自定义序列可以使用 `ratio_of_sums`、`sum` 或 `benchmark`。公式输入与合计值放在 `series[].extra`，rank 对比等较大的 Benchmark 专属诊断放在报告级 `extra`；如果类别或层级公式使用的分母不是有效任务数，相应节点还会通过 `aggregation_weight` 明确记录实际权重。

## 查看输出

聚合成功后会写入两种互补文件：

| 文件 | 用途 |
| - | - |
| `summary.md` | 所有 `k` 共享任务计数与 `Metrics` 结构；`k=1` 使用原来的指标表，`k>1` 在指标区域补充尝试计划、序列角色、公式和独立计数。 |
| `metrics.json` | 规范的指标报告，包含全部重点及辅助序列、计数、类别和层级节点。 |

CLI 也会输出重点指标。工具和审计应读取 `metrics.json`，不要从 Markdown 中解析数据。单次尝试的观测见[任务结果](/zh/user_guide/other_features/results/task_results)，完整输出布局见[汇总与分析](/zh/user_guide/other_features/results/summary_analysis)。


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