Osmosis CLI 评估

使用 evaluation run 可在训练前针对 platform dataset 测试 rollout 和 grader。Evaluation config 位于 configs/eval/ 下；提交前请先 push 代码，因为平台会克隆 Git origin 标识的 workspace repository，并在服务端运行 rollout。

osmosis eval submit 也是 training run 之前推荐的 pre-flight——先运行它，在投入 GPU 训练前发现问题。

快速开始

在 workspace directory 内：

osmosis dataset list                                # 确认 platform dataset 名称
git push                                            # 确保平台能看到您的 commit
osmosis eval submit configs/eval/my-rollout.toml

然后查看或管理该 run：

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]
# 可选。省略字段表示使用平台默认值。
# 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 时，平台会对 dataset 随机抽取 10% 的样本进行评估（至少一行）。设置 limit 可评估固定行数——即 dataset 的前 N 行（按顺序）。

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

工作方式

解析 workspace 和 config

CLI 读取 evaluation TOML，根据 Git origin remote 解析 workspace，校验 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 submit <config>.toml [--yes]`	从 `configs/eval/` 下的 TOML 提交一次 evaluation run。
`osmosis eval list [--limit N] [--all]`	列出当前 workspace directory 的 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 run

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

迭代 rollout 代码

把修复 push 到 workspace repository 并重新提交。可用 branch 选择 feature branch，或用 commit_sha 在比较改动时重新运行旧版本。

提交 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

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

训练

当 evaluation 结果健康后，提交并管理 training run。

开始使用

运行

工作区

参考

快速开始

Evaluation 配置

工作方式

命令

从 Evaluation Run 到 Training Run

下载 Run 输出

本地 Rubric 评分

下一步

配置文件

Git Sync

训练

​快速开始

​Evaluation 配置

​工作方式

​命令

​从 Evaluation Run 到 Training Run

​下载 Run 输出

​本地 Rubric 评分

​下一步

配置文件

Git Sync

训练

快速开始

Evaluation 配置

工作方式

命令

从 Evaluation Run 到 Training Run

下载 Run 输出

本地 Rubric 评分

下一步