HarborBackend Task 与 Dataset 执行

HarborBackend 会在 Harbor trial 中运行 Osmosis AgentWorkflow 或已注册的原生 Harbor agent。每个 rollout 都会获得复制的 task directory、task-defined environment，以及 Harbor-managed agent 和 verifier phases。

SDK v0.3 移除了 pre-v0.3 HarborBackend，并把 HarborBackendV2 改名为 HarborBackend。当前 class 使用不同的 constructor，且不提供 compatibility alias。升级已有 harness 前，请先阅读 v0.3 迁移指南。

安装与 Import

安装 Harbor 和 rollout-server features：

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

uv 还必须位于 PATH 上：截至 v0.3.0rc3，Harbor extra 不会安装它，而 backend 在打包 AgentWorkflow 或 Grader bundle 时会运行 uv build。从 Harbor submodule import backend：

from osmosis_ai.rollout.backend.harbor import HarborBackend, TaskMode

HarborBackend 不会从 osmosis_ai.rollout 或 osmosis_ai.rollout.backend re-export。不要安装 harbor[skypilot]；managed rollout runtime 会提供兼容的 SkyPilot SDK。

选择 Task Mode

task_mode 决定谁拥有 instruction、如何选择默认 task，以及 request prompt 是否进入 task。

行为	Template mode	Dataset mode
`tasks_dir`	一个可复用 Harbor task directory	包含多个 Harbor task directories 的根目录
Instruction 所有者	传入的 rollout request	选中的 Harbor task
Request prompt	序列化到复制后 task 的 `instruction.md`	被 backend 丢弃
默认 task 选择	始终使用配置的 task	`metadata["harbor_task_id"]` 指定子目录
典型 reward source	Osmosis `Grader` 或可复用 task verifier	选中 task 的原生 verifier
最适合	把一个 environment 应用于变化的 dataset rows	已有 Harbor tasks 或 datasets，可按原样运行

两种 mode 都使用 Harbor trials，并提供相同 isolation。Mode selection 改变 task semantics，不改变 sandbox technology。

Template Mode

Template mode 会让每个 rollout 从一个 task directory 开始。Request 包含 prompt 时，backend 会复制 task，并在 Harbor 启动 trial 前用序列化后的 message list 替换 instruction.md。

rollouts/my-rollout/
├── main.py
├── pyproject.toml
└── task-template/
    ├── task.toml
    └── environment/
        └── Dockerfile

如果每个 rollout 都提供 prompt，则配置好的 template 可以不含 instruction.md。如果还希望该目录通过 Harbor 独立 task validation，请添加 placeholder instruction。Backend 提供 Osmosis Grader 时，tests/test.sh 可选。

from pathlib import Path

from harbor.models.environment_type import EnvironmentType
from harbor.models.trial.config import EnvironmentConfig as HarborEnvironmentConfig
from harbor.trial.queue import TrialQueue
from osmosis_ai.rollout.backend.harbor import HarborBackend
from osmosis_ai.rollout.server import create_rollout_server

backend = HarborBackend(
    orchestrator=TrialQueue(n_concurrent=4),
    tasks_dir=Path("task-template"),
    task_mode="template",
    agent=MyWorkflow,
    workflow_config=my_workflow_config,
    grader=MyGrader,
    grader_config=my_grader_config,
    environment_config=HarborEnvironmentConfig(type=EnvironmentType.SKYPILOT),
    max_queue_depth=8,
)

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

Template mode 是最接近 LocalBackend 的 Harbor 路径：一个 workflow 处理变化的 dataset prompts。当这些 prompts 每次都需要同一套隔离 operating system、tools、services 或 filesystem setup 时，请选择它。

在 template mode 中，metadata["harbor_task"] 可以为某个 request 选择另一个 task，但 request prompt 仍会替换该 task 的 instruction。动态选择的 task 自带 instruction 被覆盖时，backend 会记录 warning。

Dataset Mode

Dataset mode 会把每个 Harbor task 当作完整工作单元。Task 保留自己的 instruction.md、environment、configuration 和 verifier。

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

配置 root directory 和一个原生 Harbor agent 或 Osmosis workflow：

from pathlib import Path

from harbor.models.environment_type import EnvironmentType
from harbor.models.trial.config import EnvironmentConfig as HarborEnvironmentConfig
from harbor.trial.queue import TrialQueue
from osmosis_ai.rollout.backend.harbor import HarborBackend
from osmosis_ai.rollout.server import create_rollout_server

backend = HarborBackend(
    orchestrator=TrialQueue(n_concurrent=4),
    tasks_dir=Path("tasks"),
    task_mode="dataset",
    agent="mini-swe-agent",
    grader=None,
    environment_config=HarborEnvironmentConfig(type=EnvironmentType.SKYPILOT),
    max_queue_depth=8,
)

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

