LocalBackend 进程内执行

LocalBackend 会在创建 backend 的 Python 进程中运行 AgentWorkflow 和可选 Grader。它是 rollout 开发的默认起点，也是标准 rollout scaffold 使用的 backend。

LocalBackend 是 execution strategy，不是只能在 laptop 上使用的 mode。同一个 entrypoint 可以在本机或 Platform-managed rollout infrastructure 上运行；两种情况下，workflow 都会共享 rollout server 的进程和 filesystem。

安装

LocalBackend 属于基础 osmosis-ai package。通过 create_rollout_server() 暴露它时，请添加 server extra：

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

创建 Rollout Server

from osmosis_ai.rollout import LocalBackend
from osmosis_ai.rollout.server import create_rollout_server

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

app = create_rollout_server(backend=backend)

Constructor 只接受 keywords。Workflow 必填，grading 可选。

参数	类型	说明
`workflow`	`type[AgentWorkflow] \| str`	`AgentWorkflow` subclass 或 `"module:attr"` import path
`workflow_config`	`AgentWorkflowConfig \| str \| None`	传给 workflow 的可选 config instance 或 import path
`grader`	`type[Grader] \| str \| None`	可选 `Grader` subclass 或 import path
`grader_config`	`GraderConfig \| str \| None`	传给 grader 的可选 config instance 或 import path

导入的 module 中可以存在多个 classes。这些 arguments 会显式选择 workflow、grader 和 configs。

执行生命周期

创建 workflow context

Backend 把 request prompt 和 metadata 传入 AgentWorkflowContext，并为该次 execution 深拷贝配置好的 workflow config。

运行 workflow

Workflow 在当前进程的 active RolloutContext 中运行。它的显式 return value 或已注册 sample source 会成为 rollout sample。

适用时运行 grader

Workflow 成功后，如果 request 有 label 或 metadata，配置好的 grader 就会运行。它通过 GraderContext 接收 sample、label、metadata 和 artifact directory。

返回 result

Workflow 和 grader results 会分别返回给 rollout server。Grading 仍在 rollout 的 critical path 上；其 latency 或 failure 会影响 completed result。

进程与隔离模型

LocalBackend 特意不提供 sandbox boundary：

Workflow 和 grader code 共享 server 的 Python interpreter、installed packages、environment variables、filesystem 和 event loop。
Breakpoints、普通 logging、stack traces 和 print debugging 可以直接工作。
Process crash、blocking call、global-state mutation 或 dependency conflict 可能影响该 server 中的其他 rollouts。
修改文件或 spawn processes 的 tools 不会在 executions 之间自动隔离，除非您的代码自行创建 isolation。

每个 rollout 需要 task-owned environment 或独立 process 与 filesystem 时，请使用 HarborBackend。

Concurrency 与 Timeouts

LocalBackend 使用 workflow_config.concurrency.max_concurrent 作为进程内 execution limit：

from osmosis_ai.rollout import AgentWorkflowConfig, ConcurrencyConfig, LocalBackend

config = AgentWorkflowConfig(
    name="my-workflow",
    concurrency=ConcurrencyConfig(max_concurrent=8),
)

backend = LocalBackend(workflow=MyWorkflow, workflow_config=config)

配置	有效 limit
没有 `workflow_config`	`4` 个并发 executions
`max_concurrent=<n>`	最多 `<n>` 个并发 executions
提供 config 且 `max_concurrent=None`	Backend 不限制 concurrency

LocalBackend 本身不会强制执行 agent_timeout_sec 或 grader_timeout_sec。这些 request fields 不会中断进程内 code。您的代码主动抛出的 TimeoutError 会被分类为 timeout，但自定义 harness 必须在 backend 外部执行自己需要的 hard deadline。

Grading 规则

Grader 会在每次 workflow execution 成功后创建，而不是在 requests 之间共享。只有同时满足以下条件时才会运行：

已配置 grader。
Workflow result 成功。
Request 包含 label 或 metadata。
Caller 请求 grader completion result；create_rollout_server() 会为 graded rollouts 这样做。

Grader 必须在 sample 上保留 reward，除非它设置 remove_sample=True 丢弃该 sample。如果未配置 grader，workflow result 仍可携带未 grading 的 sample 成功返回。

Artifacts 与 Persistence

如果路径可写，backend 会给 workflow 和 grader 提供 ~/.osmosis/<rollout-id>/artifacts 下的 artifacts directory。创建该目录失败时会降级为 artifacts_dir=None，但不会单独导致 rollout 失败。 ATIF persistence 属于 create_rollout_server()，不属于 LocalBackend。直接调用 run_workflow() 或 execute() 的 harness 必须自行持久化所需 trajectory。

错误分类

LocalBackend 会把未捕获的 workflow 和 grader exceptions 转成结构化 results：

异常	分类
`TimeoutError`	`TIMEOUT`
`ValueError`, `TypeError`, `AssertionError`	`VALIDATION_ERROR`
其他 exceptions	`AGENT_ERROR`

完整 traceback 由 rollout server process 记录；result 包含 exception message 和 category。

何时使用 LocalBackend

以下情况适合使用 LocalBackend：

需要最短的开发与调试循环。
由一个 workflow 处理变化的 dataset prompts。
所有 dependencies 都由当前 Python environment 提供。
构建轻量自定义 evaluation 或 rollout harness。

Prompt-driven workflow 已正确，但 tools 或 dependencies 需要可复用的隔离 environment 时，请迁移到 Harbor template mode。每个 task 已经拥有 instruction 和 verifier 时，请迁移到 Harbor dataset mode。

开始使用

核心 API

集成

执行

Agent 工具

LocalBackend 进程内执行

安装

创建 Rollout Server

执行生命周期

进程与隔离模型

Concurrency 与 Timeouts

Grading 规则

Artifacts 与 Persistence

错误分类

何时使用 LocalBackend

下一步

AgentWorkflow

HarborBackend

​安装

​创建 Rollout Server

​执行生命周期

​进程与隔离模型

​Concurrency 与 Timeouts

​Grading 规则

​Artifacts 与 Persistence

​错误分类

​何时使用 LocalBackend

​下一步

AgentWorkflow

HarborBackend

安装

创建 Rollout Server

执行生命周期

进程与隔离模型

Concurrency 与 Timeouts

Grading 规则

Artifacts 与 Persistence

错误分类

何时使用 LocalBackend

下一步