SDK v0.2 → v0.3 迁移指南

Osmosis SDK v0.3 变更了 rollout contract、optional-feature imports 与 extras、workflow return value、Harbor execution、dataset schema 和 run-secret submission。即使 rollout 只使用其中一部分，也应同时完成这些方面的升级。

请同时升级 package requirement、workflow、grader、integrations 和 backend entrypoint。混用 v0.2 rollout 代码与 v0.3 backend 通常会在 runtime 失败。

请选择与当前 backend 对应的迁移路径：

当前 backend	迁移路径
`LocalBackend`	保留 constructor，然后更新共享的 sample、reward、integration 和 routing API
Pre-v0.3 `HarborBackend`	先完成共享 API 变更，再替换 backend constructor 和 container execution model
`HarborBackendV2`	完成共享 API 变更并改名为 `HarborBackend`；它的 v2 constructor 就是 v0.3 constructor

修改代码前：

保留最近一次成功的 v0.2 evaluation run，以便对比。
使用 Python 3.12 或更高版本。
修改 SDK requirement 后，重新创建 rollout environment 和 lockfile。
迁移前后都搜索一次已移除的 API。

LocalBackend 用户

LocalBackend 在 v0.3 中保留相同的 keyword-only constructor：

from osmosis_ai.rollout import LocalBackend

backend = LocalBackend(
    workflow=MyWorkflow,
    workflow_config=my_workflow_config,
    grader=MyGrader,
    grader_config=my_grader_config,
)

迁移工作集中在 workflow、grader、integrations，以及 backend 周围的自定义 protocol 代码。

1. 升级 Package 并选择功能

基础 distribution 包含 CLI 和 framework-neutral rollout core。只添加 rollout 实际 import 的 extras：

pip install --upgrade "osmosis-ai[strands]>=0.3.0,<0.4"

pip install --upgrade "osmosis-ai[openai-agents]>=0.3.0,<0.4"

pip install --upgrade "osmosis-ai[server]>=0.3.0,<0.4"

pip install --upgrade "osmosis-ai[full]>=0.3.0,<0.4"

需要时可以组合 extras。例如，使用 Strands 的 server entrypoint 应声明：

[project]
dependencies = [
    "osmosis-ai[server,strands]>=0.3.0,<0.4",
]

其他 extras 包括 openai-agents、harbor、rubric 和 parquet。验证 Parquet dataset 时，请用 parquet 替换以前的 platform extra。对于 source checkout，请使用仓库的 dev dependency group，而不是 published dev extra。

2. 更新 Public Import 和 Workflow Return

Rollout package root 现在只导出 framework-neutral core types。请从对应的 public submodule import 每项 optional feature：

from osmosis_ai.rollout.integrations.agents.strands import (
    OsmosisRolloutModel,
    OsmosisStrandsAgent,
)

from osmosis_ai.rollout.integrations.agents.openai_agents import (
    OsmosisAgent,
    OsmosisMemorySession,
    OsmosisRolloutModel,
)

from osmosis_ai.rollout.server import create_rollout_server

from osmosis_ai.eval.rubric import evaluate_rubric

请按照 HarborBackend 用户中的示例从 osmosis_ai.rollout.backend.harbor import HarborBackend。不要再依赖 from osmosis_ai import *，也不要使用以前由 osmosis_ai.rollout re-export 的 optional name。 AgentWorkflow.run() 现在返回一个 message history，而不是 samples mapping。可以返回 AgentWorkflowOutput、返回由 SDK 包装为 messages 的 bare message list，或返回 None 以使用 active RolloutContext 收集的 sample：

from osmosis_ai.rollout import AgentWorkflow, AgentWorkflowContext, AgentWorkflowOutput


class MyWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> AgentWorkflowOutput:
        messages = await run_agent(ctx.prompt)
        return AgentWorkflowOutput(
            messages=messages,
            metrics={"latency_seconds": 1.25},
        )

metrics 中的每个 value 都必须是有限值；NaN、正无穷和负无穷都会被拒绝。只有当 integration 或 custom source 已为该 execution 注册 ambient sample 时，才应返回 None。

