# Xtrainer2 真机代码交接

这份源码来自你的 GitHub 仓库，整理在 HF 的独立目录 `real_robot/`。训练与推理服务以 `ReTime_source/main` 的 Xtrainer2 实现为主体，原开发仓库 `OPTR-StarVLA/main` 提供 HDF5 数据转换与 LeRobot 格式验证工具。逐文件来源见 [SOURCE_FILES.json](SOURCE_FILES.json)。

## 代码入口

| 用途 | 文件 |
|---|---|
| HDF5 → LeRobot 数据转换 | `source/scripts/convert_xtrainer2_hdf5_to_lerobot.py` |
| 数据格式与四元数约定验证 | `source/scripts/validate_xtrainer2_lerobot.py` |
| 数据注册、三相机及双臂状态配置 | `source/examples/Xtrainer2/train_files/data_registry/data_config.py` |
| 数据 support 构建 | `source/examples/Xtrainer2/train_files/build_pack_phone_support.py` 和 `build_pick_bottle_support.py` |
| 训练启动 | `source/examples/Xtrainer2/train_files/run_xtrainer2_train.sh` |
| ReTime proposal 与 continuation | `source/retime/cli.py` 和 `source/scripts/run_xtrainer2_arm.sh` |
| 真机 policy server 启动 | `source/examples/Xtrainer2/train_files/run_xtrainer2_policy_server.sh` |
| 双臂动作与四元数转换 | `source/deployment/model_server/xtrainer2_command.py` |
| WebSocket 客户端通信工具 | `source/deployment/model_server/tools/websocket_policy_client.py` |

`source/` 保留上游包布局。进入该目录再运行命令，使 `starVLA`、`retime` 和 `deployment` 使用这份源码。

## 环境与依赖

目标运行环境为 Linux、Python ≥ 3.10。原依赖列表为 [requirements.txt](source/requirements.txt) 和 [requirements-xtrainer2.txt](source/requirements-xtrainer2.txt)，其中 PyTorch 为 2.7.1，Transformers 为 4.57.0，Accelerate 为 1.13.0。

双臂四元数与 rotation-6D 转换需要匹配 Python、PyTorch、CUDA 的 PyTorch3D。数据转换另需 `h5py`、`pandas`、Pillow 和可执行的 `ffmpeg`。按目标 GPU 环境安装相应依赖。

## 数据与训练配置

训练配置放在 `source/configs/`，包含 pack-phone、pick-bottle、smoke 和从 pack-phone common start 延续的配置。原配置使用 Florence、8 GPU、每卡 micro-batch 4、累积 4，global batch 为 128。pack-phone 的完整训练预算为 52,380 updates，warmup 为 5,000。continuation 配置从 `steps_17460_accelerate` 延续，训练 seed 为 117465，基础训练 seed 为 42。

运行前按配置设置 `FLORENCE_MODEL_PATH`、`XTRAINER2_DATA_ROOT`、`OPTR_RUN_ROOT` 及数据 support 路径。训练入口会检查配置实际引用的环境变量。具体实现见 [Xtrainer2 数据说明](source/examples/Xtrainer2/README.md)。

## 推理服务

准备真机 checkpoint 对应的运行目录，模型、配置、归一化统计保持成套。

```text
your_real_robot_run/
├── config.yaml
├── dataset_statistics.json
└── checkpoints/
    └── your_model.pt
```

在下载后的 `real_robot/source` 中执行以下命令，将示例路径改为实际路径。

```bash
export OPTR_PYTHON=/path/to/your/python
export FLORENCE_MODEL_PATH=/path/to/Florence-2-large
export TMPDIR="$PWD/runtime_tmp"
mkdir -p "$TMPDIR"

bash examples/Xtrainer2/train_files/run_xtrainer2_policy_server.sh \
  /path/to/your_real_robot_run/checkpoints/your_model.pt 0 10093
```

服务使用 BF16，并在连接握手中返回动作维数、相机顺序、四元数约定和 action chunk 长度。

## 机械臂客户端接口

相机顺序为 `cam_high`、`cam_left_wrist`、`cam_right_wrist`，图像使用 HWC RGB uint8。客户端提供 `image`、`lang` 和原始 16 维 `state`。双臂状态与动作按每臂位置 3 维、四元数 4 维、夹爪 1 维排列，机器人侧四元数顺序为 `xyzw`。服务端负责归一化和坐标表示转换，模型内部使用 20 维 rotation-6D 表示，返回动作使用机器人侧的 16 维布局。

pick-bottle 的相对末端动作由服务端结合当前状态还原为绝对动作。真实机械臂驱动、相机采集和执行循环由独立硬件客户端完成，需接入师兄实际使用的控制程序。上游接口说明见 [ROBOT.md](source/examples/Xtrainer2/ROBOT.md)。

## 本次交接验证

- 129 个源文件与来源清单的字节数一致，逐文件来源见 `SOURCE_FILES.json`。
- 95 个 Python 文件通过语法检查，7 个 YAML、1 个 JSON 和 1 个 TOML 文件通过解析检查。
- 8 个 shell 入口通过 `bash -n`，`python -m retime --help` 可正常运行。
- 使用 jlu66 现有 Python 环境在 CPU 上执行 13 项配置测试，全部通过，覆盖双臂维数、global batch、梯度累积、ZeRO-3 权重保存设置、训练种子和 continuation 参数。

实际模型加载、GPU 推理和机械臂动作执行需在配套设备与 checkpoint 上验证。