> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osmosis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Benchmark Runs

> 使用 Osmosis CLI 配置、提交、监控并下载托管 benchmark runs

Benchmark run 用于在 Platform 管理的 benchmark 上比较一个或多个 agent harness 与 model 组合。CLI 提交 Osmosis TOML config；Platform 负责 benchmark source、task environment、执行和结果采集。

<Note>
  通过 CLI 提交前，先在 Platform 中把 benchmark 添加到 workspace。`[experiment].benchmark` 解析的是 workspace 中已有的 benchmark，可填写其 key、名称或 ID，而不是本地 dataset path。
</Note>

## 查看 benchmark

先列出当前 workspace 可用的 benchmark，再查看准备运行的 benchmark：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis benchmark list
osmosis benchmark info terminal-bench-2-1
```

`benchmark info` 会显示 key 和准确名称、指向上游项目的 `source_url`（benchmark 经过适配时指向 adapter 仓库）、task 和 category 数量、命名 task set、harness 与 judge 要求、pass threshold，以及所有隐式必需的 secret record 名称，随后是该 benchmark 的 leaderboard 和 workspace 在其上的 runs。若某个 benchmark 的公开分数是在特定 harness 上测得的，该 harness 会作为默认值显示。Terminal-Bench 2.1 是 `terminus-2`，使用其他 harness 的 run 与这些分数不可比。选择 `task_names` 或 `categories` 前，可使用 JSON 输出查看完整 task manifest 和 `required_secret_names`：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis --json benchmark info terminal-bench-2-1
```

JSON manifest 中的每个 task 都包含 `difficulty`，其值为 `easy`、`medium`、`hard` 或 `null`。`null` 表示 benchmark source 未提供难度，绝不能自行推断。

对于 HLE，该命令会把 `parity` 标记为推荐的命名 task set。省略 `[tasks]` 会选择完整 benchmark。

Harbor registry benchmark 在被添加后，其 task 列表才会从 registry 分页同步进来。同步期间 Last Run 列显示同步状态和 task 进度，此时提交会失败，直到同步完成。若同步失败，`benchmark list` 会在该列说明原因，并在 Tasks 列显示 `unavailable`，JSON 输出中包含 `sync_error`；请在 Platform 的该 benchmark 页面上重试同步。返回的 `platform_url` 会打开该页面，其中包含它的 leaderboard 和 runs。

## 创建 config

复制 workspace template 并编辑：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
cp configs/benchmark/default.toml configs/benchmark/terminal-bench-smoke.toml
```

第一次运行时，选择一个 task 和一个 agent：

```toml configs/benchmark/terminal-bench-smoke.toml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
[experiment]
benchmark = "terminal-bench-2-1"

[tasks]
task_names = ["terminal-bench/git-multibranch"]

[[agents]]
harness = "codex"

[agents.model]
type = "provider"
model = "openai/gpt-5.2"
api_key_secret = "OPENAI_API_KEY"

[execution]
attempts_per_task = 1
max_concurrent_attempts = 1
timeout_multiplier = 1.0
max_retries = 0
```

Provider、endpoint、hosted model、task filter 和 execution fields 参见[配置文件](/zh/cli/config-files#benchmark-config)。

## 注册 credentials

`api_key_secret`、`harness_api_key_secret` 和 `judge_api_key_secret` 保存 Platform secret record 名称，而不是 credential value。提交前，创建 config 引用的每个 record：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis secret set OPENAI_API_KEY
```

还应创建 `benchmark info` 响应的 `required_secret_names` 中列出的每个 record：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis secret set NAME
```

这些是不会重复写入 TOML 的隐式 benchmark 要求。响应仅返回 record 名称。例如，HLE 会列出 `HF_TOKEN`。

默认使用 personal scope。需要与能够提交 run 的 workspace 成员共享 credential 时，使用 `--scope workspace`。

Cursor CLI 和 Mini SWE-agent 使用与 model 分离的 harness credential 进行认证。在对应 agent 上，Cursor CLI 把 `harness_api_key_secret` 设为 `CURSOR_API_KEY`，Mini SWE-agent 设为 `MSWEA_API_KEY`。这是各自 harness 读取的变量，填其他值会在提交时被拒绝。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis secret set CURSOR_API_KEY
osmosis secret set MSWEA_API_KEY
```

