Skip to content

Commit 4eb2d80

Browse files
JJJYmmmJJJYmmm
committed
starvla: fix CUDA launch and installation docs
1 parent a96986d commit 4eb2d80

6 files changed

Lines changed: 121 additions & 19 deletions

File tree

‎README.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,14 @@ After downloading, run `model-server` like this:
9696

9797
For general local setups, we provide ready-to-use build-and-launch shells for three platforms. You can modify the environment variables inside the scripts, or override them directly with `export`. See [robot_server/README.md](robot_server/README.md) for details.
9898

99+
For example, from the repository root on Linux with CUDA:
100+
101+
```bash
102+
export ROBOT_CPP_ROOT="$PWD"
103+
export GGUF_DIR=/path/to/smolvla-so101-fp32
104+
bash robot_server/shell/launch_robot_server_linux_cuda.sh
105+
```
106+
99107
| Backend | macOS | Linux | Windows |
100108
| ------- | ------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
101109
| CUDA | - | `robot_server/shell/launch_robot_server_linux_cuda.sh` | `robot_server/shell/launch_robot_server_windows_cuda.bat` |
@@ -128,7 +136,7 @@ We provide a build-to-run example in `robot_client/shell/cpp_client_example.sh`.
128136
| `ROBOT_CPP_ROOT` | unset; required | Repository root. |
129137
| `BUILD_DIR` | `${ROBOT_CPP_ROOT}/build_robot_client` | C++ client CMake build directory. |
130138
| `PORT` | `5555` | Server port used by the client. |
131-
| `BUILD_CLIENT` | `0` | Whether to force rebuild the client. Set to`1` to rebuild even if the binary already exists. |
139+
| `BUILD_CLIENT` | `0` | Whether to force rebuild the client. Set to `1` to rebuild even if the binary already exists. |
132140
| `CMAKE_BIN` | `cmake` | CMake command path, useful for selecting a custom CMake binary. |
133141

134142
Then run:

‎README_ZH.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,14 @@ git submodule update --init --recursive
9696

9797
对于更加一般的情况，我们也提供了三个平台的开箱即用编译+启动的shell，可以通过修改shell里的环境变量，或者直接export的形式来快速在本机实现启动。详情参见 [robot_server/README_ZH.md](robot_server/README_ZH.md)
9898

99+
例如，在 Linux CUDA 环境中从仓库根目录运行：
100+
101+
```bash
102+
export ROBOT_CPP_ROOT="$PWD"
103+
export GGUF_DIR=/path/to/smolvla-so101-fp32
104+
bash robot_server/shell/launch_robot_server_linux_cuda.sh
105+
```
106+
99107
| Backend | macOS | Linux | Windows |
100108
| ------- | ------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
101109
| CUDA | - | `robot_server/shell/launch_robot_server_linux_cuda.sh` | `robot_server/shell/launch_robot_server_windows_cuda.bat` |
@@ -128,7 +136,7 @@ python robot_client/examples/python/minimal_example.py
128136
| `ROBOT_CPP_ROOT` | 无，必须设置 | 仓库根目录。 |
129137
| `BUILD_DIR` | `${ROBOT_CPP_ROOT}/build_robot_client` | C++ client 的 CMake build 目录 |
130138
| `PORT` | `5555` | client 连接的 server port |
131-
| `BUILD_CLIENT` | `0` | 是否强制重新build client。设为`1` 时即使 binary 已存在也会重新 build |
139+
| `BUILD_CLIENT` | `0` | 是否强制重新build client。设为 `1` 时即使 binary 已存在也会重新 build |
132140
| `CMAKE_BIN` | `cmake` | 使用的 CMake 命令路径，可用于指定自定义 CMake |
133141

134142
然后运行下面的bash：

‎eval/lerobot_so101/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
**English** | [简体中文](README_zh.md)
1+
**English** | [简体中文](README_ZH.md)
22

33
# LeRobot SO101
44

‎robot_server/README.md‎

Lines changed: 45 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,17 @@ the Python/C++ clients. The server keeps one robot policy model loaded
99
in-process and returns an action chunk for each prediction request. There are
1010
two main ways to use it.
1111

12+
Before building from source, initialize the submodules and apply the repository
13+
patches from the project root:
14+
15+
```bash
16+
git submodule update --init --recursive
17+
./tools/apply_patches.sh
18+
```
19+
20+
Source builds require CMake 3.16 or newer and a C/C++ compiler. CUDA builds also
21+
require the CUDA Toolkit and a working `nvcc`.
22+
1223
## Method 1: One-Command Build and Run
1324