每个 Osmosis metadata-mode dataset row 都通过 directory name 选择 Harbor task：

{"metadata": {"harbor_task_id": "task-a"}}
{"metadata": {"harbor_task_id": "task-b"}}

Backend 会在 dataset mode 中主动移除所有 request prompt。Harbor 会把选中 task 的 instruction 传给原生 agent 或打包后的 AgentWorkflow。通常由 task verifier 计算 reward；如果缺少 tests/test.sh，则由配置好的 Osmosis Grader 提供 verifier。

集成已有 Harbor Dataset

如果本地 dataset 已经可以通过 harbor run 运行，可复用的边界是其 task directories：

保留 task directories

把 tasks_dir 指向本地 dataset root。每个 child 都必须是 Harbor task，包含 task.toml、instruction.md、environment/，以及该 task 所需的 verifier files。

选择受支持的 agent track

如果符合需求，请使用 agent="terminus-2"、"mini-swe-agent" 或 "oracle"。否则请把 agent behavior 打包为 Osmosis AgentWorkflow，并传入其 class 或 import path。

创建 selector dataset

上传 Osmosis metadata-mode dataset，其中 harbor_task_id values 与 task directory names 对应。Platform dataset 负责选择 trials；Harbor task directories 仍与 rollout code 放在一起。

训练前先运行 evaluation

开始 training 前，确认原生 verifier 会输出 reward channel，并且 trainable agent 会生成可用 trajectory。

这条路径会复用 task content，而不是完整 Harbor job definition。HarborBackend 不会读取 Harbor JobConfig、dataset filters、attempt counts、任意 agent configs 或 harbor run CLI flags。Osmosis 会提供 request scheduling、model endpoint、callbacks 和 rollout identity。

动态 Task Sources

在任一 mode 中，request 都可以设置 metadata["harbor_task"]，替代配置好的默认选择：

来源	Metadata
本地 task	`{"harbor_task": "./tasks/task-a"}`
Harbor package	`{"harbor_task": "org/name@ref"}`
Git task	`{"harbor_task": "path/in/repo", "git_url": "https://...", "git_commit_id": "<sha>"}`

为保证可复现性，请固定 package references 和 Git commits。Instruction ownership 仍由 task_mode 决定：template mode 会替换 fetched task 的 instruction，dataset mode 则保留它。

请把这些字段视为受信任的 control-plane 输入，而不是不受信任的 dataset 内容。Rollout server 会在 trial sandbox 之外解析、下载并暂存被引用的 task，而 task 的 Dockerfile 和 verifier scripts 都是可执行内容。只接受来自你可控 task sources 的 harbor_task、git_url 和 git_commit_id。

Agent 执行轨道

agent 会选择两种 execution track 之一：

Agent 取值	行为
`type[AgentWorkflow]` 或 `"module:attr"`	把 rollout project 构建为 wheel，安装到 trial，并在 task environment 内运行 workflow
已注册 native name	运行 Harbor 原生 agent，并把 active Osmosis model endpoint 连接到其受支持配置

AgentWorkflow project 必须包含 pyproject.toml 和可导入 Python package，task image 也必须支持 Python。无法推断 project 时请传入 code_dir，也可以传入预构建 bundle wheel。Task Dockerfile 应专注于 task dependencies；backend 会安装 rollout bundle，并可把其声明的 dependencies 预装到复制后的 image。已注册 native names：

名称	用途
`"terminus-2"`	可训练 Harbor terminal agent
`"mini-swe-agent"`	可训练轻量 software-engineering agent
`"oracle"`	运行 task 的 reference solution，以验证 tasks 和 verifiers；不会输出可训练 model trajectory

AgentWorkflow 使用 workflow_config。native_agent_kwargs 只能用于已注册原生 agent。model_name 默认为 openai/osmosis-rollout；每个 request 的 metadata 可以通过 harbor_model 覆盖它。

在单独 Harbor installation 中可用的 custom agent name，不会自动在 HarborBackend 中可用。Backend 只接受上面已注册的 native names 或 Osmosis AgentWorkflow。

Reward Source 与优先级

Harbor 始终把 task-provided verifier 作为权威来源：

配置	结果
Task 包含 `tests/test.sh`	即使同时设置 `grader=MyGrader`，Harbor 仍运行该 script
没有 task `tests/test.sh`，`grader=MyGrader`	Backend 生成 verifier script，安装并运行打包后的 Osmosis grader
Task 包含 `tests/test.sh`，`grader=None`	Harbor 运行 task-native verifier
没有 task verifier，且 `grader=None`	Rollout validation 失败，因为没有 reward source

