Merge branch 'main' of https://github.com/Robot-cpp/robot.cpp

Author: CrafterSteve

README_zh.md

@@ -4,7 +4,7 @@
 
 Robot.cpp是一个轻量化的on-device机器人模型推理框架，在llama.cpp的基础上进行开发，继承了其零依赖、轻量化的哲学，无需python相关的依赖配置，即可完成机器人模型推理，这使得其在跨平台尤其是环境配置复杂的边缘设备上具有优势。
 
-具体而言，robot.cpp最核心的概念是 `model-server`，其为最主要的统一模型接口。在实际工作，仅需要启动 `model-server`，其会监听机器人发送的推理请求，即接受机器人传来的observation，在下层model进行forward计算，返回model生成的action。整体通信设计上为了轻量化零依赖采用手写TCP协议的方式。
+具体而言，robot.cpp最核心的概念是 [`model-server`](robot_server/README_zh.md)，其为最主要的统一模型接口。在实际工作，仅需要启动 `model-server`，其会监听机器人发送的推理请求，即接受机器人传来的observation，在下层model进行forward计算，返回model生成的action。整体通信设计上为了轻量化零依赖采用手写TCP协议的方式。
 
 对于如何在机器人上使用，我们亦都提供了一些示例，分别提供了libero和低成本的SO-101的示例作为仿真与真机的使用模板。具体而言，我们采用以下概念组织：
 
@@ -121,12 +121,12 @@ bash robot_client/shell/cpp_client_example.sh
 
 | Model                  | Mac M4 Pro (CPU) | Mac M4 Pro (Metal) | RTX 4090 | RTX 3060 | A100 |
 | ---------------------- | ---------------- | ------------------ | -------- | -------- | ---- |
-| smolvla@libero (bf16*) |                  | 215                |          |          | 52   |
-| smolvla@libero (f32)   |                  | 233                |          |          | 50   |
-| smolvla@so-101 (bf16*) | 339              | 145                |          |          | 35   |
-| smolvla@so-101 (f32)   | 396              | 158                |          |          | 33   |
-| pi0@libero (f32)       |                  | 720                |          |          | 78   |
-| pi0@libero (bf16*)     |                  | 643                |          |          | 69   |
+| smolvla@libero (bf16*) | 555              | 216                | 28       |          | 52   |
+| smolvla@libero (f32)   | 577              | 236                | 32       |          | 50   |
+| smolvla@so-101 (bf16*) | 339              | 145                | 23       |          | 35   |
+| smolvla@so-101 (f32)   | 396              | 158                | 24       |          | 33   |
+| pi0@libero (f32)       |                  |                    |          |          | 78   |
+| pi0@libero (bf16*)     |                  |                    |          |          | 69   |
 
 > `bf16*`：在 Mac上使用 f16 结果替代 bf16，因为当前 Mac对 bf16 的支持不够好。
 

robot_server/README_zh.md

@@ -65,6 +65,17 @@ bash robot_server/shell/launch_robot_server_linux_cuda.sh
 
 Windows 的 `.bat` 脚本：
 
+### 故障排查
+
+* `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.`
+
+这是因为CUDACXX变量没有被设置，通过以下方式设置环境变量即可（下面是一个案例，具体应当寻找对应机器的nvcc路径）
+
+```
+export CUDACXX=/usr/local/cuda-12.4/bin/nvcc
+export PATH=/usr/local/cuda-12.4/bin:$PATH
+```
+
 ## 方法2：直接下载预编译发布
 
 从release page下载之后，运行以下命令

src/readme_zh.md

@@ -114,7 +114,7 @@ STATE=0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
   --task "pick up the fork"
 ```
 
-pi0 的 `--image-name` 必须和 checkpoint metadata 里的 `pi0.image_keys` 一致。LIBERO v044 split checkpoint 使用 `observation.images.image` 和 `observation.images.image2`。
+pi0 的 `--image-name` 必须和vit部分的metadata 里的 `pi0.image_keys` 一致。LIBERO v044 split checkpoint 使用 `observation.images.image` 和 `observation.images.image2`。
 
 ### `models/model.h`
 
@@ -144,8 +144,6 @@ if (args.type == model_type::pi0) {
 }
 ```
 