3. 从多个 Sample 改为一个 Sample

每次 workflow execution 现在最多生成一个 RolloutSample，grader 为它分配一个标量 reward。

v0.2	v0.3	操作
`GraderContext.samples`	`GraderContext.sample`	读取并评分单个 sample
`ctx.set_sample_reward(sample_id, reward)`	`ctx.set_reward(reward)`	移除 sample ID 参数
`register_sample_source(name, source)`	`set_sample_source(source)`	只注册一个 source
`get_samples()`	`get_sample()`	返回一个 `RolloutSample` 或 `None`
`RolloutSample.id`	已移除	使用 execution URL 提供的 rollout identity
`MultiTurnMode`	已移除	在单个 sample 中保留 conversation history
多个已注册 agent 或 session	一个已注册 agent 或 session	把独立 candidates 拆分为不同的 workflow executions

将遍历 samples 的 grader 改为显式检查一个 sample：

class ExactMatchGrader(Grader):
    async def grade(self, ctx: GraderContext) -> None:
        for sample_id, sample in ctx.samples.items():
            answer = last_text(sample)
            reward = 1.0 if answer == ctx.label else 0.0
            ctx.set_sample_reward(sample_id, reward)

class ExactMatchGrader(Grader):
    async def grade(self, ctx: GraderContext) -> None:
        if ctx.sample is None:
            raise ValueError("workflow produced no sample")
        answer = last_text(ctx.sample)
        reward = 1.0 if answer == ctx.label else 0.0
        ctx.set_reward(reward)

Workflow 没有生成 sample 时，set_reward() 会抛出 ValueError。在评分前显式抛出错误，通常能提供更清晰的 evaluation failure。

4. 每次 Execution 只注册一个 Agent 或 Session

在 AgentWorkflow.run() 内只构造一个已注册的 OsmosisStrandsAgent 或 OsmosisMemorySession。第二次 registration 会抛出 ValueError。对于 OpenAI Agents，v0.3 session 不再接收 name 或 sample-ID 参数：

class OpenAIWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> None:
        agent = OsmosisAgent(
            name="assistant",
            instructions="Answer the user's request clearly.",
            model=OsmosisRolloutModel(),
        )
        session = OsmosisMemorySession()
        await Runner.run(agent, ctx.prompt, session=session)

Handoff 和 tool call 可以继续保留在这一次 agent run 中。如果一个 prompt 需要多个 candidate answers，请配置 evaluation 或 training 多次执行 workflow。

5. 更新自定义 Sample Source

内置 integrations 已使用 v0.3 API。自定义 integration 必须实现单数形式的 source contract：

from typing import Any

from osmosis_ai.rollout import RolloutSample, SampleSource


class MySampleSource(SampleSource):
    def __init__(self, messages: list[dict[str, Any]]) -> None:
        self.messages = messages

    async def get_sample(self) -> RolloutSample:
        return RolloutSample(messages=self.messages)


rollout_ctx.set_sample_source(MySampleSource(messages))
sample = await rollout_ctx.get_sample()

不要为 RolloutSample 设置 id。如需控制标准化的 ATIF transcript，请设置 trajectory_messages；将其设为 None 会关闭该 sample 的 trajectory 持久化。

6. 更新自定义 Routing 和 Backend Adapter

如果只使用内置 integrations 和 LocalBackend，请跳过此步骤。将 execution 提供的 chat-completions 和 callback URL 视为不透明的 rollout-scoped endpoints。不要追加 rollout ID，也不要附加已移除的 x-sample-id 和 x-rollout-id routing headers。自定义 backend 在 ExecutionResult 中返回一个 sample。如果直接读取 container exchange files，请将 reader 更新为单数 file names 和 payloads：

sample.json

{
  "messages": [],
  "reward": null,
  "remove_sample": false,
  "metrics": {},
  "extra_fields": {}
}

reward.json

{
  "reward": 1.0
}

7. 迁移 Dataset Schema

从 0.3.0rc3 开始，是否存在 metadata column 会为整个 dataset 选择一种统一的 schema mode：