v0.3 不再提供 custom_tests_dir。请把原生 verifier files 放在每个 task 的 tests/ directory 中。原生 verifier 必须写入 Harbor 的 reward channel，通常通过 /logs/verifier/reward.txt，或包含 reward key 的 reward.json；backend 不会猜测其他 channel。

Constructor 参考

参数	类型 / 默认值	说明
`orchestrator`	`TrialQueue`	用于运行 trials 的 Harbor queue
`tasks_dir`	`Path`	Template mode 下的单个 task directory，或 dataset mode 下的 task-root directory
`agent`	`type \| str \| None`	Workflow class、import path、已注册 native agent name，或在预构建 bundle 提供 workflow 时使用 `None`
`native_agent_kwargs`	`dict[str, Any] \| None`	已注册原生 agent 的额外配置；不能与 `AgentWorkflow` 一起使用
`task_mode`	`"template"`	`"template"` 或 `"dataset"`
`model_name`	`"openai/osmosis-rollout"`	传给原生 agents 的 model；request metadata 可以通过 `harbor_model` 覆盖
`grader`	`type \| str \| None`	可选 Osmosis grader；只在 task 未提供 `tests/test.sh` 时使用
`workflow_config`	`Any`	与 workflow agent 一起打包的可选 workflow config instance 或 import path
`grader_config`	`Any`	与 grader 一起打包的可选 grader config instance 或 import path
`code_dir`	`Path \| None`	要打包的 Python project；可以时从 workflow 或 grader 推断
`bundle`	`Path \| None`	替代构建 `code_dir` 的预构建 Osmosis bundle wheel
`environment_config`	`EnvironmentConfig \| None`	Harbor runtime 和 placement 配置
`trials_dir`	`Path \| None`	Harbor trial data 的 host directory
`cleanup_successful_trials`	`True`	Artifacts 归档后移除成功 trial staging
`patch_dockerfile_with_sdk`	`None`	把 bundle dependencies 预装到复制后的 task image；存在 bundle 时默认启用
`agent_setup_timeout_sec`	`float \| None`	可选 Harbor agent setup timeout
`max_queue_depth`	`int \| None`	最多等待的 queue depth；使用 >= 1 的整数，或用 `None` 表示不设上限

Prewarming、Capacity 与 Cancellation

prewarm() 会在 server 接收 traffic 前构建 task images 并运行 agent setup。Template mode 会 prewarm 配置好的 task；dataset mode 需要显式传入要 prewarm 的 task IDs。 TrialQueue(n_concurrent=<n>) 控制 Harbor trial concurrency。max_queue_depth 限制等待中的 rollouts，让 server 可以返回 HTTP 429，而不是无限扩展 queue。rollout_status() 报告 queued、running、grading 或最近完成的 state；cancel_rollouts() 可以按 ID、prefix 或全部取消 queued 或 running work。保持 TrialQueue 的默认 RetryConfig(max_retries=0)。Backend 的 terminal-event contract 不支持 queue-level attempt retries；如需重试，请使用新的 rollout ID 重新提交。

Managed 与 Self-Hosted Environments

Osmosis Platform Harbor rollouts 使用 EnvironmentType.SKYPILOT。Platform 会构建选中 task 的 Dockerfile，并提供兼容 SkyPilot runtime；您不需要构建或推送 image、配置 registry credentials 或选择 cluster。 EnvironmentType.DOCKER 仍适用于有 Docker daemon 的自托管 SDK harness，但 managed rollout server 不提供该 daemon。

开始使用

核心 API

集成

执行

Agent 工具

HarborBackend Task 与 Dataset 执行

安装与 Import

选择 Task Mode

Template Mode

Dataset Mode

集成已有 Harbor Dataset

动态 Task Sources

Agent 执行轨道

Reward Source 与优先级

Constructor 参考

Prewarming、Capacity 与 Cancellation

Managed 与 Self-Hosted Environments

下一步

执行后端概览

v0.3 迁移

​安装与 Import

​选择 Task Mode

​Template Mode

​Dataset Mode

​集成已有 Harbor Dataset

​动态 Task Sources

​Agent 执行轨道

​Reward Source 与优先级

​Constructor 参考

​Prewarming、Capacity 与 Cancellation

​Managed 与 Self-Hosted Environments

​下一步

执行后端概览

v0.3 迁移

安装与 Import

选择 Task Mode

Template Mode

Dataset Mode

集成已有 Harbor Dataset

动态 Task Sources

Agent 执行轨道

Reward Source 与优先级

Constructor 参考

Prewarming、Capacity 与 Cancellation

Managed 与 Self-Hosted Environments

下一步