只需配置所选 harness 需要的 record。除 `cursor-cli` 和 `mini-swe-agent` 外，其他 harness 会拒绝 `harness_api_key_secret`。完整 agent 示例参见[配置文件](/zh/cli/config-files#agents-and-agentsmodel)。

HLE 和 GDPVal 使用 LLM judge，并且必须设置 `judge_api_key_secret`。将其设置为 Platform secret record 名称；`judge_model` 可选，省略时使用 benchmark 默认值。对于 HLE，创建 judge record 和 `required_secret_names` 报告的 `HF_TOKEN` record：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis secret set HLE_JUDGE_API_KEY
osmosis secret set HF_TOKEN
```

然后在 HLE config 现有的 `[execution]` table 中添加 judge record 名称：

```toml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
[execution]
judge_api_key_secret = "HLE_JUDGE_API_KEY"
# judge_model = "openai/gpt-5.2"              # Optional override
```

`HF_TOKEN` 是 benchmark runner 为所有 benchmark 保留的名称，并非只对 HLE 保留。不要将它放入顶层 `[env]` 或任何 `[agents.env]`，也不要将它用作 model 的 `api_key_secret`；对于 HLE，只能把 dataset credential 存入名为 `HF_TOKEN` 的 Platform secret record。缺少 secret 时提交会失败，并给出需要创建的 record 名称。

<Tip>
  提交 HLE 前，请在 `[tasks]` 下添加 `task_set = "parity"`。我们建议 HLE run 使用已发布的 parity set；省略 `[tasks]` 会选择完整的 HLE benchmark。
</Tip>

## 提交 run

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis benchmark submit configs/benchmark/terminal-bench-smoke.toml
```

确认预览会显示 benchmark、task selection、agent models、尝试次数、并发数和 secret scopes。检查 config 后，可使用以下命令进行非交互确认：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis --json benchmark submit configs/benchmark/terminal-bench-smoke.toml --yes
```

响应包含：

* 生成的 run `id` 和 `name`
* 初始 `status`
* 解析后的 `task_count`
* `created_at` 中的提交时间
* Platform 中 benchmark run 的 `platform_url`

## 管理 run

Run 生命周期命令位于 `benchmark runs` 之下。列出当前 workspace 的 benchmark runs，其列与 Platform 的 runs 表格相同，包含每个 run 的 agent 数量和 best pass\@1，然后使用名称或 ID 查看刚提交的 run：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis benchmark runs list
osmosis benchmark runs info <run-name>
```

`runs info` 显示该 run 的状态、进度、时长和 result totals，并按 run 页面的方式为每个 agent 打分：排名、带置信区间的 pass\@1、最深的 pass\@k，以及按 task 计的 cost、time 和 tokens。

使用 `runs logs` 查看生命周期事件和诊断失败。每页日志按时间从早到晚返回；如需查看更早的日志，将 JSON 响应中的 `next_cursor` 传回命令：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis benchmark runs logs <run-name>
osmosis --json benchmark runs logs <run-name> --cursor <next-cursor>
```

检查确认提示后，可停止 pending、queued 或 running 状态的 benchmark：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis benchmark runs stop <run-name>
```

下载 run summary 和 task-level results，或选择其他输出类型：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
# 默认：summary.csv 和 results.csv
osmosis benchmark runs download <run-name>

# 包含所有可用 export 和 result artifact
osmosis benchmark runs download <run-name> --type all

# 只下载选中的输出类型
osmosis benchmark runs download <run-name> --type summary,logs
```

下载默认使用 `.osmosis/benchmarks/` 下按 run 划分的目录，并通过跳过完整文件实现断点续传。可用类型为 `summary`、`results`、`artifacts`、`logs` 和 `all`。目录结构固定如下：

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
.osmosis/benchmarks/<run-name>/
├── summary.csv
├── results.csv
├── logs.txt
└── artifacts/<result-id>/<path>
```

Run 处于 `pending` 或 `queued` 时还没有可下载的输出。下载 `running` 状态的 run 会得到当前快照；刷新可能在文件大小不变时发生变化的文件，请传入 `--overwrite`。

也可以打开 `submit` 或 `runs info` 返回的 `platform_url`，在 Platform 中跟踪进度、比较 agents 并查看 task-level results。

## 扩大运行范围

Smoke run 启动并生成预期结果后：

1. 添加明确的 `task_names`、选择 `categories`、使用已发布的 `parity` task set，或省略 `[tasks]` 运行完整 benchmark。
2. 在 workspace 限额内提高 `max_concurrent_attempts`。
3. 添加另一个 `[[agents]]` table，比较 harness 或 model 组合。
4. 确认付费 run 前，检查新的 task 和 attempt 数量。

<Warning>
  Benchmark run 可能产生 model 和 sandbox 费用。提交完整 benchmark 前，优先运行单 task smoke run；检查 run scope 前不要传入 `--yes`。
</Warning>