-新增模型时通常需要在这里 include 新模型的 wrapper 头文件，并添加一条分发分支。
-
 ### `models/ggml_backend.*`
 
 这组文件封装 ggml 后端、buffer、scheduler 等公共能力。多个模型都可能复用这层代码，避免每个模型目录里重复处理 ggml 初始化、设备选择和内存管理。
@@ -170,7 +168,7 @@ SmolVLA 的模型实现目录。当前主要分为两层：
 
 ### `models/pi0/`
 
-pi0 的模型实现目录，也采用“模型专用 engine + `Model` wrapper”的结构：
+pi0 的模型实现目录，也采用“模型专用 engine + `Model` 子类”的结构：
 
 * `pi0_engine.*`：模型专用 runtime API，例如 `pi0_params`、`pi0_context`、`pi0_init()`、`pi0_predict_raw_rgb()`、`pi0_reset()`、`pi0_free()`。
 * `pi0_model.*`：把 `pi0_engine` 适配到 `robotcpp::Model`。
@@ -324,7 +322,7 @@ bool make_model(const model_args & args, std::unique_ptr<Model> & out, std::stri
 * `print_usage()`：补充新模型的参数说明。
 * 参数解析循环：解析新模型需要的 CLI 参数，并写入 `model_args`。
 
-如果新模型对 image name、state 维度或 task 文本有特殊要求，尽量在 wrapper 的 `predict()` 或初始化校验里返回明确错误信息，方便 CLI 和 server 复用。
+如果新模型对 image name、state 维度或 task 文本有特殊要求，尽量在子类的 `predict()` 或初始化校验里返回明确错误信息，方便 CLI 和 server 复用。
 
 ### 6. 修改 CMake
 
@@ -340,8 +338,6 @@ add_library(robotcpp STATIC
 )
 ```
 
-如果新模型内部 runtime 足够大、需要单独测试，或要复用已有 ggml/llama 链接配置，也可以建立自己的 target，再让 `robotcpp` 链接它。是否叫 `newmodel_engine` 不重要，重点是外部仍通过 `robotcpp::Model` 创建和调用模型。
-
 ### 7. 验证
 
 #### 新模型最小验证模板
@@ -353,25 +349,21 @@ add_library(robotcpp STATIC
   --model-type newmodel \
   --image /path/to/image.png \
   --image-name image \
-  --state 0,0,0 \
+  --state 0,0,0,0,0,0 \
   --task "grab the block." \
   --threads 4 \
   --newmodel-weights /path/to/newmodel.gguf
 ```
 
-如果 `model-server` 也要使用该模型，还需要确认 server 启动参数能把新模型所需字段传到 `model_args`。通常应保持 server 和 CLI 使用同一套 `make_model()` 路径，以避免两边行为不一致。
+如果 `model-server` 也要使用该模型，还需要确认 server 启动参数能把新模型所需字段传到 `model_args`。
 
 ## 新模型接入检查清单
 
 * `tools/hf2gguf/<model_name>/` 已能把原始 checkpoint 或 `.pt` 转成 C++ runtime 使用的 GGUF。
 * `tools/quant/config/<model_name>_origin.yaml` 已覆盖新模型的所有 GGUF component 和 tensor group。
-* `src/models/<model_name>/` 下有清晰的 `Model` wrapper；只有在确实需要时才拆出内部 runtime 或 engine。
+* `src/models/<model_name>/` 下有清晰的 `Model` ==子类==；只有在确实需要时才拆出内部 runtime 或 engine。
 * `model_type` 已增加新枚举。
 * `model_args` 已包含新模型初始化所需参数。
 * `model_factory.cpp` 已接入新模型。
 * `model-cli.cpp` 已支持 `--model-type <model_name>` 和必要参数。
 * `CMakeLists.txt` 已加入新模型源文件，并让 `robotcpp` 能链接到必要的内部组件。
-* `predict()` 会校验输入图片、state、task，并通过 `error` 返回可读错误。
-* `model_result.actions`、`chunk_size`、`action_dim` 的含义与现有模型保持一致。
-* `reset()` 在模型有 cache 或时序状态时能正确清理状态。
-* `model-cli` 和 `model-server` 走同一套 wrapper，不额外绕过 `robotcpp::Model`。