diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x.json b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x.json new file mode 100644 index 000000000..26522c579 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x.json @@ -0,0 +1,34 @@ +{ + "version.label": { + "message": "1.2.x", + "description": "The label for version 1.2.x" + }, + "sidebar.tutorialSidebar.category.Getting Started": { + "message": "快速上手", + "description": "The label for category 'Getting Started' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.User Guides": { + "message": "用户指南", + "description": "The label for category 'User Guides' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.References": { + "message": "参考", + "description": "The label for category 'References' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Release Notes": { + "message": "版本说明", + "description": "The label for category 'Release Notes' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.model-service": { + "message": "Model Service 参考", + "description": "The label for category 'Model Service References' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.sandbox-agent": { + "message": "Sandbox Agent参考", + "description": "The label for category 'Sandbox Agent References' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Python SDK References": { + "message": "Python SDK 参考", + "description": "The label for category 'Python SDK References' in sidebar 'tutorialSidebar'" + } +} \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Getting Started/installation.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Getting Started/installation.md new file mode 100644 index 000000000..0ab70e55d --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Getting Started/installation.md @@ -0,0 +1,141 @@ +--- +sidebar_position: 3 +--- + +# 安装指南 + +本文档介绍如何使用 `uv` 和 `pip` 安装和设置 ROCK 开发环境。该项目是一个强化学习开放构建工具包，支持多种组件。 + +## 使用 uv（推荐） + +### 快速安装所有依赖 + +```bash +# 安装所有依赖（包括可选依赖） +uv sync --all-extras + +# 安装开发/测试依赖 +uv sync --all-extras --all-groups +``` + +### 安装不同依赖组 + +#### 仅核心依赖 +```bash +uv sync +``` + +#### 管理组件依赖 +```bash +uv sync --extra admin +``` + +#### Rocklet 执行环境依赖 +```bash +uv sync --extra rocklet +``` + +#### 所有依赖 +```bash +uv sync --all-extras +``` + +#### 开发/测试依赖 +```bash +uv sync --all-extras --group test +``` + +## 使用 pip + +### 从 pip 源安装 + +#### 仅核心依赖 +```bash +pip install rl-rock +``` + +#### 管理组件依赖 +```bash +pip install "rl-rock[admin]" +``` + +#### Rocklet 执行环境依赖 +```bash +pip install "rl-rock[rocklet]" +``` + +#### 构建器依赖 +```bash +pip install "rl-rock[builder]" +``` + +#### 安装所有可选依赖 +```bash +pip install "rl-rock[all]" +``` + +### 使用 pip 从源码安装 + +#### 仅核心依赖 +```bash +pip install . +``` + +#### 管理组件依赖 +```bash +pip install ".[admin]" +``` + +#### Rocklet 执行环境依赖 +```bash +pip install ".[rocklet]" +``` + +#### 构建器依赖 +```bash +pip install ".[builder]" +``` + +#### 安装所有可选依赖 +```bash +pip install ".[all]" +``` + +## 可用入口点 + +该包提供以下命令行脚本： + +- `rocklet`: ROCK 执行环境服务器 (rock.rocklet.server:main) +- `admin`: 管理服务器 (rock.admin.main:main) +- `envhub`: 环境中心服务器 (rock.envhub.server:main) +- `rock`: 主 ROCK 命令行接口 (rock.cli.main:main) + +## 开发设置 + +### 使用 uv（推荐） + +```bash +# 克隆并设置开发环境 +git clone +cd ROCK +uv sync --all-extras --group test + +# 运行测试 +uv run pytest + + +### 使用 pip + +```bash +# 开发模式安装所有可选依赖 +pip install -e ".[all]" + +# 分别安装 +pip install -e . +pip install ".[admin]" ".[rocklet]" ".[builder]" +``` + +## 附加说明 + +- 项目配置为默认使用阿里云 PyPI 镜像: `https://mirrors.aliyun.com/pypi/simple/` +- 对于本地开发，运行测试需要 `test` 依赖组 diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Getting Started/quickstart.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Getting Started/quickstart.md new file mode 100644 index 000000000..e0a0891c0 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Getting Started/quickstart.md @@ -0,0 +1,172 @@ +--- +sidebar_position: 2 +--- + +# 快速上手 + +本指南将通过完整的示例演示如何使用 ROCK 创建和管理强化学习环境。ROCK (Reinforcement Open Construction Kit) 是一个全面的沙箱环境管理框架，主要用于强化学习和AI开发环境。 + +## 1. 环境准备 + +我们推荐在 Linux 系统下启动 ROCK，能够尽量复用项目依赖，提升环境拉起速度。如果需要在 macOS 上尝试，可以参考 [MacOS 启动](#7-macos-启动) 一节。 + +在开始之前，请确保您的系统已安装以下依赖项： + +### 1.1 系统要求 + +- **Docker**: ROCK 使用 Docker 进行容器化环境管理 +- **uv**: ROCK 使用 uv 进行依赖管理和虚拟环境创建 + +### 1.2 验证依赖安装 + +```bash +# 验证 Docker 安装 +docker --version + +# 验证 Docker 可用, 且示例中依赖python:3.11镜像 +docker pull python:3.11 + +# 验证 uv 安装 +uv --version + + +``` + +### 1.3 项目初始化 + +```bash +# 克隆项目仓库 +git clone +cd ROCK + +# 创建虚拟环境（使用 uv 托管的 Python, 以python 3.11 版本为例） +uv venv --python 3.11 --python-preference only-managed + +# 安装所有依赖组 +uv sync --all-extras +``` + +> **重要提示**: 为确保 ROCK 能正确挂载项目和虚拟环境及其依赖的 base Python 解释器，强烈推荐使用 uv 托管的 Python 环境而非系统 Python。 + +## 2. 激活虚拟环境 + +在运行任何 ROCK 命令之前，需要先激活虚拟环境。确保 sys.base_prefix 是 uv 管理的环境，类似于 `/root/.local/share/uv/python/cpython-3.11.8-linux-x86_64-gnu` 等路径。 + +```bash +# 激活虚拟环境 +source .venv/bin/activate + +# 验证 Python 环境 +python -c "import sys; print('Base prefix:', sys.base_prefix)" +``` + +> **验证要点**: 确保输出的 base prefix 路径指向 uv 管理的 Python 环境，而非系统 Python。 + +## 3. 验证环境配置 + +激活虚拟环境后，验证依赖安装是否正确： + +```bash +# 检查关键依赖 +python -c "import rock; print(\"Hello ROCK\")" +``` + + +## 4. 启动 ROCK 服务 + +激活虚拟环境后，在项目根目录下，启动 ROCK Admin 服务： + +```bash +# 确保虚拟环境已激活 +source .venv/bin/activate + +# 启动 ROCK Admin 服务（本地环境） +rock admin start +``` + +服务启动后，您将看到类似以下的输出： + +``` +INFO: Started server process [12345] +INFO: Waiting for application startup. +INFO: Application startup complete. +INFO: Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit) +``` + +> **服务说明**: ROCK Admin 服务默认运行在 `http://127.0.0.1:8080`。 + +## 5. 运行示例环境 + +现在可以运行示例环境来验证安装。确保 ROCK 服务正在运行，然后打开一个新的终端窗口执行以下命令： + +```bash +# 确保虚拟环境已激活 +source .venv/bin/activate + +# 运行沙箱示例 +python examples/sandbox_demo.py + +# 运行 GEM 协议示例 +python examples/sokoban_demo.py +``` + +### 5.1 示例说明 + +- **sandbox_demo.py**: 演示如何使用 ROCK 的沙箱 SDK 创建和管理容器化环境 +- **sokoban_demo.py**: 演示如何使用 ROCK 的 GEM 协议兼容接口创建强化学习环境 + +> **运行要求**: 确保 ROCK Admin 服务正在运行，因为示例需要与服务进行通信。 + +## 6. 分布式环境配置（可选） + +对于分布式多机器环境，请确保以下配置一致： + +1. 所有机器上 ROCK 和 uv 的 Python 配置使用相同的根 Python 解释器 +2. Docker 版本在所有节点上保持一致 +3. 网络配置允许各节点间正常通信 + + + +## 7. MacOS 启动 + +在 macOS 上，如果需要启动 Linux 镜像的环境，需要先设置环境变量： + +```bash +export ROCK_WORKER_ENV_TYPE=uv +``` + +在容器启动时，会安装对应的 uv 环境，细节可以参考 `rock/rocklet/local_files/docker_run_with_uv.sh` 脚本。 + +> **注意**: 相比 Linux 系统，macOS 上的启动速度会较慢，且比较依赖网络环境，可以根据实际情况调整脚本。ROCK_WORKER_ENV_TYPE的细节可以参考 [Configuration Guide](../User%20Guides/configuration.md). + + +## 8. 从Pip源启动 + +如果从Pip源启动Admin Server，在参照[安装指南](./installation.md)安装完成ROCK后, 需要设置额外环境变量: + +```bash +export ROCK_WORKER_ENV_TYPE=pip +``` + +(这一启动方式在容器环境启动时会从Pypi源上拉取最新的rocklet并安装, 相对启动速度比较慢, 仅推荐测试使用, 生产上依旧推荐其他的启动方式) + + +## 总结 + +恭喜！您已经成功完成了 ROCK 的快速开始指南。现在您应该能够： + +- 正确设置 ROCK 开发环境 +- 使用 uv 管理的 Python 环境 +- 启动和管理 ROCK 服务 +- 运行示例程序验证安装 +- 在分布式环境中配置 ROCK（如果需要） + +如需深入了解 ROCK 的更多功能，请参考以下文档： + +## 下一步学习 + +- [配置指南](../User%20Guides/configuration.md) - 详细了解 ROCK 的配置选项 +- [API 文档](../References/api.md) - 查看完整的 API 接口 +- [Python SDK 文档](../References/Python%20SDK%20References/python_sdk.md) - 学习如何使用 Python SDK 进行开发 +- [安装指南](./installation.md) - 详细了解 ROCK 安装和配置 +- [概览](../overview.md) - 了解 ROCK 的设计理念 \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Getting Started/rock-agent.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Getting Started/rock-agent.md new file mode 100644 index 000000000..bd2dd69b0 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Getting Started/rock-agent.md @@ -0,0 +1,73 @@ +--- +sidebar_position: 4 +--- + +# Rock Agent 快速启动 + +Rock Agent 是 ROCK 提供的 AI Agent 运行框架，支持在沙箱环境中运行各种类型的 Agent。 + +## 前置条件 + +- 确保有可用的ROCK服务, 如果需要本地拉起服务端, 参考[快速启动](quickstart.md) + +## 使用示例 + +ROCK 提供了两个Hello World Agent 示例，位于 `examples/agents/` 目录下： + +``` +examples/agents/ +├── claude_code/ # ClaudeCode Agent 示例 +└── iflow_cli/ # IFlowCli Agent 示例 +``` + +### 运行 IFlowCli 示例 + +```bash +cd examples/agents/iflow_cli +python iflow_cli_demo.py +``` + +### 运行 ClaudeCode 示例 + +```bash +cd examples/agents/claude_code +python claude_code_demo.py +``` + +## IFlowCli 配置文件 + +配置文件位于 `examples/agents/iflow_cli/rock_agent_config.yaml`： + +```yaml +run_cmd: "iflow -p ${prompt} --yolo" + +runtime_env_config: + type: node + npm_registry: "https://registry.npmmirror.com" + custom_install_cmd: "npm i -g @iflow-ai/iflow-cli@latest" + +env: + IFLOW_API_KEY: "" # 填入你的 API Key + IFLOW_BASE_URL: "" # 填入你的 Base URL + IFLOW_MODEL_NAME: "" # 填入你的模型名称 +``` + +## ClaudeCode 配置文件 + +配置文件位于 `examples/agents/claude_code/rock_agent_config.yaml`： + +```yaml +run_cmd: "claude -p ${prompt}" + +runtime_env_config: + type: node + custom_install_cmd: "npm install -g @anthropic-ai/claude-code" + +env: + ANTHROPIC_BASE_URL: "" # 填入你的anthropic base url + ANTHROPIC_API_KEY: "" # 填入你的anthropic api key +``` + +## 相关文档 + +- [RockAgent 参考](../References/Python%20SDK%20References/rock-agent.md) diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Getting Started/rockroll.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Getting Started/rockroll.md new file mode 100644 index 000000000..3b53810ba --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Getting Started/rockroll.md @@ -0,0 +1,200 @@ +--- +sidebar_position: 7 +--- + +# ROCK & ROLL 快速开始指南 + +本指南将引导您使用 ROLL (训练框架) 和 ROCK (环境管理) 来运行一个基于 Sokoban 游戏（推箱子）的强化学习训练示例。 + +## 1. 单机环境准备 + +在开始之前，请先确保您的系统已安装以下依赖项： + +### 1.1 系统要求 + +- **操作系统**: 推荐使用 Linux (如 Ubuntu 20.04+) +- **硬件**: 建议使用 NVIDIA GPU 并安装对应的驱动程序 +- **Docker**: ROCK 使用 Docker 进行容器化环境管理 +- **uv**: ROCK 使用 uv 进行依赖管理和虚拟环境创建 + +### 1.2 验证依赖安装 + +```bash +# 验证 Docker 安装 +docker --version + +# 验证 Docker 可用, 且可提前拉取 Sokoban 游戏环境镜像，避免训练时等待 +docker pull rock-n-roll-registry.cn-hangzhou.cr.aliyuncs.com/rock/sokoban-sandbox:latest + +# 验证 uv 安装 +uv --version + +``` + +### 1.3 项目初始化 + +```bash +# 克隆项目仓库 +git clone https://github.com/alibaba/ROCK.git +git clone https://github.com/alibaba/ROLL.git + +# 确保两个仓库位于同一级目录下，如下所示： +# your-workspace/ +# ├── ROCK/ +# └── ROLL/ +``` + + +## 2. 启动训练流程 + +> 说明：下文均以 *torch2.6.0 + vLLM0.8.4* 为例。 + + +### 方式一： 使用虚拟环境启动（推荐） + +#### 为什么推荐这种方式？ +- 隔离性：uv 虚拟环境能确保项目依赖与系统环境隔离，避免冲突。 +- 速度快：ROCK 可以复用此虚拟环境，大大加快了后续环境的启动速度。 +- 稳定性：依赖关系更清晰，环境更易复现。 + + +```bash +# 进入 ROCK 目录 +cd ROCK + +# 使用 uv 创建并激活 Python 3.10 虚拟环境（ROLL推荐使用Python 3.10） +uv venv --python 3.10 --python-preference only-managed + +# 激活虚拟环境 +source .venv/bin/activate + +# 使用uv安装ROCK的依赖 +uv sync --all-extras + +# 若使用Python 3.10, 启动 ray 时会报错：ValueError: is not a valid Sentinel +# 原因是 ray 与 click>=8.3 版本不兼容，需要降级到 click<8.3 +# Python 3.11 不会有这个问题 +uv pip install 'click>=8.2,<8.3' + +# 切换到 ROLL 目录以安装其依赖 +cd ../ROLL + +# 设置国内 PyPI 镜像源以加速下载 +PYPI_MIRROR="https://mirrors.aliyun.com/pypi/simple/" + +# 安装核心 PyTorch 组件 +uv pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 -i $PYPI_MIRROR + +# 安装transformer-engine，--no-build-isolation 避免因环境隔离导致找不到 torch +uv pip install transformer-engine[pytorch]==2.2.0 --no-build-isolation -i $PYPI_MIRROR + +# 安装预编译的 flash-attention，以匹配特定的 CUDA 和 PyTorch 版本 +uv pip install https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.2.post1/flash_attn-2.7.2.post1+cu12torch2.6cxx11abiFALSE-cp310-cp310-linux_x86_64.whl + +# 安装其余依赖 +uv pip install -r requirements_torch260_vllm.txt -i $PYPI_MIRROR + +# (可选) 安装Tensorboard，用于查看训练指标 +uv pip install tensorboard -i $PYPI_MIRROR + +# 启动ROLL脚本（包含ROCK服务的启动） +bash examples/agentic_demo/run_agentic_pipeline_sokoban_sandbox_single_node.sh +``` + +### 方式二：使用系统环境启动（备选方案） + +为获得最佳兼容性，推荐使用 ROLL 官方提供的基础 Docker 镜像，因为它们已经预装了匹配的 CUDA、cuDNN 和其他基础库。 + +> [ROLL 官方镜像列表](https://alibaba.github.io/ROLL/zh-Hans/docs/Getting%20Started/Installation/image_address/) + + +#### 注意 +此方式会将所有 Python 包直接安装到您的当前环境（例如，容器的基础环境）中，可能会与系统自带的包或其他项目产生冲突。 + +由于 ROCK 无法复用环境，每次启动任务时都可能需要重新安装部分依赖，启动速度较慢且受网络影响。 + + +```bash +PYPI_MIRROR="https://mirrors.aliyun.com/pypi/simple/" + +# 安装ROCK的依赖 +cd ROCK +pip install . -i $PYPI_MIRROR +pip install ".[admin]" -i $PYPI_MIRROR + +# 安装ROLL的依赖 +cd ../ROLL +pip install -r requirements_torch260_vllm.txt -i $PYPI_MIRROR + +# 配置ROCK用uv启动的环境变量 +export ROCK_WORKER_ENV_TYPE=uv + +# 启动ROLL脚本（包含ROCK服务的启动） +bash examples/agentic_demo/run_agentic_pipeline_sokoban_sandbox_single_node.sh +``` + +至此，您已成功启动了 Sokoban 强化学习训练流程。祝您 Rock & Roll 愉快！ + + +## 3. 多机部署 + +除了在单机上运行，您也可以将 **ROCK 服务** 和 **ROLL 训练** 部署在不同的机器上，通过网络进行通信。这是一种常见的服务化部署模式。 + +### 3.1 在机器 A 上部署 ROCK 服务 + +在一台独立的机器（或容器）上，参照[ROCK快速指南](./quickstart.md)部署并启动 ROCK 服务。 + +> **重要提示** +> 启动服务后，请记下ROCK服务的IP地址和端口，例如`http://192.168.1.10:8000`，后续步骤将需要这个地址。 + +### 3.2 在机器 B 上准备 ROLL 客户端 + +在另一台将要运行训练任务的机器上，执行以下操作。 + +1. 验证网络连通性 + +首先，使用 curl 命令检查是否能从机器 B 访问到机器 A 上的 ROCK 服务。 +```bash +# 将 : 替换为您的 ROCK 服务实际地址 +# 如果成功，会收到 ROCK 服务的响应 {"message":"hello, ROCK!"} +curl http://: +``` + +2. 准备 ROLL 环境 + +```bash +# 克隆 ROLL 仓库 +git clone https://github.com/alibaba/ROLL.git +cd ROLL + +# 安装依赖 +pip install -r requirements_torch260_vllm.txt -i https://mirrors.aliyun.com/pypi/simple/ +``` + +3. 配置 ROLL 连接地址 + +修改 ROLL 的配置文件，使其能够找到并连接到远程的 ROCK 服务。 +- 打开配置文件：examples/agentic_demo/agentic_val_sokoban_sandbox.yaml +- 找到 SokobanSandbox 下的 env_config 部分 +- 将 base_url 的值修改为您的 ROCK 服务地址 +```yaml +custom_envs: + SokobanSandbox: + env_config: + # 将这里的地址修改为您的 ROCK 服务地址 + # 例如: base_url: 'http://192.168.1.10:8000' + base_url: 'http://:' +``` + +4. 启动训练 +配置完成后，即可在机器 B 上启动 ROLL 训练脚本。 + +```bash +# 此脚本现在会通过网络请求机器 A 上的 ROCK 服务来创建环境 +bash examples/agentic_demo/run_agentic_pipeline_sokoban_sandbox_multi_nodes.sh +``` + +### 进阶：分布式 ROLL 训练 + +如果您希望将 ROLL 训练任务本身进行分布式部署，可以参考 ROLL 的官方分布式部署文档。 +> [快速上手：多节点部署指南](https://alibaba.github.io/ROLL/zh-Hans/docs/Getting%20Started/Quick%20Start/multi_nodes_quick_start) \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/codes.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/codes.md new file mode 100644 index 000000000..47b74166d --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/codes.md @@ -0,0 +1,93 @@ +# Error Codes + +错误码定义和分类，用于错误处理和重试策略。 + +## 使用示例 + +```python +import rock + +def test_codes_values(): + """测试基本状态码值""" + assert rock.codes.OK == 2000 + assert rock.codes.BAD_REQUEST == 4000 + assert rock.codes.INTERNAL_SERVER_ERROR == 5000 + assert rock.codes.COMMAND_ERROR == 6000 +``` + +## Codes 分类 + +```python +OK = 2000, "OK" +""" +成功状态码 (2xxx) +""" + +BAD_REQUEST = 4000, "Bad Request" +""" +客户端错误码 (4xxx): + +这些错误表示客户端请求有问题， +SDK 会抛出异常。 +""" + +INTERNAL_SERVER_ERROR = 5000, "Internal Server Error" +""" +服务端错误码 (5xxx): + +这些错误表示服务端出现问题， +SDK 会抛出异常。 +""" + +COMMAND_ERROR = 6000, "Command Error" +""" +命令/执行错误码 (6xxx): + +这些错误与命令执行相关，由模型处理， +SDK 不会抛出异常。 +""" +``` + +## 重试策略建议 + +- **重试触发条件**: 只有当 `INTERNAL_SERVER_ERROR` 时才需要重试 +- **其他情况的处理策略**: + - `BAD_REQUEST`: 需要检查 arun 调用逻辑是否有异常 + - `COMMAND_ERROR`: stdout 输出到 `observation.output`，stderr 输出到 `observation.failure_reason` +- `COMMAND_ERROR` 说明: 由于 bash 执行失败时，stdout/stderr 可能全部非空，建议将 observation 中 output 和 failure_reason 全部 prompt 给模型进行推理 + +## 重试示例 + +```python +# Background execution with nohup +while retry_times < retry_limit: + try: + observation: Observation = await sandbox.arun( + "python long_running_script.py", + mode="nohup" + ) + if observation.exit_code != 0: + logging.warning( + f"Command failed with exit code {observation.exit_code}, " + f"output: {observation.output}, failure_reason: {observation.failure_reason}" + ) + return observation + except RockException as e: + if rock.codes.is_server_error(e.code): + if retry_times >= retry_limit: + logging.error(f"All {retry_limit} attempts failed") + raise e + else: + retry_times += 1 + logging.error( + f"Server error occurred, code: {e.code}, message: {e.code.get_reason_phrase()}, " + f"exception: {str(e)}, will retry, times: {retry_times}." + ) + await asyncio.sleep(2) + continue + else: + logging.error( + f"Non-retriable error occurred, code: {e.code}, message: {e.code.get_reason_phrase()}, exception: {str(e)}." + ) + raise e +``` diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/deploy.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/deploy.md new file mode 100644 index 000000000..b4f10529b --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/deploy.md @@ -0,0 +1,20 @@ +# Deploy + +沙箱资源部署管理器，用于本地目录部署和模板格式化。 + +## 使用示例 + +```python +sandbox = Sandbox(config) +deploy = sandbox.deploy + +# 部署本地目录到沙箱 +target = await deploy.deploy_working_dir( + local_path="/local/path", # 本地目录 + target_path="/remote/path", # 可选，目标路径 +) + +# 使用 ${working_dir} 模板变量 +cmd = deploy.format("mv ${working_dir}/config.json /root/.app/") +# 结果: mv /tmp/rock_workdir_xxx/config.json /root/.app/ +``` diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/file_system.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/file_system.md new file mode 100644 index 000000000..741b14f5e --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/file_system.md @@ -0,0 +1,94 @@ +# FileSystem + +文件系统操作接口，提供沙箱环境中的权限管理和目录上传功能。 + +## chown - 修改所有者 + +```python +from rock.actions.sandbox.request import ChownRequest + +# 创建远程用户后修改所有者 +await sandbox.remote_user.create_remote_user("deploy") + +# 获取当前目录 +pwd_response = await sandbox.execute(Command(command=["pwd"])) +pwd = pwd_response.stdout.strip() + +# 修改目录所有者 +await sandbox.fs.chown( + ChownRequest( + paths=[pwd], + remote_user="deploy", + recursive=False, + ) +) + +# 递归修改目录及其内容所有者 +await sandbox.fs.chown( + ChownRequest( + paths=["/home/user/project"], + remote_user="deploy", + recursive=True, + ) +) +``` + +## chmod - 修改权限 + +```python +from rock.actions.sandbox.request import ChmodRequest + +# 创建测试目录 +await sandbox.execute(Command(command=["mkdir", "-p", "/tmp/app"])) + +# 修改目录权限 +await sandbox.fs.chmod( + ChmodRequest( + paths=["/tmp/app"], + mode="755", + recursive=False, + ) +) + +# 递归修改权限（包括子目录和文件） +await sandbox.fs.chmod( + ChmodRequest( + paths=["/tmp/app"], + mode="644", + recursive=True, + ) +) + +# 设置最高权限 +await sandbox.fs.chmod( + ChmodRequest( + paths=["/tmp/shared"], + mode="777", + recursive=True, + ) +) +``` + +## upload_dir - 上传目录 + +```python +import os +from pathlib import Path + +# 准备本地目录 +local_dir = Path("/Users/foo/my-project") +(local_dir / "config.json").write_text('{"key": "value"}') +(local_dir / "app.py").write_text("print('hello')") + +# 上传到沙箱 +result = await sandbox.fs.upload_dir( + source_dir=str(local_dir), + target_dir="/root/project", + extract_timeout=600, +) + +if result.exit_code == 0: + print(f"上传成功: {result.output}") +else: + print(f"上传失败: {result.failure_reason}") +``` diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/model-service.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/model-service.md new file mode 100644 index 000000000..ba158cf75 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/model-service.md @@ -0,0 +1,298 @@ +# Model Service（实验性） + +ROCK 提供的 Model Service 负责处理 AI 模型调用的通信，为代理(Agent)和训练框架(如 Roll)或实际的 LLM 推理服务之间提供通信桥梁。 + +## 与 RockAgent 集成 + +ModelService 通常由 **RockAgent** 自动管理，无需手动调用生命周期方法。只需在配置中启用即可： + +```python +from rock.sdk.sandbox.model_service.base import ModelServiceConfig + +config = ModelServiceConfig( + enabled=True, # 启用 ModelService，RockAgent 会自动管理其生命周期 +) +``` + +RockAgent 会自动： +- 安装 ModelService（安装 Python 运行时环境、安装模型服务包） +- 启动/停止 ModelService +- 监控 Agent 进程 + +## 架构概述（Local 模式） + +Local 模式下，模型服务使用**文件系统**作为通信媒介，实现代理和模型间的请求-响应机制。 + +当 Agent 需要调用模型时，请求首先写入日志文件，然后由负责监听的组件处理响应。当模型生成响应后，结果将写回日志文件，并由等待的 Agent 读取。 + +## anti_call_llm - 核心 API + +`anti_call_llm()` 是 **Local 模式**下最重要的 API，用于手动触发 LLM 反调用，实现模型调用的精细控制： + +```python +result = await model_service.anti_call_llm( + index=0, # LLM 调用索引 + response_payload='OpenAI type response', # 响应数据（可选） + call_timeout=600, # 操作超时（秒） + check_interval=3, # 状态检查间隔（秒） +) +``` + +**使用场景：** +- Agent 捕获到 LLM 响应后，调用此方法通知 Roll 运行时 +- 支持携带响应数据，用于错误处理或重试 +- 超时和检查间隔可配置，适应不同网络环境 + +## CLI 命令 + +如果需要通过 CLI 使用模型服务，ROCK 提供了一个 CLI 命令集，可以在沙箱中安装 ROCK 后，通过 `rock model-service` 访问： + +### start 命令 +开始模型服务进程 +```bash +rock model-service start --type [local|proxy] [选项] +``` + +参数: + +| 参数 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `--type` | str | `local` | 服务类型：`local` 或 `proxy` | +| `--config-file` | str | None | 配置文件路径 | +| `--host` | str | None | 服务器地址（覆盖配置） | +| `--port` | int | None | 服务器端口（覆盖配置） | +| `--proxy-base-url` | str | None | 代理基础 URL | +| `--retryable-status-codes` | str | None | 可重试状态码，逗号分隔 | +| `--request-timeout` | int | None | 请求超时秒数 | + +### watch-agent 命令 +监控代理进程，当进程退出时发送 SESSION_END 消息 +```bash +rock model-service watch-agent --pid <进程ID> +``` + +参数: +- `--pid`: 需要监控的代理进程 ID + +### stop 命令 +停止模型服务 +```bash +rock model-service stop +``` + +### anti-call-llm 命令 +反调用 LLM 接口 +```bash +rock model-service anti-call-llm --index <索引> [--response <响应>] +``` + +参数: +- `--index`: 上一个 LLM 调用的索引，从 0 开始 +- `--response`: 上一次 LLM 调用的响应（可选） + +## 文件通信协议 + +模型服务使用文件进行进程间通信，定义了特定的标记格式用于区分请求和响应： + +### 请求格式 +``` +LLM_REQUEST_START{JSON请求数据}LLM_REQUEST_END{元数据JSON} +``` + +### 响应格式 +``` +LLM_RESPONSE_START{JSON响应数据}LLM_RESPONSE_END{元数据JSON} +``` + +### 会话结束标识 +``` +SESSION_END +``` + +元数据包含时间戳和索引信息，用于保证消息顺序和处理。 + +## SDK 使用 + +### ModelServiceConfig + +模型服务配置类，位于 `rock/sdk/sandbox/model_service/base.py`： + +```python +from rock.sdk.sandbox.model_service.base import ModelServiceConfig + +config = ModelServiceConfig( + enabled=True, + type="local", # 服务类型 + install_cmd="pip install rock-model-service", # 安装命令 + install_timeout=300, # 安装超时（秒） + start_cmd="rock model-service start --type ${type}", # 启动命令 + stop_cmd="rock model-service stop", # 停止命令 + logging_path="/data/logs", # 日志路径 + logging_file_name="model_service.log", # 日志文件名 +) +``` + +| 配置项 | 默认值 | 说明 | +|--------|--------|------| +| `enabled` | `False` | 是否启用模型服务（RockAgent 自动管理） | +| `type` | `"local"` | 服务类型：`local` 或 `proxy` | +| `install_cmd` | - | 模型服务包安装命令 | +| `install_timeout` | `300` | 安装超时时间（秒） | +| `start_cmd` | - | 启动命令模板 | +| `stop_cmd` | - | 停止命令 | +| `logging_path` | `/data/logs` | 日志目录路径 | +| `logging_file_name` | `model_service.log` | 日志文件名 | + +### ModelService + +模型服务管理类，处理沙箱内模型服务的生命周期： + +```python +from rock.sdk.sandbox.client import Sandbox +from rock.sdk.sandbox.model_service.base import ModelServiceConfig, ModelService + +sandbox = Sandbox(config) +model_service = ModelService(sandbox, ModelServiceConfig()) + +# 通常由 RockAgent 自动管理，无需手动调用 +# 以下方法仅在需要手动控制时使用 + +# 安装模型服务 +await model_service.install() + +# 启动模型服务 +await model_service.start() + +# 监控代理进程 +await model_service.watch_agent(pid="12345") + +# 执行反调用 LLM（Local 模式核心 API） +result = await model_service.anti_call_llm( + index=0, + response_payload='{"content": "response"}', + call_timeout=600, + check_interval=3, +) + +# 停止模型服务 +await model_service.stop() +``` + +## API 参考 + +### install() + +在沙箱中安装模型服务依赖。 + +```python +await model_service.install() +``` + +执行步骤： +1. 创建并初始化 Python 运行时环境 +2. 创建 Rock 配置文件 +3. 安装模型服务包 + +**注意：** 通常由 RockAgent 自动调用。 + +### start() + +启动模型服务。 + +```python +await model_service.start() +``` + +前提条件：必须先调用 `install()`。 + +**注意：** 通常由 RockAgent 自动调用。 + +### stop() + +停止模型服务。 + +```python +await model_service.stop() +``` + +如果服务未运行，会跳过此操作。 + +**注意：** 通常由 RockAgent 自动调用。 + +### watch_agent(pid) + +监控代理进程。 + +```python +await model_service.watch_agent(pid="12345") +``` + +当进程退出时，发送 `SESSION_END` 消息。 + +### anti_call_llm(index, response_payload, call_timeout, check_interval) + +执行反调用 LLM 操作。**这是 Local 模式下最重要的 API。** + +```python +result = await model_service.anti_call_llm( + index=0, # LLM 调用索引 + response_payload='{"result": "..."}', # 响应数据（可选） + call_timeout=600, # 操作超时（秒） + check_interval=3, # 状态检查间隔（秒） +) +``` + +## 配置选项 + +### 服务配置 +- `SERVICE_HOST`: 服务主机地址，默认为 `"0.0.0.0"` +- `SERVICE_PORT`: 服务端口，默认为 `8080` + +### 日志配置 +- `LOG_FILE`: 用以通信的日志文件路径，包含请求和响应数据 + +### 轨迹（Traj）日志记录 +模型服务将 LLM 调用轨迹（traj）记录到 JSONL 文件中，用于调试和分析。 + +| 环境变量 | 默认值 | 说明 | +|----------|--------|------| +| `ROCK_MODEL_SERVICE_DATA_DIR` | `/data/logs` | traj 日志文件目录 | +| `ROCK_MODEL_SERVICE_TRAJ_APPEND_MODE` | `false` | 追加模式（true/false） | + +**traj 文件位置**: `{DATA_DIR}/LLMTraj.jsonl` + +**traj 文件格式**（JSONL - 每行一个 JSON 对象）： +```json +{"request": {...}, "response": {...}} +``` + +### 轮询配置 +- `POLLING_INTERVAL_SECONDS`: 轮询间隔，默认为 `0.1` 秒 +- `REQUEST_TIMEOUT`: 请求超时时间，默认为无限 + +### 标记配置 +定义了用于区分日志文件中不同类型消息的标记： +- `REQUEST_START_MARKER` / `REQUEST_END_MARKER` +- `RESPONSE_START_MARKER` / `RESPONSE_END_MARKER` +- `SESSION_END_MARKER` + +### ModelServiceConfig（服务端） + +服务端配置类定义了模型服务如何处理请求： + +| 字段 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `host` | str | `"0.0.0.0"` | 服务器地址 | +| `port` | int | `8080` | 服务器端口 | +| `proxy_base_url` | str \| None | `None` | 直接代理 URL | +| `proxy_rules` | dict | 见下方 | 模型名称到 URL 的映射 | +| `retryable_status_codes` | list[int] | `[429, 500]` | 可重试的 HTTP 状态码 | +| `request_timeout` | int | `120` | 请求超时时间（秒） | + +**默认 proxy_rules**: +```python +{ + "gpt-3.5-turbo": "https://api.openai.com/v1", + "default": "https://api-inference.modelscope.cn/v1", +} +``` diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/python_sdk.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/python_sdk.md new file mode 100644 index 000000000..c1083f29b --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/python_sdk.md @@ -0,0 +1,265 @@ +--- +sidebar_position: 2 +--- + +# Python SDK 参考 + +本指南详细介绍如何使用 ROCK SDK 进行开发，包括沙箱环境管理和 GEM 环境交互。 + +## 1. 概述 + +ROCK SDK为开发者提供了便捷的Python接口来使用ROCK平台的功能，包括沙箱环境管理和GEM环境交互。 + +> **重要提示**: 使用 SDK 之前，请确保 ROCK Admin 服务正在运行。可以通过以下命令启动： +> ```bash +> rock admin start +> ``` + +## 2. Sandbox SDK + +### 2.1 基本沙箱操作 + +```python +import asyncio + +from rock.actions import CreateBashSessionRequest +from rock.sdk.sandbox.client import Sandbox +from rock.sdk.sandbox.config import SandboxConfig + +async def run_sandbox(): + """Run sandbox demo with admin server requirement. + + NOTE: This demo requires the admin server to be running for proper execution. + Make sure to start the admin server before running this script. + Default admin server port is 8080. + """ + # Create sandbox configuration + config = SandboxConfig(image="python:3.11", memory="8g", cpus=2.0) + + # Create sandbox instance + sandbox = Sandbox(config) + + # Start sandbox (connects to admin server) + await sandbox.start() + + # Create session in sandbox for command execution + await sandbox.create_session(CreateBashSessionRequest(session="bash-1")) + + # Execute command in sandbox session + result = await sandbox.arun(cmd="echo Hello ROCK", session="bash-1") + print("\n" + "*" * 50 + "\n" + result.output + "\n" + "*" * 50 + "\n") + + # Stop and clean up sandbox resources + await sandbox.stop() + +if __name__ == "__main__": + # Ensure admin server is running before executing + print("IMPORTANT: Make sure the admin server is running before executing this demo!") + print("Start the admin server with: rock admin start") + asyncio.run(run_sandbox()) +``` + +### 2.2 沙箱组管理 + +```python +from rock.sdk.sandbox.config import SandboxGroupConfig + +# 创建沙箱组配置 +config = SandboxGroupConfig( + image="python:3.11", + size=4, # 创建4个沙箱 + start_concurrency=2, # 并发启动级别为2 +) + +# 创建并启动沙箱组 +sandbox_group = SandboxGroup(config) +await sandbox_group.start() + +# 批量操作 +for sandbox in sandbox_group.sandbox_list: + await sandbox.run_in_session(Action(session="default", command="echo Hello")) + +# 批量停止 +await sandbox_group.stop() +``` + +### 2.3 配置示例 + +```python +config = SandboxConfig( + image="python:3.11", + auto_clear_seconds=60 * 20, + experiment_id="test", +) +``` + +### 2.4 沙箱加速配置 + +ROCK 提供沙箱网络加速功能，支持配置 APT、PIP 和 GitHub 镜像源，提升受限网络环境下的包下载速度。 + +#### 支持的加速类型 + +**APT 镜像配置** + +配置 APT 包管理器镜像源，加速 Debian/Ubuntu 软件包下载。 + +```python +from rock.sdk.sandbox.speedup import SpeedupType + +# 配置 APT 镜像 +await sandbox.network.speedup( + speedup_type=SpeedupType.APT, + speedup_value="http://mirrors.cloud.aliyuncs.com" +) +``` + +**PIP 镜像配置** + +配置 Python 包索引镜像，加速 pip 安装。 + +```python +# HTTP 镜像 +await sandbox.network.speedup( + speedup_type=SpeedupType.PIP, + speedup_value="http://mirrors.cloud.aliyuncs.com" +) + +# HTTPS 镜像 +await sandbox.network.speedup( + speedup_type=SpeedupType.PIP, + speedup_value="https://mirrors.aliyun.com" +) +``` + +**GitHub 加速** + +通过添加自定义 DNS 解析条目加速 GitHub 访问。 + +```python +await sandbox.network.speedup( + speedup_type=SpeedupType.GITHUB, + speedup_value="11.11.11.11" +) +``` + +#### 完整示例 + +```python +from rock.sdk.sandbox.speedup import SpeedupType +from rock.actions import RunMode + +async def setup_sandbox_with_speedup(): + """创建沙箱并配置加速""" + config = SandboxConfig(image="python:3.11") + sandbox = Sandbox(config) + + await sandbox.start() + + # 配置加速（在安装包之前配置） + await sandbox.network.speedup( + speedup_type=SpeedupType.APT, + speedup_value="http://mirrors.cloud.aliyuncs.com" + ) + + await sandbox.arun(cmd="apt-get update && apt-get install -y git", mode=RunMode.NOHUP) + + await sandbox.network.speedup( + speedup_type=SpeedupType.PIP, + speedup_value="https://mirrors.aliyun.com" + ) + + # speedup 不会主动安装 PIP，仅配置镜像源进行加速 + await sandbox.arun(cmd="pip install numpy", mode=RunMode.NOHUP) + + # 可以通过镜像 IP 加速 GitHub 访问 + await sandbox.network.speedup( + speedup_type=SpeedupType.GITHUB, + speedup_value="11.11.11.11" + ) + + return sandbox +``` + +#### 注意事项 + +1. **配置顺序**: 在安装包之前配置加速 +2. **HTTPS vs HTTP**: HTTPS 镜像不需要为 PIP 配置 trusted-host +3. **GitHub IP**: 不同区域可能需要不同的 IP 以获得最佳性能 +4. **持久性**: 配置在沙箱生命周期内持久有效 +5. **多次调用**: 后续的加速调用会覆盖之前的配置 +6. **PIP 安装**: speedup 功能仅配置镜像源，不会自动安装 PIP + +## 3. GEM SDK + +### 3.1 Python SDK 方式 + +```python +import random +import rock + +def main(): + """Main function to run the Sokoban demo with admin server requirement. + + NOTE: This demo requires the admin server to be running for proper execution. + Make sure to start the admin server before running this script. + """ + # Create environment using GEM standard interface + # NOTE: This requires the admin server to be running + env_id = "game:Sokoban-v0-easy" + env = rock.make(env_id) + + # Reset environment to initial state + observation, info = env.reset(seed=42) + print( + "\n" + + "=" * 80 + + "\nInitial Observation:\n" + + str(observation) + + "\n\nInitial Info:\n" + + str(info) + + "\n" + + "=" * 80 + + "\n" + ) + + # Run environment loop until termination + step_count = 0 + while True: + # Interactive environment operation with random actions + action = f"\\boxed{{{random.choice(['up', 'left', 'right', 'down'])}}}" + observation, reward, terminated, truncated, info = env.step(action) + + step_count += 1 + print( + "\n" + + "-" * 80 + + f"\nStep {step_count} - Action: {action}\nReward: {reward}\nObservation:\n{observation}\nInfo: {info}\nTerminated: {terminated}, Truncated: {truncated}\n" + + "-" * 80 + + "\n" + ) + + # Check if environment has reached terminal state + if terminated or truncated: + print("\n" + "=" * 80 + "\nEpisode finished!\n" + "=" * 80 + "\n") + break + + # Clean up environment resources + env.close() + +if __name__ == "__main__": + # Ensure admin server is running before executing + print( + "\n" + + "=" * 80 + + "\nIMPORTANT: Make sure the admin server is running before executing this demo!\nStart the admin server with: rock admin start\n" + + "=" * 80 + + "\n" + ) + main() +``` + +## 相关文档 +- [快速开始指南](../../Getting%20Started/quickstart.md) - 了解如何快速开始使用 ROCK SDK +- [API 文档](../api.md) - 查看 SDK 封装的底层 API 接口 +- [配置指南](../../User%20Guides/configuration.md) - 了解 SDK 相关的配置选项 +- [安装指南](../../Getting%20Started/installation.md) - 详细了解 ROCK 安装和配置 \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/remote_user.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/remote_user.md new file mode 100644 index 000000000..791ca85fd --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/remote_user.md @@ -0,0 +1,69 @@ +# Remote User + +远程用户管理，用于在沙箱中创建和管理用户。 + +## 使用示例 + +```python +import asyncio +from rock.sdk.sandbox.config import SandboxConfig +from rock.sdk.sandbox.client import Sandbox + +from rock.actions import Action, CreateBashSessionRequest, Observation + +async def test_remote_user(): + config = SandboxConfig( + image='hub.docker.alibaba-inc.com/chatos/python:3.11', + xrl_authorization='xxx', + cluster='nt-c' + ) + sandbox = Sandbox(config) + await sandbox.start() + + await sandbox.remote_user.create_remote_user('rock') + assert await sandbox.remote_user.is_user_exist('rock') + print('test remote user success') + +async def test_create_session_with_remote_user(): + config = SandboxConfig( + image='hub.docker.alibaba-inc.com/chatos/python:3.11', + xrl_authorization='xxx', + cluster='nt-c' + ) + sandbox = Sandbox(config) + await sandbox.start() + + await sandbox.remote_user.create_remote_user('rock') + assert await sandbox.remote_user.is_user_exist('rock') + + await sandbox.create_session(CreateBashSessionRequest(remote_user="rock", session="bash")) + + observation: Observation = await sandbox.run_in_session( + action=Action(session="bash", command="whoami") + ) + print(observation) + assert observation.output.strip() == "rock" + print('test create session with remote user success') + +if __name__ == '__main__': + asyncio.run(test_remote_user()) + asyncio.run(test_create_session_with_remote_user()) +``` + +## API + +### create_remote_user(username) + +创建远程用户。 + +```python +await sandbox.remote_user.create_remote_user('username') +``` + +### is_user_exist(username) + +检查用户是否存在。 + +```python +exists = await sandbox.remote_user.is_user_exist('username') +``` diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/rock-agent.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/rock-agent.md new file mode 100644 index 000000000..460723511 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/rock-agent.md @@ -0,0 +1,283 @@ +# Rock Agent（实验性） + +RockAgent 是 ROCK 框架中的核心 Agent 实现，直接继承自 `Agent` 抽象基类。它提供了完整的 Agent 生命周期管理，包括环境初始化、ModelService 集成、命令执行等功能。 + +使用 `sandbox.agent.install()` 以及 `sandbox.agent.run(prompt)` 就可以在 Rock 提供的 Sandbox 环境中安装和运行 Agent。 + +## 核心概念 + +RockAgent 的核心工作流程分为两个阶段： + +1. **install(config)**: 初始化 Agent 环境，包括部署工作目录、设置环境变量、初始化运行时环境等 +2. **run(prompt)**: 执行 Agent 任务，替换占位符并启动 Agent 进程 + +## 快速开始 + +### Claude Code 示例 + +```yaml +run_cmd: "claude -p ${prompt}" + +runtime_env_config: + type: node + custom_install_cmd: "npm install -g @anthropic-ai/claude-code" + +env: + ANTHROPIC_BASE_URL: "" + ANTHROPIC_API_KEY: "" +``` + +### IFlowCli 示例 + +```yaml +run_cmd: "iflow -p ${prompt} --yolo" # ${prompt} 必须 + +runtime_env_config: + type: node + custom_install_cmd: "npm i -g @iflow-ai/iflow-cli@latest" + +env: # 环境变量 + IFLOW_API_KEY: "xxxxxxx" + IFLOW_BASE_URL: "xxxxxxx" + IFLOW_MODEL_NAME: "xxxxxxx" +``` + +### LangGraph Agent 示例 + +```yaml +working_dir: "." # 上传包含 langgraph_agent.py 的本地当前目录到 sandbox + +run_cmd: "python langgraph_agent.py ${prompt}" # 运行本地脚本 + +runtime_env_config: + type: python + pip: # 安装 pip 依赖 + - langchain==1.2.3 + - langchain-openai==1.1.7 + - langgraph==1.0.6 + +env: + OPENAI_API_KEY: xxxxxxx +``` + +## 配置详解 + +### 基础配置 + +```yaml +agent_type: "default" # Agent 类型标识（默认: "default"） +agent_name: "demo-agent" # Agent 实例名称（默认: 随机 uuid） +version: "1.0.0" # 版本标识（默认: "default"） +instance_id: "instance-001" # 实例 ID（默认: "instance-id-<随机uuid>"） +agent_installed_dir: "/tmp/installed_agent" # Agent 安装目录（默认: "/tmp/installed_agent"） +agent_session: "my-session" # bash 会话标识（默认: "agent-session-<随机uuid>"） +env: # 环境变量（默认: {}） + OPENAI_API_KEY: "xxxxxxx" +``` + +### 工作目录配置 + +```yaml +working_dir: "./my_project" # 本地目录，上传到 sandbox（默认: None 不上传） +project_path: "/testbed" # sandbox 中工作目录，用于 cd（默认: None） +use_deploy_working_dir_as_fallback: true # project_path 为空时是否回退到 deploy.working_dir（默认: true） +``` + +### 执行配置 + +```yaml +run_cmd: "python main.py --prompt ${prompt}" # Agent 执行命令，必须包含 ${prompt}（默认: None） + +# 超时配置 +agent_install_timeout: 600 # 安装超时，单位秒（默认: 600） +agent_run_timeout: 1800 # 运行超时，单位秒（默认: 1800） +agent_run_check_interval: 30 # 检查间隔，单位秒（默认: 30） +``` + +### 初始化钩子 + +```yaml +pre_init_cmds: # 初始化前执行的命令（默认: 从 env_vars 读取） + - command: "apt update && apt install -y git" + timeout_seconds: 300 # 命令超时，单位秒（默认: 300） + - command: "cp ${working_dir}/config.json /root/.config/config.json" + timeout_seconds: 60 + +post_init_cmds: # 初始化后执行的命令（默认: []） + - command: "echo 'Installation complete'" + timeout_seconds: 30 +``` + +**注意事项**： +- `pre_init_cmds` 和 `post_init_cmds` 不继承 Agent 的 `env` 环境变量 +- 通常用于执行安装操作和配置文件移动操作 +- 常用命令示例： + - `apt update && apt install -y git wget tar` + - `cp ${working_dir}/config.json /root/.config/config.json` + +### RuntimeEnv 配置 + +```yaml +runtime_env_config: # 具体参考 RuntimeEnv 有关文档 + type: "python" # 运行时类型: python / node（默认: "python"） + version: "3.11" # 版本号 + pip: # Python 依赖包列表 + - package1==1.0.0 + - package2==2.0.0 + custom_install_cmd: "git clone https://github.com/SWE-agent/SWE-agent.git && cd SWE-agent && pip install -e ." +``` + +**Node 运行时示例**： + +```yaml +runtime_env_config: + type: "node" + version: "22.18.0" + npm_registry: "https://registry.npmmirror.com" + custom_install_cmd: "npm i -g some-package" +``` + +**自动执行的操作**： +- 根据 `type` 安装对应的运行时（Python 或 Node.js） +- 安装 `pip` 依赖（如果配置了） +- 执行 `custom_install_cmd` 自定义安装命令（如果配置了） +- 支持 `npm_registry` 配置 Node.js 的 npm 镜像源 + +### ModelService 配置 + +```yaml +model_service_config: # 具体参考 ModelService 有关文档 + enabled: true # 启用 ModelService（默认: false） +``` + +**自动执行的操作**： +- 安装阶段：安装 ModelService（仅安装，不启动） +- 运行阶段：启动 ModelService + `watch_agent` 监控进程 + +**注意事项**：需要将模型请求的 URL 设置为 ModelService 的 URL。例如 ModelService 提供的 OpenAI-compatible 的 URL 为 `http://127.0.0.1:8080/v1/chat/completions`，则通常需要将 Agent 向 LLM 请求的 URL 设置为 `http://127.0.0.1:8080/v1/`。 + +## API 参考 + +### install(config) + +初始化 Agent 环境。 + +**执行流程**： +1. 如果配置了 `working_dir`，部署到 sandbox +2. 设置 bash session，以及配置 env 环境变量 +3. 执行 `pre_init_cmds` +4. 并行初始化 RuntimeEnv 和 ModelService（如果启用） +5. 执行 `post_init_cmds` + +**参数**： +- `config`: Agent 配置文件，支持两种传入方式： + - **字符串路径**: YAML 配置文件路径，默认值为 `"rock_agent_config.yaml"` + - **RockAgentConfig 对象**: 直接传入 `RockAgentConfig` 实例 + +### run(prompt) + +执行 Agent 任务。 + +**执行流程**： +1. 替换占位符, 准备Agent 运行命令 +4. 启动 agent 进程 +5. 如果启用 ModelService，启动 `watch_agent` +6. 等待任务完成并返回结果 + +## 高级用法 + +### working_dir 与 project_path 的区别与联动 + +| 配置项 | 作用 | 联动方式 | +|--------|------|----------| +| `working_dir` | 本地目录，上传到 sandbox | 调用 `deploy.deploy_working_dir()` 上传，上传后 `deploy.working_dir` 变为 sandbox 中的路径 | +| `${working_dir}` | 命令中的占位符 | 被 `deploy.format()` 替换为 `deploy.working_dir` 的值，会在配置中的 init_cmds 和 run_cmd 中替换 | +| `project_path` | sandbox 中的工作目录 | 用于运行前 `cd project_path`，不设置时会进入到 `deploy.working_dir` 工作目录 | +| `use_deploy_working_dir_as_fallback` | run 时 project_path 未设置时是否回退到 deploy.working_dir | 默认为 `true`，设为 `false` 时即使未设置 project_path 也不会进入 working_dir | + +**使用建议**： +- 使用 `working_dir` 上传本地项目代码到 sandbox +- 使用 `project_path` 指定 sandbox 中的工作目录（如 `/testbed`） +- 设置 `use_deploy_working_dir_as_fallback: false` 的场景：需要进行本地文件挂载，但希望在镜像默认工作目录下运行 Agent + +### 占位符使用 + +Rock Agent 在支持在配置文件中替换以下占位符： + +- `${prompt}`: 在run_cmd 中必需，会被替换为 `run(prompt)` 传入的提示词 +- `${working_dir}`: 可选，会被替换为 sandbox 中实际的工作目录路径, 同时支持在 init_cmds和 run_cmd 中使用 + +**示例**： +```yaml +run_cmd: "python ${working_dir}/main.py --prompt ${prompt}" +``` + +### use_deploy_working_dir_as_fallback 说明 + +当 `project_path` 未设置时： +- `true`（默认）：运行 Agent 前会自动 `cd` 到 `deploy.working_dir` +- `false`：运行 Agent 前不会自动切换目录，保持在当前目录 + +适用场景： +- `true`: 大多数场景，希望 Agent 在上传的代码目录中运行 +- `false`: 需要挂载本地文件，但希望在镜像默认工作目录（如 `/app, /testbed`）下运行 Agent + +## 完整配置示例 + +```yaml +# ========== 基础配置 ========== +agent_type: "default" +agent_name: "demo-agent" +version: "1.0.0" +instance_id: "instance-001" +agent_installed_dir: "/tmp/installed_agent" +agent_session: "my-session" +env: + OPENAI_API_KEY: "xxxxxxx" + +# ========== 工作目录配置 ========== +working_dir: "./my_project" +project_path: "/testbed" +use_deploy_working_dir_as_fallback: true + +# ========== 运行配置 ========== +run_cmd: "python ${working_dir}/main.py --prompt ${prompt}" + +# 超时配置 +agent_install_timeout: 600 +agent_run_timeout: 1800 +agent_run_check_interval: 30 + +# ========== 初始化命令 ========== +pre_init_cmds: + - command: "apt update && apt install -y git" + timeout_seconds: 300 + - command: "cp ${working_dir}/config.json /root/.config/config.json" + timeout_seconds: 60 + +post_init_cmds: + - command: "echo 'Installation complete'" + timeout_seconds: 30 + +# ========== 运行时环境配置 ========== +runtime_env_config: + type: "python" + version: "3.11" + pip: + - langchain==1.2.3 + - langchain-openai==1.1.7 + +# ========== ModelService 集成 ========== +model_service_config: + enabled: true +``` + +## 使用示例 + +### 使用 YAML 配置文件（推荐） + +```python +# prepare a rock_agent_config.yaml +await sandbox.agent.install(config="rock_agent_config.yaml") +await sandbox.agent.run(prompt="hello") +``` diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/runtime-env.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/runtime-env.md new file mode 100644 index 000000000..a5532e900 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/runtime-env.md @@ -0,0 +1,137 @@ +# RuntimeEnv + +RuntimeEnv 模块用于在沙箱中管理语言运行时环境（目前提供了 Python / Node.js）。 + +## 快速开始(使用示例) + +```python +from rock.sdk.sandbox import Sandbox +from rock.sdk.sandbox.config import SandboxConfig +from rock.sdk.sandbox.runtime_env import RuntimeEnv, NodeRuntimeEnvConfig + +sandbox_config = SandboxConfig() +sandbox = Sandbox() +await sandbox.start() + +node_runtime_env_config = NodeRuntimeEnvConfig(version="default") +env = await RuntimeEnv.create(sandbox, node_runtime_env_config) + +await env.run("node --version") +``` + +## RuntimeEnv.create + +异步工厂方法，根据配置创建 RuntimeEnv 实例并初始化，自动注册到 `sandbox.runtime_envs`。 + +```python +from rock.sdk.sandbox.runtime_env import RuntimeEnv, NodeRuntimeEnvConfig + +env = await RuntimeEnv.create( + sandbox, + NodeRuntimeEnvConfig(version="22.18.0"), +) + +# 自动注册，可通过 sandbox.runtime_envs[env.runtime_env_id] 访问 +print(env.runtime_env_id in sandbox.runtime_envs) # True +``` + +## wrapped_cmd + +包装命令，将 `bin_dir` 加入 PATH，确保优先使用运行时环境中的可执行文件。 + +```python +wrapped = env.wrapped_cmd("node script.js") +# 返回: bash -c 'export PATH=/tmp/rock-runtime-envs/node/22.18.0/xxx/runtime-env/bin:$PATH && node script.js' +``` + +## run + +在运行时环境中执行命令。内部基于 `wrapped_cmd` 实现 + +```python +await env.run("node script.js") +await env.run("npm install express") +``` + +## PythonRuntimeEnvConfig + +| 字段 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `type` | `Literal["python"]` | `"python"` | 类型标识 | +| `version` | `"3.11" \| "3.12" \| "default"` | `"default"` | Python 版本，默认 3.11 | +| `pip` | `list[str] \| str \| None` | `None` | pip 包列表或 requirements.txt 路径 | +| `pip_index_url` | `str \| None` | 环境变量 | pip 镜像源 | +| `extra_symlink_dir` | `str \| None` | `None` | 符号链接的目标目录 | +| `extra_symlink_executables` | `list[str]` | `["python", "python3", "pip", "pip3"]` | 要创建符号链接的可执行文件列表 | + +## NodeRuntimeEnvConfig + +| 字段 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `type` | `Literal["node"]` | `"node"` | 类型标识 | +| `version` | `"22.18.0" \| "default"` | `"default"` | Node 版本，默认 22.18.0 | +| `npm_registry` | `str \| None` | `None` | npm 镜像源 | +| `extra_symlink_dir` | `str \| None` | `None` | 符号链接的目标目录 | +| `extra_symlink_executables` | `list[str]` | `["node", "npm", "npx"]` | 要创建符号链接的可执行文件列表 | + +## 自定义 RuntimeEnv 实现约束 + +自定义 RuntimeEnv 需遵循以下规则： + +1. **定义 `runtime_env_type` 类属性**：作为类型标识符，用于自动注册到 RuntimeEnv 工厂 +2. **重写 `_get_install_cmd()`**：返回安装命令 +3. **安装命令最后必须**：将目录重命名为 `runtime-env` + + +## NodeRuntimeEnv 简化版实现示例 + +```python +from rock.sdk.sandbox.runtime_env import RuntimeEnv, RuntimeEnvConfig +from typing import Literal +from pydantic import Field +from typing_extensions import override + +# Config 类：定义配置类型，用于 RuntimeEnv.create() 路由到对应实现 +class NodeRuntimeEnvConfig(RuntimeEnvConfig): + type: Literal["node"] = "node" # 必须与 runtime_env_type 一致 + +# RuntimeEnv 实现类：定义如何安装和运行该运行时环境 +class NodeRuntimeEnv(RuntimeEnv): + runtime_env_type = "node" # 自动注册到 RuntimeEnv._REGISTRY + + @override + def _get_install_cmd(self) -> str: + # 下载 Node 二进制包并解压，最后重命名为 runtime-env + return ( + "wget -q -O node.tar.xz https://npmmirror.com/mirrors/node/v22.18.0/node-v22.18.0-linux-x64.tar.xz && " + "tar -xf node.tar.xz && " + "mv node-v22.18.0-linux-x64 runtime-env" + ) +``` + +## 加速基础环境安装 + +`PythonRuntimeEnv` 默认从 https://github.com/astral-sh/python-build-standalone/releases/ 下载 Python 安装包。若网络不可达或下载较慢，可通过环境变量 `ROCK_RTENV_PYTHON_V31114_INSTALL_CMD` 或 `ROCK_RTENV_PYTHON_V31212_INSTALL_CMD` 覆盖默认安装命令（例如切换到内网源/镜像源）。 + +默认值示例： + +```python +"ROCK_RTENV_PYTHON_V31114_INSTALL_CMD": lambda: os.getenv( + "ROCK_RTENV_PYTHON_V31114_INSTALL_CMD", + "[ -f cpython31114.tar.gz ] && rm cpython31114.tar.gz; [ -d python ] && rm -rf python; " + "wget -q -O cpython31114.tar.gz https://github.com/astral-sh/python-build-standalone/releases/download/20251120/cpython-3.11.14+20251120-x86_64-unknown-linux-gnu-install_only.tar.gz " + "&& tar -xzf cpython31114.tar.gz && mv python runtime-env", +), +``` + +例如，替换为镜像源下载： + +```bash +export ROCK_RTENV_PYTHON_V31114_INSTALL_CMD='[ -f cpython31114.tar.gz ] && rm cpython31114.tar.gz; [ -d python ] && rm -rf python; wget -q -O cpython31114.tar.gz https://mirror.nju.edu.cn/github-release/astral-sh/python-build-standalone/20251209/cpython-3.11.14+20251209-x86_64-unknown-linux-gnu-install_only.tar.gz && tar -xzf cpython31114.tar.gz && mv python runtime-env' +``` + +请确保该命令执行完成后，会在 `runtime_env` 的默认工作目录下生成 `runtime-env` 目录，并且 `${workdir}/runtime-env/bin/` 下包含对应可执行文件，例如： + +- `${workdir}/runtime-env/bin/python` + +Node 环境同理，可通过修改环境变量 `ROCK_RTENV_NODE_V22180_INSTALL_CMD` 来指定更快的下载/安装命令。 \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/sandbox.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/sandbox.md new file mode 100644 index 000000000..088f1e311 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/Python SDK References/sandbox.md @@ -0,0 +1,113 @@ +# 处理大文件和长命令输出 + +## `arun` +`arun()` 在 `nohup` 模式下提供了两个关键参数，帮助 Agent / 调用方在"执行"与"查看"之间按需解耦： + +1. **`response_limited_bytes_in_nohup`**（int 型） + 限制返回内容的最大字符数（例如 `64 * 1024`），适合仍需立刻查看部分日志、但必须控制带宽的场景。默认值 `None` 表示不加限制。 + +2. **`ignore_output`**（bool，默认 `False`） + 当设为 `True` 时，`arun()` 不再读取 nohup 输出文件，而是在命令执行完毕后立即返回一段提示信息（包含输出文件路径、**文件大小**及查看方式）。日志仍写入 `/tmp/tmp_.out`，后续可通过 `read_file`、下载接口或自定义命令按需读取，实现"执行"与"查看"彻底解耦。返回的文件大小信息可帮助用户决定是直接下载还是分块读取。 + +```python +from rock.sdk.sandbox.client import Sandbox +from rock.sdk.sandbox.config import SandboxConfig +from rock.sdk.sandbox.request import CreateBashSessionRequest + +config = SandboxConfig( + image=f"{image}", + xrl_authorization=f"{xrl_authorization}", + user_id=f"{user_id}", + cluster=f"{cluster}", +) +sandbox = Sandbox(config) + +session = sandbox.create_session(CreateBashSessionRequest(session="bash-1")) + +# 示例 1：限制最多 1024 个字符 +resp_limit = asyncio.run( + sandbox.arun( + cmd="cat /tmp/test.txt", + mode="nohup", + session="bash-1", + response_limited_bytes_in_nohup=1024, + ) +) + +# 示例 2：完全跳过日志读取，后续再通过 read_file / 下载获取 +resp_detached = asyncio.run( + sandbox.arun( + cmd="bash run_long_job.sh", + mode="nohup", + session="bash-1", + ignore_output=True, + ) +) +print(resp_detached.output) +# Command executed in nohup mode without streaming the log content. +# Status: completed +# Output file: /tmp/tmp_xxx.out +# File size: 15.23 MB +# 可通过 Sandbox.read_file(...) / 下载接口 / cat /tmp/tmp_xxx.out 查看日志 +``` + +## `read_file_by_line_range` + +按行范围异步读取文件内容，支持自动分块读取和会话管理，支持大文件读取。 + +### 重要特性 +- **大文件分块读取**: 自动将大文件分成多个小块进行读取 +- **自动统计行数**: 未指定结束行时，自动计算文件总行数 +- **内置重试机制**: 关键操作支持最多 3 次重试，提高可靠性 +- **参数验证**: 自动验证输入参数的合法性 +- **会话管理**: 支持指定会话或自动创建临时会话 + +### 参数说明 +| 参数 | 类型 | 默认值 | 说明 | +|------|------|--------|------| +| `file_path` | str | - | 要读取的文件路径（沙箱中的绝对路径或相对路径） | +| `start_line` | int \| None | 1 | 起始行号（从 1 开始） | +| `end_line` | int \| None | None | 结束行号（包含），默认为文件末尾 | +| `lines_per_request` | int | 1000 | 每次请求读取的行数，范围 1-10000 | + +### 返回值 +- `ReadFileResponse`: 包含文件内容的响应对象 + - `content` (str): 读取的文件内容 + +### 异常说明 +- `Exception`: 当 `start_line < 1` 时抛出 +- `Exception`: 当 `end_line < start_line` 时抛出 +- `Exception`: 当 `lines_per_request` 不在 1-10000 范围内时抛出 +- `Exception`: 当文件读取失败时抛出 + +### 使用示例 + +```python +# 读取整个文件 +response = await sandbox.read_file_by_line_range("/path/to/file.txt") + +# 读取指定行范围（第 100 到 500 行） +response = await sandbox.read_file_by_line_range( + "/path/to/file.txt", + start_line=100, + end_line=500 +) + +# 从第 1990 行读取到文件末尾 +response = await sandbox.read_file_by_line_range( + "/path/to/file.txt", + start_line=1990 +) + +# 使用自定义分块大小 +response = await sandbox.read_file_by_line_range( + "/path/to/file.txt", + lines_per_request=5000 +) +``` + +### 注意事项 +- 行号从 1 开始计数，而非 0 +- 对于大文件建议适当增加 `lines_per_request` 以提高效率 +- 文件路径必须是沙箱内的有效路径 +- 使用 `sed` 命令进行文件读取，确保沙箱镜像支持该命令 diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/api.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/api.md new file mode 100644 index 000000000..06f44c326 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/References/api.md @@ -0,0 +1,194 @@ +--- +sidebar_position: 1 +--- + +# API 参考 + +本指南详细介绍 ROCK 平台提供的核心 API 服务，包括沙箱环境管理和 GEM 环境交互。 + +## 1. 概述 + +ROCK平台提供两种核心API服务： +- Sandbox API：沙箱环境管理 +- GEM API：GEM环境交互 + +所有 API 接口都遵循 RESTful 设计原则，支持 JSON 格式的数据交换。 + +## 2. Sandbox API + +沙箱环境全生命周期管理功能： + +### 沙箱管理接口 + +1. **Start Sandbox** - 启动沙箱环境 + - 创建一个新的沙箱实例 + - 支持指定镜像、资源配置等参数 + +2. **Start Sandbox Async** - 异步启动沙箱环境 + - 异步方式创建沙箱实例 + - 适用于需要快速响应的场景 + +3. **Check Sandbox Alive Status** - 检查沙箱存活状态 + - 验证沙箱是否正常运行 + +4. **Get Sandbox Statistics** - 获取沙箱统计信息 + - 获取沙箱的资源使用统计 + +5. **Get Sandbox Status** - 获取沙箱详细状态 + - 获取沙箱的完整状态信息 + +6. **Stop Sandbox** - 停止沙箱环境 + - 安全关闭沙箱实例 + +7. **Commit Sandbox** - 提交沙箱为镜像 + - 将当前沙箱状态保存为新镜像 + +### 命令执行接口 + +8. **Execute Command** - 在沙箱中执行命令 + - 直接在沙箱中运行指定命令 + +9. **Create Bash Session** - 创建Bash会话 + - 创建持久化的Bash会话环境 + +10. **Run Command in Session** - 在会话中执行命令 + - 在已创建的会话中执行命令 + +11. **Close Session** - 关闭会话 + - 释放会话资源 + +### 文件操作接口 + +12. **Read File** - 读取沙箱文件 + - 从沙箱中读取指定文件内容 + +13. **Write File** - 写入沙箱文件 + - 向沙箱中写入文件 + +14. **Upload File** - 上传文件到沙箱 + - 将本地文件上传到沙箱 + +## 3. GEM API + +GEM环境交互功能： + +1. **Make Environment** - 创建GEM环境 + - 初始化一个新的GEM环境实例 + +2. **Reset Environment** - 重置GEM环境 + - 将GEM环境重置到初始状态 + +3. **Step Environment** - 执行GEM环境步骤 + - 在GEM环境中执行一个动作步骤 + +4. **Close Environment** - 关闭GEM环境 + - 释放GEM环境资源 + +## 4. HTTP API 使用示例 + +### 4.1 Sandbox API 示例 + +#### 启动沙箱 +```bash +curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/start' \ +-H 'Content-Type: application/json' \ +-d '{ + "image": "python:3.11", + "resources": { + "cpu": "2", + "memory": "8g" + } +}' +``` + +#### 异步启动沙箱 +```bash +curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/start_async' \ +-H 'Content-Type: application/json' \ +-d '{ + "image": "python:3.11", + "resources": { + "cpu": "2", + "memory": "8g" + } +}' +``` + +#### 执行命令 +```bash +curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/execute' \ +-H 'Content-Type: application/json' \ +-d '{ + "sandbox_id": "sandbox-12345", + "command": "ls -la" +}' +``` + +#### 创建会话 +```bash +curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/create_session' \ +-H 'Content-Type: application/json' \ +-d '{ + "sandbox_id": "sandbox-12345", + "session": "my_session" +}' +``` + +#### 在会话中执行命令 +```bash +curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/run_in_session' \ +-H 'Content-Type: application/json' \ +-d '{ + "sandbox_id": "sandbox-12345", + "session": "my_session", + "command": "python script.py" +}' +``` + +#### 上传文件 +```bash +curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/upload' \ +-F 'file=@./local_file.txt' \ +-F 'target_path=./remote_file.txt' \ +-F 'sandbox_id=sandbox-12345' +``` + +#### 停止沙箱 +```bash +curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/stop' \ +-H 'Content-Type: application/json' \ +-d '{ + "sandbox_id": "sandbox-12345" +}' +``` + +### 4.2 GEM API 示例 + +```bash +# 创建GEM环境 +curl -X POST 'http://localhost:8080/apis/v1/envs/gem/make' \ +-H 'Content-Type: application/json' \ +-d '{"env_id": "game:Sokoban-v0-easy"}' + +# 重置环境 +curl -X POST 'http://localhost:8080/apis/v1/envs/gem/reset' \ +-H 'Content-Type: application/json' \ +-d '{"sandbox_id": "sandbox-12345", "seed": 42}' + +# 执行步骤 +curl -X POST 'http://localhost:8080/apis/v1/envs/gem/step' \ +-H 'Content-Type: application/json' \ +-d '{"sandbox_id": "sandbox-12345", "action": "random_action"}' + +# 关闭环境 +curl -X POST 'http://localhost:8080/apis/v1/envs/gem/close' \ +-H 'Content-Type: application/json' \ +-d '{"sandbox_id": "sandbox-12345"}' +``` + +## 相关文档 + +- [快速开始指南](../Getting%20Started/quickstart.md) - 了解如何快速开始使用 ROCK API +- [Python SDK 文档](./Python%20SDK%20References/python_sdk.md) - 学习如何使用 SDK 调用 API +- [配置指南](../User%20Guides/configuration.md) - 了解 API 相关的配置选项 +- [安装指南](../Getting%20Started/installation.md) - 详细了解 ROCK 安装和配置 diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Release Notes/index.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Release Notes/index.md new file mode 100644 index 000000000..474503cad --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Release Notes/index.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 1 +--- +# 版本说明 +* [release v1.2.0](v1.2.0.md) \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Release Notes/v1.2.0.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Release Notes/v1.2.0.md new file mode 100644 index 000000000..15b9fc92b --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/Release Notes/v1.2.0.md @@ -0,0 +1,54 @@ +# v1.2.0 + +## 发布日期 +2026 年 2 月 3 日 + + +--- + +## SDK + +### 新功能 + +#### 运行时环境（Runtime Environment） +**[运行时环境参考文档](../References/Python%20SDK%20References/runtime-env.md)** + +- **新增**：通过 `extra_symlink_dir` 和 `extra_symlink_executables` 支持可执行文件符号链接，可将运行时可执行文件暴露到系统路径 + +#### Model Service（实验性） +**[Model Service 参考文档](../References/Python%20SDK%20References/model-service.md)** + +处理 Agent 与 LLM 推理服务之间的模型调用通信： +- Local 模式：Agent 与 Roll 运行时之间的文件通信，基于文件的通信协议，实现请求-响应机制 +- Proxy 模式：支持请求转发到外部 LLM 服务，具备路由和重试功能 + +- SDK 支持 `anti_call_llm`，用于代理 Agent 请求 +- **新增**：完整的 CLI start 命令参数（`--config-file`、`--host`、`--port`、`--proxy-base-url`、`--retryable-status-codes`、`--request-timeout`） +- **新增**：轨迹（traj）日志记录 - 将 LLM 请求/响应记录到 JSONL 文件（`ROCK_MODEL_SERVICE_DATA_DIR`、`ROCK_MODEL_SERVICE_TRAJ_APPEND_MODE`） +- **新增**：服务端 `ModelServiceConfig` 配置（`host`、`port`、`proxy_base_url`、`proxy_rules`、`retryable_status_codes`、`request_timeout`） + +#### Agent 示例 +**[示例目录](https://github.com/Modelized/ROCK/tree/master/examples/agents)** + +演示 ROCK Agent 与各种 AI 框架集成的实践示例： + +- **claude_code/**: Claude Code Agent 集成示例（使用 Node.js 运行时） + - 命令：`claude -p ${prompt}` + - 依赖：`npm install -g @anthropic-ai/claude-code` + - 通过 `rock_agent_config.yaml` 配置 + +- **iflow_cli/**: iFlow CLI Agent 集成示例（使用 Node.js 运行时） + - 命令：`iflow -p ${prompt} --yolo` + - 依赖：`npm i -g @iflow-ai/iflow-cli@latest` + +- **swe_agent/**: SWE Agent 集成示例 + - 演示标准 ROCK Agent 设置模式 + +- **iflow_cli/integration_with_model_service/**: Model Service 集成示例 + - **local/**: Local 模式示例，包含自定义 LLM 后端 + - 展示 `anti_call_llm` 用法和服务循环模式 + - **proxy/**: Proxy 模式示例，配合 iFlow CLI 使用 + - 演示 `rock model-service start --type proxy --proxy-base-url` 用法 + + +## Admin \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/User Guides/configuration.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/User Guides/configuration.md new file mode 100644 index 000000000..a212189bc --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/User Guides/configuration.md @@ -0,0 +1,188 @@ +--- +sidebar_position: 4 +--- + +# 配置指南 + +本指南详细介绍如何配置 ROCK 环境以满足不同的使用需求，包括本地开发、测试和生产部署。 + +## 1. 环境变量配置 + +ROCK 支持通过环境变量配置关键参数。以下是主要的环境变量： + +```bash +export ROCK_BASE_URL=http://localhost:8080 # ROCK服务基础URL +export ROCK_LOG_LEVEL=INFO # 日志级别 +export ROCK_LOGGING_PATH=/path/to/logs # 日志文件路径，默认 None (输出到控制台) +export ROCK_LOGGING_FILE_NAME=rocklet.log # 日志文件名，默认 "rocklet.log", 启动admin时可以自定义日志文件名, 如admin.log +export ROCK_LOGGING_LEVEL=INFO # 日志输出级别，默认 "INFO" +export ROCK_WORKER_ENV_TYPE=local # 运行时环境类型，可选值: local, docker, uv, pip +``` + +更多环境变量可参考 `rock/env_vars.py` 文件。 + +### 1.1 运行时环境 (Runtime Environments) + +ROCK 提供了多种不同的运行时环境来满足不同场景的需求，选择通过环境变量 `ROCK_WORKER_ENV_TYPE` 进行配置。每种环境有不同的部署要求、性能特征和适用场景。每种环境都有其独特的优势和限制，开发者可以根据部署环境的需要选择最适合的运行时环境。 + +#### 1.1.1 Docker 运行时环境 + +Docker 运行时环境适用于已经预安装了所需依赖的 Docker 镜像环境。这种环境要求部署环境中直接可用 `/tmp/miniforge/bin/rocklet` 可执行文件。 + +**挂载配置:** +- `/tmp/miniforge` - 包含预安装的 Python 环境 +- `/tmp/local_files` - 包含执行所需的本地文件 + +**启动命令:** +```bash +chmod +x /tmp/local_files/docker_run.sh && /tmp/local_files/docker_run.sh +``` + +**适用场景:** +- 容器化部署环境 +- 已经构建了包含 `rocklet` 的自定义 Docker 镜像 +- 适合生产环境，启动速度快 + +**要求:** +- 需要使用定制的 Docker 镜像，其中包含 `/tmp/miniforge/bin/rocklet` 可执行文件 +- Docker 环境支持 + +#### 1.1.2 本地运行时环境 + +本地运行时环境直接利用当前部署环境的 Python 环境和项目文件。该环境要求宿主机和容器之间具有相同的操作系统，以便能够直接挂载虚拟环境和 Python 解释器。 + +**挂载配置:** +- `python_env_path` - Python 环境路径 +- `project_root` - 项目根目录 +- `.venv` - 虚拟环境目录（挂载为容器中的 `/tmp/miniforge`） +- `local_files` - 执行所需的本地文件 + +**启动命令:** +```bash +chmod +x /tmp/local_files/docker_run.sh && /tmp/local_files/docker_run.sh +``` + +**适用场景:** +- 开发环境 +- 宿主机和目标容器使用相同操作系统的场景 +- 需要快速重新使用现有 Python 环境 + +**要求:** +- 相同的操作系统（主机/容器） +- 可直接访问当前部署的 `.venv` 虚拟环境 +- Python 解释器路径兼容 + +#### 1.1.3 UV 运行时环境 + +UV 运行时环境只依赖于可用的 ROCK 项目，但初始化相对较慢且网络要求较高。这种环境最适合没有预配置环境的场景。它从原始项目重新构建 rocklet 环境。这是推荐在 Mac 操作系统上使用的环境。 + +**挂载配置:** +- `project_root` - 项目根目录（挂载为容器中的 `/tmp + project_root`） +- `local_files` - 执行所需的本地文件 + +**启动命令:** +```bash +chmod +x /tmp/local_files/docker_run_with_uv.sh && /tmp/local_files/docker_run_with_uv.sh '' +``` + +**适用场景:** +- Mac 操作系统 +- 跨操作系统启动 +- 没有预配置环境的场景 +- 没有使用 uv 管理 Rock + +**优势:** +- 无需预构建镜像 +- 跨平台兼容性好 +- 特别适合开发和测试 + +**限制:** +- 初始化速度较慢 +- 网络要求较高 +- 启动时间较长 + +#### 1.1.4 PIP 运行时环境 + +PIP 运行时环境使用 pip 在容器内安装所需依赖。这种环境适合快速设置并能在容器中完成依赖安装的场景，是默认的运行时环境。它不需要预先构建包含依赖的镜像，通过 pip 直接管理 Python 包。 + +**挂载配置:** +- `local_files` - 包含执行所需的本地文件 + +**启动命令:** +```bash +chmod +x /tmp/local_files/docker_run_with_pip.sh && /tmp/local_files/docker_run_with_pip.sh +``` + +**适用场景:** +- 使用PIP源安装的ROCK +- 快速测试ROCK + +**优势:** +- 简单的部署设置 + +**限制:** +- 依赖安装时间较长 +- 需要网络访问以安装依赖包 +- 每次启动时都需要安装依赖 + +#### 1.1.5 配置指南 + +根据不同的使用场景，可以参考以下选择指南： + +| 场景 | 推荐环境 | 原因 | +|------|----------|------| +| 生产环境 | Docker 运行时 | 快速启动，稳定性能 | +| 开发环境，同一 OS | 本地运行时 | 环境重用，开发周期快 | +| Mac 开发 | UV 运行时 | 支持最佳的跨平台兼容性 | +| 跨平台开发 | UV 运行时 | 避免环境兼容性问题 | +| 快速测试 | UV 运行时 | 无需预配置工作 | +| PIP源安装 | PIP 运行时 | 直接使用 pip 安装依赖 | + +这些运行时环境通过 `ROCK_WORKER_ENV_TYPE` 环境变量进行配置，该变量可设置为 "local"、"docker"、"uv" 或 "pip"。 + +### 1.2 日志配置 + +在日志配置方面，ROCK 的日志系统具有以下特性： + +- 日志系统不能同时输出到文件和控制台，只有当设置了 `ROCK_LOGGING_PATH` 时，日志才会输出到指定文件，否则输出到控制台。 +- `ROCK_LOGGING_LEVEL` 用于控制日志输出级别，`ROCK_LOG_LEVEL` 用于通用日志级别设置。 + +## 2. 分布式部署要求 + +由于 ROCK 支持分布式部署，当在 Ray 集群的不同节点上运行时，需要满足以下一致性要求： + +#### 目录结构一致性 +在所有 Ray 节点上，必须保证以下目录结构完全一致： +- ROCK 项目仓库目录 +- `.venv` 虚拟环境目录 +- `.venv` 依赖的 base Python 目录 + + +#### 挂载要求 +ROCK 的启动依赖于挂载 ROCK 项目和对应的 base Python 环境，要求在多机环境中保持一致性： + +#### 验证分布式配置 +可以通过以下方式验证分布式部署配置： + +```bash +# 在所有节点上检查目录一致性 +ls -la /path/to/rock +ls -la /path/to/rock/.venv +ls -la $ROCK_PYTHON_ENV_PATH + +# 验证 Python 环境可用性 +$ROCK_PYTHON_ENV_PATH/bin/python --version + +# 检查所有节点上的环境变量设置 +echo $ROCK_PYTHON_ENV_PATH +echo $ROCK_PROJECT_ROOT +``` + + + +## 相关文档 + +- [快速开始指南](../Getting%20Started/quickstart.md) - 了解如何快速搭建 ROCK 环境 +- [API 文档](../References/api.md) - 查看沙箱相关的 API 接口 +- [Python SDK 文档](../References/Python%20SDK%20References/python_sdk.md) - 学习如何使用 SDK 配置沙箱 +- [安装指南](../Getting%20Started/installation.md) - 详细了解 ROCK 安装和配置 diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/overview.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/overview.md new file mode 100644 index 000000000..a02536f50 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.2.x/overview.md @@ -0,0 +1,40 @@ +--- +sidebar_position: 1 +--- + +# 概览 + +ROCK (Reinforcement Open Construction Kit) 是一个开源的强化学习环境开发框架，旨在简化强化学习环境的开发、部署和管理流程。 + +## 什么是 ROCK + +ROCK (Reinforcement Open Construction Kit) 是一个开源强化学习环境开发框架。通过使用 ROCK，开发者可以快速地开发强化学习环境，并结合其他强化学习训练框架，实现高效的强化学习训练。 + +ROCK 提供了完整的沙箱环境管理功能，支持容器化部署，能够实现环境的快速创建、运行和销毁。同时，ROCK 兼容 GEM 协议，为强化学习环境提供了标准化的接口。 + +## ROCK 的核心功能 + +1. **简化开发流程**：简化强化学习环境的开发、构建和管理流程，支持多种开源的强化学习环境 +2. **大规模调度部署**：支持快速强化学习环境的大规模调度部署，通过 GEM 协议可以方便地访问强化学习环境 +3. **框架集成**：与其他强化学习训练框架集成，实现大规模可扩展的强化学习训练 + +## ROCK 的价值 + +ROCK 为不同角色的工程师提供了显著价值： + +- **强化学习算法工程师**：ROCK 可以简化强化学习环境的开发流程，让工程师专注于算法实现 +- **强化学习应用工程师**：ROCK 可以进行快速强化学习环境的大规模部署，提高应用开发效率 + +## 相关文档 + +如果您是第一次使用 ROCK，建议按以下顺序阅读文档： +1. [快速开始指南](./Getting%20Started/quickstart.md) - 快速搭建开发环境 +2. [配置指南](./User%20Guides/configuration.md) - 配置您的 ROCK 环境 +3. [Python SDK 文档](./References/Python%20SDK%20References/python_sdk.md) - 学习如何使用 Python SDK 进行开发 +4. [API 文档](./References/api.md) - 了解完整的 API 接口 +5. [安装指南](./Getting%20Started/installation.md) - 详细了解 ROCK 安装和配置 + + + + + diff --git a/docs/versioned_docs/version-1.2.x/Getting Started/installation.md b/docs/versioned_docs/version-1.2.x/Getting Started/installation.md new file mode 100644 index 000000000..c45b09a8f --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/Getting Started/installation.md @@ -0,0 +1,143 @@ +--- +sidebar_position: 3 +--- + +# Installation + +This document explains how to install and set up the ROCK development environment using both `uv` and `pip`. The project is a Reinforcement Open Construction Kit that supports various components. + +## Using uv (Recommended) + +### Quick Install All Dependencies + +```bash +# Install all dependencies including optional ones +uv sync --all-extras + +# Install development/testing dependencies +uv sync --all-extras --all-groups +``` + +### Install Different Dependency Groups + +#### Core Dependencies Only +```bash +uv sync +``` + +#### Admin Component Dependencies +```bash +uv sync --extra admin +``` + +#### Rocklet Execution Environment Dependencies +```bash +uv sync --extra rocklet +``` + + +#### All Dependencies at Once +```bash +uv sync --all-extras +``` + +#### Development/Testing Dependencies +```bash +uv sync --all-extras --group test +``` + +## Using pip + +### Install from pip source + +#### Core Dependencies Only +```bash +pip install rl-rock +``` + +#### Admin Component Dependencies +```bash +pip install "rl-rock[admin]" +``` + +#### Rocklet Execution Environment Dependencies +```bash +pip install "rl-rock[rocklet]" +``` + +#### Builder Dependencies +```bash +pip install "rl-rock[builder]" +``` + +#### Install All Optional Dependencies +```bash +pip install "rl-rock[all]" +``` + +### Install with pip from source code + +#### Core Dependencies Only +```bash +pip install . +``` + +#### Admin Component Dependencies +```bash +pip install ".[admin]" +``` + +#### Rocklet Execution Environment Dependencies +```bash +pip install ".[rocklet]" +``` + +#### Builder Dependencies +```bash +pip install ".[builder]" +``` + +#### Install All Optional Dependencies +```bash +pip install ".[all]" +``` + +## Available Entry Points + +The package provides the following command line scripts: + +- `rocklet`: ROCK execution environment server (rock.rocklet.server:main) +- `admin`: Admin management server (rock.admin.main:main) +- `envhub`: Environment hub server (rock.envhub.server:main) +- `rock`: Main ROCK command line interface (rock.cli.main:main) + +## Development Setup + +### Using uv (Recommended) + +```bash +# Clone and set up development environment +git clone +cd ROCK +uv sync --all-extras --group test + +# Run tests +uv run pytest + +``` + +### Using pip + +```bash +# For development, install in editable mode with all extras +pip install -e ".[all]" + +# Or separately +pip install -e . +pip install ".[admin]" ".[rocklet]" ".[builder]" # Optional extras +``` + +## Additional Notes + +- The project is configured to use the Alibaba cloud PyPI mirror by default: `https://mirrors.aliyun.com/pypi/simple/` +- For local development, running tests requires the `test` dependency group diff --git a/docs/versioned_docs/version-1.2.x/Getting Started/quickstart.md b/docs/versioned_docs/version-1.2.x/Getting Started/quickstart.md new file mode 100644 index 000000000..2f14808f5 --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/Getting Started/quickstart.md @@ -0,0 +1,166 @@ +--- +sidebar_position: 2 +--- + +# Getting Started + +This guide will demonstrate how to use ROCK to create and manage reinforcement learning environments through complete examples. + +## 1. Environment Preparation + +We recommend starting ROCK on Linux systems to maximize dependency reuse and improve environment startup speed. If you need to try on macOS, please refer to the [MacOS Startup](#7-macos-startup) section. + +Before starting, please ensure your system has the following dependencies installed: + +### 1.1 System Requirements + +- **Docker**: ROCK uses Docker for containerized environment management +- **uv**: ROCK uses uv for dependency management and virtual environment creation + +### 1.2 Verify Dependency Installation + +```bash +# Verify Docker installation +docker --version + +# Verify Docker image, and example depends on python:3.11 image +docker pull python:3.11 + +# Verify uv installation +uv --version +``` + +### 1.3 Project Initialization + +```bash +# Clone repository +git clone +cd ROCK + +# Create virtual environment (using uv-managed Python, use python 3.11 as an example) +uv venv --python 3.11 --python-preference only-managed + +# Install all dependency groups +uv sync --all-extras +``` + +> **Important Note**: To ensure ROCK can correctly mount the project and virtual environment along with its base Python interpreter, it is strongly recommended to use uv-managed Python environments to create virtual environments rather than system Python. + +## 2. Activate Virtual Environment + +Before running any ROCK commands, you need to activate the virtual environment. Ensure sys.base_prefix is a uv-managed environment, such as `/root/.local/share/uv/python/cpython-3.11.8-linux-x86_64-gnu` or similar paths. + +```bash +# Activate virtual environment +source .venv/bin/activate + +# Verify Python environment +python -c "import sys; print('Base prefix:', sys.base_prefix)" +``` + +> **Verification Point**: Ensure the output base prefix path points to a uv-managed Python environment, not system Python. + +## 3. Verify Environment Configuration + +After activating the virtual environment, verify that dependencies are installed correctly: + +```bash +# Check key dependencies +python -c "import rock; print(\"Hello ROCK\")" +``` + +## 4. Start ROCK Service + +After activating the virtual environment, start the ROCK Admin service on project root: + +```bash +# Ensure virtual environment is activated +source .venv/bin/activate + +# Start ROCK Admin service (local environment) +rock admin start +``` + +After the service starts, you will see output similar to the following: + +``` +INFO: Started server process [12345] +INFO: Waiting for application startup. +INFO: Application startup complete. +INFO: Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit) +``` + +> **Service Information**: The ROCK Admin service runs by default on `http://127.0.0.1:8080`. + +## 5. Run Example Environments + +Now you can run example environments to verify the installation. Ensure the ROCK service is running, then open a new terminal window to execute the following commands: + +```bash +# Ensure virtual environment is activated +source .venv/bin/activate + +# Run sandbox example +python examples/sandbox_demo.py + +# Run GEM protocol example +python examples/sokoban_demo.py +``` + +### 5.1 Example Descriptions + +- **sandbox_demo.py**: Demonstrates how to use ROCK's sandbox SDK to create and manage containerized environments +- **sokoban_demo.py**: Demonstrates how to use ROCK's GEM protocol compatible interface to create reinforcement learning environments + +> **Running Requirements**: Ensure the ROCK Admin service is running, as examples need to communicate with the service. + +## 6. Distributed Environment Configuration (Optional) + +For distributed multi-machine environments, ensure the following configurations are consistent: + +1. All machines use the same root Python interpreter for ROCK and uv Python configurations +2. Docker versions are consistent across all nodes +3. Network configuration allows normal communication between nodes + + +## 7. MacOS Startup + +On macOS, if you need to start Linux image environments, you first need to set the environment variable: + +```bash +export ROCK_WORKER_ENV_TYPE=uv +``` + +During container startup, the corresponding uv environment will be installed. For details, please refer to the `rock/rocklet/local_files/docker_run_with_uv.sh` script. + +> **Note**: Compared to Linux systems, the startup speed on macOS will be slower and more dependent on network conditions. You can adjust the script according to actual conditions.You can find detatils for ROCK_WORKER_ENV_TYPE in [Configuration Guide](../User%20Guides/configuration.md). + +## 8. Starting from Pip Source + +If starting the Admin Server from Pip source, after completing the ROCK installation by referring to [installation](./installation.md), you need to set an additional environment variable: + +```bash +export ROCK_WORKER_ENV_TYPE=pip +``` + +(This startup method will pull and install the latest rocklet from the PyPI source when starting the container environment. The startup speed is relatively slow, so it is only recommended for testing purposes. For production environments, other startup methods are still recommended.) + +## Summary + +Congratulations! You have successfully completed the ROCK quick start guide. You should now be able to: + +- Properly set up the ROCK development environment +- Use uv-managed Python environments +- Start and manage ROCK services +- Run example programs to verify installation +- Configure ROCK in distributed environments (if needed) + +For a deeper understanding of ROCK's additional features, please refer to the following documents: + +## Next Steps + +- [Configuration Guide](../User%20Guides/configuration.md) - Detailed information about ROCK configuration options +- [API Documentation](../References/api.md) - View complete API interfaces +- [Python SDK Documentation](../References/Python%20SDK%20References/python_sdk.md) - Learn how to use the Python SDK for development +- [Installation Guide](./installation.md) - Detailed information about ROCK installation and setup +- [Overview](../overview.md) - Understand ROCK's design philosophy \ No newline at end of file diff --git a/docs/versioned_docs/version-1.2.x/Getting Started/rock-agent.md b/docs/versioned_docs/version-1.2.x/Getting Started/rock-agent.md new file mode 100644 index 000000000..eb6b54a65 --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/Getting Started/rock-agent.md @@ -0,0 +1,72 @@ +--- +sidebar_position: 4 +--- + +# Rock Agent Quick Start + +Rock Agent is an AI Agent runtime framework provided by ROCK, supporting various types of Agents running in sandbox environments. + +## Prerequisites +- Make sure you have a working ROCK service, if you need to locally start the service side, refer to [Quick Start](quickstart.md). + +## Examples + +ROCK provides two Hello World Agent examples in the `examples/agents/` directory: + +``` +examples/agents/ +├── claude_code/ # ClaudeCode Agent example +└── iflow_cli/ # IFlowCli Agent example +``` + +### Run IFlowCli Example + +```bash +cd examples/agents/iflow_cli +python iflow_cli_demo.py +``` + +### Run ClaudeCode Example + +```bash +cd examples/agents/claude_code +python claude_code_demo.py +``` + +## IFlowCli Configuration File + +The configuration file is located at `examples/agents/iflow_cli/rock_agent_config.yaml`: + +```yaml +run_cmd: "iflow -p ${prompt} --yolo" + +runtime_env_config: + type: node + npm_registry: "https://registry.npmmirror.com" + custom_install_cmd: "npm i -g @iflow-ai/iflow-cli@latest" + +env: + IFLOW_API_KEY: "" # Enter your API key + IFLOW_BASE_URL: "" # Enter your base URL + IFLOW_MODEL_NAME: "" # Enter your model name +``` + +## ClaudeCode Configuration File + +The configuration file is located at `examples/agents/claude_code/rock_agent_config.yaml`: + +```yaml +run_cmd: "claude -p ${prompt}" + +runtime_env_config: + type: node + custom_install_cmd: "npm install -g @anthropic-ai/claude-code" + +env: + ANTHROPIC_BASE_URL: "" # Enter your anthropic base url + ANTHROPIC_API_KEY: "" # Enter your anthropic api key +``` + +## Related Documentation + +- [RockAgent Reference](../References/Python%20SDK%20References/rock-agent.md) diff --git a/docs/versioned_docs/version-1.2.x/Getting Started/rockroll.md b/docs/versioned_docs/version-1.2.x/Getting Started/rockroll.md new file mode 100644 index 000000000..2465a7733 --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/Getting Started/rockroll.md @@ -0,0 +1,194 @@ +--- +sidebar_position: 7 +--- + +# ROCK & ROLL Quick Start Guide + +This guide will walk you through running a reinforcement learning training example based on the Sokoban game, using ROLL (the training framework) and ROCK (the environment management tool). + +## 1. Prerequisites + +Before you begin, please ensure your system has the following dependencies installed. + +### 1.1 System Requirements + +- **OS**: A Linux-based system is recommended (e.g., Ubuntu 20.04+). +- **Hardware**: An NVIDIA GPU with the corresponding drivers is recommended. +- **Docker**: ROCK uses Docker for containerized environment management. +- **uv**: ROCK uses uv for dependency management and virtual environment creation. + +### 1.2 Verify Dependencies & Pre-pull Image + +```bash +# Verify Docker installation +docker --version + +# Verify Docker is running and pre-pull the Sokoban environment image +# This will save time when the training starts. +docker pull rock-n-roll-registry.cn-hangzhou.cr.aliyuncs.com/rock/sokoban-sandbox:latest + +# Verify uv installation +uv --version + +``` + +### 1.3 Initialize the Project + +```bash +# Clone the project repositories +git clone https://github.com/alibaba/ROCK.git +git clone https://github.com/alibaba/ROLL.git + +# Ensure both repositories are in the same parent directory, like this: +# your-workspace/ +# ├── ROCK/ +# └── ROLL/ +``` + + +## 2. Launch the Training Process + +> Note: The following instructions use torch==2.6.0 and vLLM==0.8.4 as an example. + + +### Option 1: Using a Virtual Environment (Recommended) + +#### Why is this method recommended? +- Isolation: A uv virtual environment ensures that project dependencies are isolated from your system, preventing conflicts. +- Fast Startup: ROCK can reuse this virtual environment, significantly speeding up subsequent task initializations. +- Stability & Reproducibility: Dependency management is cleaner and more reliable. + + +```bash +# Navigate to the ROCK directory +cd ROCK + +# Create and activate a Python 3.10 virtual environment (ROLL recommends Python 3.10) +uv venv --python 3.10 --python-preference only-managed +source .venv/bin/activate + +# Install all of ROCK's dependencies using uv +uv sync --all-extras + +# If using Python 3.10, starting Ray may raise a `ValueError: is not a valid Sentinel`. +# This is due to an incompatibility between `ray` and `click` versions 8.3+. +# To fix this, downgrade `click` to a version below 8.3. This issue does not affect Python 3.11. +uv pip install 'click>=8.2,click<8.3' + +# Navigate to the ROLL directory to install its dependencies +cd ../ROLL + +# Install core PyTorch components +uv pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 + +# Install transformer-engine. The --no-build-isolation flag prevents errors where torch cannot be found. +uv pip install transformer-engine[pytorch]==2.2.0 --no-build-isolation + +# Install a pre-compiled version of flash-attention matching the specific CUDA and PyTorch versions +uv pip install https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.2.post1/flash_attn-2.7.2.post1+cu12torch2.6cxx11abiFALSE-cp310-cp310-linux_x86_64.whl + +# Install the remaining dependencies +uv pip install -r requirements_torch260_vllm.txt + +# (Optional) Install Tensorboard to check training metrics +uv pip install tensorboard -i $PYPI_MIRROR + +# All set! Launch the training script. +bash examples/agentic_demo/run_agentic_pipeline_sokoban_sandbox_single_node.sh +``` + +### Option 2: Using the System Environment (Alternative) + +For optimal compatibility with this method, we recommend running these commands inside one of ROLL's official base Docker images. These images come pre-installed with matching CUDA, cuDNN, and other foundational libraries. + +> [ROLL's Official Docker Image List](https://alibaba.github.io/ROLL/docs/Getting%20Started/Installation/image_address) + + +#### Warning +This method will install all Python packages directly into your current environment (e.g., the container's base system), which may cause conflicts with system packages or other projects. + +Since ROCK cannot reuse the environment, it may need to reinstall some dependencies each time a task starts, leading to slower startup times that are dependent on network speed. + + +```bash +# Install ROCK's dependencies +cd ROCK +pip install . +pip install ".[admin]" + +# Install ROLL's dependencies +cd ../ROLL +pip install -r requirements_torch260_vllm.txt + +# Crucial: Configure ROCK to use uv as its worker environment manager +export ROCK_WORKER_ENV_TYPE=uv + +# Launch the training script +bash examples/agentic_demo/run_agentic_pipeline_sokoban_sandbox_single_node.sh +``` + +You have now successfully launched the Sokoban reinforcement learning training process. Happy Rock & Roll！ + + +## 3. Multi-Node Deployment + +Instead of running everything on a single machine, you can deploy the **ROCK Service** and **ROLL job** on separate machines. This is a common client-server setup where they communicate over the network. + +### 3.1 Deploy the ROCK Service on Machine A + +On a dedicated machine (or container), follow the [ROCK Quick Start Guide](./quickstart.md) to deploy and start the ROCK service. + +> **Important** +> After starting the service, take note of its IP address and port (e.g., `http://192.168.1.10:8000`). You will need this address for the subsequent steps. + +### 3.2 Prepare the ROLL Client on Machine B + +On the other machine where you will run the training task, perform the following steps. + +1. Verify Network Connectivity + +First, use the curl command to check if you can reach the ROCK service on Machine A from Machine B. +```bash +# Replace : with the actual address of your ROCK service +# If successful, you should receive a response like {"message":"hello, ROCK!"} +curl http://: +``` + +2. Prepare the ROLL Environment + +```bash +# Clone the ROLL repository +git clone https://github.com/alibaba/ROLL.git +cd ROLL + +# Install dependencies +pip install -r requirements_torch260_vllm.txt +``` + +3. Configure the ROLL Connection Address + +Modify ROLL's configuration file to point to the remote ROCK service. +- Open the configuration file: examples/agentic_demo/agentic_val_sokoban_sandbox.yaml. +- Find the "SokobanSandbox" section under "env_config". +- Update the base_url value to your ROCK service's address. +```yaml +custom_envs: + SokobanSandbox: + env_config: + # Change the address here to your ROCK service's address + # Example: base_url: 'http://192.168.1.10:8000' + base_url: 'http://:' +``` + +4. Start Training +Once configured, you can start the ROLL training script on Machine B. + +```bash +# This script will now request environments from the ROCK service on Machine A over the network. +bash examples/agentic_demo/run_agentic_pipeline_sokoban_sandbox_multi_nodes.sh +``` + +### Advanced: Distributed ROLL Training + +If you wish to deploy the ROLL training task itself in a distributed manner, you can refer to ROLL's official documentation for distributed deployment. +> [Quick Start: Multi-Node Deployment Guide](https://alibaba.github.io/ROLL/docs/Getting%20Started/Quick%20Start/multi_nodes_quick_start) \ No newline at end of file diff --git a/docs/versioned_docs/version-1.2.x/References/Python SDK References/codes.md b/docs/versioned_docs/version-1.2.x/References/Python SDK References/codes.md new file mode 100644 index 000000000..dceb8d318 --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/References/Python SDK References/codes.md @@ -0,0 +1,93 @@ +# Error Codes + +Error code definitions and categories for error handling and retry strategies. + +## Usage Example + +```python +import rock + +def test_codes_values(): + """Test basic status code values""" + assert rock.codes.OK == 2000 + assert rock.codes.BAD_REQUEST == 4000 + assert rock.codes.INTERNAL_SERVER_ERROR == 5000 + assert rock.codes.COMMAND_ERROR == 6000 +``` + +## Codes Categories + +```python +OK = 2000, "OK" +""" +Success codes (2xxx) +""" + +BAD_REQUEST = 4000, "Bad Request" +""" +Client error codes (4xxx): + +These errors indicate issues with the client request, +SDK will raise Exceptions for these errors. +""" + +INTERNAL_SERVER_ERROR = 5000, "Internal Server Error" +""" +Server error codes (5xxx): + +These errors indicate issues on the server side, +SDK will raise Exceptions for these errors. +""" + +COMMAND_ERROR = 6000, "Command Error" +""" +Command/execution error codes (6xxx): + +These errors are related to command execution and should be handled by the model, +SDK will NOT raise Exceptions for these errors. +""" +``` + +## Retry Strategy Recommendations + +- **Retry trigger**: Only retry when `INTERNAL_SERVER_ERROR` occurs +- **Other error handling**: + - `BAD_REQUEST`: Check if there are issues with the arun call logic + - `COMMAND_ERROR`: stdout goes to `observation.output`, stderr goes to `observation.failure_reason` +- `COMMAND_ERROR` note: When bash execution fails, both stdout and stderr may be non-empty. It is recommended to prompt the model with both output and failure_reason from the observation. + +## Retry Example + +```python +# Background execution with nohup +while retry_times < retry_limit: + try: + observation: Observation = await sandbox.arun( + "python long_running_script.py", + mode="nohup" + ) + if observation.exit_code != 0: + logging.warning( + f"Command failed with exit code {observation.exit_code}, " + f"output: {observation.output}, failure_reason: {observation.failure_reason}" + ) + return observation + except RockException as e: + if rock.codes.is_server_error(e.code): + if retry_times >= retry_limit: + logging.error(f"All {retry_limit} attempts failed") + raise e + else: + retry_times += 1 + logging.error( + f"Server error occurred, code: {e.code}, message: {e.code.get_reason_phrase()}, " + f"exception: {str(e)}, will retry, times: {retry_times}." + ) + await asyncio.sleep(2) + continue + else: + logging.error( + f"Non-retriable error occurred, code: {e.code}, message: {e.code.get_reason_phrase()}, exception: {str(e)}." + ) + raise e +``` diff --git a/docs/versioned_docs/version-1.2.x/References/Python SDK References/deploy.md b/docs/versioned_docs/version-1.2.x/References/Python SDK References/deploy.md new file mode 100644 index 000000000..f7b86bdfa --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/References/Python SDK References/deploy.md @@ -0,0 +1,55 @@ +# Deploy + +Sandbox resource deployment manager for local directory deployment and template formatting. + +## deploy_working_dir - Deploy Local Directory + +```python +sandbox = Sandbox(config) +deploy = sandbox.deploy + +# Deploy local directory (auto-generated target path) +target = await deploy.deploy_working_dir( + local_path="/path/to/local/project", +) +print(f"Deployed to: {target}") # e.g., /tmp/rock_workdir_abc123 + +# Deploy to specific target path +target = await deploy.deploy_working_dir( + local_path="/path/to/local/project", + target_path="/root/workdir", +) +``` + +## format - Template Variable Substitution + +```python +# After deploy_working_dir, use ${working_dir} placeholder +cmd = deploy.format("mv ${working_dir}/config.json /root/.app/") +# Result: mv /tmp/rock_workdir_abc123/config.json /root/.app/ + +# Combine with custom variables +cmd = deploy.format( + "cat ${working_dir}/${config_file}", + config_file="settings.json" +) +# Result: cat /tmp/rock_workdir_abc123/settings.json + +# Access working_dir directly +if deploy.working_dir: + print(f"Current working directory: {deploy.working_dir}") +``` + +## Multiple Deployments + +Subsequent calls overwrite previous working directory paths: + +```python +# First deployment +path1 = await deploy.deploy_working_dir(local_path="/project/v1") +print(deploy.working_dir) # /tmp/rock_workdir_xxx1 + +# Second deployment (overwrites previous path) +path2 = await deploy.deploy_working_dir(local_path="/project/v2") +print(deploy.working_dir) # /tmp/rock_workdir_xxx2 +``` diff --git a/docs/versioned_docs/version-1.2.x/References/Python SDK References/file_system.md b/docs/versioned_docs/version-1.2.x/References/Python SDK References/file_system.md new file mode 100644 index 000000000..a64228e8f --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/References/Python SDK References/file_system.md @@ -0,0 +1,94 @@ +# FileSystem + +File system interface for sandbox environment operations including permission and ownership management. + +## chown - Change Owner + +```python +from rock.actions.sandbox.request import ChownRequest + +# Create remote user before changing ownership +await sandbox.remote_user.create_remote_user("deploy") + +# Get current working directory +pwd_response = await sandbox.execute(Command(command=["pwd"])) +pwd = pwd_response.stdout.strip() + +# Change directory owner +await sandbox.fs.chown( + ChownRequest( + paths=[pwd], + remote_user="deploy", + recursive=False, + ) +) + +# Recursively change owner for directory and contents +await sandbox.fs.chown( + ChownRequest( + paths=["/home/user/project"], + remote_user="deploy", + recursive=True, + ) +) +``` + +## chmod - Change Permissions + +```python +from rock.actions.sandbox.request import ChmodRequest + +# Create test directory +await sandbox.execute(Command(command=["mkdir", "-p", "/tmp/app"])) + +# Change directory permissions +await sandbox.fs.chmod( + ChmodRequest( + paths=["/tmp/app"], + mode="755", + recursive=False, + ) +) + +# Recursively change permissions (includes subdirectories and files) +await sandbox.fs.chmod( + ChmodRequest( + paths=["/tmp/app"], + mode="644", + recursive=True, + ) +) + +# Set maximum permissions +await sandbox.fs.chmod( + ChmodRequest( + paths=["/tmp/shared"], + mode="777", + recursive=True, + ) +) +``` + +## upload_dir - Upload Directory + +```python +import os +from pathlib import Path + +# Prepare local directory +local_dir = Path("/Users/foo/my-project") +(local_dir / "config.json").write_text('{"key": "value"}') +(local_dir / "app.py").write_text("print('hello')") + +# Upload to sandbox +result = await sandbox.fs.upload_dir( + source_dir=str(local_dir), + target_dir="/root/project", + extract_timeout=600, +) + +if result.exit_code == 0: + print(f"Upload success: {result.output}") +else: + print(f"Upload failed: {result.failure_reason}") +``` diff --git a/docs/versioned_docs/version-1.2.x/References/Python SDK References/model-service.md b/docs/versioned_docs/version-1.2.x/References/Python SDK References/model-service.md new file mode 100644 index 000000000..23dbc21bf --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/References/Python SDK References/model-service.md @@ -0,0 +1,298 @@ +# Model Service (Experimental) + +The Model Service provided by ROCK is responsible for handling AI model call communications, serving as a communication bridge between agents and training frameworks (such as Roll) or actual LLM inference services. + +## RockAgent Integration + +ModelService is typically **automatically managed by RockAgent** - no manual lifecycle management is required. Simply enable it in the configuration: + +```python +from rock.sdk.sandbox.model_service.base import ModelServiceConfig + +config = ModelServiceConfig( + enabled=True, # Enable ModelService, RockAgent manages its lifecycle +) +``` + +RockAgent will automatically: +- Install ModelService (install Python runtime, install model service package) +- Start/stop ModelService +- Monitor Agent process + +## Architecture Overview (Local Mode) + +In local mode, the model service uses the **file system** as the communication medium, implementing a request-response mechanism between agents and models. + +When an agent needs to call a model, the request is first written to a log file, then processed by the listening component. When the model generates a response, the result is written back to the log file and read by the waiting agent. + +## anti_call_llm - Core API + +`anti_call_llm()` is the **most important API in Local mode**, used to manually trigger LLM anti-calls for fine-grained control over model calls: + +```python +result = await model_service.anti_call_llm( + index=0, # LLM call index + response_payload='OpenAI type response', # Response data (optional) + call_timeout=600, # Operation timeout (seconds) + check_interval=3, # Status check interval (seconds) +) +``` + +**Use cases:** +- After Agent captures LLM response, call this method to notify Roll runtime +- Supports carrying response data for error handling or retry +- Configurable timeout and check interval for different network environments + +## CLI Commands + +To use the model service via CLI, ROCK provides a set of CLI commands that can be accessed via `rock model-service` after installing ROCK in the sandbox: + +### start command +Start the model service process +```bash +rock model-service start --type [local|proxy] [options] +``` + +Parameters: + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `--type` | str | `local` | Service type: `local` or `proxy` | +| `--config-file` | str | None | Path to configuration file | +| `--host` | str | None | Server host address (overrides config) | +| `--port` | int | None | Server port (overrides config) | +| `--proxy-base-url` | str | None | Proxy base URL | +| `--retryable-status-codes` | str | None | Comma-separated list of retryable status codes | +| `--request-timeout` | int | None | Request timeout in seconds | + +### watch-agent command +Monitor the agent process and send a SESSION_END message when the process exits +```bash +rock model-service watch-agent --pid +``` + +Parameters: +- `--pid`: The ID of the agent process to monitor + +### stop command +Stop the model service +```bash +rock model-service stop +``` + +### anti-call-llm command +Anti-call the LLM interface +```bash +rock model-service anti-call-llm --index [--response ] +``` + +Parameters: +- `--index`: Index of the previous LLM call, starting from 0 +- `--response`: Response from the previous LLM call (optional) + +## File Communication Protocol + +The model service uses files for inter-process communication, defining specific marker formats to distinguish requests and responses: + +### Request Format +``` +LLM_REQUEST_START{JSON request data}LLM_REQUEST_END{metadata JSON} +``` + +### Response Format +``` +LLM_RESPONSE_START{JSON response data}LLM_RESPONSE_END{metadata JSON} +``` + +### Session End Marker +``` +SESSION_END +``` + +Metadata contains timestamp and index information to ensure message order and processing. + +## SDK Usage + +### ModelServiceConfig + +Model service configuration class, located in `rock/sdk/sandbox/model_service/base.py`: + +```python +from rock.sdk.sandbox.model_service.base import ModelServiceConfig + +config = ModelServiceConfig( + enabled=True, + type="local", # Service type + install_cmd="pip install rock-model-service", # Install command + install_timeout=300, # Install timeout (seconds) + start_cmd="rock model-service start --type ${type}", # Start command + stop_cmd="rock model-service stop", # Stop command + logging_path="/data/logs", # Log path + logging_file_name="model_service.log", # Log filename +) +``` + +| Config | Default | Description | +|--------|---------|-------------| +| `enabled` | `False` | Whether to enable model service (RockAgent manages) | +| `type` | `"local"` | Service type: `local` or `proxy` | +| `install_cmd` | - | Model service package install command | +| `install_timeout` | `300` | Install timeout in seconds | +| `start_cmd` | - | Start command template | +| `stop_cmd` | - | Stop command | +| `logging_path` | `/data/logs` | Log directory path | +| `logging_file_name` | `model_service.log` | Log filename | + +### ModelService + +Model service management class, handles the lifecycle of model services within the sandbox: + +```python +from rock.sdk.sandbox.client import Sandbox +from rock.sdk.sandbox.model_service.base import ModelServiceConfig, ModelService + +sandbox = Sandbox(config) +model_service = ModelService(sandbox, ModelServiceConfig()) + +# Typically auto-managed by RockAgent, no manual calls needed +# The following methods are only for manual control when needed + +# Install model service +await model_service.install() + +# Start model service +await model_service.start() + +# Monitor agent process +await model_service.watch_agent(pid="12345") + +# Execute anti-call LLM (Core API for Local mode) +result = await model_service.anti_call_llm( + index=0, + response_payload='{"content": "response"}', + call_timeout=600, + check_interval=3, +) + +# Stop model service +await model_service.stop() +``` + +## API Reference + +### install() + +Install model service dependencies in the sandbox. + +```python +await model_service.install() +``` + +Execution steps: +1. Create and initialize Python runtime environment +2. Create Rock config file +3. Install model service package + +**Note:** Typically auto-called by RockAgent. + +### start() + +Start the model service. + +```python +await model_service.start() +``` + +Prerequisite: Must call `install()` first. + +**Note:** Typically auto-called by RockAgent. + +### stop() + +Stop the model service. + +```python +await model_service.stop() +``` + +If the service is not running, this operation will be skipped. + +**Note:** Typically auto-called by RockAgent. + +### watch_agent(pid) + +Monitor the agent process. + +```python +await model_service.watch_agent(pid="12345") +``` + +Sends `SESSION_END` message when the process exits. + +### anti_call_llm(index, response_payload, call_timeout, check_interval) + +Execute anti-call LLM operation. **This is the most important API in Local mode.** + +```python +result = await model_service.anti_call_llm( + index=0, # LLM call index + response_payload='{"result": "..."}', # Response data (optional) + call_timeout=600, # Operation timeout (seconds) + check_interval=3, # Status check interval (seconds) +) +``` + +## Configuration Options + +### Service Configuration +- `SERVICE_HOST`: Service host address, defaults to `"0.0.0.0"` +- `SERVICE_PORT`: Service port, defaults to `8080` + +### Log Configuration +- `LOG_FILE`: Log file path used for communication, containing request and response data + +### Trajectory (Traj) Logging +The model service records LLM call trajectories (traj) to a JSONL file for debugging and analysis. + +| Environment Variable | Default | Description | +|---------------------|---------|-------------| +| `ROCK_MODEL_SERVICE_DATA_DIR` | `/data/logs` | Directory for traj log files | +| `ROCK_MODEL_SERVICE_TRAJ_APPEND_MODE` | `false` | Append mode (true/false) | + +**Traj file location**: `{DATA_DIR}/LLMTraj.jsonl` + +**Traj file format** (JSONL - one JSON object per line): +```json +{"request": {...}, "response": {...}} +``` + +### Polling Configuration +- `POLLING_INTERVAL_SECONDS`: Polling interval, defaults to `0.1` seconds +- `REQUEST_TIMEOUT`: Request timeout, defaults to unlimited + +### Marker Configuration +Defines markers used to distinguish different types of messages in the log file: +- `REQUEST_START_MARKER` / `REQUEST_END_MARKER` +- `RESPONSE_START_MARKER` / `RESPONSE_END_MARKER` +- `SESSION_END_MARKER` + +### ModelServiceConfig (Server-side) + +The server-side configuration class defines how the model service handles requests: + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `host` | str | `"0.0.0.0"` | Server host address | +| `port` | int | `8080` | Server port | +| `proxy_base_url` | str \| None | `None` | Direct proxy URL | +| `proxy_rules` | dict | See below | Model name to URL mapping | +| `retryable_status_codes` | list[int] | `[429, 500]` | Retryable HTTP status codes | +| `request_timeout` | int | `120` | Request timeout in seconds | + +**Default proxy_rules**: +```python +{ + "gpt-3.5-turbo": "https://api.openai.com/v1", + "default": "https://api-inference.modelscope.cn/v1", +} +``` diff --git a/docs/versioned_docs/version-1.2.x/References/Python SDK References/python_sdk.md b/docs/versioned_docs/version-1.2.x/References/Python SDK References/python_sdk.md new file mode 100644 index 000000000..5272d7edb --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/References/Python SDK References/python_sdk.md @@ -0,0 +1,265 @@ +--- +sidebar_position: 2 +--- + +# Python SDK Reference + +This guide provides detailed information on how to use the ROCK SDK for development, including sandbox environment management and GEM environment interaction. + +## 1. Overview + +ROCK SDK provides developers with convenient Python interfaces to use ROCK platform features, including sandbox environment management and GEM environment interaction. + +> **Important Note**: Before using the SDK, ensure that the ROCK Admin service is running. You can start it with the following command: +> ```bash +> rock admin start +> ``` + +## 2. Sandbox SDK + +### 2.1 Basic Sandbox Operations + +```python +import asyncio + +from rock.actions import CreateBashSessionRequest +from rock.sdk.sandbox.client import Sandbox +from rock.sdk.sandbox.config import SandboxConfig + +async def run_sandbox(): + """Run sandbox demo with admin server requirement. + + NOTE: This demo requires the admin server to be running for proper execution. + Make sure to start the admin server before running this script. + Default admin server port is 8080. + """ + # Create sandbox configuration + config = SandboxConfig(image="python:3.11", memory="8g", cpus=2.0) + + # Create sandbox instance + sandbox = Sandbox(config) + + # Start sandbox (connects to admin server) + await sandbox.start() + + # Create session in sandbox for command execution + await sandbox.create_session(CreateBashSessionRequest(session="bash-1")) + + # Execute command in sandbox session + result = await sandbox.arun(cmd="echo Hello ROCK", session="bash-1") + print("\n" + "*" * 50 + "\n" + result.output + "\n" + "*" * 50 + "\n") + + # Stop and clean up sandbox resources + await sandbox.stop() + +if __name__ == "__main__": + # Ensure admin server is running before executing + print("IMPORTANT: Make sure the admin server is running before executing this demo!") + print("Start the admin server with: rock admin start") + asyncio.run(run_sandbox()) +``` + +### 2.2 Sandbox Group Management + +```python +from rock.sdk.sandbox.config import SandboxGroupConfig + +# Create sandbox group configuration +config = SandboxGroupConfig( + image="python:3.11", + size=4, # Create 4 sandboxes + start_concurrency=2, # Concurrency level for startup is 2 +) + +# Create and start sandbox group +sandbox_group = SandboxGroup(config) +await sandbox_group.start() + +# Batch operations +for sandbox in sandbox_group.sandbox_list: + await sandbox.run_in_session(Action(session="default", command="echo Hello")) + +# Batch stop +await sandbox_group.stop() +``` + +### 2.3 Configuration Example + +```python +config = SandboxConfig( + image="python:3.11", + auto_clear_seconds=60 * 20, + experiment_id="test", +) +``` + +### 2.4 Sandbox Speedup Configuration + +ROCK provides sandbox network acceleration capabilities, supporting configuration of APT, PIP, and GitHub mirror sources to improve package download speeds in restricted network environments. + +#### Supported Speedup Types + +**APT Mirror Configuration** + +Configure APT package manager mirror sources for faster Debian/Ubuntu package downloads. + +```python +from rock.sdk.sandbox.speedup import SpeedupType + +# Configure APT mirror +await sandbox.network.speedup( + speedup_type=SpeedupType.APT, + speedup_value="http://mirrors.cloud.aliyuncs.com" +) +``` + +**PIP Mirror Configuration** + +Configure Python package index mirrors for faster pip installations. + +```python +# HTTP mirror +await sandbox.network.speedup( + speedup_type=SpeedupType.PIP, + speedup_value="http://mirrors.cloud.aliyuncs.com" +) + +# HTTPS mirror +await sandbox.network.speedup( + speedup_type=SpeedupType.PIP, + speedup_value="https://mirrors.aliyun.com" +) +``` + +**GitHub Acceleration** + +Configure GitHub IP acceleration by adding custom DNS resolution entries. + +```python +await sandbox.network.speedup( + speedup_type=SpeedupType.GITHUB, + speedup_value="11.11.11.11" +) +``` + +#### Complete Example + +```python +from rock.sdk.sandbox.speedup import SpeedupType +from rock.actions import RunMode + +async def setup_sandbox_with_speedup(): + """Create sandbox and configure acceleration""" + config = SandboxConfig(image="python:3.11") + sandbox = Sandbox(config) + + await sandbox.start() + + # Configure acceleration (before installing packages) + await sandbox.network.speedup( + speedup_type=SpeedupType.APT, + speedup_value="http://mirrors.cloud.aliyuncs.com" + ) + + await sandbox.arun(cmd="apt-get update && apt-get install -y git", mode=RunMode.NOHUP) + + await sandbox.network.speedup( + speedup_type=SpeedupType.PIP, + speedup_value="https://mirrors.aliyun.com" + ) + + # Speedup does not automatically install PIP, it only configures mirror sources for acceleration + await sandbox.arun(cmd="pip install numpy", mode=RunMode.NOHUP) + + # GitHub can be accelerated through mirror IP + await sandbox.network.speedup( + speedup_type=SpeedupType.GITHUB, + speedup_value="11.11.11.11" + ) + + return sandbox +``` + +#### Important Notes + +1. **Configuration Order**: Configure speedup before installing packages +2. **HTTPS vs HTTP**: HTTPS mirrors don't require trusted-host configuration for PIP +3. **GitHub IP**: Different regions may require different IPs for optimal performance +4. **Persistence**: Configurations persist within the sandbox lifecycle +5. **Multiple Calls**: Subsequent speedup calls will override previous configurations +6. **PIP Installation**: The speedup feature only configures mirror sources and does not automatically install PIP + +## 3. GEM SDK + +### 3.1 Python SDK Approach + +```python +import random +import rock + +def main(): + """Main function to run the Sokoban demo with admin server requirement. + + NOTE: This demo requires the admin server to be running for proper execution. + Make sure to start the admin server before running this script. + """ + # Create environment using GEM standard interface + # NOTE: This requires the admin server to be running + env_id = "game:Sokoban-v0-easy" + env = rock.make(env_id) + + # Reset environment to initial state + observation, info = env.reset(seed=42) + print( + "\n" + + "=" * 80 + + "\nInitial Observation:\n" + + str(observation) + + "\n\nInitial Info:\n" + + str(info) + + "\n" + + "=" * 80 + + "\n" + ) + + # Run environment loop until termination + step_count = 0 + while True: + # Interactive environment operation with random actions + action = f"\\boxed{{{random.choice(['up', 'left', 'right', 'down'])}}}" + observation, reward, terminated, truncated, info = env.step(action) + + step_count += 1 + print( + "\n" + + "-" * 80 + + f"\nStep {step_count} - Action: {action}\nReward: {reward}\nObservation:\n{observation}\nInfo: {info}\nTerminated: {terminated}, Truncated: {truncated}\n" + + "-" * 80 + + "\n" + ) + + # Check if environment has reached terminal state + if terminated or truncated: + print("\n" + "=" * 80 + "\nEpisode finished!\n" + "=" * 80 + "\n") + break + + # Clean up environment resources + env.close() + +if __name__ == "__main__": + # Ensure admin server is running before executing + print( + "\n" + + "=" * 80 + + "\nIMPORTANT: Make sure the admin server is running before executing this demo!\nStart the admin server with: rock admin start\n" + + "=" * 80 + + "\n" + ) + main() +``` + +## Related Documents +- [Quick Start Guide](../../Getting%20Started/quickstart.md) - Learn how to quickly get started with the ROCK SDK +- [API Documentation](../api.md) - View the underlying API interfaces encapsulated by the SDK +- [Configuration Guide](../../User%20Guides/configuration.md) - Learn about SDK-related configuration options +- [Installation Guide](../../Getting%20Started/installation.md) - Detailed information about ROCK installation and setup \ No newline at end of file diff --git a/docs/versioned_docs/version-1.2.x/References/Python SDK References/remote_user.md b/docs/versioned_docs/version-1.2.x/References/Python SDK References/remote_user.md new file mode 100644 index 000000000..810bbcf02 --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/References/Python SDK References/remote_user.md @@ -0,0 +1,70 @@ +# Remote User + +Remote user management for creating and managing users in the sandbox. + +## Usage Examples + +```python +import asyncio +from rock.sdk.sandbox.config import SandboxConfig +from rock.sdk.sandbox.client import Sandbox + +from rock.actions import Action, CreateBashSessionRequest, Observation + + +async def test_remote_user(): + config = SandboxConfig( + image='hub.docker.alibaba-inc.com/chatos/python:3.11', + xrl_authorization='xxx', + cluster='nt-c' + ) + sandbox = Sandbox(config) + await sandbox.start() + + await sandbox.remote_user.create_remote_user('rock') + assert await sandbox.remote_user.is_user_exist('rock') + print('test remote user success') + +async def test_create_session_with_remote_user(): + config = SandboxConfig( + image='hub.docker.alibaba-inc.com/chatos/python:3.11', + xrl_authorization='xxx', + cluster='nt-c' + ) + sandbox = Sandbox(config) + await sandbox.start() + + await sandbox.remote_user.create_remote_user('rock') + assert await sandbox.remote_user.is_user_exist('rock') + + await sandbox.create_session(CreateBashSessionRequest(remote_user="rock", session="bash")) + + observation: Observation = await sandbox.run_in_session( + action=Action(session="bash", command="whoami") + ) + print(observation) + assert observation.output.strip() == "rock" + print('test create session with remote user success') + +if __name__ == '__main__': + asyncio.run(test_remote_user()) + asyncio.run(test_create_session_with_remote_user()) +``` + +## API + +### create_remote_user(username) + +Create a remote user. + +```python +await sandbox.remote_user.create_remote_user('username') +``` + +### is_user_exist(username) + +Check if a user exists. + +```python +exists = await sandbox.remote_user.is_user_exist('username') +``` diff --git a/docs/versioned_docs/version-1.2.x/References/Python SDK References/rock-agent.md b/docs/versioned_docs/version-1.2.x/References/Python SDK References/rock-agent.md new file mode 100644 index 000000000..b0a13183d --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/References/Python SDK References/rock-agent.md @@ -0,0 +1,283 @@ +# Rock Agent (Experimental) + +RockAgent is the core Agent implementation in the ROCK framework, directly inheriting from the `Agent` abstract base class. It provides complete Agent lifecycle management, including environment initialization, ModelService integration, command execution, and more. + +Using `sandbox.agent.install()` and `sandbox.agent.run(prompt)`, you can install and run Agents in the Sandbox environment provided by Rock. + +## Core Concepts + +The core workflow of RockAgent is divided into two phases: + +1. **install(config)**: Initialize the Agent environment, including deploying the working directory, setting environment variables, initializing the runtime environment, etc. +2. **run(prompt)**: Execute the Agent task, replace placeholders, and start the Agent process + +## Quick Start + +### Claude Code Example + +```yaml +run_cmd: "claude -p ${prompt}" + +runtime_env_config: + type: node + custom_install_cmd: "npm install -g @anthropic-ai/claude-code" + +env: + ANTHROPIC_BASE_URL: "" + ANTHROPIC_API_KEY: "" +``` + +### IFlowCli Example + +```yaml +run_cmd: "iflow -p ${prompt} --yolo" # ${prompt} is required + +runtime_env_config: + type: node + custom_install_cmd: "npm i -g @iflow-ai/iflow-cli@latest" + +env: # Environment variables + IFLOW_API_KEY: "xxxxxxx" + IFLOW_BASE_URL: "xxxxxxx" + IFLOW_MODEL_NAME: "xxxxxxx" +``` + +### LangGraph Agent Example + +```yaml +working_dir: "." # Upload local current directory containing langgraph_agent.py to sandbox + +run_cmd: "python langgraph_agent.py ${prompt}" # Run local script + +runtime_env_config: + type: python + pip: # Install pip dependencies + - langchain==1.2.3 + - langchain-openai==1.1.7 + - langgraph==1.0.6 + +env: + OPENAI_API_KEY: xxxxxxx +``` + +## Configuration Details + +### Basic Configuration + +```yaml +agent_type: "default" # Agent type identifier (default: "default") +agent_name: "demo-agent" # Agent instance name (default: random uuid) +version: "1.0.0" # Version identifier (default: "default") +instance_id: "instance-001" # Instance ID (default: "instance-id-") +agent_installed_dir: "/tmp/installed_agent" # Agent installation directory (default: "/tmp/installed_agent") +agent_session: "my-session" # Bash session identifier (default: "agent-session-") +env: # Environment variables (default: {}) + OPENAI_API_KEY: "xxxxxxx" +``` + +### Working Directory Configuration + +```yaml +working_dir: "./my_project" # Local directory to upload to sandbox (default: None, no upload) +project_path: "/testbed" # Working directory in sandbox for cd (default: None) +use_deploy_working_dir_as_fallback: true # Whether to fall back to deploy.working_dir when project_path is empty (default: true) +``` + +### Execution Configuration + +```yaml +run_cmd: "python main.py --prompt ${prompt}" # Agent execution command, must contain ${prompt} (default: None) + +# Timeout configuration +agent_install_timeout: 600 # Installation timeout in seconds (default: 600) +agent_run_timeout: 1800 # Run timeout in seconds (default: 1800) +agent_run_check_interval: 30 # Check interval in seconds (default: 30) +``` + +### Initialization Hooks + +```yaml +pre_init_cmds: # Commands executed before initialization (default: read from env_vars) + - command: "apt update && apt install -y git" + timeout_seconds: 300 # Command timeout in seconds (default: 300) + - command: "cp ${working_dir}/config.json /root/.config/config.json" + timeout_seconds: 60 + +post_init_cmds: # Commands executed after initialization (default: []) + - command: "echo 'Installation complete'" + timeout_seconds: 30 +``` + +**Notes**: +- `pre_init_cmds` and `post_init_cmds` do not inherit the Agent's `env` environment variables +- Typically used for installation operations and configuration file movement +- Common command examples: + - `apt update && apt install -y git wget tar` + - `cp ${working_dir}/config.json /root/.config/config.json` + +### RuntimeEnv Configuration + +```yaml +runtime_env_config: # Refer to RuntimeEnv documentation for details + type: "python" # Runtime type: python / node (default: "python") + version: "3.11" # Version number + pip: # Python dependency package list + - package1==1.0.0 + - package2==2.0.0 + custom_install_cmd: "git clone https://github.com/SWE-agent/SWE-agent.git && cd SWE-agent && pip install -e ." +``` + +**Node Runtime Example**: + +```yaml +runtime_env_config: + type: "node" + version: "22.18.0" + npm_registry: "https://registry.npmmirror.com" + custom_install_cmd: "npm i -g some-package" +``` + +**Automatic Operations**: +- Install corresponding runtime based on `type` (Python or Node.js) +- Install `pip` dependencies (if configured) +- Execute `custom_install_cmd` custom installation command (if configured) +- Support `npm_registry` configuration for Node.js npm mirror source + +### ModelService Configuration + +```yaml +model_service_config: # Refer to ModelService documentation for details + enabled: true # Enable ModelService (default: false) +``` + +**Automatic Operations**: +- Installation phase: Install ModelService (install only, do not start) +- Run phase: Start ModelService + `watch_agent` monitoring process + +**Notes**: You need to set the model request URL to the ModelService URL. For example, if the ModelService provides an OpenAI-compatible URL at `http://127.0.0.1:8080/v1/chat/completions`, you typically need to set the Agent's LLM request URL to `http://127.0.0.1:8080/v1/`. + +## API Reference + +### install(config) + +Initialize the Agent environment. + +**Execution Flow**: +1. If `working_dir` is configured, deploy to sandbox +2. Set up bash session and configure env environment variables +3. Execute `pre_init_cmds` +4. Initialize RuntimeEnv and ModelService in parallel (if enabled) +5. Execute `post_init_cmds` + +**Parameters**: +- `config`: Agent configuration file, supports two input methods: + - **String path**: YAML configuration file path, default value is `"rock_agent_config.yaml"` + - **RockAgentConfig object**: Directly pass a `RockAgentConfig` instance + +### run(prompt) + +Execute the Agent task. + +**Execution Flow**: +1. Replace placeholders and prepare Agent run command +2. Start the agent process +3. If ModelService is enabled, start `watch_agent` +4. Wait for task completion and return results + +## Advanced Usage + +### Difference and Interaction between working_dir and project_path + +| Configuration | Function | Interaction Method | +|--------------|----------|-------------------| +| `working_dir` | Local directory uploaded to sandbox | Calls `deploy.deploy_working_dir()` to upload, after upload `deploy.working_dir` becomes the path in sandbox | +| `${working_dir}` | Placeholder in commands | Replaced by `deploy.format()` with the value of `deploy.working_dir`, replaced in init_cmds and run_cmd in the configuration | +| `project_path` | Working directory in sandbox | Used for `cd project_path` before running, when not set it enters the `deploy.working_dir` working directory | +| `use_deploy_working_dir_as_fallback` | Whether to fall back to deploy.working_dir when project_path is not set at runtime | Default is `true`, when set to `false` it will not enter working_dir even if project_path is not set | + +**Usage Recommendations**: +- Use `working_dir` to upload local project code to sandbox +- Use `project_path` to specify the working directory in sandbox (e.g., `/testbed`) +- Set `use_deploy_working_dir_as_fallback: false` scenario: Need to perform local file mounting, but want to run Agent in the image's default working directory + +### Placeholder Usage + +Rock Agent supports replacing the following placeholders in the configuration file: + +- `${prompt}`: Required in run_cmd, will be replaced with the prompt passed to `run(prompt)` +- `${working_dir}`: Optional, will be replaced with the actual working directory path in sandbox, also supported in init_cmds and run_cmd + +**Example**: +```yaml +run_cmd: "python ${working_dir}/main.py --prompt ${prompt}" +``` + +### use_deploy_working_dir_as_fallback Explanation + +When `project_path` is not set: +- `true` (default): Before running Agent, it will automatically `cd` to `deploy.working_dir` +- `false`: Before running Agent, it will not automatically switch directories, staying in the current directory + +Applicable Scenarios: +- `true`: Most scenarios, where you want Agent to run in the uploaded code directory +- `false`: Need to mount local files, but want to run Agent in the image's default working directory (e.g., `/app`, `/testbed`) + +## Complete Configuration Example + +```yaml +# ========== Basic Configuration ========== +agent_type: "default" +agent_name: "demo-agent" +version: "1.0.0" +instance_id: "instance-001" +agent_installed_dir: "/tmp/installed_agent" +agent_session: "my-session" +env: + OPENAI_API_KEY: "xxxxxxx" + +# ========== Working Directory Configuration ========== +working_dir: "./my_project" +project_path: "/testbed" +use_deploy_working_dir_as_fallback: true + +# ========== Run Configuration ========== +run_cmd: "python ${working_dir}/main.py --prompt ${prompt}" + +# Timeout configuration +agent_install_timeout: 600 +agent_run_timeout: 1800 +agent_run_check_interval: 30 + +# ========== Initialization Commands ========== +pre_init_cmds: + - command: "apt update && apt install -y git" + timeout_seconds: 300 + - command: "cp ${working_dir}/config.json /root/.config/config.json" + timeout_seconds: 60 + +post_init_cmds: + - command: "echo 'Installation complete'" + timeout_seconds: 30 + +# ========== Runtime Environment Configuration ========== +runtime_env_config: + type: "python" + version: "3.11" + pip: + - langchain==1.2.3 + - langchain-openai==1.1.7 + +# ========== ModelService Integration ========== +model_service_config: + enabled: true +``` + +## Usage Examples + +### Using YAML Configuration File (Recommended) + +```python +# prepare a rock_agent_config.yaml +await sandbox.agent.install(config="rock_agent_config.yaml") +await sandbox.agent.run(prompt="hello") +``` diff --git a/docs/versioned_docs/version-1.2.x/References/Python SDK References/runtime-env.md b/docs/versioned_docs/version-1.2.x/References/Python SDK References/runtime-env.md new file mode 100644 index 000000000..e1996cfcd --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/References/Python SDK References/runtime-env.md @@ -0,0 +1,136 @@ +# RuntimeEnv + +The RuntimeEnv module is used to manage language runtime environments in the sandbox (currently providing Python / Node.js). + +## Quick Start (Example) + +```python +from rock.sdk.sandbox import Sandbox +from rock.sdk.sandbox.config import SandboxConfig +from rock.sdk.sandbox.runtime_env import RuntimeEnv, NodeRuntimeEnvConfig + +sandbox_config = SandboxConfig() +sandbox = Sandbox() +await sandbox.start() + +node_runtime_env_config = NodeRuntimeEnvConfig(version="default") +env = await RuntimeEnv.create(sandbox, node_runtime_env_config) + +await env.run("node --version") +``` + +## RuntimeEnv.create + +An async factory method that creates and initializes a RuntimeEnv instance based on the configuration, and automatically registers it to `sandbox.runtime_envs`. + +```python +from rock.sdk.sandbox.runtime_env import RuntimeEnv, NodeRuntimeEnvConfig + +env = await RuntimeEnv.create( + sandbox, + NodeRuntimeEnvConfig(version="22.18.0"), +) + +# Auto-registered; accessible via sandbox.runtime_envs[env.runtime_env_id] +print(env.runtime_env_id in sandbox.runtime_envs) # True +``` + +## wrapped_cmd + +Wraps a command by adding `bin_dir` to PATH to ensure executables from the runtime environment are used with priority. + +```python +wrapped = env.wrapped_cmd("node script.js") +# Returns: bash -c 'export PATH=/tmp/rock-runtime-envs/node/22.18.0/xxx/runtime-env/bin:$PATH && node script.js' +``` + +## run + +Executes a command within the runtime environment. Internally implemented based on `wrapped_cmd`. + +```python +await env.run("node script.js") +await env.run("npm install express") +``` + +## PythonRuntimeEnvConfig + +| Field | Type | Default | Description | +|------|------|--------|------| +| `type` | `Literal["python"]` | `"python"` | Type identifier | +| `version` | `"3.11" \| "3.12" \| "default"` | `"default"` | Python version; default is 3.11 | +| `pip` | `list[str] \| str \| None` | `None` | List of pip packages or a requirements.txt path | +| `pip_index_url` | `str \| None` | Environment variable | pip index mirror | +| `extra_symlink_dir` | `str \| None` | `None` | Target directory for executable symlinks | +| `extra_symlink_executables` | `list[str]` | `["python", "python3", "pip", "pip3"]` | List of executables to symlink | + +## NodeRuntimeEnvConfig + +| Field | Type | Default | Description | +|------|------|--------|------| +| `type` | `Literal["node"]` | `"node"` | Type identifier | +| `version` | `"22.18.0" \| "default"` | `"default"` | Node version; default is 22.18.0 | +| `npm_registry` | `str \| None` | `None` | npm registry mirror | +| `extra_symlink_dir` | `str \| None` | `None` | Target directory for executable symlinks | +| `extra_symlink_executables` | `list[str]` | `["node", "npm", "npx"]` | List of executables to symlink | + +## Constraints for Custom RuntimeEnv Implementations + +A custom RuntimeEnv must follow these rules: + +1. **Define the `runtime_env_type` class attribute**: used as a type identifier for automatic registration into the RuntimeEnv factory +2. **Override `_get_install_cmd()`**: return the install command +3. **The install command must end with**: renaming the directory to `runtime-env` + +## Simplified NodeRuntimeEnv Implementation Example + +```python +from rock.sdk.sandbox.runtime_env import RuntimeEnv, RuntimeEnvConfig +from typing import Literal +from pydantic import Field +from typing_extensions import override + +# Config class: defines the config type so RuntimeEnv.create() can route to the corresponding implementation +class NodeRuntimeEnvConfig(RuntimeEnvConfig): + type: Literal["node"] = "node" # Must match runtime_env_type + +# RuntimeEnv implementation class: defines how to install and run this runtime environment +class NodeRuntimeEnv(RuntimeEnv): + runtime_env_type = "node" # Auto-registered to RuntimeEnv._REGISTRY + + @override + def _get_install_cmd(self) -> str: + # Download the Node binary tarball and extract it, then rename to runtime-env + return ( + "wget -q -O node.tar.xz https://npmmirror.com/mirrors/node/v22.18.0/node-v22.18.0-linux-x64.tar.xz && " + "tar -xf node.tar.xz && " + "mv node-v22.18.0-linux-x64 runtime-env" + ) +``` + +## Speeding Up Base Runtime Installation + +`PythonRuntimeEnv` downloads Python packages from https://github.com/astral-sh/python-build-standalone/releases/ by default. If the network is unavailable or slow, you can override the default install command via `ROCK_RTENV_PYTHON_V31114_INSTALL_CMD` or `ROCK_RTENV_PYTHON_V31212_INSTALL_CMD` (e.g., switch to an internal registry or a mirror). + +Default value example: + +```python +"ROCK_RTENV_PYTHON_V31114_INSTALL_CMD": lambda: os.getenv( + "ROCK_RTENV_PYTHON_V31114_INSTALL_CMD", + "[ -f cpython31114.tar.gz ] && rm cpython31114.tar.gz; [ -d python ] && rm -rf python; " + "wget -q -O cpython31114.tar.gz https://github.com/astral-sh/python-build-standalone/releases/download/20251120/cpython-3.11.14+20251120-x86_64-unknown-linux-gnu-install_only.tar.gz " + "&& tar -xzf cpython31114.tar.gz && mv python runtime-env", +), +``` + +For example, override it to download from a mirror: + +```bash +export ROCK_RTENV_PYTHON_V31114_INSTALL_CMD='[ -f cpython31114.tar.gz ] && rm cpython31114.tar.gz; [ -d python ] && rm -rf python; wget -q -O cpython31114.tar.gz https://mirror.nju.edu.cn/github-release/astral-sh/python-build-standalone/20251209/cpython-3.11.14+20251209-x86_64-unknown-linux-gnu-install_only.tar.gz && tar -xzf cpython31114.tar.gz && mv python runtime-env' +``` + +Make sure the command creates a `runtime-env` directory under the default working directory of `runtime_env`, and that `${workdir}/runtime-env/bin/` contains the expected executables, e.g.: + +- `${workdir}/runtime-env/bin/python` + +The same applies to Node.js: you can override the install command via `ROCK_RTENV_NODE_V22180_INSTALL_CMD` to use a faster download/install method. \ No newline at end of file diff --git a/docs/versioned_docs/version-1.2.x/References/Python SDK References/sandbox.md b/docs/versioned_docs/version-1.2.x/References/Python SDK References/sandbox.md new file mode 100644 index 000000000..e6e1e4312 --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/References/Python SDK References/sandbox.md @@ -0,0 +1,114 @@ +# Handling Large Files and Long Command Outputs + +## `arun` + +`arun()` provides two knobs to control how `nohup` output is handled: + +1. **`response_limited_bytes_in_nohup`** *(integer type)* + Caps the number of characters returned from the nohup output file. Useful when you still need to stream some logs back but want an upper bound (default `None` = no cap). + +2. **`ignore_output`** *(bool, default `False`)* + When set to `True`, `arun()` skips reading the nohup output file entirely. The command still runs to completion and writes logs to `/tmp/tmp_.out`, but the SDK immediately returns a lightweight hint telling agents where to fetch the logs later (via `read_file`, download APIs, or custom commands). This fully decouples "execute command" from "inspect logs". The response also includes the **file size** to help users decide whether to download directly or read in chunks. + +```python +from rock.sdk.sandbox.client import Sandbox +from rock.sdk.sandbox.config import SandboxConfig +from rock.sdk.sandbox.request import CreateBashSessionRequest + +config = SandboxConfig( + image=f"{image}", + xrl_authorization=f"{xrl_authorization}", + user_id=f"{user_id}", + cluster=f"{cluster}", +) +sandbox = Sandbox(config) + +session = sandbox.create_session(CreateBashSessionRequest(session="bash-1")) + +# Example 1: limit the returned logs to 1024 characters +resp_limited = asyncio.run( + sandbox.arun( + cmd="cat /tmp/test.txt", + mode="nohup", + session="bash-1", + response_limited_bytes_in_nohup=1024, + ) +) + +# Example 2: skip collecting logs; agent will download/read them later +resp_detached = asyncio.run( + sandbox.arun( + cmd="bash run_long_job.sh", + mode="nohup", + session="bash-1", + ignore_output=True, + ) +) +print(resp_detached.output) +# Command executed in nohup mode without streaming the log content. +# Status: completed +# Output file: /tmp/tmp_xxx.out +# File size: 15.23 MB +# Use Sandbox.read_file(...), download APIs, or run 'cat /tmp/tmp_xxx.out' ... +``` + +## `read_file_by_line_range` + +Asynchronously reads file content by line range, with built-in support for automatic chunking and session management. Supports large file reading. + +### Key Features +- **Chunked reading for large files**: Automatically splits large files into chunks +- **Automatic line count**: Estimates total lines when end_line is not specified +- **Built-in retry mechanism**: Up to 3 retries for critical operations +- **Input validation**: Validates input parameters automatically +- **Session management**: Supports custom session or auto-created temporary session + +### Parameters +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `file_path` | str | - | File path to read (absolute or relative path in sandbox) | +| `start_line` | int \| None | 1 | Starting line number (1-based) | +| `end_line` | int \| None | None | Ending line number (inclusive), defaults to file end | +| `lines_per_request` | int | 1000 | Lines per request, range 1-10000 | + +### Return Value +- `ReadFileResponse`: Response object containing file content + - `content` (str): The file content read + +### Exception Handling +- `Exception`: Raised when `start_line < 1` +- `Exception`: Raised when `end_line < start_line` +- `Exception`: Raised when `lines_per_request` is not in range 1-10000 +- `Exception`: Raised when file reading fails + +### Usage Examples + +```python +# Read the entire file +response = await sandbox.read_file_by_line_range("/path/to/file.txt") + +# Read a specific line range (lines 100 to 500) +response = await sandbox.read_file_by_line_range( + "/path/to/file.txt", + start_line=100, + end_line=500 +) + +# Read from line 1990 to the end of file +response = await sandbox.read_file_by_line_range( + "/path/to/file.txt", + start_line=1990 +) + +# Use custom chunk size +response = await sandbox.read_file_by_line_range( + "/path/to/file.txt", + lines_per_request=5000 +) +``` + +### Notes +- Line numbers are 1-based, not 0-based +- For large files, consider increasing `lines_per_request` for better efficiency +- File path must be a valid path within the sandbox +- Uses `sed` command for file reading; ensure the sandbox image supports this command diff --git a/docs/versioned_docs/version-1.2.x/References/api.md b/docs/versioned_docs/version-1.2.x/References/api.md new file mode 100644 index 000000000..d73bf49d6 --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/References/api.md @@ -0,0 +1,195 @@ +--- +sidebar_position: 1 +--- + +# API Reference + +This guide provides detailed information about the core API services provided by the ROCK platform, including sandbox environment management and GEM environment interaction. + +## 1. Overview + +The ROCK platform provides two core API services: +- Sandbox API: Sandbox environment management +- GEM API: GEM environment interaction + +All API interfaces follow RESTful design principles and support JSON format data exchange. + +## 2. Sandbox API + +Full lifecycle management functions for sandbox environments: + +### Sandbox Management Interfaces + +1. **Start Sandbox** - Start a sandbox environment + - Create a new sandbox instance + - Support specifying image, resource configuration and other parameters + +2. **Start Sandbox Async** - Asynchronously start a sandbox environment + - Asynchronously create a sandbox instance + - Suitable for scenarios requiring quick response + +3. **Check Sandbox Alive Status** - Check sandbox alive status + - Verify if the sandbox is running normally + +4. **Get Sandbox Statistics** - Get sandbox statistics + - Get resource usage statistics of the sandbox + +5. **Get Sandbox Status** - Get detailed sandbox status + - Get complete status information of the sandbox + +6. **Stop Sandbox** - Stop sandbox environment + - Safely shut down the sandbox instance + +7. **Commit Sandbox** - Commit sandbox as image + - Save current sandbox state as a new image + +### Command Execution Interfaces + +8. **Execute Command** - Execute command in sandbox + - Run specified command directly in the sandbox + +9. **Create Bash Session** - Create Bash session + - Create a persistent Bash session environment + +10. **Run Command in Session** - Run command in session + - Execute command in a created session + +11. **Close Session** - Close session + - Release session resources + +### File Operation Interfaces + +12. **Read File** - Read sandbox file + - Read specified file content from the sandbox + +13. **Write File** - Write sandbox file + - Write file to the sandbox + +14. **Upload File** - Upload file to sandbox + - Upload local file to the sandbox + +## 3. GEM API + +GEM environment interaction functions: + +1. **Make Environment** - Create GEM environment + - Initialize a new GEM environment instance + +2. **Reset Environment** - Reset GEM environment + - Reset GEM environment to initial state + +3. **Step Environment** - Execute GEM environment step + - Execute an action step in the GEM environment + +4. **Close Environment** - Close GEM environment + - Release GEM environment resources + + +## 4. HTTP API Usage Examples + +### 4.1 Sandbox API Examples + +#### Start Sandbox +```bash +curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/start' \ +-H 'Content-Type: application/json' \ +-d '{ + "image": "python:3.11", + "resources": { + "cpu": "2", + "memory": "8g" + } +}' +``` + +#### Asynchronously Start Sandbox +```bash +curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/start_async' \ +-H 'Content-Type: application/json' \ +-d '{ + "image": "python:3.11", + "resources": { + "cpu": "2", + "memory": "8g" + } +}' +``` + +#### Execute Command +```bash +curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/execute' \ +-H 'Content-Type: application/json' \ +-d '{ + "sandbox_id": "sandbox-12345", + "command": "ls -la" +}' +``` + +#### Create Session +```bash +curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/create_session' \ +-H 'Content-Type: application/json' \ +-d '{ + "sandbox_id": "sandbox-12345", + "session": "my_session" +}' +``` + +#### Run Command in Session +```bash +curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/run_in_session' \ +-H 'Content-Type: application/json' \ +-d '{ + "sandbox_id": "sandbox-12345", + "session": "my_session", + "command": "python script.py" +}' +``` + +#### Upload File +```bash +curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/upload' \ +-F 'file=@./local_file.txt' \ +-F 'target_path=./remote_file.txt' \ +-F 'sandbox_id=sandbox-12345' +``` + +#### Stop Sandbox +```bash +curl -X POST 'http://localhost:8080/apis/envs/sandbox/v1/stop' \ +-H 'Content-Type: application/json' \ +-d '{ + "sandbox_id": "sandbox-12345" +}' +``` + +### 4.2 GEM API Examples + +```bash +# Create GEM environment +curl -X POST 'http://localhost:8080/apis/v1/envs/gem/make' \ +-H 'Content-Type: application/json' \ +-d '{"env_id": "game:Sokoban-v0-easy"}' + +# Reset environment +curl -X POST 'http://localhost:8080/apis/v1/envs/gem/reset' \ +-H 'Content-Type: application/json' \ +-d '{"sandbox_id": "sandbox-12345", "seed": 42}' + +# Execute step +curl -X POST 'http://localhost:8080/apis/v1/envs/gem/step' \ +-H 'Content-Type: application/json' \ +-d '{"sandbox_id": "sandbox-12345", "action": "random_action"}' + +# Close environment +curl -X POST 'http://localhost:8080/apis/v1/envs/gem/close' \ +-H 'Content-Type: application/json' \ +-d '{"sandbox_id": "sandbox-12345"}' +``` + +## Related Documents + +- [Quick Start Guide](../Getting%20Started/quickstart.md) - Learn how to quickly get started with ROCK API +- [Python SDK Documentation](./Python%20SDK%20References/python_sdk.md) - Learn how to use the SDK to call APIs +- [Configuration Guide](../User%20Guides/configuration.md) - Learn about API-related configuration options +- [Installation Guide](../Getting%20Started/installation.md) - Detailed information about ROCK installation and setup \ No newline at end of file diff --git a/docs/versioned_docs/version-1.2.x/Release Notes/index.md b/docs/versioned_docs/version-1.2.x/Release Notes/index.md new file mode 100644 index 000000000..27d56c625 --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/Release Notes/index.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 1 +--- +# Release Notes +* [release v1.2.0](v1.2.0.md) diff --git a/docs/versioned_docs/version-1.2.x/Release Notes/v1.2.0.md b/docs/versioned_docs/version-1.2.x/Release Notes/v1.2.0.md new file mode 100644 index 000000000..8c09e2b0c --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/Release Notes/v1.2.0.md @@ -0,0 +1,54 @@ +# v1.2.0 + +## Release Date +February 3, 2026 + + +--- + +## SDK + +### New Features + +#### Runtime Environment +**[Runtime Environment References Documentation](../References/Python%20SDK%20References/runtime-env.md)** + +- **NEW**: Executable symlink support via `extra_symlink_dir` and `extra_symlink_executables` for exposing runtime executables to system paths + +#### Model Service (Experimental) +**[Model Service References Documentation](../References/Python%20SDK%20References/model-service.md)** + +Handles AI model call communications between agents and LLM inference services: +- Local mode: File-based IPC between Agent and Roll runtime, implementing request-response via file protocol +- Proxy mode: Request forwarding to external LLM services with routing and retry support + +- SDK supports `anti_call_llm` for proxying Agent requests +- **NEW**: Complete CLI start command parameters (`--config-file`, `--host`, `--port`, `--proxy-base-url`, `--retryable-status-codes`, `--request-timeout`) +- **NEW**: Trajectory (traj) logging - records LLM request/response to JSONL files (`ROCK_MODEL_SERVICE_DATA_DIR`, `ROCK_MODEL_SERVICE_TRAJ_APPEND_MODE`) +- **NEW**: Server-side `ModelServiceConfig` configuration (`host`, `port`, `proxy_base_url`, `proxy_rules`, `retryable_status_codes`, `request_timeout`) + +#### Agent Examples +**[Examples Directory](https://github.com/Modelized/ROCK/tree/master/examples/agents)** + +Practical examples demonstrating ROCK Agent integration with various AI frameworks: + +- **claude_code/**: Claude Code Agent integration example using Node.js runtime + - Command: `claude -p ${prompt}` + - Requires: `npm install -g @anthropic-ai/claude-code` + - Configuration via `rock_agent_config.yaml` + +- **iflow_cli/**: iFlow CLI Agent integration example using Node.js runtime + - Command: `iflow -p ${prompt} --yolo` + - Requires: `npm i -g @iflow-ai/iflow-cli@latest` + +- **swe_agent/**: SWE Agent integration example + - Demonstrates standard ROCK Agent setup pattern + +- **iflow_cli/integration_with_model_service/**: Model Service integration examples + - **local/**: Local mode example with custom LLM backend + - Shows `anti_call_llm` usage and model service loop pattern + - **proxy/**: Proxy mode example with iFlow CLI + - Demonstrates `rock model-service start --type proxy --proxy-base-url` usage + + +## Admin diff --git a/docs/versioned_docs/version-1.2.x/User Guides/configuration.md b/docs/versioned_docs/version-1.2.x/User Guides/configuration.md new file mode 100644 index 000000000..604256878 --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/User Guides/configuration.md @@ -0,0 +1,189 @@ +--- +sidebar_position: 4 +--- + +# Configuration + +This guide provides detailed instructions on how to configure the ROCK environment to meet different usage requirements, including local development, testing, and production deployment. + +## 1. Environment Variable Configuration + +ROCK supports configuring key parameters through environment variables. The main environment variables are as follows: + +```bash +export ROCK_BASE_URL=http://localhost:8080 # ROCK service base URL +export ROCK_LOG_LEVEL=INFO # Log level +export ROCK_LOGGING_PATH=/path/to/logs # Log file path, default None (output to console) +export ROCK_LOGGING_FILE_NAME=rocklet.log # Log file name, default "rocklet.log", can be customized by admin like admin.log +export ROCK_LOGGING_LEVEL=INFO # Log output level, default "INFO" +export ROCK_WORKER_ENV_TYPE=local # Runtime environment type, options: local, docker, uv, pip +``` + +More environment variables can be found in `rock/env_vars.py`. + +### 1.1 Runtime Environments + +ROCK provides multiple different runtime environments to meet the needs of different scenarios, configured through the `ROCK_WORKER_ENV_TYPE` environment variable. Each environment has different deployment requirements, performance characteristics and applicable scenarios. Each environment has its own unique advantages and limitations, and developers can choose the most suitable runtime environment according to their deployment needs. + +#### 1.1.1 Docker Runtime Environment + +The Docker runtime environment is suitable for Docker image environments where dependencies are pre-installed. This environment requires the `/tmp/miniforge/bin/rocklet` executable to be directly available in the deployment environment. + +**Mount Configuration:** +- `/tmp/miniforge` - Contains pre-installed Python environment +- `/tmp/local_files` - Contains local files required for execution + +**Start Command:** +```bash +chmod +x /tmp/local_files/docker_run.sh && /tmp/local_files/docker_run.sh +``` + +**Use Cases:** +- Containerized deployment environments +- Already built custom Docker image containing `rocklet` +- Suitable for production, fast startup + +**Requirements:** +- Requires a custom Docker image containing `/tmp/miniforge/bin/rocklet` executable +- Docker environment support + +#### 1.1.2 Local Runtime Environment + +The local runtime environment directly uses the Python environment and project files of the current deployment. This environment requires the same operating system between the host and container to directly mount the virtual environment and Python interpreter. + +**Mount Configuration:** +- `python_env_path` - Python environment path +- `project_root` - Project root directory +- `.venv` - Virtual environment directory (mounted as `/tmp/miniforge` in container) +- `local_files` - Local files required for execution + +**Start Command:** +```bash +chmod +x /tmp/local_files/docker_run.sh && /tmp/local_files/docker_run.sh +``` + +**Use Cases:** +- Development environments +- Scenarios where host and target container use the same operating system +- Need to quickly reuse existing Python environment + +**Requirements:** +- Same operating system (host/container) +- Direct access to the currently deployed `.venv` virtual environment +- Python interpreter path compatibility + +#### 1.1.3 UV Runtime Environment + +The UV runtime environment only depends on the available ROCK project, but initialization is relatively slow and network requirements are higher. This environment is most suitable for scenarios without preconfigured environments. It rebuilds the rocklet environment from the original project. This is the recommended environment for Mac OS. + +**Mount Configuration:** +- `project_root` - Project root directory (mounted as `/tmp + project_root` in container) +- `local_files` - Local files required for execution + +**Start Command:** +```bash +chmod +x /tmp/local_files/docker_run_with_uv.sh && /tmp/local_files/docker_run_with_uv.sh '' +``` + +**Use Cases:** +- Mac OS +- Cross-OS startup +- Scenarios without preconfigured environment +- No uv management Rock + +**Advantages:** +- No pre-built image required +- Good cross-platform compatibility +- Suitable for development and testing especially + +**Limitations:** +- Initialization is relatively slow +- Higher network requirements +- Longer startup time + +#### 1.1.4 PIP Runtime Environment + +The PIP runtime environment uses pip to install required dependencies in the container. This environment is suitable for quick setup and scenarios where dependencies can be installed in the container. It is the default runtime environment. It does not require pre-built images containing dependencies, and manages Python packages directly through pip. + +**Mount Configuration:** +- `local_files` - Contains local files required for execution + +**Start Command:** +```bash +chmod +x /tmp/local_files/docker_run_with_pip.sh && /tmp/local_files/docker_run_with_pip.sh +``` + +**Use Cases:** +- ROCK installation from PIP source +- Fast testing of ROCK + +**Advantages:** +- Simple deployment setup + +**Limitations:** +- Long dependency installation time +- Requires network access to install dependency packages +- Dependencies need to be installed each time on startup + +#### 1.1.5 Configuration Guide + +Refer to the following selection guide for different use cases: + +| Scenario | Recommended Environment | Reason | +|----------|--------------------------|-------| +| Production environment | Docker Runtime | Fast startup, stable performance | +| Development environment, same OS | Local Runtime | Environment reuse, fast development cycle | +| Mac development | UV Runtime | Best cross-platform compatibility support | +| Cross-platform development | UV Runtime | Avoids environment compatibility issues | +| Fast testing | UV Runtime | Requires no pre-configuration | +| PIP source installation | PIP Runtime | Install dependencies directly with pip | + +These runtime environments are configured through the `ROCK_WORKER_ENV_TYPE` environment variable, which can be set to "local", "docker", "uv" or "pip". + +### 1.2 Logging Configuration + +Regarding logging configuration, ROCK's logging system has the following characteristics: + +- The logging system cannot output to both file and console simultaneously. If `ROCK_LOGGING_PATH` is set, logs will be output to the designated file, otherwise to console. +- `ROCK_LOGGING_LEVEL` is used to control the output log level, while `ROCK_LOG_LEVEL` is used for general log level settings. + +## 2. Distributed Deployment Requirements + +Since ROCK supports distributed deployment, when running on different nodes of a Ray cluster, the following consistency requirements must be met: + +#### Directory Structure Consistency + +On all Ray nodes, the following directory structure must be completely consistent: +- ROCK project repository directory +- `.venv` virtual environment directory +- The base Python directory that `.venv` depends on + + +#### Mounting Requirements + +ROCK's startup depends on mounting the ROCK project and the corresponding base Python environment, requiring consistency in multi-machine environments: + +#### Verifying Distributed Configuration + +Distributed deployment configuration can be verified through the following methods: + +```bash +# Check directory consistency on all nodes +ls -la /path/to/rock +ls -la /path/to/rock/.venv +ls -la $ROCK_PYTHON_ENV_PATH + +# Verify Python environment availability +$ROCK_PYTHON_ENV_PATH/bin/python --version + +# Check environment variable settings on all nodes +echo $ROCK_PYTHON_ENV_PATH +echo $ROCK_PROJECT_ROOT +``` + +## Related Documents + +- [Quick Start Guide](../Getting%20Started/quickstart.md) - Learn how to quickly set up the ROCK environment +- [API Documentation](../References/api.md) - View sandbox-related API interfaces +- [Python SDK Documentation](../References/Python%20SDK%20References/python_sdk.md) - Learn how to use the SDK to configure sandboxes +- [Installation Guide](../Getting%20Started/installation.md) - Detailed information about ROCK installation and setup \ No newline at end of file diff --git a/docs/versioned_docs/version-1.2.x/overview.md b/docs/versioned_docs/version-1.2.x/overview.md new file mode 100644 index 000000000..0c377e8b2 --- /dev/null +++ b/docs/versioned_docs/version-1.2.x/overview.md @@ -0,0 +1,33 @@ +--- +sidebar_position: 1 +--- + +# Overview + +ROCK (Reinforcement Open Construction Kit) is an open-source reinforcement learning environment development framework designed to simplify the development, deployment, and management of reinforcement learning environments. + +## What is ROCK + +ROCK (Reinforcement Open Construction Kit) is an open-source reinforcement learning environment development framework. By using ROCK, developers can quickly develop reinforcement learning environments and integrate with other reinforcement learning training frameworks to implement efficient reinforcement learning training. + +ROCK provides comprehensive sandbox environment management capabilities, supports containerized deployment, and enables rapid creation, execution, and destruction of environments. Additionally, ROCK is compatible with the GEM protocol, providing standardized interfaces for reinforcement learning environments. + +## Core Capabilities of ROCK + +1. **Simplified Development Process**: Simplifies the development, construction, and management of reinforcement learning environments, supporting various open-source reinforcement learning environments +2. **Large-scale Scheduling and Deployment**: Enables large-scale scheduling and deployment of rapid reinforcement learning environments. By supporting the GEM protocol, reinforcement learning environments can be easily accessed +3. **Framework Integration**: Integrates with other reinforcement learning training frameworks to achieve large-scale and scalable reinforcement learning training + +## Value of ROCK + +ROCK provides significant value to different roles of engineers: + +- **Reinforcement Learning Algorithm Engineers**: ROCK simplifies the development process of reinforcement learning environments, allowing engineers to focus on algorithm implementation +- **Reinforcement Learning Application Engineers**: ROCK enables large-scale deployment of rapid reinforcement learning environments, improving application development efficiency + +## Learn More + +- [Quick Start Guide](./Getting%20Started/quickstart.md) - Get started with ROCK quickly +- [Configuration Guide](./User%20Guides/configuration.md) - Detailed information about ROCK configuration options +- [API Documentation](./References/api.md) - View ROCK's API interfaces +- [Python SDK Documentation](./References/Python%20SDK%20References/python_sdk.md) - Learn how to use ROCK's Python SDK \ No newline at end of file diff --git a/docs/versioned_sidebars/version-1.2.x-sidebars.json b/docs/versioned_sidebars/version-1.2.x-sidebars.json new file mode 100644 index 000000000..b475b1153 --- /dev/null +++ b/docs/versioned_sidebars/version-1.2.x-sidebars.json @@ -0,0 +1,64 @@ +{ + "tutorialSidebar": [ + "overview", + { + "type": "category", + "label": "Getting Started", + "link": { + "type": "doc", + "id": "Getting Started/quickstart" + }, + "items": [ + { + "type": "autogenerated", + "dirName": "Getting Started" + } + ] + }, + { + "type": "category", + "label": "User Guides", + "items": [ + { + "type": "autogenerated", + "dirName": "User Guides" + } + ] + }, + { + "type": "category", + "label": "References", + "items": [ + "References/api", + { + "type": "category", + "label": "Python SDK References", + "link": { + "type": "doc", + "id": "References/Python SDK References/python_sdk" + }, + "items": [ + { + "type": "autogenerated", + "dirName": "References/Python SDK References" + } + ] + } + ] + }, + { + "type": "category", + "label": "Release Notes", + "link": { + "type": "doc", + "id": "Release Notes/index" + }, + "items": [ + { + "type": "autogenerated", + "dirName": "Release Notes" + } + ] + } + ] +}