G0.5：从新观测到双臂重新就位

本节采用“G0.5 提案 + IK 对齐 + 手指技能”的分层控制。它的价值在于让预训练 VLA 接入实际可执行的双臂流程，同时保留专用演奏控制器的节奏与指法。

1. 模型环境与下载

使用独立的 Python 3.10 环境。上游安装方法和许可证见 GalaxeaVLA，模型资源见 OpenGalaxea/G05。

本次接口核对使用提交 89f2322b4ad016e192437adc1a2c253b05bab246：

bashgit clone https://github.com/OpenGalaxea/GalaxeaVLA.git "$HOME/GalaxeaVLA"
export G05_REPO="$HOME/GalaxeaVLA"
git -C "$G05_REPO" checkout 89f2322b4ad016e192437adc1a2c253b05bab246
cd "$G05_REPO"
uv sync --index-strategy unsafe-best-match
export G05_PY="$G05_REPO/.venv/bin/python"
export G05_MODELS="$HOME/models/G05"

uv 安装见官方说明。CUDA 扩展应与上游要求的 PyTorch / CUDA 版本配套；本章不会修改其他已运行的训练环境。

下载 base 模型及共享组件，保留配置与统计文件：

bashuv pip install --python "$G05_PY" huggingface_hub
"$G05_PY" -c 'import os; from huggingface_hub import snapshot_download; snapshot_download("OpenGalaxea/G05", local_dir=os.environ["G05_MODELS"], allow_patterns=["g05-base/*", "action_tokenizer.pt", "qwen3_5_2b_base_processor/*"])'

下载只需一次；已有模型可直接设置目录。先检查：

textG05_MODELS/
  action_tokenizer.pt
  qwen3_5_2b_base_processor/
  g05-base/
    .hydra/config.yaml
    dataset_stats.json
    checkpoints/model_state_dict.pt

有些下载布局在 g05-base/ 下多一层同名目录。可用下面命令定位，然后把确切路径赋给变量：

bashfind "$G05_MODELS/g05-base" -name model_state_dict.pt
export G05_CHECKPOINT="$G05_MODELS/g05-base/checkpoints/model_state_dict.pt"
test -f "$G05_CHECKPOINT"
cd "$PIANO_ROOT"

脚本从检查点相邻的配置和数据统计读取实际模型架构；应保留下载目录层级。不要只复制一个权重文件。

工作站验证使用约 96 GB 显存设备；早期单进程推理记录约占 11 GB 显存，这不是最低硬件保证。发布脚本默认允许使用当前设备的全部可用配额，可通过 G05_CUDA_MEMORY_FRACTION 限制 PyTorch 分配比例，例如共享 96 GB 设备时设为 0.25。它是占整张卡总显存的比例，不会预留显存，也不会阻止其他进程占用。

2. 模型具体接收和输出什么

方向	内容
输入画面	头部、左腕、右腕相机 RGB
输入状态	左右臂各 7 个关节角，以及手部开合代理量
任务指令	移琴后的双臂准备 / 重新就位要求
输出	R1 Pro 双臂动作块，作为姿态提案
执行结果	限幅后的提案与腕部目标共同进入 IK，再发送执行器控制

Shadow Hand 的开合量由拇指与食指距离归一化得到，用于适配原生夹爪观测；独立指关节由钢琴控制器驱动。

g05_piano_client.py 启动 g05_piano_worker.py 子进程，加载一次检查点，多次处理新观测。仿真环境与模型环境通过消息交换协作，不需要把两个环境的依赖合并。

3. 动作提案如何参与控制

G0.5 输出先经过关节范围与步长限制，再作为 IK 的关节姿态参考。求解同时考虑：

腕部到目标演奏位置的误差；
腕部方向误差；
与 G0.5 双臂姿态提案的距离；
关节限位、速度约束和当前构型。

--model-weight 调整姿态参考权重。随附练习使用 0.1，历史连续实验使用 0.5；不同起始构型可按恢复残差选择权重，腕部到位标准保持不变。

因此模型输出会改变发送给双臂的控制量，而不是只在视频上展示一次模型调用。报告中的 model_induced_command_distance_rad_seconds 记录加入提案后控制量的变化；非零值说明提案参与了控制，不单独代表精度提升。

本 Demo 的演奏目标坐标来自已知的仿真钢琴几何。G0.5 的优势重点是多模态动作接口与技能组合，本实验没有把琴键几何定位交给视觉模型。

4. 演奏中移琴

运行 README 中的连续实验，会依次执行：

阶段	操作
演奏	按原计划执行指法
抬手	释放琴键并抬高双手
移琴	场景控制器平移钢琴
恢复	新相机图像与关节状态送入 G0.5；双臂提案与 IK 联合对齐
落手	根据当前关节目标差计算交接时长，满足速度限制后接入新琴位轨迹
续弹	保留手指指令，按新位置执行手臂轨迹

--boundary 必须处于乐句休止处，不能切断还在持续的音；时间应对齐 50 Hz 控制步长。随附练习使用 4.5 秒。先从水平 2 厘米平移开始，不移动高度。

恢复求解直接包含关节运动范围与速度约束，避免求解后的单关节裁剪改变腕部对齐。落手时长根据关节目标差自动延长，曲谱暂停时间同步更新。

当前推理期间暂停仿真时钟；报告同时保留仿真时间与实际耗时。这样能先验证动作交接，后续可将模型调用改为异步并加入超时与保持状态。

5. 单独观察重新就位

bash"$SIM_PY" g05_recovery.py \
  --reference runs/public-physical --out runs/recovery-comparison \
  --modes ik_only g05_assisted --cases aligned \
  --piano-shift 0 0.06 0 --duration 1.6 --hover-height 0.04 --model-weight 0.5 \
  --g05-python "$G05_PY" --g05-repo "$G05_REPO" \
  --g05-models "$G05_MODELS" --g05-checkpoint "$G05_CHECKPOINT" \
  --g05-config-mode checkpoint --video

这是新实验命令，其结果以本机生成的报告为准。随附的历史 6 厘米实验使用另一份演奏初始状态，完整对照报告保留两种方法的结果。

6. 如何确认模型确实参与

检查输出目录和报告：

worker 记录实际模型仓库提交、检查点哈希和加载配置。
每次调用保存观测和输出记录，用于追溯新画面与动作。
会话报告记录新推理次数与提案引起的控制量变化。
恢复误差、接触记录、琴键事件和音频对应同一次执行。

对外可表述为：“G0.5 根据移琴后的新观测提出双臂调整动作，与 IK 和专用手指技能配合，实现重新就位与续弹。”