> ## 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.
# Benchmarks
> 在 Osmosis platform 上添加 benchmark、提交 benchmark run 并比较 agent
Benchmark 是一组公开的 task，自带运行环境和评分方式。Benchmark run 在这些 task 上为一个或多个 agent 打分，task environment、执行和结果采集都由平台负责，您无需自行准备任何资源。结果会汇总到 leaderboard，用于比较您在该 benchmark 上运行过的所有 agent。
## 概念
### Benchmark 与 Benchmark Run
**Benchmark** 存在于您的 workspace 中，包含 task 列表、harness 与 judge 要求以及 pass threshold。**Benchmark run** 是针对某个 task 选择的一次执行。各个 run 相互独立：需要比较 agent、task 子集或尝试次数时，提交多个 run 即可。
### Agent
**Agent** 是 harness 与 model 的组合，例如 `codex` 搭配 `openai/gpt-5.2`。一个 run 可以包含多个 agent，这是在完全相同的条件下比较 scaffold 或 model 的方式。同一 run 中的每个 agent 拿到相同的 task、相同的尝试次数和相同的评分。
### 尝试次数与 pass\@k
`attempts_per_task` 决定每个 agent 在每个 task 上可以独立尝试多少次。Pass\@1 是首次尝试的通过率，pass\@k 是 k 次尝试内解决 task 的比率。两者都带 95% 置信区间；若统计上无法与最佳 agent 区分，该 agent 会与其并列第 1，而不是被排在其后。将鼠标悬停在其排名上可查看对比详情。
### Task 选择
可以运行全部 task，也可以按命名 task set、category 或明确的 task 名称缩小范围。部分 benchmark 会公开 **parity** task set，即其参考分数所测量的样本。HLE 是需要特别注意的例子：若希望得到与公开结果可比的数字，请优先使用它的 parity set。
## 添加 benchmark
在侧边栏打开 **Benchmarks**。Osmosis 托管的 benchmark 已在您的 workspace 中；**Add Benchmark** 可按名称添加 Harbor registry 中的任意 dataset。
表格列出 workspace 可以运行的内容：
| 列 | 含义 |
| ------------ | ---------------------------------------------------------- |
| **Name** | Benchmark 名称；点击该行打开它的页面。 |
| **Last Run** | 最新 run 的状态、距今时长和名称。task 列表同步完成前，这里显示同步状态。 |
| **Tasks** | Benchmark 包含的 task 数量。task 列表同步期间为空，同步失败时显示 `unavailable`。 |
| **Added** | Benchmark 加入 workspace 的时间。 |
| **Added By** | 添加者。 |
Harbor benchmark 的 task 列表在添加之后才会从 registry 分页同步进来，同步就绪前无法提交 run。若同步失败，该行会说明原因，benchmark 页面提供 **Retry sync**。您自己添加的 benchmark 可以从页面的操作菜单中移除，托管的 benchmark 不可移除。
## Benchmark 页面
每个 benchmark 页面打开时显示它的 **Leaderboard** 和 **Benchmark Runs** 表格，**New Run** 是提交入口。页眉显示该 benchmark 的 source 引用（点击即可复制），task 列表就绪后还会显示 task 数量徽标；操作菜单提供 **View source**，同步失败后还提供 **Retry sync**。
### Leaderboard
每个参赛者一行，参赛者即 harness 与 model 的组合。每个参赛者的分数取自它**最新**的合格 run，因此重跑某个 agent 会更新它的名次，而不是新增一行。表格可按 Pass\@1、Pass\@k、Cost / task、Time / task 或 Tokens / task 排名。点击某个指标的列标题即可按它重新排序，当前排序指标会体现在 URL 中。名次按并列规则计算：并列的参赛者共享同一名次，因此名次可能跳号（如 1、1、3）。点击某一行会打开产生该分数的 run。
Agent 进入 leaderboard 的条件：
* run 已 finished，且该 agent 自身已 finished；
* run 覆盖了完整 task 列表，或 benchmark 为对比而公开的 parity set；
* 每个 task 与尝试的组合都产生了结果；
* 该 agent 有 pass\@1 分数。
所有合格参赛者都在同一份排名中，按所选指标排序。task set 与 benchmark 版本只影响并列检验：显著性只在 task set 相同且解析版本相同的参赛者之间检验，因此 parity 样本与完整运行，或不同 manifest 版本的 run，绝不会被判为并列，因为它们不是同一种测量。
按 category 或少量 task 名称过滤的 run 有意不参与排序。它仍然拥有完整的 run 页面、分数和下载。
## 提交 run
**New Run** 会打开一个带三个标签页的表单，并实时汇总即将提交的内容：
* **Tasks**：全部 task、命名 task set、category 或明确的 task 名称。
* **Agents**：每个 agent 一项，包含 harness、model，以及保存该 provider API key 的 workspace 或个人 secret record。添加更多项即可在一个 run 中比较多个 agent。
* **Run settings**：每个 task 的尝试次数、并发尝试数、超时倍数、重试次数、pass threshold，以及 benchmark 使用 LLM judge 时的 judge 设置。
API key 始终以 secret record 名称引用，绝不直接粘贴到表单中。请先在 **Secrets** 中创建这些记录；表单会标出该 benchmark 需要而 workspace 中缺失的记录。计费在提交时校验，因此计费信息无效的 workspace 会在提交时被告知，而不是被挡在表单之外。
Benchmark run 会产生 model 与 sandbox 费用，其中模型花费计入您自己的 provider key。请先提交只含一个 task 的 run，确认 agent 与 secret 可用，再运行完整 benchmark。
## 状态流转
| 状态 | 说明 |
| ------------ | ----------------------- |
| **pending** | 已提交；平台正在准备该 run。 |
| **queued** | 等待可用资源启动。 |
| **running** | Agent 正在执行 task，结果持续写入。 |
| **finished** | 全部预期结果均已产生，分数已最终确定。 |
| **failed** | Run 因错误终止。原因见 Logs 标签页。 |
| **stopped** | 有人在完成前停止了该 run。 |
## Run 页面
Run 的地址是 `/benchmarks/runs/`，侧边栏显示状态、进度、时长、已用 token、LLM cost、提交信息、锁定的 benchmark 版本及其 agent。四个标签页覆盖整个 run：
* **Overview**：**Agent Results** 是一张可排序的表格，每个 agent 一行，使用与 leaderboard 相同的指标，进度列在 run 进行期间实时显示时长。agent 的尝试次数足够时会出现 pass\@k 曲线，有已评分的 category 后会出现按 category 的分解。
* **Task Results**：覆盖每个 task 与尝试的结果表格，可搜索、可筛选，并可查看任一结果的评分输出、对话和 artifact。通过工具栏的 Agent 筛选可只看指定 agent。
* **Configuration**：解析后的 run 配置（TOML 格式），包含它锁定的 benchmark 版本。
* **Logs**：从提交到清理的生命周期事件。
**LLM Cost** 是 harness 上报的、使用您自己 provider key 产生的模型花费，不由 Osmosis 计费。
Metrics、task 级结果和每个结果的 artifact 都可从 run 页面下载。pending 或 queued 的 run 尚无可下载内容；running 的 run 下载的是当前快照。
## 停止 run
pending、queued 和 running 状态的 run 可以从 run 页面或 runs 表格中的对应行停止。平台清理完 sandbox 后，该 run 变为 `stopped`。已写入的结果会保留在该 run 上。
## 后续步骤
用 TOML config 提交并管理同样的 run。
Benchmark TOML config 参考。
针对 platform dataset 为自己的 rollout 打分。
管理 agent 引用的 secret record。