VLA/docs/WALLX_RTC_USAGE.md

# 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
```