Osmosis CLI 评估

使用 evaluation run 可针对 dataset 测试 rollout 和 grader。Evaluation config 位于 configs/eval/ 下。可通过 rollout entrypoint 构建的 backend（LocalBackend 或 Harbor）在本地运行以快速迭代，可选择发布已完成的结果，也可以通过 eval submit 使用 managed infrastructure。

Training pre-flight 仍要求由 osmosis eval submit 创建的 managed full-size run。上传的本地结果可在 Platform 上查看，但不能替代该 gate。

无法访问本机 loopback interface 的 Harbor sandbox（Daytona、SkyPilot，以及 macOS 之外的 Docker）需要一个公网 URL 才能访问本地 model bridge。osmosis eval run 会根据 rollout server 的 health 报告检测这一情况，并自动启动托管的 cloudflared quick tunnel，因此请把该 binary 保留在 PATH 中，或使用 --advertise-url 配合 --listener-port 指向您自行运行的 tunnel。

快速开始

在 workspace directory 内：

osmosis eval run configs/eval/my-rollout.toml
osmosis eval run configs/eval/my-rollout.toml --dataset-file data/my-eval.jsonl
osmosis eval run configs/eval/my-rollout.toml --upload

省略 --upload 时，--dataset-file 形式不需要 platform credentials。选择 config 中命名的 platform dataset 或通过 --upload 发布时，仍需要已认证的 Git workspace context。本地输出默认位于 .osmosis/evals/<run-name>/。之后也可以按名称或显式目录发布已完成的本地 run：

osmosis eval upload <run-name>
osmosis eval upload .osmosis/evals/<run-name>/

对于 managed run，请先 push 目标 revision，再提交：

git push
osmosis eval submit configs/eval/my-rollout.toml

如果当前位于其他目录，请显式选择 workspace，并传入绝对的标准 config 路径：

osmosis --workspace <workspace-name> eval submit /absolute/path/to/repository/configs/eval/my-rollout.toml

然后查看或管理 Platform 中可见的 runs：

osmosis eval list
osmosis eval info <name>
osmosis eval stop <name>

Evaluation 配置

完整字段参考请参见 Config Files。

configs/eval/my-rollout.toml

[experiment]
rollout = "my-rollout"                # rollouts/ 下的 rollout 目录
entrypoint = "main.py"                # 相对 rollout 目录的 entrypoint
model_path = "openai/gpt-5-mini"      # LiteLLM 风格的 evaluation policy model 名称
dataset = "my-platform-dataset"       # 来自 `osmosis dataset list` 的 platform dataset 名称
# branch = "my-feature"               # 可选：使用已 push 的分支（省略则用默认分支）
# commit_sha = "abc1234"             # 可选：固定到指定 commit

[evaluation]
# 可选。省略字段表示使用所选 execution mode 的默认值。
# limit = 200
# n = 1
# batch_size = 1
# pass_threshold = 1.0
# agent_workflow_timeout_s = 450
# grader_timeout_s = 150

# [env]
# LOG_LEVEL = "INFO"

[secrets]
# Eval config 必填。仅在不需要任何 secret 时写 required = []。
required = ["OPENAI_API_KEY"]

省略 [evaluation].limit 时，managed eval submit 会随机评估 dataset 的 10% 样本（至少一行），而本地 eval run 会评估每一行，除非用 --rows 选择明确的 subset。两种模式下，设置 limit 都会评估前 N 行。

Git Sync 是您 rollout 代码的 source of truth。CLI 会读取您传入的本地 TOML config 值，但 rollout 代码来自已同步的 workspace repository。提交代码修改前，请先 commit 并 push。设置 branch 可使用已 push 的分支，设置 commit_sha 可固定到特定已 push revision；都省略时使用默认分支。

工作方式

本地执行与上传