1425
We provide one-command build-and-run scripts for several mainstream platforms
@@ -21,6 +32,9 @@ under `robot_server/shell`. After running a script, the corresponding
2132
| CPU | `robot_server/shell/launch_robot_server_mac_cpu.sh` | `robot_server/shell/launch_robot_server_linux_cpu.sh` | `robot_server/shell/launch_robot_server_windows_cpu.bat` |
2233
| Metal | `robot_server/shell/launch_robot_server_mac_metal.sh` | - | - |
2334

35+
The Linux CUDA script supports SmolVLA, pi0, and StarVLA. The other launch
36+
scripts currently support SmolVLA and pi0.
37+
2438
### Set Variables
2539

2640
Before running a script, configure the variables below as needed.
@@ -30,14 +44,18 @@ Common variables:
3044
| Variable | Description | Default |
3145
| ------------------ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
3246
| `ROBOT_CPP_ROOT` | Repository root. | Must be set explicitly |
33-
| `MODEL_TYPE` | Model type,`smolvla` or `pi0`. | `smolvla` |
47+
| `MODEL_TYPE` | Model type: `smolvla`, `pi0`, or `starvla`. | `smolvla` |
3448
| `GGUF_DIR` | Directory containing GGUF files. | Must be set explicitly |
35-
| `BUILD_DIR` | CMake build directory. | macOS / Linux defaults are organized as`build_{mac/linux}_{cpu/metal/cuda}` |
49+
| `BUILD_DIR` | CMake build directory. | macOS / Linux defaults use `build_{mac/linux}_{cpu/metal/cuda}` |
50+
| `HOST` | Server listen address. | `127.0.0.1` |
3651
| `PORT` | Server listen port. | `5555` |
3752
| `THREADS` | Inference thread count. | `8` |
38-
| `TASK` | Language input describing the task. | `grab the block.` |
53+
| `N_BATCH` | LLM batch size. | `512` |
54+
| `N_CTX` | LLM context size. | `2048` |
55+
| `TASK` | Compatibility fallback; each client request supplies the actual task. | `grab the block.` |
3956
| `NOISE_SEED` | Action noise seed. | `-1` |
40-
| `SKIP_BUILD` | Whether to skip configure/build. Set to`1` to directly launch an existing binary. | `0` |
57+
| `VERBOSITY` | Model log verbosity. | `0` |
58+
| `SKIP_BUILD` | Whether to skip configure/build. Set to `1` to launch an existing binary. | `0` |
4159
| `CMAKE_BIN` | CMake executable. | `cmake` |
4260

4361
SmolVLA variables:
@@ -61,6 +79,14 @@ pi0 variables:
6179
| `STATE_GGUF` | Full path to the pi0 state GGUF. | `${GGUF_DIR}/${MODEL_BASENAME}.state.gguf` |
6280
| `ACTION_DECODER_GGUF` | Full path to the pi0 action decoder GGUF. | `${GGUF_DIR}/${MODEL_BASENAME}.action_decoder.gguf` |
6381

82+
StarVLA variables (Linux CUDA):
83+
84+
| Variable | Description | Default |
85+
| ------------- | ------------------------------------- | -------- |
86+
| `LLM_GGUF` | Full path to the Qwen text GGUF. | Required |
87+
| `MMPROJ_GGUF` | Full path to the Qwen vision GGUF. | Required |
88+
| `POLICY_GGUF` | Full path to the StarVLA policy GGUF. | Required |
89+
6490
### Invocation
6591

6692
Run the macOS / Linux `.sh` scripts with `bash`:
@@ -74,6 +100,21 @@ bash robot_server/shell/launch_robot_server_linux_cuda.sh
74100

75101
Windows uses the `.bat` scripts.
76102

103+
For example, run the Qwen3-VL OFT bundle from the Model Zoo on Linux CUDA:
104+
105+
```bash
106+
export ROBOT_CPP_ROOT="$PWD"
107+
export GGUF_DIR=/path/to/starvla-qwen3-oft-bridge-bf16
108+
export MODEL_TYPE=starvla
109+
export LLM_GGUF="${GGUF_DIR}/qwen-oft-bf16.gguf"
110+
export MMPROJ_GGUF="${GGUF_DIR}/mmproj-oft-bf16.gguf"
111+
export POLICY_GGUF="${GGUF_DIR}/starvla-oft-policy-fp32.gguf"
112+
bash robot_server/shell/launch_robot_server_linux_cuda.sh
113+
```
114+
115+
The script automatically configures CMake with
116+
`ROBOT_CPP_BUILD_STARVLA=ON` when `MODEL_TYPE=starvla`.
117+
77118
### Troubleshooting
78119

