跳转到主要内容

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 train submit 提交训练任务时，Osmosis 会自动为您部署和运行 rollout — 您不需要选择或配置执行后端。本页面是开源 osmosis-ai 包的 SDK 级参考，适用于您希望自己驱动 rollout 的场景（例如自定义的本地测试框架或自托管实验环境）。
执行后端决定了当您直接通过 SDK 编排 AgentWorkflow 和 Grader 时，代码在哪里运行。您可以在当前 Python 进程中直接执行以保持简洁，也可以将每次执行隔离在 Docker 容器中。

​
ExecutionBackend 接口

所有后端都实现了 ExecutionBackend 抽象类： 
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"}
方法描述
execute()针对单个请求运行 AgentWorkflow（以及可选的 Grader）
max_concurrency最大并行执行数。0 表示无限制。
health()返回后端健康状态。默认实现返回 {"status": "ok"}。

​
LocalBackend

在当前 Python 进程中直接执行您的 AgentWorkflow 和 Grader。无需额外基础设施。 
from osmosis_ai.rollout.backend import LocalBackend

backend = LocalBackend(
    workflow=MyWorkflow,
    grader=MyGrader,
)
构造函数参数：
参数类型描述
workflow类或 "module:attr" 字符串您的 AgentWorkflow 子类或冒号分隔的导入路径（例如 "my_module:MyWorkflow"）
workflow_configAgentWorkflowConfig | None传递给工作流的可选配置
grader类或 "module:attr" 字符串您的 Grader 子类或冒号分隔的导入路径
grader_configGraderConfig | None传递给评分器的可选配置
执行流程：
1

接收请求

后端接收一个 ExecutionRequest，其中包含某一行数据集对应的输入 prompt 和参考答案。
2

运行工作流

创建 AgentWorkflowContext，建立 RolloutContext，然后调用 workflow.run(ctx)。
3

收集样本

工作流完成后，从 RolloutContext 中收集所有 RolloutSample 对象。
4

运行评分器

使用收集到的样本和这一行的参考答案创建 GraderContext，然后调用 grader.grade(ctx)。
5

返回结果

返回包含样本及其分配奖励的 ExecutionResult。
并发控制通过 AgentWorkflowConfig.concurrency.max_concurrent（默认值：4）进行管理。后端使用 ConcurrencyLimiter 来限制并行工作流执行数量。 错误分类： LocalBackend 将异常映射为结构化的错误类型 — TimeoutError 变为 TIMEOUT，ValueError/TypeError 变为 VALIDATION_ERROR，所有其他异常变为 AGENT_ERROR。

​
HarborBackend

通过 harbor 包在 Docker 容器中执行您的 AgentWorkflow 和 Grader。每次执行都会获得独立的容器，拥有独立的文件系统和进程空间。 
from osmosis_ai.rollout.backend import HarborBackend

backend = HarborBackend(
    orchestrator=orchestrator,
    task_dir="/path/to/task",
    user_code_dir="/path/to/code",
    workflow=MyWorkflow,
    grader=MyGrader,
)
主要特点：
  • 构造时预构建 Docker 镜像
  • 每次执行在全新容器中运行
  • HarborAgentWorkflowContext 扩展了 AgentWorkflowContext，提供用于容器交互的 environment 对象 — environment.exec()、environment.upload_file() 等
HarborBackend 在构造时会调用 Docker，因此需要在实例化它的主机上安装并运行 Docker。如果您是通过 osmosis train submit 提交训练任务，这不适用 — 平台会为您管理执行环境。

​
对比

LocalBackendHarborBackend
执行环境当前 Python 进程Docker 容器
隔离性无 — 共享进程内存完全隔离 — 独立的文件系统和进程
启动速度即时需要构建 Docker 镜像
依赖管理共享 Python 环境每个容器独立管理
调试直接 — 断点、print 语句容器日志、trace 文件
适用场景开发、评估、简单部署生产环境、复杂 Agent

​
选择后端

直接驱动 SDK 时，建议从 LocalBackend 开始 — 它没有基础设施依赖，最容易调试。只有在需要文件系统/进程隔离，或希望每次 rollout 管理自己的 Python 依赖时，才考虑 HarborBackend。
osmosis eval run 在内部使用 LocalBackend。如果您把 osmosis-ai 嵌入自己的测试框架，可以自行选择任一后端。

​
下一步

本地评估

使用 osmosis eval run 在本地评估 rollout，也可以作为训练前的 smoke test。

Strands 集成

结合使用 AWS Strands Agent 框架，在 Osmosis 上训练。