模式	每行必需	可选
Prompt mode	`user_prompt` 和 `ground_truth`（接受 `label` 作为 alias）	`system_prompt` 和其他一致的 fields
Metadata mode	Non-empty `metadata` JSON object	`system_prompt` 和其他一致的 fields

不要混用 prompt-mode 和 metadata-mode rows。JSONL rows 必须使用一致的 field set，metadata value 在整个 file 中也必须有效且 type-consistent。Upload 或 submission 前请在本地验证 JSONL、CSV 或 Parquet：

osmosis dataset validate data/train.jsonl

Validator 会扫描每一行 JSONL 和 CSV，以及每个 Parquet metadata value，因此应修复每一条 reported row，而不只是第一个示例。

8. 迁移 Per-Run Secret

在 run config 中只声明 secret name，绝不要填写 value：

[secrets]
required = ["OPENAI_API_KEY"]

Stored secret name 会发送到 platform 并由 server-side 解析。若只想为当前 run 提供 value，请使用 --secrets-file、process environment 或隐藏的 interactive prompt：

osmosis eval submit configs/eval/my-rollout.toml --secrets-file .env.run

本地提供的 value 会随受 TLS 保护的 submit request 发送，但不会加入 platform secret store 或持久化 run config，CLI 和 platform response 也不会将其回显。每次 run 都必须重新提供。osmosis train submit 和 osmosis benchmark submit 的行为相同。对于 benchmark run，只有 [secrets].required 中的 name 可以接收 per-run value；model、harness、judge 和 verifier secret reference 必须已存在于 platform secret store 中。

9. 验证 LocalBackend 迁移

确认 rollout 中不再出现已移除的 API：

rg "ctx\.samples|set_sample_reward|register_sample_source|get_samples|MultiTurnMode|x-sample-id|x-rollout-id" rollouts

重新创建 rollout environment，确保 lockfile 中包含 osmosis-ai>=0.3.0,<0.4 和所选 extras。
在本地运行 workflow，确认每次成功的 execution 都生成一个 sample。
提交一次 evaluation run，确认每个已评分 sample 都有一个标量 reward。
在提交 training 前，将 reward 和最终 messages 与最近一次成功的 v0.2 evaluation 进行对比。

LocalBackend 常见问题

第二个 agent 或 session 触发 registration error

该 workflow execution 已经注册了 sample source。请复用一个 agent 或 session 完成 conversation，或者将独立 candidates 拆分到不同的 workflow executions。

Grader 没有 sample

请在 AgentWorkflow.run() 内构造受支持的 agent 或 session。在模块 import 时创建的 object 无法向 active rollout context 注册。

无法导入可选 integration

在 rollout-local environment 中安装对应的 extra，然后重新生成 lockfile。

Model call 到达了错误的 rollout

将提供的 chat-completions URL 直接传给 integration。移除重新构造 URL、追加 rollout path segment 或附加旧 routing headers 的代码。

HarborBackend 用户

Harbor 用户必须先完成 LocalBackend 用户中的共享 dependency、import、workflow、grader、sample-source、routing、dataset 和 secret 变更，然后再迁移 Harbor class 和 constructor。

HarborBackend 这个名称在 v0.3 中仍可 import，但现在指向之前名为 HarborBackendV2 的实现。使用 task_dir、user_code_dir 或 workflow 的 pre-v0.3 调用会抛出 TypeError；不存在 legacy compatibility mode。

1. 升级 Package 和 Import

安装 v0.3 Harbor 和 server 功能：

pip install --upgrade "osmosis-ai[server,harbor]>=0.3.0,<0.4"

请安装 osmosis-ai[harbor]，不要安装 Harbor 的 skypilot extra。Managed rollout runtime 会提供兼容的 SkyPilot SDK。

使用 Harbor submodule import：

from osmosis_ai.rollout.backend.harbor import HarborBackend

如果已经使用 HarborBackendV2，只需修改 class name，并保留其 v2 constructor arguments：

