diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 891cd6306..892d696d8 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -144,7 +144,7 @@ const config = { // release note按照版本号倒排 return reverseReleaseNoteSidebars(filterHiddenSidebars); }, - lastVersion: '0.2.x', + lastVersion: '1.0.x', includeCurrentVersion: false, versions: convertVersionsArrayToObject(versions) }, diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x.json b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x.json new file mode 100644 index 000000000..06f3df300 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x.json @@ -0,0 +1,30 @@ +{ + "version.label": { + "message": "1.0.x", + "description": "The label for version current" + }, + "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'" + } +} \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/Getting Started/installation.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/Getting Started/installation.md new file mode 100644 index 000000000..50368c151 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.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.0.x/Getting Started/quickstart.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/Getting Started/quickstart.md new file mode 100644 index 000000000..1fe3dfe7d --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/Getting Started/quickstart.md @@ -0,0 +1,191 @@ +--- +sidebar_position: 2 +--- + +# 快速上手 + +本指南将通过完整的示例演示如何使用 ROCK 创建和管理强化学习环境。ROCK (Reinforcement Open Construction Kit) 是一个全面的沙箱环境管理框架，主要用于强化学习和AI开发环境。 + +## 目录 + +- [快速上手](#快速上手) + - [目录](#目录) + - [1. 环境准备](#1-环境准备) + - [1.1 系统要求](#11-系统要求) + - [1.2 验证依赖安装](#12-验证依赖安装) + - [1.3 项目初始化](#13-项目初始化) + - [2. 激活虚拟环境](#2-激活虚拟环境) + - [3. 验证环境配置](#3-验证环境配置) + - [4. 启动 ROCK 服务](#4-启动-rock-服务) + - [5. 运行示例环境](#5-运行示例环境) + - [5.1 示例说明](#51-示例说明) + - [6. 分布式环境配置（可选）](#6-分布式环境配置可选) + - [7. MacOS 启动](#7-macos-启动) + - [8. 从Pip源启动](#8-从pip源启动) + - [总结](#总结) + - [下一步学习](#下一步学习) + +## 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/docker_run_with_uv.sh` 脚本。 + +> **注意**: 相比 Linux 系统，macOS 上的启动速度会较慢，且比较依赖网络环境，可以根据实际情况调整脚本。ROCK_WORKER_ENV_TYPE的细节可以参考 [Configuration Guide](../User%20Guides/configuration.md). + + +## 8. 从Pip源启动 + +如果从Pip源启动Admin Server，在参照[installation.md](./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.0.x/Getting Started/rockroll.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/Getting Started/rockroll.md new file mode 100644 index 000000000..d53a6dbc4 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.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/docs/English/QuickStart/) + + +#### 注意 +此方式会将所有 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快速指南](https://rock.io.alibaba-inc.com/docs/rock/CN/quickstart)部署并启动 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.0.x/References/Python SDK References/python_sdk.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/References/Python SDK References/python_sdk.md new file mode 100644 index 000000000..388cb37be --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/References/Python SDK References/python_sdk.md @@ -0,0 +1,183 @@ +--- +sidebar_position: 2 +--- + +# Python SDK 参考 + +本指南详细介绍如何使用 ROCK SDK 进行开发，包括沙箱环境管理和 GEM 环境交互。 + +## 目录 + +- [Python SDK 参考](#python-sdk-参考) + - [目录](#目录) + - [1. 概述](#1-概述) + - [2. Sandbox SDK](#2-sandbox-sdk) + - [2.1 基本沙箱操作](#21-基本沙箱操作) + - [3.2 沙箱组管理](#32-沙箱组管理) + - [相关文档](#相关文档) + - [3.3 配置示例](#33-配置示例) + - [4. GEM SDK](#4-gem-sdk) + - [4.1 Python SDK 方式](#41-python-sdk-方式) + +## 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()) +``` + +### 3.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() +``` + +## 相关文档 + +- [快速开始指南](../../Getting%20Started/quickstart.md) - 了解如何快速开始使用 ROCK SDK +- [API 文档](../api.md) - 查看 SDK 封装的底层 API 接口 +- [配置指南](../../User%20Guides/configuration.md) - 了解 SDK 相关的配置选项 +- [安装指南](../../Getting%20Started/installation.md) - 详细了解 ROCK 安装和配置 + +### 3.3 配置示例 + +```python +config = SandboxConfig( + image="python:3.11", + auto_clear_seconds=60 * 20, + experiment_id="test", +) +``` + +## 4. GEM SDK + +### 4.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() +``` \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/References/Python SDK References/sandbox.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/References/Python SDK References/sandbox.md new file mode 100644 index 000000000..5a94c93a5 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/References/Python SDK References/sandbox.md @@ -0,0 +1,62 @@ +# Sandbox SDK 参考 + +## `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次重试）、参数验证。以下是使用示例: +```python +# 读取整个文件 +response = await read_file_by_line_range("example.txt") + +# 读取指定行范围 +response = await read_file_by_line_range("example.txt", start_line=1, end_line=2000) +``` \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/References/api.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/References/api.md new file mode 100644 index 000000000..0200ed969 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/References/api.md @@ -0,0 +1,217 @@ +--- +sidebar_position: 1 +--- + +# API 参考 + +本指南详细介绍 ROCK 平台提供的核心 API 服务，包括沙箱环境管理和 GEM 环境交互。 + +## 目录 + +- [API 参考](#api-参考) + - [目录](#目录) + - [1. 概述](#1-概述) + - [2. Sandbox API](#2-sandbox-api) + - [沙箱管理接口](#沙箱管理接口) + - [命令执行接口](#命令执行接口) + - [文件操作接口](#文件操作接口) + - [3. GEM API](#3-gem-api) + - [相关文档](#相关文档) + - [4. HTTP API 使用示例](#4-http-api-使用示例) + - [4.1 Sandbox API 示例](#41-sandbox-api-示例) + - [启动沙箱](#启动沙箱) + - [异步启动沙箱](#异步启动沙箱) + - [执行命令](#执行命令) + - [创建会话](#创建会话) + - [在会话中执行命令](#在会话中执行命令) + - [上传文件](#上传文件) + - [停止沙箱](#停止沙箱) + - [4.2 GEM API 示例](#42-gem-api-示例) + +## 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环境资源 + +## 相关文档 + +- [快速开始指南](../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 安装和配置 + + +## 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"}' +``` \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/References/model-service.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/References/model-service.md new file mode 100644 index 000000000..11098ec92 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/References/model-service.md @@ -0,0 +1,115 @@ +--- +sidebar_position: 2 +--- + +# 模型服务 (Model Service) + +ROCK提供的Model Service负责处理AI模型调用的通信，为代理(Agent)和训练框架(如Roll)或实际的LLM推理服务之间提供通信桥梁。 + +## 架构概述 + +模型服务使用文件系统作为通信媒介，实现代理和模型间的请求-响应机制。当代理需要调用模型时，请求首先写入日志文件，然后由负责监听的组件处理响应。当模型生成响应后，结果将写回日志文件，并由等待的代理读取。 + +## CLI命令 + +如果需要通过CLI使用模型服务, ROCK提供了一个CLI命令集，可以在沙箱中安装ROCK后, 通过 `rock model-service` 访问: + +### start命令 +开始模型服务进程 +```bash +rock model-service start --type [local|proxy] +``` + +参数: +- `--type`: 模型服务类型，可选`local`或`proxy`，默认为`local` + +### 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 +``` + +元数据包含时间戳和索引信息，用于保证消息顺序和处理。 + +## 沙箱集成 + +### ModelServiceConfig +位于`rock/sdk/sandbox/model_service/base.py`，定义了沙箱中的模型服务配置: +- 工作目录 +- Python和模型服务安装命令 +- 会话环境变量 +- 各种命令模板 + +### ModelService类 +处理沙箱内模型服务的生命周期: +- `install()`: 在沙箱中安装模型服务依赖 +- `start()`: 启动模型服务 +- `stop()`: 停止模型服务 +- `watch_agent()`: 监控代理进程 +- `anti_call_llm()`: 执行反调用LLM操作 + +## 工作流程 + +1. 代理发起模型调用请求 +2. 请求被格式化并写入日志文件 +3. 模型服务监听日志文件，捕获新请求 +4. 运行时(Roll)处理请求并生成响应 +5. 响应写入日志文件 +6. 模型服务返回响应给代理 + +## 配置选项 + +### 服务配置 +- `SERVICE_HOST`: 服务主机地址，默认为"0.0.0.0" +- `SERVICE_PORT`: 服务端口，默认为8080 + +### 日志配置 +- `LOG_FILE`: 用以通信的日志文件路径，包含请求和响应数据 + +### 轮询配置 +- `POLLING_INTERVAL_SECONDS`: 轮询间隔，默认为0.1秒 +- `REQUEST_TIMEOUT`: 请求超时时间，默认为无限 + +### 标记配置 +定义了用于区分日志文件中不同类型消息的标记: +- `REQUEST_START_MARKER` / `REQUEST_END_MARKER` +- `RESPONSE_START_MARKER` / `RESPONSE_END_MARKER` +- `SESSION_END_MARKER` \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/References/sandbox-agent.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/References/sandbox-agent.md new file mode 100644 index 000000000..13583a3a6 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/References/sandbox-agent.md @@ -0,0 +1,49 @@ +--- +sidebar_position: 3 +--- + +# 沙箱代理 (Sandbox Agent) + +沙箱代理是ROCK框架中用于在隔离环境中运行AI智能体任务的组件，提供安全且可控制的智能体执行环境。代理可以与模型服务(Model Service)集成，实现LLM模型调用的优雅处理。 + +## 架构概述 + +沙箱代理通过在隔离的沙箱环境中初始化和执行智能体任务，包括安装必要的依赖、配置运行环境等步骤。代理系统支持多种不同的智能体类型，如SWE-agent和IFlow CLI等，每种类型都有其特定的配置和实现方式。 + +代理可以与模型服务集成，在任务执行期间处理AI模型调用。当代理需要查询或调用AI模型时，模型服务会在后台处理模型通信，使代理专注于任务执行。 + + +## Sandbox Agent 初始化流程 + +1. 创建沙箱环境和代理实例 +2. 调用`init()`方法初始化代理 +3. 在沙箱中创建专用的bash会话 +4. 执行预启动命令（如环境配置） +5. 安装必要的依赖（Python、Node.js等） +6. 安装特定的智能体工具（如SWE-agent或IFlow CLI） +7. 如果配置了模型服务，将同步初始化模型服务 + +## Sandbox Agent 执行流程 + +1. 准备任务运行参数（问题陈述、项目路径等） +2. 调用`run()`方法执行任务 +3. 准备运行所需的配置文件, 并将配置文件上传到沙箱环境(如果需要) +4. 执行Agent +6. 如果配置了模型服务，同步监控Agent进程 +7. 等待任务完成并返回结果 + +## Model Service 集成能力 + +沙箱Agent支持与模型服务的无缝集成，为AI模型调用提供通信桥梁。这种集成允许Agent通过文件系统通信协议与模型服务交互，实现异步的请求-响应机制。在Agent初始化时, 可以将Agent请求的LLM地址配置为model-service server的地址(如默认提供http://localhost:8080/v1/chat/completions), 从而利用model-service代理访问实际推理服务; 当Agent与模型服务集成时的工作流程: + +### 任务开始前 +1. 调用`start_model_service()`启动模型服务 +2. 调用`watch_agent()`设置对Agent进程的监控 + +### Agent调用LLM时 +1. Agent发起模型调用请求 +2. 请求通过文件通信协议写入文件 +3. 模型服务监听器捕获请求 +4. 实际的AI模型返回响应 +5. 响应通过文件通信协议写回 +6. Agent读取响应并继续执行 \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/Release Notes/index.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/Release Notes/index.md new file mode 100644 index 000000000..846d74e8b --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/Release Notes/index.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 1 +--- +# 版本说明 +* [release v1.0.0](v1.0.0.md) \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/Release Notes/v1.0.0rc1.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/Release Notes/v1.0.0rc1.md new file mode 100644 index 000000000..e34288f81 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/Release Notes/v1.0.0rc1.md @@ -0,0 +1,143 @@ +# v1.0.0rc1 + +## 发布日期 +2026 年 1 月 5 日 + +## 概览 +这是一次重大版本发布，引入了多项强大的新功能，包括 Model Service、ROCK Install Agent、Remote User 管理等, 同时还包含显著的性能提升、系统优化与更强的可观测性能力。 + +--- + +## SDK + +### 新功能 + +#### Model Service +**[Model Service 参考文档](../References/model-service.md)** + +提供完整的模型服务能力，包括： +- 支持文件处理器的本地模型服务器 +- 用于无缝交互的模型客户端 +- 支持模型请求代理（Proxy） +- 通过 CLI 参数按“类型”选择模型 +- 与 SWE Agent 安装并发初始化 +- 用于线程安全操作的锁机制 + + +#### Sandbox Agent +**[Sandbox Agent 参考文档](../References/sandbox-agent.md)** + +用于在ROCK的Sandbox中快速安装Agent的功能： +- 简易的 Agent 安装接口 +- 与Model-Service快速集成的能力 +- 支持多种类型的Agent在隔离的沙箱环境中本地运行 +--- + +### 增强 + +#### Environment Builder +- 新增 `build_remote` 参数，用于远程环境构建 +- 更新超时配置，提供更好的控制能力 +- 在 `arun` 的 ignore_output 中增强文件大小信息展示 + +#### 性能优化 +- 优化 PID 提取逻辑，使用兼容 bash 的模式 +- 提升 `arun` 方法性能 +- 改进文件处理相关操作 + +#### API 改进 +- 为运行 API execute 操作增加更多可选变量 +- 增强请求/响应处理 +- 改进错误报告，包含文件大小细节 + +--- + +### Bug 修复 +- 修复 PID 提取逻辑，改用兼容 bash 的模式 +- 修正 PIPE 重定向策略 +- 修复写集群（write cluster）操作的状态获取 +- 改进服务启动失败时的异常处理 + +--- + +## Admin + +### 新功能 + +#### 增强的可观测性 +- 为过期的时间线（timelines）增加 OpenTelemetry 指标清理 +- 为测试用例提供内存指标读取器（in-memory metric reader） +- 增强 Model Service 操作日志 + +#### 系统改进 +- 支持只读挂载路径（read-only mount path），提升安全性 +- 增强写集群状态获取 +- 改进服务启动异常处理 + +--- + +### 增强 + +#### Actor 系统 +- 重构 actor 的 pip 依赖以便更好管理 +- 增强 actor 依赖更新机制 +- 改进 actor 初始化流程 + +#### 镜像管理 +- Image Mirror 增强重试支持 +- 改进镜像构建并支持实验 ID 追踪 +- 升级镜像标签管理 + +--- + +### Bug 修复 +- 修复写集群操作的状态获取 +- 修正 PIPE 重定向策略 +- 改进服务启动失败时的异常处理 + +--- + +## 全局系统变更 + +### 重构 +- 将 `is_absolute_db_path` 移至 database 模块 +- 移除未使用的 API key 并清理测试 +- 移除冗余的 `DockerDeploymentConfig` 导入 + +### 日志改进 +- 更新 logger 格式以提升可读性 +- 为 Sandbox 类增加 `__str__` 与 `__repr__` 方法 +- 在 `init_logger` 中阻止 logger 传播（propagation） +- 为 CLI 的配置加载增加日志 + +### CLI 增强 +- 增加系统资源限制 +- 增强 EnvHub 预检查功能 +- 改进 CLI 命令结构与组织 + +### 文档 +- 增加全面的发布说明 +- 创建 ROCK & ROLL 快速入门指南 +- 增强 GitHub Actions CI 工作流 +- 改进 Issue 模板以便更好地报告 Bug +- 增加 GitHub 指标统计页面 + +### 测试 +- 使用内存指标读取器优化测试用例 +- 增强新功能测试覆盖率 +- 改进测试加载器路径解析 + +--- + + +--- + +## 已知问题 +- 目前暂无 + +## 贡献者 +感谢所有为本次发布做出贡献的贡献者！ + +## 下一步计划 +- 增强文档与教程 +- 进一步的性能优化与 Bug 修复 \ No newline at end of file diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/User Guides/configuration.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/User Guides/configuration.md new file mode 100644 index 000000000..6e134ccc2 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/User Guides/configuration.md @@ -0,0 +1,195 @@ +--- +sidebar_position: 4 +--- + +# 配置指南 + +本指南详细介绍如何配置 ROCK 环境以满足不同的使用需求，包括本地开发、测试和生产部署。 + +## 目录 + +- [环境变量配置](#1-环境变量配置) + - [运行时环境](#11-运行时环境) + - [日志配置](#12-日志配置) +- [分布式部署要求](#2-分布式部署要求) + +## 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.0.x/overview.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/overview.md new file mode 100644 index 000000000..4d209b6e3 --- /dev/null +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.0.x/overview.md @@ -0,0 +1,58 @@ +--- +sidebar_position: 1 +--- + +# 概览 + +ROCK (Reinforcement Open Construction Kit) 是一个开源的强化学习环境开发框架，旨在简化强化学习环境的开发、部署和管理流程。 + +## 目录 + +- [概览](#概览) + - [目录](#目录) + - [什么是 ROCK](#什么是-rock) + - [ROCK 的核心功能](#rock-的核心功能) + - [ROCK 的价值](#rock-的价值) + - [了解更多](#了解更多) + - [相关文档](#相关文档) + +## 什么是 ROCK + +ROCK (Reinforcement Open Construction Kit) 是一个开源强化学习环境开发框架。通过使用 ROCK，开发者可以快速地开发强化学习环境，并结合其他强化学习训练框架，实现高效的强化学习训练。 + +ROCK 提供了完整的沙箱环境管理功能，支持容器化部署，能够实现环境的快速创建、运行和销毁。同时，ROCK 兼容 GEM 协议，为强化学习环境提供了标准化的接口。 + +## ROCK 的核心功能 + +1. **简化开发流程**：简化强化学习环境的开发、构建和管理流程，支持多种开源的强化学习环境 +2. **大规模调度部署**：支持快速强化学习环境的大规模调度部署，通过 GEM 协议可以方便地访问强化学习环境 +3. **框架集成**：与其他强化学习训练框架集成，实现大规模可扩展的强化学习训练 + +## ROCK 的价值 + +ROCK 为不同角色的工程师提供了显著价值： + +- **强化学习算法工程师**：ROCK 可以简化强化学习环境的开发流程，让工程师专注于算法实现 +- **强化学习应用工程师**：ROCK 可以进行快速强化学习环境的大规模部署，提高应用开发效率 + +## 了解更多 + +- [快速开始指南](./Getting%20Started/quickstart.md) - 快速上手 ROCK +- [配置指南](./User%20Guides/configuration.md) - 详细了解 ROCK 的配置选项 +- [API 文档](./References/api.md) - 查看 ROCK 提供的 API 接口 +- [Python SDK 文档](./References/Python%20SDK%20References/python_sdk.md) - 学习如何使用 ROCK 的 Python SDK +- [安装指南](./Getting%20Started/installation.md) - 详细了解 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.0.x/References/model-service.md b/docs/versioned_docs/version-1.0.x/References/model-service.md new file mode 100644 index 000000000..9e7c37ad5 --- /dev/null +++ b/docs/versioned_docs/version-1.0.x/References/model-service.md @@ -0,0 +1,115 @@ +--- +sidebar_position: 2 +--- + +# Model Service + +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. + +## Architecture Overview + +The model service uses the file system as a 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. + +## 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] +``` + +Parameters: +- `--type`: Model service type, optional `local` or `proxy`, defaults to `local` + +### 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. + +## Sandbox Integration + +### ModelServiceConfig +Located in `rock/sdk/sandbox/model_service/base.py`, defines model service configuration in the sandbox: +- Working directory +- Python and model service installation commands +- Session environment variables +- Various command templates + +### ModelService Class +Handles the lifecycle of model services within the sandbox: +- `install()`: Install model service dependencies in the sandbox +- `start()`: Start the model service +- `stop()`: Stop the model service +- `watch_agent()`: Monitor the agent process +- `anti_call_llm()`: Perform anti-call LLM operations + +## Workflow + +1. Agent initiates a model call request +2. Request is formatted and written to a log file +3. Model service listens to the log file and captures new requests +4. Runtime (Roll) processes the request and generates a response +5. Response is written to the log file +6. Model service returns the response to the agent + +## 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 + +### 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` \ No newline at end of file diff --git a/docs/versioned_docs/version-1.0.x/References/sandbox-agent.md b/docs/versioned_docs/version-1.0.x/References/sandbox-agent.md new file mode 100644 index 000000000..0ba0cdb00 --- /dev/null +++ b/docs/versioned_docs/version-1.0.x/References/sandbox-agent.md @@ -0,0 +1,50 @@ +--- +sidebar_position: 3 +--- + +# Sandbox Agent + +Sandbox Agent is a component in the ROCK framework used to run AI agent tasks in an isolated environment, providing a secure and controllable execution environment for agents. Agents can be integrated with Model Service to achieve elegant handling of LLM model calls. + +## Architecture Overview + +Sandbox Agent initializes and executes agent tasks in an isolated sandbox environment, including steps such as installing necessary dependencies and configuring the runtime environment. The agent system supports multiple types of agents, such as SWE-agent and IFlow CLI, each with their specific configurations and implementation approaches. + +Agents can be integrated with Model Service to handle AI model calls during task execution. When an agent needs to query or call an AI model, the Model Service handles model communication in the background, allowing the agent to focus on task execution. + +## Sandbox Agent Initialization Workflow + +1. Create sandbox environment and agent instance +2. Call `init()` method to initialize the agent +3. Create a dedicated bash session in the sandbox +4. Execute pre-startup commands (such as environment configuration) +5. Install necessary dependencies (Python, Node.js, etc.) +6. Install specific agent tools (such as SWE-agent or IFlow CLI) +7. If model service is configured, synchronously initialize the model service + +## Sandbox Agent Execution Workflow + +1. Prepare task running parameters (problem statement, project path, etc.) +2. Call `run()` method to execute the task +3. Prepare configuration files required for running and upload them to the sandbox environment (if needed) +4. Execute Agent +5. If model service is configured, synchronously monitor the Agent process +6. Wait for task completion and return results + +## Model Service Integration Capabilities + +Sandbox Agent supports seamless integration with Model Service, providing a communication bridge for AI model calls. This integration allows agents to interact with Model Service through the file system communication protocol, implementing an asynchronous request-response mechanism. During Agent initialization, the LLM address requested by the Agent can be configured to the address of the model-service server (such as the default http://localhost:8080/v1/chat/completions), thereby leveraging model-service to access the actual inference service. + +The workflow when an agent is integrated with model service: + +### Before Task Starts +1. Call `start_model_service()` to start the model service +2. Call `watch_agent()` to set up monitoring of the agent process + +### When Agent Calls LLM +1. Agent initiates a model call request +2. Request is written to the log file through the file communication protocol +3. Model service listener captures the request +4. Actual AI model returns a response +5. Response is written back through the file communication protocol +6. Agent reads the response and continues execution diff --git a/docs/versioned_docs/version-1.0.x/Release Notes/index.md b/docs/versioned_docs/version-1.0.x/Release Notes/index.md index 7863c9741..ac3edab26 100644 --- a/docs/versioned_docs/version-1.0.x/Release Notes/index.md +++ b/docs/versioned_docs/version-1.0.x/Release Notes/index.md @@ -2,5 +2,4 @@ sidebar_position: 1 --- # Release Notes -* [release v0.2.1](v0.2.1.md) -* [release v0.2.0](v0.2.0.md) \ No newline at end of file +* [release v1.0.0](v1.0.0.md) diff --git a/docs/versioned_docs/version-1.0.x/Release Notes/v0.2.0.md b/docs/versioned_docs/version-1.0.x/Release Notes/v0.2.0.md deleted file mode 100644 index 25f15455a..000000000 --- a/docs/versioned_docs/version-1.0.x/Release Notes/v0.2.0.md +++ /dev/null @@ -1,9 +0,0 @@ -# v0.2.0 - -## Release Date -November 8, 2025 - -## Overview -Fisrt time Release RL ROCK, ROCK (Reinforcement Open Construction Kit) is a comprehensive sandbox environment management framework, primarily for reinforcement learning and AI development environments. It provides tools for building, running, and managing isolated containerized environments, suitable for development, testing, and research scenarios. - -ROCK adopts a client-server architecture, uses Docker for containerization, and seamlessly integrates with modern development workflows. ROCK not only supports traditional sandbox management functions but also complies with the GEM protocol, providing standardized interfaces for reinforcement learning environments. \ No newline at end of file diff --git a/docs/versioned_docs/version-1.0.x/Release Notes/v0.2.1.md b/docs/versioned_docs/version-1.0.x/Release Notes/v0.2.1.md deleted file mode 100644 index f1a9ecd04..000000000 --- a/docs/versioned_docs/version-1.0.x/Release Notes/v0.2.1.md +++ /dev/null @@ -1,20 +0,0 @@ -# v0.2.1 - -## Release Date -November 10, 2025 - -## Overview -This release focuses on system optimization and enhancement, including code cleanup, validation improvements, internal structure optimization, and logging enhancements to improve system stability and maintainability. - -## SDK - -### Deprecations -- Removed unused `download_files` method - -### New Features -* Added DockerValidator capability to validate required startup images - -### Enhancements -* Optimized ROCK internal Request/Response structure -* Optimized system logging -* Adjusted SDK internal method names \ No newline at end of file diff --git a/docs/versioned_docs/version-1.0.x/Release Notes/v1.0.0rc1.md b/docs/versioned_docs/version-1.0.x/Release Notes/v1.0.0rc1.md index beee8335a..2e6fce160 100644 --- a/docs/versioned_docs/version-1.0.x/Release Notes/v1.0.0rc1.md +++ b/docs/versioned_docs/version-1.0.x/Release Notes/v1.0.0rc1.md @@ -1,192 +1,140 @@ # v1.0.0rc1 ## Release Date -December 26, 2025 +January 5, 2026 ## Overview -This is a major release that introduces powerful new features including Model Service, SWE Agent, Image Mirror support, Remote User management, and Agent ABC framework. The release also includes significant performance improvements, system optimizations, and enhanced observability. +This is a major release that introduces several powerful new features, including Model Service, ROCK Install Agent, Remote User management, etc., along with significant performance improvements, system optimizations, and enhanced observability capabilities. + +--- ## SDK ### New Features #### Model Service -**[Model Service Usage Documentation](../Getting Started/model-service.md)** +**[Model Service References Documentation](../References/model-service.md)** -A comprehensive model service that provides: +Provides comprehensive model service capabilities, including: - Local model server with file handler support -- Model client for seamless model interaction -- Proxy support for model requests -- Type-based model selection via CLI parameters +- Model client for seamless interaction +- Support for model request proxy +- Model selection by "type" via CLI parameters - Concurrent initialization with SWE Agent installation -- Lock mechanism for thread-safe operations - -#### SWE Agent -**[SWE Agent Documentation](../Getting Started/swe-agent.md)** - -Software Engineering Agent implementation featuring: -- Automated code generation and analysis -- Enhanced logging for better debugging -- Retry logic for installation failures -- Base dependencies integration - -#### Image Mirror -**[Image Mirror Documentation](../Getting Started/image-mirror.md)** - -Advanced image mirroring capabilities: -- Automatic image building with retry mechanism -- Experiment ID tracking -- Detailed reporting with retry statistics -- Upgraded image tag support - -#### Remote User -**[Remote User Documentation](../Getting Started/remote-user.md)** - -Remote user management system: -- Create and use remote users across deployments -- Enhanced sandbox isolation and security -- Seamless integration with existing workflows - -#### Agent ABC -**[Agent Framework Documentation](../Getting Started/agent-framework.md)** +- Lock mechanisms for thread-safe operations -Abstract base class for agent development: -- Standardized agent interface -- Extensible framework for custom agents -- Simplified agent implementation +#### Sandbox Agent +**[Sandbox Agent References Documentation](../References/sandbox-agent.md)** -#### iFlow CLI Agent -**[iFlow CLI Agent Documentation](../Getting Started/iflow-cli-agent.md)** +Features for quickly installing Agents in ROCK's Sandbox: +- Simple Agent installation interface +- Quick integration capability with Model-Service +- Support for running multiple Agents in isolated sandbox environments -Integration with iFlow CLI agent system: -- Seamless CLI agent support -- Enhanced command execution capabilities - -#### Code Feature -**[Code Feature Documentation](../Getting Started/code-feature.md)** - -Advanced code generation and manipulation features: -- Code generation capabilities -- Enhanced code analysis tools +--- ### Enhancements #### Environment Builder - Added `build_remote` parameter for remote environment building -- Updated timeout configuration for better control -- Enhanced file size information in `arun` ignore_output +- Updated timeout configurations for better control +- Enhanced file size information display in `arun`'s ignore_output #### Performance Optimizations -- Optimized PID extraction with bash-compatible patterns -- Enhanced `arun` method performance -- Improved file handling operations +- Optimized PID extraction logic using bash-compatible patterns +- Improved `arun` method performance +- Enhanced file processing related operations #### API Improvements -- Added more optional variables for running API execute operations +- Added more optional variables for Run API execute operations - Enhanced request/response handling - Improved error reporting with file size details -### Deprecations -- Removed unused `download_file` method in client.py -- Renamed `write_file_directly` to `write_file_by_path` for clarity +--- ### Bug Fixes -- Fixed PID extraction to use bash-compatible patterns -- Corrected PIPE redirect strategy -- Fixed status retrieval for write cluster operations -- Improved exception handling for service startup failures +- Fixed PID extraction logic with bash-compatible pattern +- Corrected PIPE redirection strategy +- Fixed write cluster operation status retrieval +- Improved exception handling when service startup fails + +--- ## Admin ### New Features #### Enhanced Observability -- Added OpenTelemetry metrics cleanup for expired timelines -- In-memory metric reader for test cases -- Enhanced logging for model service operations +- Added OpenTelemetry metric cleanup for expired timelines +- Provided in-memory metric reader for test cases +- Enhanced Model Service operation logs #### System Improvements -- Read-only mount path support for enhanced security -- Enhanced status retrieval for write clusters -- Improved exception handling for service startup +- Support for read-only mount paths, enhancing security +- Enhanced write cluster status retrieval +- Improved service startup exception handling + +--- ### Enhancements #### Actor System -- Reconstructed actor pip dependencies for better management -- Enhanced actor dependency updates -- Improved actor initialization process +- Refactored actor pip dependencies for better management +- Enhanced actor dependency update mechanism +- Improved actor initialization flow #### Image Management -- Enhanced image mirror with retry support +- Image Mirror enhanced with retry support - Improved image building with experiment ID tracking - Upgraded image tag management -#### Model Service (Admin) -- Enhanced ModelService start logic -- Added lock mechanism for thread-safe operations -- Parallel initialization with SWE Agent -- Proxy support for model requests -- Type-based model selection +--- ### Bug Fixes -- Fixed status retrieval for write cluster operations -- Corrected PIPE redirect strategy -- Improved exception handling for service startup failures +- Fixed write cluster operation status retrieval +- Corrected PIPE redirection strategy +- Improved exception handling when service startup fails -## System-Wide Changes +--- + +## Global System Changes ### Refactoring -- Removed `InternalRequest` class for cleaner architecture -- Replaced `DockerEnvHub` with `DockerValidator` in docker deployment - Moved `is_absolute_db_path` to database module - Removed unused API keys and cleaned up tests - Removed redundant `DockerDeploymentConfig` imports -### Logging Improvements +### Log Improvements - Updated logger format for better readability - Added `__str__` and `__repr__` methods to Sandbox class -- Prevented logger propagation in `init_logger` function -- Added logging for config loading in CLI +- Prevented logger propagation in `init_logger` +- Added logging for CLI configuration loading ### CLI Enhancements - Added system resource limits -- Enhanced EnvHub precheck functionality +- Enhanced EnvHub pre-check functionality - Improved CLI command structure and organization ### Documentation - Added comprehensive release notes -- Created ROCK & ROLL quick start guides +- Created ROCK & ROLL Quick Start guide - Enhanced GitHub Actions CI workflows -- Improved issue templates for better bug reporting -- Added statistics page for GitHub metrics +- Improved Issue template for better bug reporting +- Added GitHub metrics statistics page ### Testing -- Optimized test cases with in-memory metric reader +- Optimized test cases using in-memory metric readers - Enhanced test coverage for new features - Improved test loader path resolution -## Migration Guide - -### Breaking Changes -- `InternalRequest` class has been removed. Use standard request classes instead. -- `write_file_directly` method renamed to `write_file_by_path` -- `download_file` method has been removed - -### Recommended Actions -1. Update any code using `InternalRequest` to use standard request classes -2. Replace `write_file_directly` calls with `write_file_by_path` -3. Review and update timeout configurations in EnvBuilder -4. Test remote user functionality if using sandbox isolation -5. Update model service integration to use new proxy and type selection features +--- ## Known Issues - None at this time ## Contributors -Thanks to all contributors who made this release possible! +Thanks to all the contributors who made this release possible! ## Next Steps -- Full 1.0.0 release with additional features and improvements -- Enhanced documentation and tutorials -- Performance optimizations and bug fixes \ No newline at end of file +- Enhance documentation and tutorials +- Further performance optimizations and bug fixes \ No newline at end of file diff --git a/docs/versioned_sidebars/version-1.0.x-sidebars.json b/docs/versioned_sidebars/version-1.0.x-sidebars.json new file mode 100644 index 000000000..f343b4758 --- /dev/null +++ b/docs/versioned_sidebars/version-1.0.x-sidebars.json @@ -0,0 +1,66 @@ +{ + "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", + "References/model-service", + "References/sandbox-agent", + { + "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" + } + ] + } + ] +} diff --git a/docs/versions.json b/docs/versions.json index 864b49a3e..69b69959e 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,3 +1,4 @@ [ + "1.0.x", "0.2.x" ] \ No newline at end of file