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（OpenSandbox、Daytona，以及 macOS 之外的 Docker）需要一个公网 URL 才能访问本地 model bridge。
osmosis eval run 会根据 rollout server 的 health 报告检测这一情况，并自动启动托管的 cloudflared quick tunnel。请把该 binary 保留在 PATH 中，或使用 --advertise-url 配合 --listener-port 指向您自行运行的 tunnel。快速开始
在 workspace directory 内：--upload 时，--dataset-file 形式不需要 platform credentials。选择 config 中命名的 platform dataset 或通过 --upload 发布时，仍需要已认证的 Git workspace context。
本地输出默认位于 .osmosis/evals/<run-name>/。之后也可以按名称或显式目录发布已完成的本地 run：
--workspace。Run name 或目录仍指向本地文件：
Evaluation 配置
完整字段参考请参见 Config Files。configs/eval/my-rollout.toml
省略
[evaluation].limit 时，managed eval submit 会随机评估 dataset 的 10% 样本（至少一行），而本地 eval run 会评估每一行，除非用 --rows 选择明确的 subset。两种模式下，设置 limit 都会评估前 N 行。工作方式
本地执行与上传
使用python -m pip install "osmosis-ai[eval]>=0.3.10,<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，CLI 会在 run 退出时恢复原有 environment。
CLI 会将 logs.txt 中非空的已配置 [secrets] 值替换为 [REDACTED]。它还会对一组已知 provider 和 platform 环境变量中长度至少为 8 个字符的值脱敏，包括 OPENAI_API_KEY 和 OSMOSIS_TOKEN。这些环境变量中更短的值会保持不变，除非它们也是已配置的 secrets。
CLI 打印的所有内容也会将这些已知值替换为 [REDACTED]，适用于每个命令和每种输出格式，包括成功输出、warnings、错误消息及其 details，以及 OSMOSIS_DEBUG traces。CLI 还会匹配每个值去除首尾空白、JSON 转义和 Python 引号形式的写法。脱敏只针对 CLI 已知的值，不会清理你的 dataset 内容、trajectories 或 artifacts。
osmosis eval run 通过 rollout entrypoint 构建的 backend（LocalBackend 或 Harbor）执行 local workspace 文件。添加 --upload 后，仅在同一 run lock 下的完整 terminal run 结束后发布。Failed 和 skipped samples 属于 terminal 状态，可以上传；pending 和 cancelled runs 不能上传。实时 pass rate 排除 skipped samples，与最终 metrics 一致。Rollout 未返回 sample 时会释放 worker slot，不再等待 trajectory 文件。
osmosis eval upload <run-name> 用于发布已完成且兼容的本地 run，不需要 confirmation。仅给出 run name 时会在 workspace 的 .osmosis/evals/ 下解析，显式的相对或绝对目录则按给定路径使用。该目录必须包含兼容的 manifest.json、index.jsonl、progress.json 和 metrics.json 文件，并且命令需要已认证的 workspace context。上传是 idempotent 且以 server 为准：中断后再次运行同一命令，会返回相同的 platform run，跳过 server 已有的上传，从头重新流式上传中断的 archive，并重新开始失败的解压。这适用于未完成的上传。为一个已完成导入的 local run 发布另一份结果属于另一种情况，需要 --replace；参见重试失败的 Samples。
Payload 包含 index.jsonl、progress.json、合并的 logs.txt（如果存在）、dataset_rows.jsonl（如果存在），以及仅由所选 rollout IDs 引用的 canonical trajectory*.json 文件与 safe artifacts。上传的 logs.txt 会出现在 platform 上该 run 的 Logs 标签页。在计算日志 hash 之前，eval upload 会使用当前 process environment 中长度至少为 8 个字符的已知 provider 和 platform key 值再次脱敏。这无法检测任意 secret，也无法检测已不在当前 environment 中的旧凭证；发布旧日志前请先检查内容。CLI 不会上传本地 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。
SDK 0.3.10 及更高版本会将这些文件作为两个上传发送：列出每个文件路径、大小和 SHA-256 的 files.jsonl，以及 run.zip archive。CLI 会逐个 part 流式上传该 archive，不会将其写入磁盘，因此无需额外的本地磁盘空间来存放完整 archive。随后平台会解压该 archive，只有解压成功后 CLI 才会完成该 run。上传需要平台支持 archive import；没有逐文件上传的回退方式。
Evaluation Samples 标签页使用 dataset_rows.jsonl 按 prompt 和 ground truth 搜索 samples，并按 ground truth 排序，与 managed evaluations 一致。由旧版 CLI 创建的 run 上传时不包含该文件，因此只能按 sample ID 和 error 搜索。使用 0.3.8 或更早版本创建的 run 无法在 0.3.9 中仅通过恢复来补充该文件。请原样保留或上传已完成的结果，或者开始新的 run；参见 Source digest upgrades。
上传的结果会显示在 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。
eval run 还会在分发任何工作之前写入 dataset_rows.jsonl。该文件按 dataset 顺序为每个 selected row 写入一行 JSON：
row_index是该行在 selected rows 中的位置，与index.jsonl使用的 index 相同。除非传入--rows，否则它与 dataset 文件中的 offset 一致。prompt是该行的非 system message 文本，截断至 2,000 个字符。没有 prompt 的行改用按键排序的metadataJSON。label是该行的 ground truth，截断至 500 个字符。没有 ground truth 的行会省略该字段。
--retry-failed 以及重新运行已完成的 run 都会写入完全相同的字节。
每行 index.jsonl 都会记录该 rollout 的 token 用量：
tokens是该 rollout 中所有 model call 的总和。max_context_tokens是单次最大的 model call，计算其 prompt 与 completion tokens 之和。可用它为训练确定 model 的 context window 大小。总 tokens 会高估所需窗口，而单次调用的平均值会低估它。
eval run 从 model bridge 的逐次调用 usage 中读取这两个值，并保存在 journal 中，因此恢复的 run 会保留它们。如果 bridge 没有看到 usage，这些值会改为取自 rollout 的 trajectory metrics。两个来源都没有报告 usage 时，会省略该字段。eval upload 会原样发送 index.jsonl，platform 会将 max_context_tokens 显示为该 run 的 Context Length 列和 Context Length Distribution。
省略 --name 时会创建 adjective-animal-number 名称。将该名称传回后，只会恢复没有 durable terminal result 的工作。Named run 会锁定解析后的 model、dataset、selected rows、evaluation settings、entrypoint 和 rollout source；输入变化时会拒绝恢复。使用 --fresh 可在重新开始前归档旧 run；在不改代码的情况下，使用 --retry-failed 可重试 failures 并保留 successes；参见重试失败的 Samples。如果 named run 已完成，交互式 invocation 会建议启动新的 generated-name run；非交互模式不会修改它，并会打印 next steps。
Rollout server 通过 uv 在 rollouts/<name>/pyproject.toml 解析出的环境中运行，因此请在该文件中声明 Harbor 和其他 rollout-side dependencies。首次运行会同步该环境，后续运行会复用它。请在这两个环境中都使用 osmosis-ai>=0.3.10,<0.4：本地 eval 使用 0.3.3 引入的长轮询协议，与先前的 callback 协议不兼容。ROLLOUT_SDK_VERSION_MISMATCH warning 只表示已安装版本不同，并不保证兼容。eval run 支持 LocalBackend 和所有 Harbor environment，并使用 entrypoint 的 environment_config。无法访问 host loopback 的 sandbox 会使用上文所述的 tunnel。环境选择请参见Managed 与 Self-Hosted Environments。
若要针对本地 SDK checkout 开发 rollout，请在同一文件中指向它：
eval run。
恢复以 journal 为依据：通过长轮询返回的 terminal 结果会写入并执行 fsync，然后才计入已完成的本地工作。中断后，没有持久 terminal 记录的工作仍处于 pending 状态，可以再次运行。SDK 0.3.3 在恢复所用的输入中记录 rollout protocol 0.4，因此先前 callback 协议的本地 run 无法恢复。请使用新名称或 --fresh；后者会将既有目录移动到 .osmosis/evals/<run-name>.archive-<utc-timestamp>/，而不是删除它。参见 0.3.3 迁移指南。
Source digest upgrades
SDK0.3.9 及更高版本使用新格式计算 rollout source digest。Source digest 是命名 run 所锁定的 rollout 文件指纹。升级后，即使 rollout 文件没有变化，该指纹也会改变。因此，使用 0.3.8 或更早版本创建的命名 run 在恢复和使用 --retry-failed 时都会被拒绝，并显示 Changed: rollout。
升级前，请使用创建这些 run 的 SDK 版本完成被中断的 run。升级后，可以通过以下任一方式重新开始：
- 选择新的 run 名称。
- 传入
--fresh，在同一名称下归档先前目录并开始新的 run。
osmosis eval upload 上传。请勿手动修改 manifest.json 中的 source digest，因为 manifest 字节也绑定了平台导入身份。Harbor bundle cache 会在升级后重建一次。
按一次 Ctrl-C 可取消正在执行的工作，并等待 workflow 和 sandbox 清理。再次按 Ctrl-C 会跳过较长的清理等待，给 rollout server 五秒退出时间，之后强制停止。CLI 仍会停止 tunnel 和 listener，但 sandbox 清理可能尚未完成。使用相同的 --name 重新运行，可恢复没有持久 terminal 结果的工作。
Managed Execution
1
解析 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 中的文件。2
提交到平台
CLI 提交 evaluation run 请求。平台只解析一次所选
branch 或 commit_sha，从已连接的 workspace repository 克隆该 commit，并准备 evaluation 环境。3
校验模型
在评估任何行之前，平台会先做一次 pre-flight 检查，确认
[experiment].model_path 能用您配置的凭据访问。如果模型不可达——名称错误、API key 缺失或无效，或被 provider 限流——run 会提前失败，而不会浪费 evaluation 资源。请用 osmosis secret set 注册该模型的 provider API key，并把它列在 [secrets].required 中（参见 [env] 和 [secrets]）。4
在服务端运行 rollout
平台启动您的 rollout，使用
[experiment].model_path 作为 evaluation policy，为选中的每一行 dataset 驱动 AgentWorkflow.run(ctx)。该行的 ground_truth 会作为 ctx.label 提供给 Grader.grade(ctx)，可选的行 metadata 会作为 ctx.metadata 提供；只要 label 或 metadata 任一存在，grader 就会运行，并可使用其中一个或两者。5
汇总结果
平台聚合 rewards、pass rates 和 per-row 结果。使用
osmosis eval info <name>（或 osmosis --json eval info <name>）查看。Inference 参数
在osmosis eval run 期间，您的 rollout 可以通过本地 model bridge 发送 provider 专属的 inference 选项，例如 OpenRouter 的 reasoning 和 provider 设置，或 Anthropic 的 thinking。以下规则适用于本地 evaluation；托管 run 的支持情况还取决于已部署的 model endpoint。
- 自定义 inference 字段会被转发。 没有 inference 参数 allowlist；下文所述的 bridge 控制字段仍会被阻止。可以把字段放在 chat request 顶层，或放在客户端的
extra_body中；冲突时以extra_body的值为准。OpenAI Python 客户端会把extra_body浅合并到 request 顶层，因此extra_body中的嵌套对象（例如metadata）会替换顶层的同名对象，而不是与其合并。 - OpenRouter 和 OpenAI-compatible endpoints 以 request JSON 接收字段。 无论 LiteLLM 的 model catalog 是否列出这些字段，都会转发。
- 原生 providers 使用 LiteLLM 转换，且不会丢弃参数。 不受支持的标准参数会报错，而不是被静默移除。转换遵循 LiteLLM 与 provider 的语义，不是逐字节透传。例如，Anthropic metadata 只接受
user_id，而 OpenAI、Azure 和 Anthropic 之外的原生 providers 会拒绝metadata。 - Provider 拒绝会以错误形式返回。 Provider 的 4xx 响应会带着脱敏后的详情返回给您的 rollout。Bridge 不会移除参数后重试。
[experiment].model_path 是 OpenRouter model 时，rollout 中的 OpenAI-compatible 客户端可以请求低 reasoning effort 并按延迟路由：
model 名称仅为占位符。Bridge 还负责 endpoint、credentials 和上游传输。包含传输或运行时控制字段的 request 会被拒绝，错误信息会列出被阻止的字段。被阻止的字段包括 LiteLLM 路由、认证、timeout 与 retry 设置，base_url、extra_headers、callbacks、mock 控制，会替换配置的 model、用量统计或 prompt 的字段（例如 OpenRouter 的 models、preset 和 usage，以及 system 和 prompt），以及带有保留前缀的字段，例如 _、litellm_、aws_、azure_ 和 vertex_。Bridge 每个 request 只返回一个 completion，因此 n 必须省略或为 1。
CLI 与每个 rollout 环境分别安装 SDK。请在 CLI 环境和
rollouts/<name>/pyproject.toml 中都使用 osmosis-ai>=0.3.10,<0.4，并保留所需 extras，才能端到端获得这些修复。命令
完整 flag 列表请参见 命令参考。
重试失败的 Samples
托管eval retry 和本地上传的 --replace 需要 CLI 0.3.4 或更高版本。
每次 attempt 中，sample 会被归类为 success、failed 或 skipped，其中 skipped 在不同来源下含义不同：managed run 在 attempt 超时且没有 grade 时记为 skipped，而 local run 则是在 grader 成功执行并设置 remove_sample 排除该行时记为 skipped。重试会重新运行 skipped 和 failed 的行，并保留所有 success，因此只产生一份结果，无需对账两个 run，并且只有重新运行的 samples 会消耗算力。已评分的 sample 永远不会被重跑，即使其 reward 低于 pass threshold。
Managed run 原地重试：
--secrets-file、环境变量或交互式提示中解析，详情页则会在 Retry 对话框中请求输入。
Local run 在产生它的机器上重试，然后重新发布：
osmosis eval retry 会打印同一条命令而不是发起重试，因为本地重试需要该 run 所属的 workspace。
使用 root --workspace 时（例如 osmosis --workspace <workspace-name> eval retry <run-name>），CLI 会改为打印两条命令。第一条在本地重新运行失败的 samples。只有它成功后，第二条才会把结果发布到所选 workspace，即使 source repository 连接的是另一个 workspace：
--retry-failed 会重新派发 journal 中 failed 和 skipped 的 work items 并保留 successes，--upload 则原地替换该 run 已发布的结果。Platform run 会保留其 ID 和 URL；其 manifest digest 仍必须匹配，这正是两次 attempt 评估了相同已解析输入的证明。若要在之后用单独的命令发布重试后的 run，请使用 osmosis eval upload <run-name> --replace。
从 Evaluation Run 到 Training Run
1
运行本地 evaluation
运行
osmosis eval run configs/eval/my-rollout.toml 进行 smoke test 与迭代。仅当已完成的结果应显示在 Platform 上时添加 --upload。2
迭代 rollout 代码
针对本地文件迭代，然后将 settled revision push 到 workspace repository。使用
branch 指定 feature branch，或使用 commit_sha 固定 managed evaluation。3
通过 managed evaluation gate
运行
osmosis eval submit configs/eval/my-rollout.toml 执行 full-size managed evaluation，再使用 osmosis eval list 和 osmosis eval info <name> 跟踪进度并查看结果。4
提交 training run
Evaluation run 结果健康后，运行
osmosis train submit configs/training/my-rollout.toml。参见 Training。下载 Run 输出
Run 有数据后，使用osmosis eval download 将 metrics、trajectories、artifacts 和 logs 拉到本地，而不必去 Web UI 逐个点击下载。
--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 的隐私与数据留存条款。
下一步
配置文件
evaluation 和 training 配置文件的完整参考。
Git Sync
在提交 managed evaluation run 或 training run 前 push 并同步 rollout 代码。
训练
Managed full-size evaluation gate 通过后，提交并管理 training run。