# v0.2 preview API
from osmosis_ai.rollout.backend.harbor import HarborBackendV2

# v0.3
from osmosis_ai.rollout.backend.harbor import HarborBackend

HarborBackendV2 不会作为 alias 保留。

2. 替换 Pre-v0.3 Constructor

旧 backend 会把 source tree 和 SDK mount 到 task environment。v0.3 backend 会把 workflow project 打包为 wheel，并安装到 task container 内。

from pathlib import Path

from osmosis_ai.rollout.backend.harbor import HarborBackend

backend = HarborBackend(
    orchestrator=trial_queue,
    task_dir=Path("tasks/my-task"),
    user_code_dir=Path("."),
    workflow=MyWorkflow,
    workflow_config=my_workflow_config,
    grader=MyGrader,
    grader_config=my_grader_config,
    cleanup_successful_trials=True,
)

from pathlib import Path

from osmosis_ai.rollout.backend.harbor import HarborBackend

backend = HarborBackend(
    orchestrator=trial_queue,
    tasks_dir=Path("tasks/my-task"),
    task_mode="template",
    agent=MyWorkflow,
    workflow_config=my_workflow_config,
    grader=MyGrader,
    grader_config=my_grader_config,
    code_dir=Path("."),
    cleanup_successful_trials=True,
)

按照下表迁移所有旧 constructor parameters：

v0.3 之前的参数	v0.3 替代项	迁移说明
`orchestrator=`	`orchestrator=`	保持不变
`task_dir=`	`tasks_dir=` 和 `task_mode=`	一个可复用 task 使用 `"template"`，task directory 集合使用 `"dataset"`
`user_code_dir=`	`code_dir=` 或 `bundle=`	`code_dir` 指向包含 `pyproject.toml` 的 package project，或提供预构建 bundle wheel
`workflow=`	`agent=`	传入 `AgentWorkflow` class/import path 或已注册的原生 Harbor agent name
`workflow_config=`	`workflow_config=`	保持不变；它会与 workflow agent 一起打包
`grader=`	`grader=`	保持不变；grader 会被打包并作为 Harbor verifier 运行
`grader_config=`	`grader_config=`	保持不变
`trials_dir=`	`trials_dir=`	继续支持，但省略时现在使用 backend-specific temporary root，而不是 `Path("trials")`
`custom_tests_dir=`	已移除	把 tests 放在每个 task 的 `tests/` 下，或传入 Osmosis `grader=`
`environment_config=`	`environment_config=`	保持不变
`prebuild_local_image=`	已移除	Harbor 负责 image caching；开始服务前调用 `prewarm()` 或 `prewarm_lifespan()`
`symlink_environment=`	已移除	每个 rollout 都会 materialize 一个 task 副本，并依赖 Harbor image caching
`cleanup_successful_trials=`	`cleanup_successful_trials=`	保持不变

如果 harness 使用了 private _sdk_source_dir argument，请将其移除。 v0.3 constructor 还新增了以下控制项：

新增参数	用途
`native_agent_kwargs`	配置已注册的原生 Harbor agent
`model_name`	选择原生 agent model；默认为 `openai/osmosis-rollout`
`bundle`	复用预构建 Osmosis bundle wheel，而不是从 `code_dir` 构建
`patch_dockerfile_with_sdk`	控制是否在 task image 中预装 bundle dependencies
`agent_setup_timeout_sec`	限制 Harbor agent setup 时间
`max_queue_depth`	限制 queued rollouts，并启用 `429` admission control

3. 选择 Task Mode

要最接近地替代旧的单个 task_dir，请使用 template mode：

backend = HarborBackend(
    orchestrator=trial_queue,
    tasks_dir=Path("tasks/my-task"),
    task_mode="template",
    agent=MyWorkflow,
)

Request prompt 会在每个 rollout 的副本中替换 instruction.md。这会保留与 LocalBackend 相同的 prompt ownership，同时增加 Harbor trial environment。当 tasks_dir 中每个 task 都有独立目录时，请使用 dataset mode：