使用 python -m pip install "osmosis-ai[eval]>=0.3.2,<0.4" 安装 local-run dependencies。每次本地运行都需要有效的本地 workspace 和标准 eval config。使用 --dataset-file PATH 且不带 --upload 时，run 不会初始化 platform credentials；选择 platform dataset 或上传时则仍会初始化。Provider 和 workflow credentials 从 process environment 或 --secrets-file 解析，并留在您的机器上；--secrets-file 中的值仅对本次 run 生效并优先于 process environment，run 退出时会恢复原有 environment。 osmosis eval run 通过 rollout entrypoint 构建的 backend（LocalBackend 或 Harbor）执行 local workspace 文件。添加 --upload 后，仅在同一 run lock 下的完整 terminal run 结束后发布。Failed 和 skipped samples 属于 terminal 状态，可以上传；pending 和 cancelled runs 不能上传。 osmosis eval upload <run-name> 用于发布已完成且兼容的本地 run，不需要 confirmation，也没有额外 flags。仅给出 run name 时会在 workspace 的 .osmosis/evals/ 下解析，显式的相对或绝对目录则按给定路径使用。该目录必须包含兼容的 manifest.json、index.jsonl、progress.json 和 metrics.json 文件，并且命令需要已认证的 workspace context。上传是 idempotent 且以 server 为准：中断后再次运行同一命令，会返回相同的 platform run，并仅上传 server 仍缺少的文件。 Payload 包含 index.jsonl、progress.json，以及仅由所选 rollout IDs 引用的 canonical trajectory*.json 文件与 safe artifacts。CLI 会将 logs.txt 保留在本地，也不会上传本地 manifest.json bytes、events.jsonl、metrics.json、summary 或 projection copies、control files、per-trial logs 或 superseded attempts。Manifest digest、schema versions 和 allowlisted redacted Git provenance 会作为 metadata 发送。Server 会严格校验文件、重新计算 metrics，并且不会因 upload 启动 hosted 或 Temporal evaluation work。上传的结果会显示在 eval list、eval info 和 Platform viewers 中，并带有 Local badge。Dirty source tree 会显示 provenance warning。本地输出使用与 eval download 相同的 metrics.json、summary.jsonl、trajectories/ 和 artifacts/ 结构，并在 .osmosis/evals/<run-name>/ 下额外包含 durable journal、local manifest、经过 secret redaction 的 logs，以及 canonical rollout_trials/<rollout-id>/ store。省略 --name 时会创建 adjective-animal-number 名称。将该名称传回后，只会恢复没有 durable terminal result 的工作。Named run 会锁定解析后的 model、dataset、selected rows、evaluation settings、entrypoint 和 rollout source；输入变化时会拒绝恢复。使用 --fresh 可在重新开始前归档旧 run；在不改代码的情况下，使用 --retry-failed 可重试 failures 并保留 successes。如果 named run 已完成，交互式 invocation 会建议启动新的 generated-name run；非交互模式不会修改它，并会打印 next steps。 Rollout server 通过 uv 在 rollouts/<name>/pyproject.toml 解析出的环境中运行，因此请在该文件中声明 Harbor 和其他 rollout-side dependencies。首次运行会同步该环境，后续运行会复用它；当该环境的 osmosis-ai 版本与 CLI 不一致时，CLI 会打印非致命的 ROLLOUT_SDK_VERSION_MISMATCH warning。eval run 支持 LocalBackend 和所有 Harbor environment；Daytona、SkyPilot 以及 macOS 之外的 Docker 会通过上文所述的 tunnel 访问本地 model bridge；固定在 0.3.2 以下的环境无法自行请求该 tunnel，此时请传入 --tunnel cloudflared。若要针对本地 SDK checkout 开发 rollout，请在同一文件中指向它：

[tool.uv.sources]
osmosis-ai = { path = "/path/to/osmosis-sdk-python", editable = true }

经过 tunnel 时，只有 sandbox 的 OpenAI-compatible chat 流量会离开您的机器：callback 保持在 loopback 上，listener 的每个 route 都需要 bearer，controller token 与 model-bridge token 也会在每次 run 时重新生成。Tunnel 模式还会让缓慢的非 streaming model 调用在 proxy 的 idle-read timeout 之后继续存活。相关机制以及 Cloudflare 对创建 quick tunnel 的速率限制，请参见 eval run。恢复以 journal 为依据：每个 terminal 结果都会在 rollout server 的 callback 被确认之前写入并 fsync，因此被中断的 run 既不会丢失已确认的结果，也不会静默跳过未确认的工作。--fresh 会把既有目录移动到 .osmosis/evals/<run-name>.archive-<utc-timestamp>/，而不是删除它。

Managed Execution

解析 workspace 和 config

通常，CLI 会读取 evaluation TOML，并根据当前 Git origin 解析 workspace。使用 root --workspace 和绝对 config 路径时，它会改为定位 config 所在的 Osmosis Git workspace，并验证所选 platform workspace 连接到同一 repository。两种情况下，CLI 都会校验标准 config 路径，并导入配置的 rollout entrypoint，让其 backend 自行校验。该导入是 best-effort 的：当本地环境无法满足 rollout 声明的 dependencies 时会跳过并给出警告，改由平台在安装这些 dependencies 后校验 entrypoint。CLI 不会扫描 module namespace 来发现 workflow 或 grader classes。SDK entrypoint contract 及本地执行警告请参见 Rollout 中的文件。

提交到平台

CLI 提交 evaluation run 请求。平台只解析一次所选 branch 或 commit_sha，从已连接的 workspace repository 克隆该 commit，并准备 evaluation 环境。

校验模型

在评估任何行之前，平台会先做一次 pre-flight 检查，确认 [experiment].model_path 能用您配置的凭据访问。如果模型不可达——名称错误、API key 缺失或无效，或被 provider 限流——run 会提前失败，而不会浪费 evaluation 资源。请用 osmosis secret set 注册该模型的 provider API key，并把它列在 [secrets].required 中（参见 [env] 和 [secrets]）。

在服务端运行 rollout

平台启动您的 rollout，使用 [experiment].model_path 作为 evaluation policy，为选中的每一行 dataset 驱动 AgentWorkflow.run(ctx)。该行的 ground_truth 会作为 ctx.label 提供给 Grader.grade(ctx)，可选的行 metadata 会作为 ctx.metadata 提供；只要 label 或 metadata 任一存在，grader 就会运行，并可使用其中一个或两者。

