Skip to content

Commit 5e00501

Browse files
lxsy-xcylxsy-xcy
committed
doc
1 parent 37f2731 commit 5e00501

4 files changed

Lines changed: 221 additions & 23 deletions

File tree

‎README_zh.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# Robot.cpp
2+
3+
【demo 位置】
4+
5+
Robot.cpp是一个轻量化的on-device机器人模型推理框架，在llama.cpp的基础上进行开发，继承了其零依赖、轻量化的哲学，无需python相关的依赖配置，即可完成机器人模型推理，这使得其在跨平台尤其是环境配置复杂的边缘设备上具有优势。
6+
7+
具体而言，robot.cpp最核心的概念是 `model-server`，其为最主要的统一模型接口。在实际工作，仅需要启动 `model-server`，其会监听机器人发送的推理请求，即接受机器人传来的observation，在下层model进行forward计算，返回model生成的action。整体通信设计上为了轻量化零依赖采用手写TCP协议的方式。
8+
9+
对于如何在机器人上使用，我们亦都提供了一些示例，分别提供了libero和低成本的SO-101的示例作为仿真与真机的使用模板。具体而言，我们采用以下概念组织：
10+
11+
* `model-client`：用来与 `model-server`进行通信的client，封装通信协议部分，负责给 `model-server`发送请求。我们提供了c++和python版本的client，供君选择。
12+
* `policy`：实际使用 `model-client`，与具体的机器人系统或者仿真系统连接的一层抽象，policy负责接受机器人平台给的observation，对其进行处理，然后交给 `model-client`，获得action的最终输出，在这一层看不到通信细节，使用更加友好。
13+
* `platform`：不同的机器人平台，负责传感器管理，以及机器人控制。
14+
15+
工具上，我们亦都提供了两种工具帮助更好地对机器人模型进行开发
16+
17+
* [`hf2gguf`](tools/hf2gguf/README_zh.md)：用来将safetensor格式的checkpoint转化成项目所需的gguf格式
18+
* [`quant`](tools/quant/README_zh.md)：对模型的任意tensor族群进行选择性quant的工具，用户仅需要调整yaml进行需求配置即可完成量化gguf的生成
19+
20+
## 快速使用
21+
22+
我们介绍三类使用案例来帮助你快速了解本仓库：
23+
24+
* model-server的启动，其与最小dummy model-client通信的案例
25+
* model-server在仿真平台上的使用（以LIBERO为例）
26+
* model-server在真机平台上的使用（以SO-101为例）
27+
28+
### model-server的启动与连接dummy client
29+
30+
我们以smolvla的gguf为例，教您快速使用model-server
31+
32+
#### step0: 下载gguf model
33+
34+
在hugging-face上下载一份gguf示例：[huggingface.co/rrobottt/smolvla-so101-fp32](https://huggingface.co/rrobottt/smolvla-so101-fp32)
35+
36+
#### step1：model-server的启动
37+
38+
我们提供了两种方式来完成model-server的启动
39+
40+
##### 方法1：直接下载
41+
42+
对于特定的一些平台与设定，我们已经预编译了一些`model-server`的二进制文件，可以直接在release page下载下来直接用
43+
44+
下载之后，可以直接用下面的方式运行`model-server`
45+
46+
```
47+
48+
./model-server \
49+
--model-type smolvla\
50+
--llm /path/to/smolvla-llm-f32.gguf \
51+
--mmproj /path/to/mmproj-smolvla-f32.gguf \
52+
--state-proj /path/to/state-proj-smolvla-f32.gguf \
53+
--action-expert /path/to/action-expert-smolvla-f32.gguf \
54+
--host 127.0.0.1 \
55+
--port 5555
56+
```
57+
58+
##### 方法2：本地编译
59+
60+
对于更加一般的情况，我们也提供了三个平台的开箱即用编译+启动的shell，可以通过修改shell里的环境变量，或者直接export的形式来快速在本机实现启动。详情参见 [robot_server/README_zh.md](robot_server/README_zh.md)
61+
62+
| Backend | macOS | Linux | Windows |
63+
| ------- | ------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
64+
| CUDA | - | `robot_server/shell/launch_robot_server_linux_cuda.sh` | `robot_server/shell/launch_robot_server_windows_cuda.bat` |
65+
| 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` |
66+
| Metal | `robot_server/shell/launch_robot_server_mac_metal.sh` | - | - |
67+
68+
启动成功后会显示：
69+
70+
```
71+
[model-server] listening on 127.0.0.1:5555 model=smolvla
72+
```
73+
74+
#### step2：完成一次对model-server的dummy请求
75+
76+
server启动过后，会监听请求，我们提供了一份最小示例来进行一个随机的observation请求。可以使用python或者c++的方式来进行请求。
77+
78+
##### python最小例子
79+
80+
```
81+
pip install numpy
82+
python robot_client/examples/python/minimal_example.py
83+
```
84+
85+
##### cpp最小例子
86+
87+
我们提供了一个从编译到运行的例子（`robot_client/shell/cpp_client_example.sh`），按需修改以下环境变量：
88+
89+
| 环境变量 | 默认值 | 作用 |
90+
| ------------------ | ---------------------------------------- | ---------------------------------------------------------------------- |
91+
| `ROBOT_CPP_ROOT` | 无，必须设置 | 仓库根目录。 |
92+
| `BUILD_DIR` | `${ROBOT_CPP_ROOT}/build_robot_client` | C++ client 的 CMake build 目录 |
93+
| `PORT` | `5555` | client 连接的 server port |
94+
| `BUILD_CLIENT` | `0` | 是否强制重新build client。设为`1` 时即使 binary 已存在也会重新 build |
95+
| `CMAKE_BIN` | `cmake` | 使用的 CMake 命令路径，可用于指定自定义 CMake |
96+
97+
然后运行下面的bash：
98+
99+
```
100+
bash robot_client/shell/cpp_client_example.sh
101+
```
102+
103+
### model-server在仿真平台上的使用（以LIBERO为例）
104+
105+
链接
106+
107+
### model-server在真机平台上的使用（以SO-101为例）
108+
109+
链接
110+
111+
## 性能
112+
113+
我们在不同的平台测试了我们的实现性能，我们对模型进行5次warmup，100次loop，取其从收到图片开始包括process，forward，到输出可用action chunk的latency平均值（单位：ms）。（所有state projector均保持f32精度）
114+
115+
| Model | Mac M4 Pro (CPU) | Mac M4 Pro (Metal) | RTX 4090 | RTX 3060 | A100 |
116+
| ---------------------- | ---------------- | ------------------ | -------- | -------- | ---- |
117+
| smolvla@libero (bf16*) | | 215 | | | |
118+
| smolvla@libero (f32) | | 233 | | | |
119+
| smolvla@so-101 (bf16*) | 339 | 145 | | | |
120+
| smolvla@so-101 (f32) | 396 | 158 | | | |
121+
| pi0@libero (f32) | | 720 | | | |
122+
| pi0@libero (bf16*) | | 643 | | | |
123+
124+
> `bf16*`：在 Mac上使用 f16 结果替代 bf16，因为当前 Mac对 bf16 的支持不够好。
125+
126+
## Repository Structure
127+
128+
关键目录如下：
129+
130+
```text
131+
vla.cpp/
132+
├── src/
133+
│ ├── model-cli.cpp # 直接从命令行调用 Model 层的调试 / smoke 入口
134+
│ └── models/
135+
│ ├── model.h # 统一 Model 抽象：predict / reset / type
136+
│ ├── model_factory.cpp # 根据 --model-type 创建具体模型
137+
│ ├── ggml_backend.* # ggml backend / buffer / scheduler 等公共抽象
138+
│ ├── gguf_loader.* # GGUF 读取的公共抽象
139+
│ ├── smolvla/ # SmolVLA runtime实现
140+
│ └── pi0/ # pi0 runtime实现
141+
├── robot_server/
142+
│ ├── model-server.cpp # 常驻 daemon 入口，监听本机 TCP 请求
143+
│ ├── protocol.* # little-endian 二进制协议
144+
│ ├── session.* / socket.* # 连接、收发包和跨平台 socket 封装
145+
│ ├── model_adapter.* # 协议 observation 与 Model 层之间的胶水
146+
│ ├── shell/ # macOS / Linux / Windows 的model-server启动脚本
147+
│ └── test/ # 测试和辅助脚本
148+
├── robot_client/
149+
│ ├── cpp/ # C++ model-client
150+
│ ├── python/ # Python model-client
151+
│ ├── policy/ # 面向机器人platform / 仿真的 policy 封装
152+
│ ├── examples/ # 最小 client 示例
153+
│ └── shell/ # client 编译与运行脚本
154+
├── tools/
155+
│ ├── hf2gguf/ # Hugging Face checkpoint -> GGUF 转换工具
156+
│ │ ├── smolvla/
157+
│ │ └── pi0/
158+
│ └── quant/ # 基于 YAML plan 的 GGUF tensor 选择性量化工具
159+
├── eval/
160+
│ ├── libero/ # LIBERO 仿真评测
161+
│ └── lerobot_so101/ # SO-101 真机相关脚本与示例
162+
└── third_party/
163+
├── llama.cpp/ # ggml / llama.cpp 后端
164+
└── lerobot/ # LeRobot 相关依赖或参考代码
165+
```
166+
167+
## Contributing
168+
169+
如何新增一个新的model
170+
171+
新增模型时，优先在 `src/models/<model_name>` 下实现 runtime，并在 `model_factory.cpp` 接入
172+
173+
## License
174+
175+
## Acknowledgements

‎robot_server/README_zh.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414

1515
### 设置变量
1616

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

1919
公共变量：
2020

‎robot_server/test/test_server_latency.sh‎

Lines changed: 27 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -15,23 +15,33 @@ MODEL_TYPE="${1:-${MODEL_TYPE:-smolvla}}"
1515
BACKEND="${2:-${BACKEND:-mac-metal}}"
1616

1717
# ====== model GGUF overrides ======
18-
# SmolVLA defaults are resolved by robot_server/shell/launch_robot_server_*.sh:
19-
# ${GGUF_DIR}/smolvla-llm-f32.gguf
20-
# ${GGUF_DIR}/mmproj-smolvla-f32.gguf
21-
# ${GGUF_DIR}/state-proj-smolvla-f32.gguf
22-
# ${GGUF_DIR}/action-expert-smolvla-f32.gguf
23-
LLM_GGUF="${LLM_GGUF:-}"
24-
VISION_GGUF="${VISION_GGUF:-}"
25-
STATE_PROJ_GGUF="${STATE_PROJ_GGUF:-}"
26-
ACTION_EXPERT_GGUF="${ACTION_EXPERT_GGUF:-}"
27-
28-
# pi0 defaults are resolved from MODEL_BASENAME by launch scripts.
29-
MODEL_BASENAME="${MODEL_BASENAME:-}"
30-
VIT_GGUF="${VIT_GGUF:-}"
31-
MMPROJ_GGUF="${MMPROJ_GGUF:-}"
32-
TOKENIZER_GGUF="${TOKENIZER_GGUF:-}"
33-
STATE_GGUF="${STATE_GGUF:-}"
34-
ACTION_DECODER_GGUF="${ACTION_DECODER_GGUF:-}"
18+
case "${MODEL_TYPE}" in
19+
smolvla)
20+
# SmolVLA defaults are resolved by robot_server/shell/launch_robot_server_*.sh:
21+
# ${GGUF_DIR}/smolvla-llm-f32.gguf
22+
# ${GGUF_DIR}/mmproj-smolvla-f32.gguf
23+
# ${GGUF_DIR}/state-proj-smolvla-f32.gguf
24+
# ${GGUF_DIR}/action-expert-smolvla-f32.gguf
25+
LLM_GGUF="${LLM_GGUF:-${GGUF_DIR}/smolvla-llm-f32.gguf}"
26+
VISION_GGUF="${VISION_GGUF:-${GGUF_DIR}/mmproj-smolvla-f32.gguf}"
27+
STATE_PROJ_GGUF="${STATE_PROJ_GGUF:-${GGUF_DIR}/state-proj-smolvla-f32.gguf}"
28+
ACTION_EXPERT_GGUF="${ACTION_EXPERT_GGUF:-${GGUF_DIR}/action-expert-smolvla-f32.gguf}"
29+
;;
30+
pi0)
31+
# pi0 defaults are resolved from MODEL_BASENAME by launch scripts.
32+
MODEL_BASENAME="${MODEL_BASENAME:-pi0}"
33+
VIT_GGUF="${VIT_GGUF:-${GGUF_DIR}/${MODEL_BASENAME}.vit.gguf}"
34+
MMPROJ_GGUF="${MMPROJ_GGUF:-${GGUF_DIR}/${MODEL_BASENAME}.mmproj.gguf}"
35+
TOKENIZER_GGUF="${TOKENIZER_GGUF:-${GGUF_DIR}/${MODEL_BASENAME}.tokenizer.gguf}"
36+
STATE_GGUF="${STATE_GGUF:-${GGUF_DIR}/${MODEL_BASENAME}.state.gguf}"
37+
ACTION_DECODER_GGUF="${ACTION_DECODER_GGUF:-${GGUF_DIR}/${MODEL_BASENAME}.action_decoder.gguf}"
38+
LLM_GGUF="${LLM_GGUF:-${GGUF_DIR}/${MODEL_BASENAME}.llm.gguf}"
39+
;;
40+
*)
41+
echo "unsupported MODEL_TYPE=${MODEL_TYPE}" >&2
42+
exit 1
43+
;;
44+
esac
3545

3646
case "${BACKEND}" in
3747
mac-cpu)

‎tools/hf2gguf/README_zh.md‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
# HF 到 GGUF 转换工具
22

3-
这个目录放 checkpoint 到 GGUF 的转换工具。
3+
这个目录放将checkpoint 到 GGUF 的转换工具。
44

5-
- `smolvla/`：将 SmolVLA checkpoint 转成四个 GGUF component。
6-
- `pi0/`：将 pi0/OpenPI checkpoint 转成六个 split GGUF component。
5+
- `smolvla/`：将 SmolVLA的lerobot-style的checkpoint 转成四个 GGUF component。
6+
- `pi0/`：将 pi0的lerobot-style的checkpoint 转成六个 split GGUF component。
77
- `environment.yaml`：converter conda 环境。
88

9-
## 环境配置
9+
## 使用说明
10+
11+
### step0：环境配置
1012

1113
第一次使用前先创建 converter 环境：
1214

@@ -23,7 +25,7 @@ converter shell 会自动把仓库里配套的 llama.cpp `gguf-py` 加到 `PYTHO
2325
PYTHON_BIN="$(which python)"
2426
```
2527

26-
## 转换入口
28+
### step1：执行转换
2729

2830
SmolVLA:
2931

@@ -48,3 +50,14 @@ DTYPE=fp32 \
4850
FORCE=1 \
4951
bash tools/hf2gguf/pi0/convert_pi0_all.sh
5052
```
53+
54+
参数说明：
55+
56+
| 参数 | 是否必填 | 说明 | 默认值 / 可选值 |
57+
| ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
58+
| `ROBOT_CPP_ROOT` | 是 | 仓库根目录。 | 无 |
59+
| `CHECKPOINT_DIR` | 是 | 原始 checkpoint 目录 | 无 |
60+
| `OUTPUT_DIR` / `OUTPUT_PREFIX` | 是 | 输出路径。SmolVLA 使用`OUTPUT_DIR` 表示输出目录；pi0 使用 `OUTPUT_PREFIX` 表示输出文件名前缀（例如上述例子中最终输出为/path/to/output/robotcpp-pi0.vit.gguf等） | 无 |
61+
| `PYTHON_BIN` | 否 | 用来运行 converter 的 Python。建议传step0中 conda 环境里的`$(which python)`。 | `python3` |
62+
| `DTYPE` | 是 | 输出 GGUF tensor 精度。SmolVLA 可选`f32` / `f16` / `bf16`；pi0 可选 `preserve` / `fp32` / `f16` / `bf16`。 | 无 |
63+
| `FORCE` | 否 | 是否允许覆盖已有 GGUF 文件。 | `0`；设为 `1` 时覆盖 |

0 commit comments

Comments
 (0)