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

Osmosis SDK v0.3 包含两项相互独立的 breaking change。所有 rollout 都改为一次 execution、一个 sample、一个 reward 的契约。与此同时，pre-v0.3 HarborBackend 被移除，HarborBackendV2 成为新的 HarborBackend，并采用不同的 constructor 和 execution model。

请同时升级 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.4"

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

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

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

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

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

其他 extras 包括 openai-agents、harbor、rubric 和 parquet。

2. 从多个 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。

3. 每次 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。

4. 更新自定义 Sample Source

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

class MySampleSource(SampleSource):
    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 持久化。

5. 更新自定义 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
}

6. 验证 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 中包含 v0.3 和所选 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 用户中的共享 workflow、grader、sample-source 和 routing 变更，然后再迁移 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.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：

Pre-v0.3 parameter	v0.3 replacement	迁移说明
`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 还新增了以下控制项：

New parameter	用途
`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。当 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。无论使用哪种 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
├── environment/
│   └── Dockerfile
└── tests/
    └── test.sh

然后传入 grader=None，使用 task-native verifier。

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 路径：

Configuration	Reward source
`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

传入 Osmosis grader，或设置 grader=None 并确认所选 task 包含可正常运行的 tests/ verifier。

Rollout 代码仍依赖 ctx.environment

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

版本说明

迁移指南

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

LocalBackend 用户

1. 升级 Package 并选择功能

2. 从多个 Sample 改为一个 Sample

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

4. 更新自定义 Sample Source

5. 更新自定义 Routing 和 Backend Adapter

6. 验证 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. 从多个 Sample 改为一个 Sample

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

​4. 更新自定义 Sample Source

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

​6. 验证 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. 从多个 Sample 改为一个 Sample

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

4. 更新自定义 Sample Source

5. 更新自定义 Routing 和 Backend Adapter

6. 验证 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 常见问题

相关资源