π0.5 羽毛球任务:推理部署与执行流程

badminton651 · step 89999 · h6 Thor(agi@192.168.247.6)· 代码目录 /data/project_r/agibotg2_pi0.5_deploy

第一章 π0.5 推理部署

整套系统由两个独立进程组成:一个只做模型推理的 WebSocket 服务,另一个负责采集观测、调度推理并通过 GDK 控制机器人。两者都在 h6 的 Thor 上运行,通过本机 127.0.0.1:8012 通信。

项目当前值
模型π0.5,PaliGemma(Gemma 2B)+ Gemma 300M 动作专家;内部动作维度 32,对外 24
权重目录downloads/badminton-pi05-651-step89999(Orbax,JAX 直接加载,不需要转 safetensors)
归一化assets/badminton651/norm_stats.json,q01/q99 分位数
提示词Put the shuttlecock into the shuttlecock tube.
输出每次 30 帧 × 24 维绝对关节角(弧度),按 15 Hz 播放,整段 2 秒
推理耗时(h6 实测)首次预热约 9.7 s;稳定中位数 448 ms,P95 494 ms(10 步去噪)

部署步骤

  1. 确认机器环境一次性

    目标是 ARM64 的 Thor、Python ≥ 3.11、支持 CUDA 13 的驱动。不要替换 Jetson 驱动或改动机器人已有的 Python 环境。

    uname -m; cat /etc/nv_tegra_release; nvidia-smi; python3 --version; df -h .
  2. 放置代码到固定目录一次性

    代码必须位于 /data/project_r/agibotg2_pi0.5_deploy。采集容器 ral-g2-bridge 把这个目录挂载为 /ws/agibotg2_pi0.5_deploy,run_robot.sh 会检查路径,不一致直接退出。

  3. 建立独立 venv 并自检一次性

    只按 requirements-thor.txt 安装(JAX/JAXLIB 0.9.2 + CUDA 13 插件、Flax 0.12.5、Orbax 0.11.33)。不要安装 vendor/openpi 的训练依赖,那会把 JAX 降到 CUDA 12 的 0.5.3。

    bash scripts/setup_thor.sh          # 建 .venv、装依赖、pip check、跑 doctor
    source scripts/env.sh
    .venv/bin/python scripts/doctor.py  # 必须在 GPU 上完成矩阵运算和模型结构构造

    scripts/env.sh 在 Thor 上会加 --xla_gpu_enable_triton_gemm=false --xla_gpu_autotune_level=0,避免 h6 上的 cudaErrorNoKernelImageForDevice。

  4. 放入权重与 tokenizer一次性

    downloads/badminton-pi05-651-step89999/
      params/                            # Orbax OCDBT 权重
      assets/badminton651/norm_stats.json
    results/badminton651-cache/big_vision/paligemma_tokenizer.model

    启动脚本把 OPENPI_DATA_HOME 指到 tokenizer 缓存,推理全程不联网。

  5. 启动推理服务每次运行

    cd /data/project_r/agibotg2_pi0.5_deploy
    bash scripts/run_inference_badminton651.sh
    # 等待 MODEL_LOADED 和 server listening on 127.0.0.1:8012

    服务找不到 JAX GPU 会直接报错退出。首个请求包含 JIT 编译,约 10 秒。

  6. 只读联调(shadow)建议每次先跑

    bash scripts/run_robot_badminton651.sh --schedule sync --mode shadow

    采集真实相机和关节,请求 20 次推理并记录动作、延迟、是否超 SDK 限位,不初始化 GDK 控制,也不下发任何命令。

  7. 复位到保存姿态可选

    bash scripts/run_reset_saved_20261030.sh               # 只读计划
    bash scripts/run_reset_saved_20261030.sh --execute     # 真机复位全身
    bash scripts/run_reset_saved_20261030.sh --arms-only --execute

    姿态文件 results/saved_poses/h6-20261030-151620.json 只存在于 h6,不在代码包里。复位不是推理启动链的一部分,控制程序不会自动复位。

  8. 真机执行每次运行

    # 异步 20+5(脚本默认调度)
    bash scripts/run_robot_badminton651.sh --schedule async --mode execute
    # 同步:执行 25 帧后停住等新推理
    bash scripts/run_robot_badminton651.sh --schedule sync --replan-steps 25 --mode execute
    • 必须在操作员的交互终端运行,并取得 /tmp/agibot-pi05-control.lock;复位和执行不能同时跑。
    • 单次最长 300 秒,Ctrl+C 可提前结束;日志与轨迹写入 results/robot-live-XXXXXXXX/。
    • 执行前会校验机器人 AID G2A0205C900081、SDK 源地址 192.168.112.203(wlan0)和 discovery 地址。
安全边界:腰被锁在启动时实测角度,头不下发;任何超出 SDK 关节限位、观测超过 0.2 s、预测超过 0.8 s、控制周期间隔超过 50 ms、腰/头被外力推动超过 0.03 rad 的情况都会拒绝或停止,不会重试。

第二章 当前推理流程:从观测到控制执行

以下按默认的异步 20+5 调度描述(配置 configs/badminton651/h6_89999_async.json)。点击图中方块可查看说明。

2.1 组件交互图

