Xtrainer2 真机代码交接

这份源码来自你的 GitHub 仓库，整理在 HF 的独立目录 real_robot/。训练与推理服务以 ReTime_source/main 的 Xtrainer2 实现为主体，原开发仓库 OPTR-StarVLA/main 提供 HDF5 数据转换与 LeRobot 格式验证工具。逐文件来源见 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 和 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 数据说明。

推理服务

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

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

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

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。

本次交接验证

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 参数。