> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osmosis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 执行后端

> 在开源 osmosis-ai SDK 中选择进程内或 Harbor-managed rollout 执行

<Info>
  大多数用户不需要通过 CLI 配置执行后端。`osmosis eval submit` 和 `osmosis train submit` 都会把执行交给 Osmosis 平台；rollout entrypoint 在服务端构造 backend。本页面是面向把开源 [`osmosis-ai`](https://pypi.org/project/osmosis-ai/) 包嵌入自定义 harness 或自托管实验的用户的 SDK 级指南。
</Info>

当您直接通过 SDK 编排 rollouts 时，执行后端决定 `AgentWorkflow` 和 `Grader` **在哪里**运行。

| Backend         | Runs where                        | Best for                           |
| --------------- | --------------------------------- | ---------------------------------- |
| `LocalBackend`  | 当前 Python 进程                      | 快速本地开发、自定义 eval harnesses、调试       |
| `HarborBackend` | Harbor-managed trial environments | 每次 trial 隔离、task environments、依赖隔离 |

## 后端职责

每个后端都有相同的核心职责：

<Steps>
  <Step title="接收 execution request">
    Request 包含某一行数据集的输入 prompt，以及在启用 grading 时使用的参考 label。
  </Step>

  <Step title="运行 workflow">
    后端创建 `AgentWorkflowContext`，安装 `RolloutContext`，并调用 `AgentWorkflow.run(ctx)`。
  </Step>

  <Step title="收集 samples">
    `OsmosisStrandsAgent` 和 `OsmosisAgent` 等 agent integrations 会在 rollout context 上注册 sample sources。Workflow 完成后，后端会收集这些 samples。
  </Step>

  <Step title="运行 grader">
    如果 grader 和 label 可用，后端会创建 `GraderContext` 并调用 `Grader.grade(ctx)`。
  </Step>

  <Step title="返回结构化结果">
    后端返回包含 status、samples、rewards 和任何分类错误的 `ExecutionResult` objects。
  </Step>
</Steps>

## ExecutionBackend 接口

所有后端都实现以下形状：

```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
class ExecutionBackend(ABC):
    async def execute(
        self,
        request: ExecutionRequest,
        on_workflow_complete: ResultCallback,
        on_grader_complete: ResultCallback | None = None,
    ) -> None: ...

    @property
    def max_concurrency(self) -> int: ...  # 0 = no limit

    def health(self) -> dict[str, Any]: ...  # default: {"status": "ok"}
```

| Method            | Description                                   |
| ----------------- | --------------------------------------------- |
| `execute()`       | 为一个 request 运行 `AgentWorkflow`，并可选运行 `Grader` |
| `max_concurrency` | 最大并行执行数。`0` 表示无限制。                            |
| `health()`        | 返回后端健康信息                                      |

## LocalBackend

`LocalBackend` 会在当前 Python 进程中直接执行 workflow 和 grader。

```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
from osmosis_ai.rollout.backend import LocalBackend

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

Constructor fields：

| Parameter         | Type                            | Description                            |
| ----------------- | ------------------------------- | -------------------------------------- |
| `workflow`        | class or `"module:attr"` string | `AgentWorkflow` subclass 或 import path |
| `workflow_config` | `AgentWorkflowConfig \| None`   | 传给 workflow 的可选 config                 |
| `grader`          | class or `"module:attr"` string | 可选 `Grader` subclass 或 import path     |
| `grader_config`   | `GraderConfig \| None`          | 传给 grader 的可选 config                   |

适合使用 `LocalBackend` 的情况：

* 您需要最短的调试循环。
* 您需要 breakpoints、stack traces 或简单 print debugging。
* 您的 rollout 可以共享当前 Python 环境。
* 您正在围绕 SDK 构建自定义 harness 或 eval runner。

`LocalBackend` 使用 `AgentWorkflowConfig.concurrency.max_concurrent` 限制并行 workflow executions。如果没有提供 workflow config，默认 concurrency 为 `4`。

### 本地错误分类

`LocalBackend` 会把 workflow 和 grader exceptions 映射到结构化 categories：

| Exception                                   | Category           |
| ------------------------------------------- | ------------------ |
| `TimeoutError`                              | `TIMEOUT`          |
| `ValueError`, `TypeError`, `AssertionError` | `VALIDATION_ERROR` |
| Other exceptions                            | `AGENT_ERROR`      |

## HarborBackend

`HarborBackend` 会在 Harbor-managed trial environments 中运行 workflows。对于面向平台的 Harbor rollouts，请使用 workspace template 使用的 Daytona-backed 路径；当前 managed platform 不支持 Docker-backed Harbor execution。

<Warning>
  仅在需要面向平台训练的 Harbor-specific execution 或 SDK 级实验时，才使用 Daytona-backed Harbor template。当前 managed platform 不支持 Docker-backed Harbor execution。
</Warning>

```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
from pathlib import Path

from osmosis_ai.rollout.backend import HarborBackend

backend = HarborBackend(
    orchestrator=trial_queue,
    task_dir=Path("tasks/my-task"),
    user_code_dir=Path("."),
    workflow="rollouts.my_rollout.main:MyWorkflow",
    grader="rollouts.my_rollout.main:MyGrader",
)
```

关键 constructor fields：

| Parameter                   | Description                                                           |
| --------------------------- | --------------------------------------------------------------------- |
| `orchestrator`              | 用于运行 trials 的 Harbor `TrialQueue`                                     |
| `task_dir`                  | 用于构建 Harbor environment 的 task directory                              |
| `user_code_dir`             | 包含 rollout code、会复制进 Harbor workspace 的目录                             |
| `workflow`                  | `AgentWorkflow` class 或 import path                                   |
| `workflow_config`           | 可选 workflow config class/object import path                           |
| `grader`                    | 可选 `Grader` class 或 import path                                       |
| `grader_config`             | 可选 grader config class/object import path                             |
| `environment_config`        | 可选 Harbor environment configuration；面向平台的 Harbor rollouts 应使用 Daytona |
| `prebuild_local_image`      | SDK 实验中的本地 Docker runtime 选项；managed platform 不支持                     |
| `cleanup_successful_trials` | 成功 completion 后是否移除 trial artifacts                                   |

<Warning>
  只有在 SDK harness 中显式使用本地 Docker runtime 时，`HarborBackend` 才会调用 Docker shell 命令。当前 managed Osmosis platform 不支持 Docker-backed Harbor execution；面向平台运行的 Harbor rollouts 请使用 Daytona。
</Warning>

### Harbor Runtime Notes

使用 `HarborBackend` 时，workflow 会在 Harbor-managed trial environment 内运行，但它仍然接收标准的 `AgentWorkflowContext`：

```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
from osmosis_ai.rollout import AgentWorkflow, AgentWorkflowContext


class HarborWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> None:
        # This code is already running inside the Harbor trial environment.
        ...
```

不要在 rollout 代码中期待 `ctx.environment` object。如果 workflow 需要 trial environment 内的文件、tools 或 processes，请把它们打包到 Harbor task environment 中，并在 `run()` 内通过普通 Python 代码访问。

## 对比

| Dimension             | LocalBackend                          | HarborBackend                 |
| --------------------- | ------------------------------------- | ----------------------------- |
| Execution environment | 当前 Python 进程                          | Harbor trial environment      |
| Isolation             | 共享进程和文件系统                             | 每个 trial 隔离进程和文件系统            |
| Startup cost          | 最小                                    | 准备 Harbor task environment    |
| Dependencies          | 当前 Python environment                 | Harbor task environment       |
| Debugging             | 直接 debugger、stack traces、print output | Harbor logs 和 trial artifacts |
| Typical user          | SDK harness author、eval tooling       | 需要隔离的自托管实验                    |

## 选择后端

<Tip>
  除非确定需要 Harbor 隔离，否则从 `LocalBackend` 开始。它更容易调试、moving parts 更少，并且匹配默认本地 starter templates 的 smoke test 行为。
</Tip>

以下情况可以考虑 `HarborBackend`：

* 不受信任或混乱的 rollout code 不应共享 host process。
* Tools 会写文件或 spawn processes，且每次 trial 应该隔离。
* 每次 rollout execution 都需要可复现 task environment。
* 您正在 managed Osmosis training path 之外实验 Harbor。

## 与 Eval 和训练的关系

`osmosis eval submit` 和 `osmosis train submit` 都在服务端运行 rollout，并不把这些 SDK backends 作为用户可选项暴露。rollout server 在平台启动时，由 entrypoint 构造 backend。这些 SDK 级 backends 只在您把 `osmosis-ai` 嵌入自己的 harness 时才需要关注。

## 下一步

<CardGroup cols={2}>
  <Card title="评估" icon="flask-vial" href="/zh/cli/rollout/eval">
    在训练前提交 evaluation run。
  </Card>

  <Card title="构建 AgentWorkflow" icon="robot" href="/zh/cli/rollout/agent-workflows">
    了解 workflows 如何通过受支持 integrations 注册 samples。
  </Card>

  <Card title="Strands 集成" icon="link" href="/zh/cli/rollout/strands-integration">
    在 Osmosis workflow 中使用 Strands Agents。
  </Card>

  <Card title="OpenAI Agents 集成" icon="route" href="/zh/cli/rollout/openai-agents-integration">
    在 Osmosis workflow 中使用 OpenAI Agents SDK。
  </Card>
</CardGroup>