osmosis CLI 位于同一个 osmosis-ai Python package 中。SDK 需要 Python 3.12 或更高版本,并支持 Python 3.12、3.13 和 3.14。
安装 v0.3
安装稳定的 v0.3 版本线,同时避免跨越下一个 minor-version 边界:0.3.10 为基线,<0.4 则限制在当前 minor-version 版本线。请升级 CLI、rollout 调用方以及 rollouts/<name>/pyproject.toml 中的 rollout 依赖,然后更新各自的 lockfile 并重新构建受影响的运行时镜像。仅升级 CLI 不会更新已有的 rollout 环境。如果您从 0.3.2 或更早版本升级,必须同时更新调用方与服务端,因为旧的 callback 协议无法与长轮询互通。参见 v0.3 迁移指南。
可选 Extras
只安装项目实际 import 的功能:
Extras 可以组合安装。例如,通过 HTTP 提供服务的 Strands rollout 使用:
strands、openai-agents、harbor、rubric 和 eval extras(包括 full)要求 fsspec>=2026.6.0。0.3.6 还为安全修复提高了相关 extras 中 LiteLLM、urllib3 和 PyJWT 的最低版本。0.3.8 更新了 certifi 和 uv 的 CA 信任库,并提高了相关 aiohttp、multidict 和 MCP 的版本要求。更新 lockfile 时请解决应用版本约束冲突;具体范围见更新日志。
0.3.9 提高了相关 LiteLLM、filelock、Strands Agents 和 OpenTelemetry API 的安全版本要求,也改变了命名本地 eval run 使用的 source digest。升级前请使用原 SDK 完成被中断的 run;升级后请使用新名称或 --fresh。参见 0.3.9 迁移步骤。
0.3.10 会将本地 eval 结果作为单个流式 archive 上传,需要平台支持 archive import。参见 0.3.10 迁移步骤。
最小 SDK 示例
此 entrypoint 将 workflow 和 grader 显式连接到LocalBackend,然后把该 backend 作为 rollout server 暴露:
server extra,将示例保存为 main.py,然后运行该 entrypoint:
timeout_keep_alive=2160。SDK 0.3.7 新生成的 scaffold 使用此值,使空闲连接的存活时间超过托管负载均衡器的空闲超时。
Platform 会设置 _OSMOSIS_ROLLOUT_PORT,此时 server 会在托管容器中绑定所有网络接口;本地运行默认使用 127.0.0.1:8000。
此示例用于展示 wiring,不包含可训练的 policy call。进行训练时,请使用 Strands integration 或 OpenAI Agents integration,使模型请求通过活跃的 rollout context 路由。
Platform 认证与升级
仅运行本地 SDK 代码不需要登录 Platform。提交 evaluation 或 training run 的命令需要登录;请按照 CLI 安装与认证 运行osmosis auth login 或配置 OSMOSIS_TOKEN。
如果您正在升级已有 v0.2 harness,请先阅读 SDK v0.2 → v0.3 迁移指南,然后再修改 dependency,尤其是 harness 会构造 HarborBackend 时。
下一步
AgentWorkflow
实现产生一个 rollout sample 的行为。
执行后端
将 workflow 和 grader 连接到 Local 或 Harbor execution。