79120
- `Tell CMake where to find the compiler by setting either the environment variable "CUDACXX" or the CMake cache entry CMAKE_CUDA_COMPILER to the full path to the compiler, or to the compiler name if it is in the PATH.`

‎robot_server/README_ZH.md‎

Lines changed: 51 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,35 +4,52 @@
44

55
# Robot Server
66

7-
`robot_server` 提供了 `model-server` 与 Python/C++ 客户端使用的轻量级 TCP 协议。服务端会在进程内常驻加载一个机器人策略模型，并针对每个预测请求返回一段 action chunk。具体有两种使用方式
7+
`robot_server` 提供了 `model-server` 与 Python/C++ 客户端使用的轻量级 TCP 协议。服务端会在进程内常驻加载一个机器人策略模型，并针对每个预测请求返回一段 action chunk。具体有两种使用方式。
88

9-
## 方法1：一键编译与运行
9+
从源码构建前，先在仓库根目录初始化子模块并应用项目补丁：
1010

11-
我们在`robot_server/shell`下提供了几种主流平台的一键编译运行的脚本，运行之后，将直接开始运行对应的`model-server`开始监听
11+
```bash
12+
git submodule update --init --recursive
13+
./tools/apply_patches.sh
14+
```
15+
16+
源码构建需要 CMake 3.16 或更高版本及 C/C++ 编译器。CUDA 构建还需要 CUDA Toolkit
17+
和可用的 `nvcc`。
18+
19+
## 方法 1：一键编译与运行
20+
21+
`robot_server/shell` 提供多个平台的编译启动脚本。脚本会配置、编译并启动对应的
22+
`model-server`。
1223

1324
| Backend | macOS | Linux | Windows |
1425
| ------- | ------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
1526
| CUDA | - | `robot_server/shell/launch_robot_server_linux_cuda.sh` | `robot_server/shell/launch_robot_server_windows_cuda.bat` |
1627
| CPU | `robot_server/shell/launch_robot_server_mac_cpu.sh` | `robot_server/shell/launch_robot_server_linux_cpu.sh` | `robot_server/shell/launch_robot_server_windows_cpu.bat` |
1728
| Metal | `robot_server/shell/launch_robot_server_mac_metal.sh` | - | - |
1829

30+
Linux CUDA 脚本支持 SmolVLA、pi0 和 StarVLA；其他启动脚本当前支持 SmolVLA 和 pi0。
31+
1932
### 设置变量
2033

21-
在运行之前，我们需要在脚本中设置一些设定上的变量，具体而言有以下变量可以按需设置。
34+
运行脚本前，按需设置以下环境变量。
2235

2336
公共变量：
2437

2538
| 变量 | 说明 | 默认值 |
2639
| ------------------ | --------------------------------------------------------- | --------------------------------------------------------------- |
2740
| `ROBOT_CPP_ROOT` | 仓库根目录 | 必须显式设置 |
28-
| `MODEL_TYPE` | 模型类型，可选`smolvla` / `pi0` | `smolvla` |
41+
| `MODEL_TYPE` | 模型类型，可选 `smolvla`、`pi0` 或 `starvla` | `smolvla` |
2942
| `GGUF_DIR` | GGUF 文件所在目录 | 必须显式设置 |
30-
| `BUILD_DIR` | CMake build 目录 | macOS / Linux 默认按`build_{mac/linux}_{cpu/metal/cuda}` 组织 |
43+
| `BUILD_DIR` | CMake build 目录 | macOS / Linux 默认使用 `build_{mac/linux}_{cpu/metal/cuda}` |
44+
| `HOST` | server 监听地址 | `127.0.0.1` |
3145
| `PORT` | server 监听端口 | `5555` |
3246
| `THREADS` | 推理线程数 | `8` |
33-
| `TASK` | 语言输入，描述任务 | `grab the block.` |
47+
| `N_BATCH` | LLM batch size | `512` |
48+
| `N_CTX` | LLM context size | `2048` |
49+
| `TASK` | 兼容用默认值；实际 task 由每个 client 请求提供 | `grab the block.` |
3450
| `NOISE_SEED` | action noise seed | `-1` |
35-
| `SKIP_BUILD` | 是否跳过 configure/build，设为`1` 时直接启动已有 binary | `0` |
51+
| `VERBOSITY` | 模型日志级别 | `0` |
52+
| `SKIP_BUILD` | 是否跳过 configure/build；设为 `1` 时直接启动已有 binary | `0` |
3653
| `CMAKE_BIN` | CMake 可执行文件 | `cmake` |
3754

