克隆官方模板仓库、实现 Agent 逻辑、连接 Osmosis 训练集群 —— 这是搭建 Remote Rollout 服务器的最快路径。
从模板创建您的项目
克隆并安装依赖
克隆您新创建的仓库并安装依赖：如果您没有安装 uv，也可以使用 pip：pip install osmosis-ai[server]
登录 Osmosis Platform
通过 Osmosis Platform 进行身份验证以启用服务器注册：这将打开浏览器进行身份验证。登录后，您的凭据将保存到 ~/.config/osmosis/credentials.json。您可以使用以下命令验证登录状态：服务器使用您的凭据向 Osmosis Platform 注册，使训练系统能够发现并连接到您的服务器。
运行服务器
使用 SDK CLI 启动服务器：uv run osmosis serve -m server:agent_loop
INFO: Osmosis RolloutServer starting...
INFO: Agent: calculator
INFO: Tools: 4
INFO: Uvicorn running on http://0.0.0.0:9000
模板结构
模板仓库包含以下关键组件：
my-rollout-server/
├── server.py # Agent Loop 主文件
├── tools.py # 工具定义和执行逻辑
├── rewards.py # 奖励计算（可选）
├── test_data.jsonl # 测试数据集
├── pyproject.toml # 项目依赖
└── README.md # 文档
核心概念：Agent Loop
Agent Loop 是 Remote Rollout 的核心。它继承自 RolloutAgentLoop 并实现两个必需的方法：
from osmosis_ai.rollout import RolloutAgentLoop, RolloutContext, RolloutResult, RolloutRequest, create_app
class CalculatorAgent(RolloutAgentLoop):
name = "calculator"
def get_tools(self, request: RolloutRequest):
"""Return available tools."""
return CALCULATOR_TOOLS # Defined in tools.py
async def run(self, ctx: RolloutContext) -> RolloutResult:
"""Execute the agent loop."""
... # See template repo for full implementation
agent_loop = CalculatorAgent()
app = create_app(agent_loop)
工具定义
工具使用 OpenAI function calling 格式定义：
CALCULATOR_TOOLS = [
{
"type": "function",
"function": {
"name": "multiply",
"description": "Multiply two numbers",
"parameters": {
"type": "object",
"properties": {
"a": {"type": "number", "description": "First number"},
"b": {"type": "number", "description": "Second number"}
},
"required": ["a", "b"]
}
}
}
]
验证与测试
验证 Agent 配置
在运行之前，使用 CLI 验证您的 Agent 实现：
uv run osmosis validate -m server:agent_loop
✓ Agent loop validated successfully
Name: calculator
Tools: 4 (add, subtract, multiply, divide)
本地测试
模板包含一个 test_data.jsonl 测试数据集。设置您的 API 密钥并运行测试：
export OPENAI_API_KEY="your-key-here"
# Run batch tests
uv run osmosis test -m server:agent_loop -d test_data.jsonl
# Limit number of tests
uv run osmosis test -m server:agent_loop -d test_data.jsonl --limit 10
# Use a different model
uv run osmosis test -m server:agent_loop -d test_data.jsonl --model anthropic/claude-sonnet-4-5
开发技巧
启用热重载
在开发过程中启用自动重载，当代码更改时自动重启服务器：
uv run osmosis serve -m server:agent_loop --reload
启用调试日志
将执行轨迹写入文件以便调试：
uv run osmosis serve -m server:agent_loop --log ./logs
logs/
└── {timestamp}/
├── rollout-abc123.jsonl
└── rollout-def456.jsonl
本地模式（无需登录）
跳过登录和平台注册，用于本地开发：
uv run osmosis serve -m server:agent_loop --local
本地模式会禁用 API 密钥认证和平台注册。这仅用于开发环境，不应在生产环境中使用。
下一步