backend = HarborBackend(
    orchestrator=trial_queue,
    tasks_dir=Path("tasks"),
    task_mode="dataset",
    agent=MyWorkflow,
)

每个 request 都必须设置 metadata["harbor_task_id"]；选中的 task 会保留自己的 instruction.md。需要保留已编写 Harbor tasks，或已经可以逐 task 运行的本地 Harbor dataset 时，请使用此 mode。无论使用哪种 mode，metadata["harbor_task"] 都可以选择 per-rollout 本地路径、"org/name@ref" 形式的 Harbor registry package，或 Git task。Git task 还需要设置 metadata["git_url"]，并应固定 metadata["git_commit_id"]。如果旧 backend 使用 custom_tests_dir，请把这些 tests 移入每个 task：

tasks/my-task/
├── instruction.md
├── task.toml
├── environment/
│   └── Dockerfile
└── tests/
    └── test.sh

即使同时配置 grader=，task-native verifier 仍然是权威来源；只有缺少 tests/test.sh 时，backend 才会生成 Osmosis grader verifier。传入 grader=None 可明确选择 task-native reward path。

4. 打包 Workflow 代码，而不是 Mount

对于 AgentWorkflow，backend 会从 code_dir 构建 wheel，并在 trial 启动时安装到 container。该目录必须包含 pyproject.toml 和一个可导入的 top-level Python package。省略 code_dir 时，backend 会尝试定位包含 workflow class 的 project。如果 build system 会提前创建 Osmosis bundle wheel，请使用 bundle=。不要同时传入两个路径并期望它们合并；提供 bundle 后会直接使用它。旧的 HarborAgentWorkflowContext.environment adapter 已移除。Workflow 现在会在 task container 内运行，接收标准 AgentWorkflowContext，并通过普通 Python API 访问文件或 processes：

import asyncio

from osmosis_ai.rollout import AgentWorkflow, AgentWorkflowContext


class HarborWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> None:
        result = await asyncio.create_subprocess_exec(
            "python",
            "/workspace/run_task.py",
        )
        await result.wait()

OsmosisInstalledAgent 也已移除。不要实例化或继承它；请通过 agent= 传入 AgentWorkflow，或选择已注册的原生 Harbor agent name。

5. 选择 Agent 和 Reward Source

agent= 接受 AgentWorkflow class/import path，或以下已注册的原生名称之一："terminus-2"、"mini-swe-agent" 和 "oracle"。

"oracle" 会运行 reference solution 来验证 dataset 或 verifier。它不会生成 model trajectory，不能用于 training。

请选择一种 reward 路径：

配置	Reward 来源
`grader=MyGrader`	打包后的 Osmosis grader 作为 Harbor verifier 运行
`grader=None`	Task 自己的 `tests/` 生成 reward

6. 添加 Prewarming 和 Lifecycle Controls

在 rollout server 接收流量前，prewarm 所选 task images 和 agent setup：

from osmosis_ai.rollout.server import create_rollout_server

app = create_rollout_server(
    backend=backend,
    lifespan=backend.prewarm_lifespan(),
)

Dataset mode 需要显式 task IDs：

app = create_rollout_server(
    backend=backend,
    lifespan=backend.prewarm_lifespan(["task-a", "task-b"]),
)

设置 max_queue_depth 后，queue 已满时 POST /rollout 会返回带 Retry-After: 5 的 429。v0.3 还提供：

GET /rollout/{rollout_id}/status
POST /rollout/cancel
HarborBackend.rollout_status()
HarborBackend.cancel_rollouts()

7. 验证 HarborBackend 迁移

确认旧 class 和 constructor keywords 不再出现：

rg "HarborBackendV2|HarborAgentWorkflowContext|OsmosisInstalledAgent|task_dir=|user_code_dir=|workflow=|custom_tests_dir=|prebuild_local_image=|symlink_environment=" rollouts