3855
SmolVLA 变量：
@@ -56,6 +73,14 @@ pi0 变量：
5673
| `STATE_GGUF` | pi0 state GGUF 完整路径 | `${GGUF_DIR}/${MODEL_BASENAME}.state.gguf` |
5774
| `ACTION_DECODER_GGUF` | pi0 action decoder GGUF 完整路径 | `${GGUF_DIR}/${MODEL_BASENAME}.action_decoder.gguf` |
5875

76+
StarVLA 变量（Linux CUDA）：
77+
78+
| 变量 | 说明 | 默认值 |
79+
| ------------- | ---------------------------- | -------- |
80+
| `LLM_GGUF` | Qwen text GGUF 完整路径 | 必须设置 |
81+
| `MMPROJ_GGUF` | Qwen vision GGUF 完整路径 | 必须设置 |
82+
| `POLICY_GGUF` | StarVLA policy GGUF 完整路径 | 必须设置 |
83+
5984
### 调用方式
6085

6186
macOS / Linux 的 `.sh` 脚本直接用 `bash` 运行。
@@ -67,7 +92,22 @@ bash robot_server/shell/launch_robot_server_linux_cpu.sh
6792
bash robot_server/shell/launch_robot_server_linux_cuda.sh
6893
```
6994

70-
Windows 的 `.bat` 脚本：
95+
Windows 直接运行对应的 `.bat` 脚本。
96+
97+
例如，在 Linux CUDA 上运行 Model Zoo 中的 Qwen3-VL OFT bundle：
98+
99+
```bash
100+
export ROBOT_CPP_ROOT="$PWD"
101+
export GGUF_DIR=/path/to/starvla-qwen3-oft-bridge-bf16
102+
export MODEL_TYPE=starvla
103+
export LLM_GGUF="${GGUF_DIR}/qwen-oft-bf16.gguf"
104+
export MMPROJ_GGUF="${GGUF_DIR}/mmproj-oft-bf16.gguf"
105+
export POLICY_GGUF="${GGUF_DIR}/starvla-oft-policy-fp32.gguf"
106+
bash robot_server/shell/launch_robot_server_linux_cuda.sh
107+
```
108+
109+
当 `MODEL_TYPE=starvla` 时，脚本会自动使用
110+
`ROBOT_CPP_BUILD_STARVLA=ON` 配置 CMake。
71111

72112
### 故障排查
73113

@@ -80,9 +120,9 @@ export CUDACXX=/usr/local/cuda-12.4/bin/nvcc
80120
export PATH=/usr/local/cuda-12.4/bin:$PATH
81121
```
82122

83-
## 方法2：直接下载预编译发布
123+
## 方法 2：直接下载预编译发布
84124

85-
从release page下载之后，运行以下命令
125+
从 release page 下载后，运行以下命令。
86126

87127
### 启动 SmolVLA
88128

‎robot_server/shell/launch_robot_server_linux_cuda.sh‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,10 @@ SKIP_BUILD="${SKIP_BUILD:-0}"
2121
CMAKE_BIN="${CMAKE_BIN:-cmake}"
2222
GGML_NATIVE="${GGML_NATIVE:-OFF}"
2323
GGML_OPENMP="${GGML_OPENMP:-OFF}"
24+
ROBOT_CPP_BUILD_STARVLA="${ROBOT_CPP_BUILD_STARVLA:-OFF}"
25+
if [ "${MODEL_TYPE}" = "starvla" ]; then
26+
ROBOT_CPP_BUILD_STARVLA=ON
27+
fi
2428

2529
SERVER_BIN="${BUILD_DIR}/bin/model-server"
2630

@@ -32,7 +36,8 @@ if [ "${SKIP_BUILD}" != "1" ]; then
3236
-DGGML_OPENMP="${GGML_OPENMP}" \
3337
-DGGML_CUDA=ON \
3438
-DGGML_METAL=OFF \
35-
-DROBOT_CPP_BUILD_ROBOT_SERVER=ON
39+
-DROBOT_CPP_BUILD_ROBOT_SERVER=ON \
40+
-DROBOT_CPP_BUILD_STARVLA="${ROBOT_CPP_BUILD_STARVLA}"
3641

3742
echo "== build =="
3843
"${CMAKE_BIN}" --build "${BUILD_DIR}" --target model-server -j8

0 commit comments

Comments
 (0)