汇总结果

平台聚合 rewards、pass rates 和 per-row 结果。使用 osmosis eval info <name>（或 osmosis --json eval info <name>）查看。

命令

命令	描述
`osmosis eval run <config>.toml [--upload]`	在本地执行 evaluation，并可在完成后发布；现有 run options 请参见命令参考。
`osmosis eval upload <run-name>`	按名称或 run directory 发布已完成且兼容的本地 run。
`osmosis eval submit <config>.toml [--yes]`	从 source repository 的 `configs/eval/` 下的 TOML 提交一次 evaluation run。
`osmosis eval list [--limit N] [--all]`	列出所选 workspace 的 evaluation runs。
`osmosis eval info <run-name>`	显示某次 evaluation run 的详细信息和结果。
`osmosis eval download <run-name>`	下载 run 的 metrics、trajectories、artifacts 与 logs。
`osmosis eval stop <run-name> [--yes]`	停止一次 pending 或 running 的 evaluation run。
`osmosis eval rubric`	对 JSONL conversation 文件运行本地 LLM-as-judge。不与 Osmosis 平台交互。

完整 flag 列表请参见命令参考。

从 Evaluation Run 到 Training Run

运行本地 evaluation

运行 osmosis eval run configs/eval/my-rollout.toml 进行 smoke test 与迭代。仅当已完成的结果应显示在 Platform 上时添加 --upload。

迭代 rollout 代码

针对本地文件迭代，然后将 settled revision push 到 workspace repository。使用 branch 指定 feature branch，或使用 commit_sha 固定 managed evaluation。

通过 managed evaluation gate

运行 osmosis eval submit configs/eval/my-rollout.toml 执行 full-size managed evaluation，再使用 osmosis eval list 和 osmosis eval info <name> 跟踪进度并查看结果。

提交 training run

Evaluation run 结果健康后，运行 osmosis train submit configs/training/my-rollout.toml。参见 Training。

下载 Run 输出

Run 有数据后，使用 osmosis eval download 将 metrics、trajectories、artifacts 和 logs 拉到本地，而不必去 Web UI 逐个点击下载。

# 默认：下载整个 run 的 metrics 与 trajectories
osmosis eval download my-eval-run

# 只下载指定行的 trajectories 与 artifacts
osmosis eval download my-eval-run --type trajectories,artifacts --rows 3,7,10-20

# 下载所有内容到自定义根目录
osmosis eval download my-eval-run --type all -o ./eval-outputs/

文件会落到一份固定的目录结构下，重复运行命令时可以断点续传：

.osmosis/evals/<run-name>/
├── metrics.json
├── summary.jsonl
├── trajectories/row_<row>_run_<n>.json
├── artifacts/row_<row>_run_<n>/...
└── logs.txt

本地大小与平台 manifest 一致的文件会被跳过，除非传入 --overwrite；下载总量超过 100 MiB 时需要确认，可用 --yes 跳过。失败的文件会自动重试；仍缺失的文件会被列出，重新运行命令即可继续。完整 flag 列表请参见命令参考。

osmosis eval info -o 现在同样指向该 run 输出根目录，rich 模式下的 metrics 导出会保存到 .osmosis/evals/<name>/metrics.json。.osmosis/metrics/ 下的旧文件不会被删除。

本地 Rubric 评分

osmosis eval rubric 是一个本地工具，用于通过 LLM judge 给已有的 JSONL conversation 文件打分。它不需要 workspace directory 或平台认证，也不会运行 rollout。这里的“本地”指命令的运行位置：对每条记录，CLI 会把 rubric 和被评分的 assistant 消息，以及该记录上的 original_input、ground_truth、metadata 字段发送给 --model 对应的 provider，因此在给敏感数据打分前请先确认该 provider 的隐私与数据留存条款。

osmosis eval rubric -d conversations.jsonl \
  --rubric "Evaluate the assistant's helpfulness..." \
  --model openai/gpt-5-mini

完整 flag 列表请参见命令参考。

下一步

配置文件

evaluation 和 training 配置文件的完整参考。

Git Sync

在提交 managed evaluation run 或 training run 前 push 并同步 rollout 代码。

训练

Managed full-size evaluation gate 通过后，提交并管理 training run。

开始使用

运行

工作区

参考

快速开始

Evaluation 配置

工作方式

本地执行与上传

Managed Execution

命令

从 Evaluation Run 到 Training Run

下载 Run 输出

本地 Rubric 评分

下一步

配置文件

Git Sync

训练

​快速开始

​Evaluation 配置

​工作方式

​本地执行与上传

​Managed Execution

​命令

​从 Evaluation Run 到 Training Run

​下载 Run 输出

​本地 Rubric 评分

​下一步

配置文件

Git Sync

训练

快速开始

Evaluation 配置

工作方式

本地执行与上传

Managed Execution

命令

从 Evaluation Run 到 Training Run

下载 Run 输出

本地 Rubric 评分

下一步