确认 tasks_dir 指向有效的 template task 或 dataset root。
构建 workflow bundle，并修复 package layout 或缺少 dependency 的错误。
Template mode 运行 await backend.prewarm()；dataset mode 则传入 task IDs。
提交一个 rollout，并检查 workflow sample、reward source、Harbor logs 和已归档 artifacts。
如果 calling controller 依赖 status 和 cancellation，请实际验证这些功能。
在 training 前运行 evaluation，并将 reward 和最终 messages 与最近一次成功的 v0.2 run 对比。

HarborBackend 常见问题

HarborBackend 拒绝 task_dir、user_code_dir 或 workflow

Import 已解析到 v0.3 backend，但调用仍使用已移除的 constructor。请按照上表替换所有旧 parameters。

无法打包 workflow project

将 code_dir 指向包含 pyproject.toml 和一个可导入 package 的目录。确保 workflow 和 grader 可以通过该 package 的 import path 寻址。

Dataset-mode request 找不到 task

将 metadata["harbor_task_id"] 设为 tasks_dir 下的目录，或将 metadata["harbor_task"] 设为受支持的本地、package 或 Git reference。

Trial 完成后没有 reward

如果 task 包含 tests/test.sh，请修复该 verifier，并确认它会输出 Harbor 的 reward channel；Osmosis grader 不会覆盖它。如果 task 没有 verifier，则改为传入 Osmosis grader。

Rollout 代码仍依赖 ctx.environment

移除 legacy adapter 调用。Workflow 现在运行在 container 内，因此请使用普通 filesystem、subprocess 和 network API。

版本说明

迁移指南

SDK v0.2 → v0.3 迁移指南

LocalBackend 用户

1. 升级 Package 并选择功能

2. 更新 Public Import 和 Workflow Return

3. 从多个 Sample 改为一个 Sample

4. 每次 Execution 只注册一个 Agent 或 Session

5. 更新自定义 Sample Source

6. 更新自定义 Routing 和 Backend Adapter

7. 迁移 Dataset Schema

8. 迁移 Per-Run Secret

9. 验证 LocalBackend 迁移

LocalBackend 常见问题

HarborBackend 用户

1. 升级 Package 和 Import

2. 替换 Pre-v0.3 Constructor

3. 选择 Task Mode

4. 打包 Workflow 代码，而不是 Mount

5. 选择 Agent 和 Reward Source

6. 添加 Prewarming 和 Lifecycle Controls

7. 验证 HarborBackend 迁移

HarborBackend 常见问题

相关资源

​LocalBackend 用户

​1. 升级 Package 并选择功能

​2. 更新 Public Import 和 Workflow Return

​3. 从多个 Sample 改为一个 Sample

​4. 每次 Execution 只注册一个 Agent 或 Session

​5. 更新自定义 Sample Source

​6. 更新自定义 Routing 和 Backend Adapter

​7. 迁移 Dataset Schema

​8. 迁移 Per-Run Secret

​9. 验证 LocalBackend 迁移

​LocalBackend 常见问题

​HarborBackend 用户

​1. 升级 Package 和 Import

​2. 替换 Pre-v0.3 Constructor

​3. 选择 Task Mode

​4. 打包 Workflow 代码，而不是 Mount

​5. 选择 Agent 和 Reward Source

​6. 添加 Prewarming 和 Lifecycle Controls

​7. 验证 HarborBackend 迁移

​HarborBackend 常见问题

​相关资源

LocalBackend 用户

1. 升级 Package 并选择功能

2. 更新 Public Import 和 Workflow Return

3. 从多个 Sample 改为一个 Sample

4. 每次 Execution 只注册一个 Agent 或 Session

5. 更新自定义 Sample Source

6. 更新自定义 Routing 和 Backend Adapter

7. 迁移 Dataset Schema

8. 迁移 Per-Run Secret

9. 验证 LocalBackend 迁移

LocalBackend 常见问题

HarborBackend 用户

1. 升级 Package 和 Import

2. 替换 Pre-v0.3 Constructor

3. 选择 Task Mode

4. 打包 Workflow 代码，而不是 Mount

5. 选择 Agent 和 Reward Source

6. 添加 Prewarming 和 Lifecycle Controls

7. 验证 HarborBackend 迁移

HarborBackend 常见问题

相关资源