Add Wall-X serving and Turtle2 TCP WebSocket bridge

2026-09-23 21:04:17 +08:00
parent 6764e8f12f
commit d1cc7d96ad
40 changed files with 8591 additions and 40 deletions
@@ -0,0 +1,200 @@
+# Wall-X Turtle2 RTC 使用说明
+
+本文描述独立 RTC 副本链路。原 Wall-X serving、bridge 和 Turtle2 客户端文件未被覆盖。
+
+## 1. 实现结构
+
+RTC 链路由三部分组成：
+
+1. `launch_serving_rtc.py` 加载 RTC policy/model 副本；
+2. `tcp_ws_bridge_rtc.py` 透传 session、request、已消费步数和推理延迟；
+3. `SlaveRos2SocketPort_TURTLE2_RTC.py` 用独立控制线程在推理期间继续执行旧动作队列。
+
+RTC guidance 在 Wall-X 的归一化相对动作空间中执行。上一段剩余绝对末端轨迹会基于最新 `follow2_pos` 重新转换为相对平移和相对 6D 旋转，然后才送入下一轮 flow inference。
+
+当前仅支持：
+
+- `model_type=qwen2_5`；
+- `infer_mode=flow`；
+- 单 GPU 串行推理；
+- Turtle2 WebSocket/TCP 部署链路。
+
+RTC serving 不支持 dynamic batching。RTC VJP 会增加推理时间和显存占用。
+
+## 2. 参数关系
+
+推荐初始参数：
+
+```text
+action_horizon = 32
+rtc_execution_horizon = 6       # 模型步
+action_interpolate_multiplier = 6
+action_end_ratio = 1.0
+```
+
+含义：
+
+- 每次模型生成完整 32 步，作为推理超时时的备用队列；
+- 真机执行约 6 个模型步后申请下一次推理；
+- 每个模型步在 bridge 端插值为 6 个控制点；
+- 因此正常情况下执行约 `6 × 6 = 36` 个控制点后重规划；
+- 完整备用队列是 `32 × 6 = 192` 个控制点。
+
+RTC 模式不要把 `action_end_ratio` 设为 `0.2`。这会删除备用队列后半段，推理稍慢时容易出现队列下溢。
+
+## 3. 启动 RTC serving
+
+建议先使用不同端口，不影响原 serving：
+
+```bash
+cd /home/xiehaolv/huanghuagui/zhanyifeng/wall-x
+
+bash scripts/run_serving_rtc.sh \
+  --checkpoint-path /home/xiehaolv/huanghuagui/wall-x-model/finetuned/7 \
+  --train-config-path /home/xiehaolv/huanghuagui/wall-x-model/finetuned/7/config.yml \
+  --port 32197 \
+  --env X2ROBOT \
+  --cuda-id 0 \
+  --serialize-actions \
+  --robot-type turtle \
+  --action-horizon 32 \
+  --robot-action-interpolate-multiplier 1 \
+  --robot-action-end-ratio 1.0 \
+  --rtc-execution-horizon 6 \
+  --rtc-max-guidance-weight 10 \
+  --rtc-prefix-schedule linear \
+  -- \
+  --model-config.cam-names face_view left_wrist_view right_wrist_view \
+  --model-config.norm-key pick_paper_lerobot_v21_3cam
+```
+
+不要添加 `--max-batch-size`。RTC policy 会保存每个机器人 session 的上一段动作。
+
+## 4. 首次启动 RTC bridge：只做 dry-run
+
+首次运行不要添加 `--allow-send`：
+
+```bash
+cd /home/xiehaolv/huanghuagui/zhanyifeng/wall-x
+
+/home/xiehaolv/huanghuagui/conda-envs/wallox_0.5/bin/python \
+  scripts/tcp_ws_bridge_rtc.py \
+  --ws-url ws://127.0.0.1:32197 \
+  --tcp-port 30126 \
+  --instruction "pick up the paper" \
+  --action-horizon 32 \
+  --action-end-ratio 1.0 \
+  --action-interpolate-multiplier 6 \
+  --rtc-execution-horizon 6 \
+  --fixed-lift 0.3 \
+  --max-position-delta 0.05 \
+  --max-rotation-delta 0.25 \
+  --clip-action-delta \
+  --max-action-cycles 0
+```
+
+dry-run 会在第一轮推理后关闭连接，这是预期行为。确认图像、状态和动作维度正常后，再进行真机发送测试。
+
+## 5. 部署真机 RTC 副本
+
+本机生成的真机文件：
+
+```text
+/home/xiehaolv/huanghuagui/robot_self/turtle2/modules/src/ui/model2arm/communicationPort/SlaveRos2SocketPort_TURTLE2_RTC.py
+/home/xiehaolv/huanghuagui/robot_self/turtle2/modules/src/ui/model2arm/communicationPort/infer_rtc.py
+```
+
+复制到真机对应目录，不覆盖原文件：
+
+```bash
+scp \
+  /home/xiehaolv/huanghuagui/robot_self/turtle2/modules/src/ui/model2arm/communicationPort/SlaveRos2SocketPort_TURTLE2_RTC.py \
+  arm@172.28.57.93:/home/arm/prj/turtle2/modules/src/ui/model2arm/communicationPort/
+
+scp \
+  /home/xiehaolv/huanghuagui/robot_self/turtle2/modules/src/ui/model2arm/communicationPort/infer_rtc.py \
+  arm@172.28.57.93:/home/arm/prj/turtle2/modules/src/ui/model2arm/communicationPort/
+```
+
+## 6. 真机发送测试
+
+重新启动 RTC bridge，并增加 `--allow-send`：
+
+```bash
+/home/xiehaolv/huanghuagui/conda-envs/wallox_0.5/bin/python \
+  scripts/tcp_ws_bridge_rtc.py \
+  --ws-url ws://127.0.0.1:32197 \
+  --tcp-port 30126 \
+  --instruction "pick up the paper" \
+  --action-horizon 32 \
+  --action-end-ratio 1.0 \
+  --action-interpolate-multiplier 6 \
+  --rtc-execution-horizon 6 \
+  --fixed-lift 0.3 \
+  --max-position-delta 0.05 \
+  --max-rotation-delta 0.25 \
+  --clip-action-delta \
+  --max-action-cycles 0 \
+  --allow-send
+```
+
+初次 RTC 测试不要添加 `--require-right-feedback`。如果右臂反馈 topic 没有变化，该选项会让 bridge 主动关闭 TCP，真机随后会出现 `BrokenPipeError`。确认 `/follow2_pos_back` 正常后再启用。
+
+在真机终端运行：
+
+```bash
+source /opt/ros/noetic/setup.bash
+source /home/arm/prj/turtle2/modules/devel/setup.bash
+cd /home/arm/prj/turtle2/modules/src/ui/model2arm/communicationPort
+python3 infer_rtc.py <推理服务器IP> 30126
+```
+
+## 7. 正常日志判据
+
+第一轮没有旧 chunk，应看到：
+
+```text
+guided=False
+```
+
+第二轮开始应看到：
+
+```text
+guided=True
+RTC merged request_id=... delay_points=... delay_model_steps=... remaining=...
+```
+
+bridge 应持续输出不同的 request ID，不应出现：
+
+```text
+stale/mismatched request_id
+```
+
+如果出现：
+
+```text
+RTC response ... is stale
+```
+
+说明推理时间已经超过完整 32 步备用队列。应先降低 flow inference steps、提高控制点周期或增加 action horizon，而不是继续提高 guidance weight。
+
+## 8. 回退
+
+RTC 使用独立文件和端口。停止 RTC 三个进程后，重新运行原始命令即可回退：
+
+```text
+launch_serving.py / run_serving.sh
+tcp_ws_bridge.py
+infer.py
+```
+
+不需要恢复或覆盖任何原始文件。
+
+## 9. 离线验证
+
+```bash
+cd /home/xiehaolv/huanghuagui/zhanyifeng/wall-x
+/home/xiehaolv/huanghuagui/conda-envs/wallox_0.5/bin/python \
+  -m pytest -q tests/test_rtc_wallx.py tests/test_tcp_ws_bridge.py
+```
+
@@ -0,0 +1,103 @@
+三、仿真任务全流程（LIBERO 数据集微调+评估）
+适用于单臂机器人仿真场景，基于 LeRobot 格式 LIBERO 数据集完成模型微调与仿真测试
+3.1 下载 LIBERO 数据集
+libero的huggingface路径：https://huggingface.co/datasets/lerobot/libero
+huggingface-cli download lerobot/libero \
+  --repo-type dataset \
+  --local-dir /path/to/libero_all
+3.2 配置训练 YAML 文件
+复制官方示例配置，替换所有本地路径参数，适配本地环境
+cp workspace/example/libero.yml /path/to/my_libero_config.yml
+核心必填配置（需完整替换）：
+参考：https://github.com/X-Square-Robot/wall-x/blob/main/workspace/example/libero.yml
+model:
+  config_path: /path/to/wall-oss-0.5/config.json  # 模型配置文件路径
+  processor_path: /path/to/Qwen2.5-VL-3B-Instruct  # 处理器路径
+  pretrained_path: /path/to/Qwen2.5-VL-3B-Instruct  # 预训练基座路径
+
+data:
+  lerobot_config:
+    repo_id: /path/to/libero_all          # 本地LIBERO数据集根目录
+  norm_stats_path: /path/to/libero_all_norm_stats.json  # 归一化统计文件
+  key_mappings:                           # 数据集字段映射（固定适配LIBERO）
+    camera:
+      observation.images.faceImg: face_view
+      observation.images.rightImg: right_wrist_view
+    state: observation.state
+    action: action
+
+checkpoint:
+  save_path: /path/to/libero_training_output  # 训练结果保存路径
+  resume_from: /path/to/wall-oss-0.5/model.safetensors  # 预训练权重路径
+
+dof_config配置
+  # Libero delta action: pos3 + rot3 + gripper1 = 7, plus action_padding(19) = 26.
+  dof_config:
+    master_right_ee_cartesian_pos: 3     # delta position
+    master_right_ee_rotation: 3          # delta rotation (ZYX euler)
+    master_right_gripper: 1
+    action_padding: 19
+  ar_dof_config:
+    master_right_ee_cartesian_pos: 3
+    master_right_ee_rotation: 3
+    master_right_gripper: 1
+    action_padding: 19
+  # State: pos3 + rot3 + gripper2 = 8, plus action_padding(18) = 26.
+  agent_pos_config:
+    follow_right_ee_cartesian_pos: 3
+    follow_right_ee_rotation: 3
+    follow_right_gripper: 2
+    action_padding: 18
+  action_horizon: 10
+  action_horizon_flow: 10
+
+
+关键适配说明：LIBERO 为7维单臂动作，需通过配置中 action_padding 补全至26维，匹配模型预训练维度（参考示例配置注释）
+3.3 生成数据集归一化统计文件
+训练前必须执行，生成数据均值、方差统计文件，保证训练稳定性
+python scripts/compute_norm_stats.py \
+  --train_config /path/to/my_libero_config.yml \
+  --data_root /path/to/libero_all \
+  --output_path /path/to/libero_all_norm_stats.json
+执行完成后，需确认配置文件中 norm_stats_path 与输出路径一致
+3.4 启动模型微调训练
+硬件要求：单卡训练最低需要 48G 显存，多卡训练推荐开启 FSDP 分布式训练
+单GPU训练命令
+CUDA_VISIBLE_DEVICES=0 \
+  python wall_x/trainer/fsdp_trainer/train_fsdp.py \
+    --config /path/to/my_libero_config.yml
+多GPU训练（推荐）
+CUDA_VISIBLE_DEVICES=0,1,2,3 \
+  torchrun --nproc_per_node=4 \
+    wall_x/trainer/fsdp_trainer/train_fsdp.py \
+    --config /path/to/my_libero_config.yml
+断点合并说明
+多卡FSDP训练会生成分片权重文件，推理前需合并为完整权重：
+python scripts/merge_sharded_weights.py \
+  /path/to/sharded_checkpoint \
+  /path/to/merged_checkpoint
+3.5 LIBERO 仿真推理评估
+批量测试模型在仿真场景的任务完成效果，支持指定任务套件、测试次数
+前置依赖校验（未安装需重新执行仿真依赖安装命令）：需提前安装 robosuite、MuJoCo、PyOpenGL 等仿真组件
+常规批量评估
+参考脚本：https://github.com/X-Square-Robot/wall-x/blob/main/scripts/run_libero.sh
+CHECKPOINT_PATH=/path/to/checkpoint \
+TRAIN_CONFIG_PATH=/path/to/my_libero_config.yml \
+TASK_SUITE_NAME=libero_spatial \
+NUM_TRIALS_PER_TASK=50 \
+bash scripts/run_libero.sh
+快速冒烟测试（调试用，单任务1次测试）
+SMOKE=1 CHECKPOINT_PATH=/path/to/checkpoint bash scripts/run_libero.sh
+核心环境变量说明
+环境变量
+参数说明
+CHECKPOINT_PATH
+训练完成的模型断点目录
+TRAIN_CONFIG_PATH
+训练使用的YAML配置文件路径
+TASK_SUITE_NAME
+仿真任务套件：libero_spatial / libero_object / libero_goal / libero_10
+ALL_SUITES=1
+开启后批量运行全部4类仿真任务套件
+TASK_INDICES
+指定测试任务序号，多任务用逗号分隔（如0,1,2）