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.4,<0.4"

在 v0.3.0 及更高版本中，Harbor extra 会安装兼容的 uv builder，backend 会优先使用 active Python interpreter 对应的 executable，无需再单独全局安装 uv。从 Harbor submodule import backend：

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

HarborBackend 不会从 osmosis_ai.rollout 或 osmosis_ai.rollout.backend re-export。该 extra 会同时安装 Harbor 及其 Daytona environment dependencies，因此选择 Harbor Daytona environment 的 rollout 无需额外安装包。

选择 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.DAYTONA),
    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.DAYTONA),
    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"、"opencode" 或 "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、结果轮询和 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
`"opencode"`	通过当前 rollout 的 chat-completions endpoint 运行的可训练 OpenCode 编码 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。

原生 OpenCode

从 0.3.4 起，可用 agent="opencode" 运行现有 Harbor task。SDK 会将 OpenCode 连接到当前 rollout 的模型 endpoint，并禁用自动 compaction 和 pruning，以保留训练 trajectory。

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

backend = HarborBackend(
    orchestrator=TrialQueue(n_concurrent=4),
    tasks_dir=Path("tasks"),
    task_mode="dataset",
    agent="opencode",
    environment_config=HarborEnvironmentConfig(type=EnvironmentType.DAYTONA),
)

按上方 dataset mode 的示例将 backend 传给 create_rollout_server()；托管运行还需要下方说明的 Daytona 凭据。可通过 native_agent_kwargs={"version": "1.18.27"} 固定 OpenCode 版本，该选项同时用于执行和 prewarm。通过 native_agent_kwargs["opencode_config"] 传入额外的 OpenCode 配置，但 endpoint、认证和 compaction 设置由 SDK 管理。 model_name 必须采用非空的 provider/model 格式，默认值 openai/osmosis-rollout 已满足要求。每个 request 可通过 metadata["harbor_model"] 覆盖它；空值、空字符串及非字符串会被拒绝。

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。 rollout_status() 仍可用于 backend 本地诊断，但 server 的结果轮询从活跃的 RolloutContext 读取进度。自定义 backend 必须 await RolloutContext.set_status() 发布状态；调用方可使用 RolloutClient 观察进度和取消单个 rollout。保持 TrialQueue 的默认 RetryConfig(max_retries=0)。Backend 的 terminal-event contract 不支持 queue-level attempt retries；如需重试，请使用新的 rollout ID 重新提交。

Managed 与 Self-Hosted Environments

对于 Osmosis Platform Harbor rollouts，请显式设置 environment_config=HarborEnvironmentConfig(type=EnvironmentType.DAYTONA)。省略 environment_config 会保留 Harbor 默认的 Docker 环境，不会自动选择 Daytona。Harbor 会为 Daytona 构建选中 task 的 Dockerfile；您不需要手动构建或推送 image、配置 registry credentials 或选择 cluster。在 evaluation 和 training configs 的 [secrets].required 中添加 DAYTONA_API_KEY，并保留其他必需的名称。使用以下命令保存 managed runs 所需的凭据：

osmosis secret set DAYTONA_API_KEY

对于本地 osmosis eval run，请通过进程环境变量或 --secrets-file 提供 DAYTONA_API_KEY；仅创建 Platform secret record 不会让该凭据在本地可用。不要将 secret 值写入 TOML config。 osmosis eval run 在 local eval 中支持所有 Harbor environment，并保留 entrypoint 原有的 environment_config。当解析出的 sandbox 无法访问开发者机器的 loopback interface（Daytona，或 macOS 之外的 Docker）时，CLI 会自动启动托管的 cloudflared tunnel，让 sandbox 能够访问本地 model bridge；也可以使用 --advertise-url 指向您自行运行的 tunnel。参见 eval run。 EnvironmentType.DOCKER 也仍适用于有 Docker daemon 的自托管 SDK harness，但 managed rollout server 不提供该 daemon。自托管 harness 同样可以选择 EnvironmentType.DAYTONA；harbor extra 已包含其 dependencies，因此只需额外提供 Daytona credentials。

Daytona Sandbox 生命周期默认值

在 0.3.3 中，内置 Daytona 环境（type="daytona"、import_path=None 且 delete=True）默认设置 auto_stop_interval_mins=60 和 auto_delete_interval_mins=0。Daytona 在观测到 sandbox 连续 60 分钟无活动后将其停止，并在停止后立即删除。这为 rollout server 崩溃提供清理保障；正常的 trial 清理以及 agent 或 grader timeout 仍然生效。活动指 Daytona 能识别的交互，不是 sandbox 内部的 CPU 运算。Server 驱动命令时，Harbor 的命令轮询通常会刷新活动。该策略不检查 server 健康状态，其他客户端的活动也可能让 sandbox 在 server 崩溃后继续存活。如果 trial 存在较长时间没有 Daytona 可见活动的阶段，请在 environment_config.kwargs 中设置更大的间隔，或设为 0 禁用自动停止：

from harbor.models.environment_type import EnvironmentType
from harbor.models.trial.config import EnvironmentConfig as HarborEnvironmentConfig

environment_config = HarborEnvironmentConfig(
    type=EnvironmentType.DAYTONA,
    kwargs={"auto_stop_interval_mins": 240},  # or 0 to disable auto-stop
)

将此配置传给 HarborBackend(environment_config=environment_config, ...)。SDK 保留显式的生命周期设置，并且不会为 delete=False、自定义 import_path 或其他 provider 添加默认值。禁用自动停止后，清理由正常 trial 清理或您自己的清理策略负责。

Harbor 0.22 对基于 snapshot 的 Daytona sandbox 强制在停止后立即删除，即使指定了非零删除间隔；GPU task 也不接受非零删除间隔。默认值 0 适用于这两条路径。

开始使用

核心 API

集成

执行

Agent 工具

HarborBackend Task 与 Dataset 执行

安装与 Import

选择 Task Mode

Template Mode

Dataset Mode

集成已有 Harbor Dataset

动态 Task Sources

Agent 执行轨道

原生 OpenCode

Reward Source 与优先级

Constructor 参考

Prewarming、Capacity 与 Cancellation

Managed 与 Self-Hosted Environments

Daytona Sandbox 生命周期默认值

下一步

执行后端概览

v0.3 迁移

​安装与 Import

​选择 Task Mode

​Template Mode

​Dataset Mode

​集成已有 Harbor Dataset

​动态 Task Sources

​Agent 执行轨道

​原生 OpenCode

​Reward Source 与优先级

​Constructor 参考

​Prewarming、Capacity 与 Cancellation

​Managed 与 Self-Hosted Environments

​Daytona Sandbox 生命周期默认值

​下一步

执行后端概览

v0.3 迁移

安装与 Import

选择 Task Mode

Template Mode

Dataset Mode

集成已有 Harbor Dataset

动态 Task Sources

Agent 执行轨道

原生 OpenCode

Reward Source 与优先级

Constructor 参考

Prewarming、Capacity 与 Cancellation

Managed 与 Self-Hosted Environments

Daytona Sandbox 生命周期默认值

下一步