机器人 / ROS 采集容器 控制进程 推理服务
G2 机器人 容器 ral-g2-bridge(ROS Jazzy) 宿主机:run_robot_badminton651.sh 宿主机:run_inference_badminton651.sh 三路相机 头部 + 左/右腕 JPEG 关节 / 夹爪状态 /g2/joint_state 等 GDK / 运动控制器 joint_servo_control get_joint_states robot_capture.py 订阅 5 个话题,配组 live.npz 共享挂载目录,原子替换 推理子进程(spawn) 读观测、改 state、发请求 robot_bridge 主循环 100 Hz 接收动作块、调度推理 AsyncBufferGuard 选帧 → map_target → 限位 GdkBackend(read / send) serve_badminton651 WebSocket :8012 π0.5(JAX GPU) 10 步去噪 ROS 读取 JPEG+state (30,24) 结果队列 请求 + 交接目标 21 维位置目标,100 Hz 反馈(每拍读取)

点击上图中的方块

查看每个组件的职责、输入输出和代码位置。

2.2 数据流程图:一次推理内部发生了什么

① 采集(容器) 相机 JPEG × 3 head / hand_left / hand_right 22 关节 + 2 夹爪 按名字重排为 24 维 配组(latest) 每个话题取最新一条 最多每 50 ms 写一次 live.npz state + 原始 JPEG 字节 ② 推理子进程 • 等待请求之后才写出的新观测 • 首次:state 用实测值 • 之后:state[8:24] ← 上一块第 24 帧目标 • 腰/头 state[0:8] 保持实测 • msgpack 发 JPEG + state 到 :8012 ③ 推理服务 serve_badminton651.py 解码 JPEG BGR → 拉伸 640×480 INTER_LINEAR → RGB 归一化 state q01/q99 → [-1, 1] badminton651 统计 图像 224×224 等比例缩放 居中补黑边 文本 token 提示词 + 离散化 state (π0.5 无 state_proj) 补齐到 32 维 state / 动作空间 sample_actions 随机噪声,10 步 flow → (30, 32) ④ 输出回到控制进程 反归一化 取前 24 维 → (30, 24) 校验后接收 预测年龄 < 0.8 s、手臂/夹爪限位 按 15 Hz 选帧 执行第 0–24 帧 GDK 位置伺服 21 维目标,100 Hz 发布
采集写进 state 的是 ROS /g2/joint_state 的 position;控制循环每拍从 GDK 读的反馈是 get_joint_states() 的 motor_position。两者用途不同:前者喂模型,后者只用于安全检查和跟踪诊断。

2.3 时序图:异步 20+5 的一个完整周期

G2 / GDK 控制主循环 100 Hz 推理子进程 采集容器 推理服务 持续写 live.npz(≤20 Hz) 启动:读实测姿态作 baseline,保持不动 ① 首次请求(state 用实测) 请求之后的新观测 ② infer(JPEG×3, state24) ~450 ms actions (30, 24) 结果放入队列 ③ 接收块 A,从第 0 帧开始播放 每 10 ms:读反馈 + 发目标 帧 0–19(1.333 s) ④ 到第 20 帧:发下一次请求 state_override = 块 A 第 24 帧目标 ⑤ infer(新图像 + 交接 state) 帧 20–24 继续执行(0.333 s) actions B(提前到) 块 B 已就绪,但必须等块 A 执行到第 25 帧 ⑥ 交接点(块 A 开始后 1.667 s) ⑦ 切到块 B 的第 0 帧,时间从接收时刻起算 块 A 第 25–29 帧丢弃;不插值、不混合 到第 20 帧再次请求,循环往复

5 帧缓冲只有 333 ms,而实测推理中位数 448 ms,因此大多数周期会落入“推理晚于交接点”的情况。

2.4 动作播放时间轴:30 帧里哪些被执行

执行,然后发请求 请求后继续执行(缓冲) 不执行 / 丢弃

2.5 流程图:每 10 ms 控制一拍

tick(每 10 ms) GDK 读反馈 健康/控制模式/22 关节/夹爪/时间戳 查结果队列 有新块且已到交接点 → 校验后接收 该请求了吗? 无块,或当前块已过第 20 帧 当前块仍在 播放窗口内? step:按时间选帧 index = ⌊已过秒数 × 15⌋ hold:保持上一目标 启动等待 / 推理迟到 map_target + SDK 限位检查 腰锁 baseline,去掉头,夹爪改名 joint_servo_control(21 维) 是 否 异步发给推理子进程(不阻塞) 最多同时 1 个未完成请求 任一触发即停止发布 • 机器人报错或控制模式变化 • 读反馈超过 50 ms / 时间戳 150 ms 不前进 • 两拍间隔超过 50 ms(不追赶) • 腰/头偏离 baseline 超过 0.03 rad • 目标越过 SDK 限位或发送失败

2.6 24 维动作如何变成 GDK 命令

模型下标含义下发
0–4腰 idx01–idx05写入请求,但值被替换为启动时实测角(锁定)
5–7头 idx11–idx13不在请求中,头保持原地
8–14左臂 idx21–idx27模型绝对角
15–21右臂 idx61–idx67模型绝对角
22gripper_l改名 idx31_gripper_l_inner_joint1
23gripper_r改名 idx71_gripper_r_inner_joint1
req = sdk.JointServoControlReq()
req.joint_names      = COMMAND_NAMES   # 21 个:腰5 + 双臂14 + 夹爪2
req.joint_positions  = target.tolist() # 绝对位置,弧度
req.joint_velocities = []
req.control_period   = 0.02
robot.joint_servo_control(req, False)  # 普通伺服,非 low-delay

实际每 10 ms 调用一次,但 control_period 写的是 0.02。同一个 15 Hz 目标会原样重复发 6–7 次,羽毛球配置没有帧间插值。