Skip to content

Commit f5e35b6

Browse files
BCeZnBCeZn
authored
Chore/xinshi/bump version 140 (alibaba#634)
* build: bump version to 1.4.0 * docs: add python sdk references and release notes for version 1.4.x * docs: update release notes for version 1.4.0 * docs: update release notes for version 1.4.0 and remove older versions * chore: update lock to 1.4.0
1 parent f3c7fb7 commit f5e35b6

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+5440
-2
lines changed

‎docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.4.x.json‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{
2+
"version.label": {
3+
"message": "1.4.x",
4+
"description": "The label for version 1.3.x"
5+
},
6+
"sidebar.tutorialSidebar.category.Getting Started": {
7+
"message": "快速上手",
8+
"description": "The label for category 'Getting Started' in sidebar 'tutorialSidebar'"
9+
},
10+
"sidebar.tutorialSidebar.category.User Guides": {
11+
"message": "用户指南",
12+
"description": "The label for category 'User Guides' in sidebar 'tutorialSidebar'"
13+
},
14+
"sidebar.tutorialSidebar.category.References": {
15+
"message": "参考",
16+
"description": "The label for category 'References' in sidebar 'tutorialSidebar'"
17+
},
18+
"sidebar.tutorialSidebar.category.Release Notes": {
19+
"message": "版本说明",
20+
"description": "The label for category 'Release Notes' in sidebar 'tutorialSidebar'"
21+
},
22+
"sidebar.tutorialSidebar.category.model-service": {
23+
"message": "Model Service 参考",
24+
"description": "The label for category 'Model Service References' in sidebar 'tutorialSidebar'"
25+
},
26+
"sidebar.tutorialSidebar.category.sandbox-agent": {
27+
"message": "Sandbox Agent参考",
28+
"description": "The label for category 'Sandbox Agent References' in sidebar 'tutorialSidebar'"
29+
},
30+
"sidebar.tutorialSidebar.category.Python SDK References": {
31+
"message": "Python SDK 参考",
32+
"description": "The label for category 'Python SDK References' in sidebar 'tutorialSidebar'"
33+
}
34+
}

‎docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.4.x/Getting Started/installation.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# 安装指南
6+
7+
本文档介绍如何使用 `uv` 和 `pip` 安装和设置 ROCK 开发环境。该项目是一个强化学习开放构建工具包，支持多种组件。
8+
9+
## 使用 uv（推荐）
10+
11+
### 快速安装所有依赖
12+
13+
```bash
14+
# 安装所有依赖（包括可选依赖）
15+
uv sync --all-extras
16+
17+
# 安装开发/测试依赖
18+
uv sync --all-extras --all-groups
19+
```
20+
21+
### 安装不同依赖组
22+
23+
#### 仅核心依赖
24+
```bash
25+
uv sync
26+
```
27+
28+
#### 管理组件依赖
29+
```bash
30+
uv sync --extra admin
31+
```
32+
33+
#### Rocklet 执行环境依赖
34+
```bash
35+
uv sync --extra rocklet
36+
```
37+
38+
#### 所有依赖
39+
```bash
40+
uv sync --all-extras
41+
```
42+
43+
#### 开发/测试依赖
44+
```bash
45+
uv sync --all-extras --group test
46+
```
47+
48+
## 使用 pip
49+
50+
### 从 pip 源安装
51+
52+
#### 仅核心依赖
53+
```bash
54+
pip install rl-rock
55+
```
56+
57+
#### 管理组件依赖
58+
```bash
59+
pip install "rl-rock[admin]"
60+
```
61+
62+
#### Rocklet 执行环境依赖
63+
```bash
64+
pip install "rl-rock[rocklet]"
65+
```
66+
67+
#### 构建器依赖
68+
```bash
69+
pip install "rl-rock[builder]"
70+
```
71+
72+
#### 安装所有可选依赖
73+
```bash
74+
pip install "rl-rock[all]"
75+
```
76+
77+
### 使用 pip 从源码安装
78+
79+
#### 仅核心依赖
80+
```bash
81+
pip install .
82+
```
83+
84+
#### 管理组件依赖
85+
```bash
86+
pip install ".[admin]"
87+
```
88+
89+
#### Rocklet 执行环境依赖
90+
```bash
91+
pip install ".[rocklet]"
92+
```
93+
94+
#### 构建器依赖
95+
```bash
96+
pip install ".[builder]"
97+
```
98+
99+
#### 安装所有可选依赖
100+
```bash
101+
pip install ".[all]"
102+
```
103+
104+
## 可用入口点
105+
106+
该包提供以下命令行脚本：
107+
108+
- `rocklet`: ROCK 执行环境服务器 (rock.rocklet.server:main)
109+
- `admin`: 管理服务器 (rock.admin.main:main)
110+
- `envhub`: 环境中心服务器 (rock.envhub.server:main)
111+
- `rock`: 主 ROCK 命令行接口 (rock.cli.main:main)
112+
113+
## 开发设置
114+
115+
### 使用 uv（推荐）
116+
117+
```bash
118+
# 克隆并设置开发环境
119+
git clone <repository>
120+
cd ROCK
121+
uv sync --all-extras --group test
122+
123+
# 运行测试
124+
uv run pytest
125+
126+
127+
### 使用 pip
128+
129+
```bash
130+
# 开发模式安装所有可选依赖
131+
pip install -e ".[all]"
132+
133+
# 分别安装
134+
pip install -e .
135+
pip install ".[admin]" ".[rocklet]" ".[builder]"
136+
```
137+
138+
## 附加说明
139+
140+
- 项目配置为默认使用阿里云 PyPI 镜像: `https://mirrors.aliyun.com/pypi/simple/`
141+
- 对于本地开发，运行测试需要 `test` 依赖组

‎docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.4.x/Getting Started/quickstart.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# 快速上手
6+
7+
本指南将通过完整的示例演示如何使用 ROCK 创建和管理强化学习环境。ROCK (Reinforcement Open Construction Kit) 是一个全面的沙箱环境管理框架，主要用于强化学习和AI开发环境。
8+
9+
## 1. 环境准备
10+
11+
我们推荐在 Linux 系统下启动 ROCK，能够尽量复用项目依赖，提升环境拉起速度。如果需要在 macOS 上尝试，可以参考 [MacOS 启动](#7-macos-启动) 一节。
12+
13+
在开始之前，请确保您的系统已安装以下依赖项：
14+
15+
### 1.1 系统要求
16+
17+
- **Docker**: ROCK 使用 Docker 进行容器化环境管理
18+
- **uv**: ROCK 使用 uv 进行依赖管理和虚拟环境创建
19+
20+
### 1.2 验证依赖安装
21+
22+
```bash
23+
# 验证 Docker 安装
24+
docker --version
25+
26+
# 验证 Docker 可用, 且示例中依赖python:3.11镜像
27+
docker pull python:3.11
28+
29+
# 验证 uv 安装
30+
uv --version
31+
32+
33+
```
34+
35+
### 1.3 项目初始化
36+
37+
```bash
38+
# 克隆项目仓库
39+
git clone <repository>
40+
cd ROCK
41+
42+
# 创建虚拟环境（使用 uv 托管的 Python, 以python 3.11 版本为例）
43+
uv venv --python 3.11 --python-preference only-managed
44+
45+
# 安装所有依赖组
46+
uv sync --all-extras
47+
```
48+
49+
> **重要提示**: 为确保 ROCK 能正确挂载项目和虚拟环境及其依赖的 base Python 解释器，强烈推荐使用 uv 托管的 Python 环境而非系统 Python。
50+
51+
## 2. 激活虚拟环境
52+
53+
在运行任何 ROCK 命令之前，需要先激活虚拟环境。确保 sys.base_prefix 是 uv 管理的环境，类似于 `/root/.local/share/uv/python/cpython-3.11.8-linux-x86_64-gnu` 等路径。
54+
55+
```bash
56+
# 激活虚拟环境
57+
source .venv/bin/activate
58+
59+
# 验证 Python 环境
60+
python -c "import sys; print('Base prefix:', sys.base_prefix)"
61+
```
62+
63+
> **验证要点**: 确保输出的 base prefix 路径指向 uv 管理的 Python 环境，而非系统 Python。
64+
65+
## 3. 验证环境配置
66+
67+
激活虚拟环境后，验证依赖安装是否正确：
68+
69+
```bash
70+
# 检查关键依赖
71+
python -c "import rock; print(\"Hello ROCK\")"
72+
```
73+
74+
75+
## 4. 启动 ROCK 服务
76+
77+
激活虚拟环境后，在项目根目录下，启动 ROCK Admin 服务：
78+
79+
```bash
80+
# 确保虚拟环境已激活
81+
source .venv/bin/activate
82+
83+
# 启动 ROCK Admin 服务（本地环境）
84+
rock admin start
85+
```
86+
87+
服务启动后，您将看到类似以下的输出：
88+
89+
```
90+
INFO: Started server process [12345]
91+
INFO: Waiting for application startup.
92+
INFO: Application startup complete.
93+
INFO: Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
94+
```
95+
96+
> **服务说明**: ROCK Admin 服务默认运行在 `http://127.0.0.1:8080`。
97+
98+
## 5. 运行示例环境
99+
100+
现在可以运行示例环境来验证安装。确保 ROCK 服务正在运行，然后打开一个新的终端窗口执行以下命令：
101+
102+
```bash
103+
# 确保虚拟环境已激活
104+
source .venv/bin/activate
105+
106+
# 运行沙箱示例
107+
python examples/sandbox_demo.py
108+
109+
# 运行 GEM 协议示例
110+
python examples/sokoban_demo.py
111+
```
112+
113+
### 5.1 示例说明
114+
115+
- **sandbox_demo.py**: 演示如何使用 ROCK 的沙箱 SDK 创建和管理容器化环境
116+
- **sokoban_demo.py**: 演示如何使用 ROCK 的 GEM 协议兼容接口创建强化学习环境
117+
118+
> **运行要求**: 确保 ROCK Admin 服务正在运行，因为示例需要与服务进行通信。
119+
120+
## 6. 分布式环境配置（可选）
121+
122+
对于分布式多机器环境，请确保以下配置一致：
123+
124+
1. 所有机器上 ROCK 和 uv 的 Python 配置使用相同的根 Python 解释器
125+
2. Docker 版本在所有节点上保持一致
126+
3. 网络配置允许各节点间正常通信
127+
128+
129+
130+
## 7. MacOS 启动
131+
132+
在 macOS 上，如果需要启动 Linux 镜像的环境，需要先设置环境变量：
133+
134+
```bash
135+
export ROCK_WORKER_ENV_TYPE=uv
136+
```
137+
138+
在容器启动时，会安装对应的 uv 环境，细节可以参考 `rock/rocklet/local_files/docker_run_with_uv.sh` 脚本。
139+
140+
> **注意**: 相比 Linux 系统，macOS 上的启动速度会较慢，且比较依赖网络环境，可以根据实际情况调整脚本。ROCK_WORKER_ENV_TYPE的细节可以参考 [Configuration Guide](../User%20Guides/configuration.md).
141+
142+
143+
## 8. 从Pip源启动
144+
145+
如果从Pip源启动Admin Server，在参照[安装指南](./installation.md)安装完成ROCK后, 需要设置额外环境变量:
146+
147+
```bash
148+
export ROCK_WORKER_ENV_TYPE=pip
149+
```
150+
151+
(这一启动方式在容器环境启动时会从Pypi源上拉取最新的rocklet并安装, 相对启动速度比较慢, 仅推荐测试使用, 生产上依旧推荐其他的启动方式)
152+
153+
154+
## 总结
155+
156+
恭喜！您已经成功完成了 ROCK 的快速开始指南。现在您应该能够：
157+
158+
- 正确设置 ROCK 开发环境
159+
- 使用 uv 管理的 Python 环境
160+
- 启动和管理 ROCK 服务
161+
- 运行示例程序验证安装
162+
- 在分布式环境中配置 ROCK（如果需要）
163+
164+
如需深入了解 ROCK 的更多功能，请参考以下文档：
165+
166+
## 下一步学习
167+
168+
- [配置指南](../User%20Guides/configuration.md) - 详细了解 ROCK 的配置选项
169+
- [API 文档](../References/api.md) - 查看完整的 API 接口
170+
- [Python SDK 文档](../References/Python%20SDK%20References/python_sdk.md) - 学习如何使用 Python SDK 进行开发
171+
- [安装指南](./installation.md) - 详细了解 ROCK 安装和配置
172+
- [概览](../overview.md) - 了解 ROCK 的设计理念

0 commit comments

Comments
 (0)