Pi05 + YAM 运行手册

本文覆盖 Pi05 模型、checkpoint、输入输出契约和配套启动命令。推理方法的原理、 完整参数和验证步骤归各自的方法文档，不在模型 runbook 重复维护。

放瓶子 step-30000

纯 joint 与 joint+EE 是两份不同的 checkpoint；即使都使用端口 8500，也不能混用 server 和 infra 配置。以下命令从仓库根目录执行，要求已安装 YAM / OpenPI 环境并准备 配置指定的 checkpoint 和相机。权重和本机设备配置不会随 README 命令自动安装。

纯 joint + RTC

完整的四终端启动命令集中在 使用指南： 相机 → RoboGUI → server/put-bottles/joint-step30000.yaml 模型服务 → infra/put-bottles/rtc-joint-step30000.yaml runtime。

该配对使用 pi05-yam-put-bottles-joint-step30000 权重，模型 horizon 为 50，轨迹点间隔 为 1/30 s，RTC 的 chunk_policy_steps 为 12。这不是将模型输出裁成 12 步： RTC 发起下一次推理后，仍会在等待响应时继续执行旧 chunk。

切换为 joint+EE

先停止旧模型 server 和当前 runtime，再将两条命令中的配置一起换为：

• server：manimux/configs/policy/pi05/yam/put-bottles/joint-ee-step30000.yaml；
• runtime：manimux/configs/experiments/put_bottles/pi05/yam_pi05_rtc_joint_ee_step30000.yaml。

两套 RTC 都显式引用 manimux/configs/embodiment/robot/yam_control.yaml， 与 YAM 数采共享硬件参数、动作间隔和运动限幅；执行器仍为 100 Hz Smooth、8 Hz 滤波。 公共配置当前不附加手臂速度/加速度限幅，夹爪保留 1.0 /s 的闭合目标限速，打开目标直接切换。 这不等于取消硬件保护，也不保证物理夹爪恰好一秒闭合。 详见 共享控制说明。其他历史配置不会自动继承这些设置。

遇到 policy backend identity mismatch，先检查端口上实际加载的模型与配置是否匹配， 不要删除 expected_backend 来绕过检查。只核对本地路径和契约、不启动服务时， 可在模型 server 命令中添加 --check。

本地红球任务 checkpoint

本次训练从官方 pi05_base 初始化，使用以下 20 条 YAM episode 微调：

/home/ubuntu/yam-abc-reproduce/data/episodes/pick_the_red_ball_up_and_place_it_into_the_box/

推理使用 step 1000 checkpoint 自带的同名 stats，不复用 Robocurve stats：

checkpoints/finetuned/ziyang/pi05-yam-pick-red-ball-box-b384/1000/
  params/
  assets/yam_pick_red_ball_box_v1/norm_stats.json

• server：manimux/configs/policy/pi05/yam/finetune-pick-red-ball-box-step1000.yaml；
• ManiMux：manimux/configs/experiments/pick_red_object/pi05/yam_pi05_manimux_step1000.yaml；
• 输入：三路独立 RGB、14 维 YAM state 和红球任务文本；
• 输出：50 x 14 absolute joint positions；
• 时间语义：轨迹点 30Hz，底层下发 100Hz；
• 起始位：episode 20260812_193716_0751770e 的第一帧，左右臂关节和夹爪逐值匹配；
• 当前证据：真实 checkpoint 的离线 GPU、XPolicy WebSocket、三相机、ManiMux 和双臂 YAM 真机链路均已通过。模型能明显复现示教轨迹，但20条练手数据质量有限，尚不能稳定 完成任务，因此记录为部署成功、policy质量有限，不记作任务成功率。

只检查路径与契约：

cd /home/ubuntu/manimux
XPolicyLab/policy/Pi_05/openpi/.venv/bin/python \
  manimux/servers/pi05.py --check \
  --config manimux/configs/policy/pi05/yam/finetune-pick-red-ball-box-step1000.yaml

离线 GPU forward 会用上述 episode 第一帧的 14 维状态，不连接相机、CAN 或机器人：

XLA_PYTHON_CLIENT_PREALLOCATE=false \
  XPolicyLab/policy/Pi_05/openpi/.venv/bin/python \
  scripts/validation/pi05_yam_offline_infer.py \
  --config manimux/configs/policy/pi05/yam/finetune-pick-red-ball-box-step1000.yaml \
  --infra-config manimux/configs/experiments/pick_red_object/pi05/yam_pi05_manimux_step1000.yaml

模型服务：

XPolicyLab/policy/Pi_05/openpi/.venv/bin/python \
  manimux/servers/pi05.py \
  --config manimux/configs/policy/pi05/yam/finetune-pick-red-ball-box-step1000.yaml

完成相机、CAN 和 preflight 检查后，真机 ManiMux 由操作者运行：

envs/yam/.venv/bin/manimux run \
  --config manimux/configs/experiments/pick_red_object/pi05/yam_pi05_manimux_step1000.yaml

螺丝刀 step-15000：七种算法、统一 Executor

这套配置使用同一份 step-15000 checkpoint、checkpoint-matched norm stats、任务文本、 三相机映射、起始位和 Recorder。模型原生输出均为 50 × 14 absolute joint actions， 轨迹点间隔 1/30 s。算法只改变采样、chunk 选择和调度，不切换底层 executor。

所有配置位于 manimux/configs/experiments/assemble_screwdriver/pi05/，文件名为 yam_pi05_<算法>_step15000.yaml（算法名称使用下划线）：

算法 / 文件名前缀	runtime	算法配置
manimux	manimux	single-inflight，剩余 0.4 s 发起补充推理，blend 4 步
rtc	rtc	最少执行 20 步，初始延迟 4 步，beta 9.1，blend 4 步
act-temporal-ensemble	act_temporal_ensemble	coefficient 0.01，每 20 个 policy 步（约 0.667 s）请求一次
aac	aac	20 个候选，motion threshold 0.2，backward beta 0.99
paint	paint	execution steps 12，初始延迟 10 步，延迟历史窗口 10
autohorizon	autohorizon	使用已接入的 JAX selector，由模型返回执行长度
dvac	dvac	tail 5，alpha 2.0，滚动窗口 5，执行长度 1–50

统一的底层设置为 executor.type: smooth、100 Hz 控制、8 Hz cutoff、关节速度上限 0.25 rad/s、加速度上限 0.5 rad/s²、绝对位置上限 3.14 rad；左右夹爪均为 连续 0–1，速度上限 1.0 /s、加速度上限 12.0 /s²。 这些设置和原有螺丝刀 ManiMux / RTC 一致。ACT、AAC、PAINT、AutoHorizon、DVAC 按各自 契约保留 blend_policy_steps: 0；blend 属于 Timeline 拼接，不是底层 SmoothExecutor 参数。

AAC 继续使用现有 yam_60ep_ee_increment.json 作为候选评分用 EE 增量统计； 它不是螺丝刀任务专门重新估计的统计，也不替换 checkpoint 的动作归一化文件。 各方法保留已有的冷启动 timeout，输出分别写入 data/experiments/pi05-assemble-screwdriver-step15000/<算法前缀>/。

2026-09-08 补齐 ACT、AAC、PAINT、AutoHorizon、DVAC 五份螺丝刀配置。 这表示复用现有算法实现并完成配置/单元回归，不代表新增的五种组合已在该 checkpoint 上 完成 GPU 或真机测试；既有算法的实测记录见下方方法文档。历史红球和 Robocurve 配置保留不变。

先在 /home/ubuntu/manimux 启动同一个 Pi05 policy server：

cd /home/ubuntu/manimux
XPolicyLab/policy/Pi_05/openpi/.venv/bin/python \
  manimux/servers/pi05.py \
  --config manimux/configs/policy/pi05/yam/finetune-assemble-screwdriver-step15000.yaml

模型服务无需随算法更换；在另一终端选择一种 runtime，例如 PAINT：

cd /home/ubuntu/manimux
envs/yam/.venv/bin/manimux serve \
  --config manimux/configs/experiments/assemble_screwdriver/pi05/yam_pi05_paint_step15000.yaml

替换文件名前缀即可选择表中的其他算法，例如 RTC：

cd /home/ubuntu/manimux
envs/yam/.venv/bin/manimux serve \
  --config manimux/configs/experiments/assemble_screwdriver/pi05/yam_pi05_rtc_step15000.yaml

七种 runtime 选择一种运行，共用上面的同一个 policy server。

Pi05 上的训练免推理方法由方法文档单独维护：

• ACT temporal ensemble：act-temporal-ensemble.md；
• AAC：reproductions/aac-pi05.md；
• PAINT：reproductions/paint-pi05.md；
• AutoHorizon：reproductions/autohorizon-pi05.md。
• DVAC：reproductions/dvac-pi05.md。 先用 scripts/validation/xpolicylab_yam_dvac_probe.py --requests 3 验证同一 session 内的滚动阈值， 再决定是否开放真机命令。

以下章节记录先前 Robocurve 16-step checkpoint 的独立实验，不要与本地 50-step 配置混用。

Robocurve 模型

YAM 微调权重位于：

checkpoints/finetuned/robocurve/pi05-yam-molmoact2/  # robocurve/pi05-yam-molmoact2
  params/
  assets/yam-bimanual-merged/norm_stats.json

• 输入：base、left wrist、right wrist 三路独立 RGB，不拼成一张图；
• state：14 维，左 6+1 后右 6+1；
• 输出：16 x 14 absolute joint positions，30Hz；
• flow sampling：OpenPI 默认 10 steps；
• stats：checkpoint 自带 quantile norm stats；
• 发布来源：robocurve/pi05-yam-molmoact2；
• server：manimux/configs/policy/pi05/yam/finetune.yaml；
• ManiMux 30Hz 默认配置：manimux/configs/experiments/pick_red_object/pi05/yam_pi05_manimux.yaml；
• Pi-guided RTC 对照：manimux/configs/experiments/pick_red_object/pi05/yam_pi05_rtc.yaml；
• 50ms 拉伸时序对照：manimux/configs/experiments/pick_red_object/pi05/yam_pi05_stretched_50ms.yaml。

当前验证状态

已完成一次不连接硬件的真实 checkpoint GPU forward，输出为 finite 的 16 x 14 absolute joint actions。2026-08-20 又完成了一次真实 YAM rollout：操作者观察到策略明确朝 pick 任务执行，但旧实验配置的 0.20 rad/s、0.40 rad/s² 低速包络造成慢速追赶和抖动， 因此这次不能记作成功率。

该 episode 位于：

data/archive/pre-campaign-20260824/root-runs/run-20260820T061701Z-8cfd2e00/episode-6bcee9a699eb/

记录中 143 次推理提交、141 个 plan 接受，常见 stale-prefix 只有 2–3 步，说明 16-step horizon 没有被推理延迟耗尽。当前 ManiMux infra 配置使用共享的 smooth executor 参数：8Hz cutoff、0.25 rad/s、0.5 rad/s²。Pi05 只保留模型契约要求的 30Hz 和 16-step horizon。这些是执行器 跟踪上限，不是模型动作好坏的阈值判定。

1. 离线检查

只检查路径和契约，不加载模型：

cd /home/ubuntu/manimux
XPolicyLab/policy/Pi_05/openpi/.venv/bin/python \
  manimux/servers/pi05.py --check \
  --config manimux/configs/policy/pi05/yam/finetune.yaml

只做合成三相机 observation 的 GPU forward，不启动服务或机器人：

XLA_PYTHON_CLIENT_PREALLOCATE=false \
  XPolicyLab/policy/Pi_05/openpi/.venv/bin/python \
  scripts/validation/pi05_yam_offline_infer.py \
  --config manimux/configs/policy/pi05/yam/finetune.yaml

2. 模型服务

cd /home/ubuntu/manimux
XPolicyLab/policy/Pi_05/openpi/.venv/bin/python \
  manimux/servers/pi05.py \
  --config manimux/configs/policy/pi05/yam/finetune.yaml

终端保持前台没有持续日志是正常的。确认 ready：

ss -ltnp | rg ':8500'
nvidia-smi

必须看到 127.0.0.1:8500 处于 LISTEN。

3. 相机与 RoboGUI

相机服务：

cd /home/ubuntu/manimux
envs/yam/.venv/bin/manimux-camera-server --config manimux/configs/embodiment/sensor/cameras/realsense_3_views.yaml

已有 5555 服务时不要重复启动。RoboGUI 可选：

envs/yam/.venv/bin/manimux-viewer --robot yam --host 0.0.0.0 --port 8086

4. Preflight

读取真实三相机和当前关节并推理，但显式禁止 start-position 和退出回 Home，也不发送 模型动作：

cd /home/ubuntu/manimux
envs/yam/.venv/bin/python scripts/validation/pi05_base_yam_preflight.py \
  --config manimux/configs/experiments/pick_red_object/pi05/yam_pi05_manimux.yaml

保存它打印的 measured state、first action、shape、gripper range 和 steady latency。脚本只 报告契约，不给主观 safe_for_live 结论。

5. 真机 runtime

清空工作区、急停在手，并确认两路 CAN 都是 ERROR-ACTIVE：

for c in can_left can_right; do
  ip -details link show "$c" | grep -o 'ERROR-ACTIVE\|ERROR-PASSIVE\|BUS-OFF'
done

默认 ManiMux 实验保留 Pi05-YAM checkpoint 的 30Hz 时序：

cd /home/ubuntu/manimux
envs/yam/.venv/bin/manimux run --config manimux/configs/experiments/pick_red_object/pi05/yam_pi05_manimux.yaml

这个 ManiMux 基线将 16 个绝对关节点按约 0.50 秒执行。机器人控制环也是 30Hz，避免 改变 checkpoint 学到的时间语义；异步调度、Timeline、SmoothExecutor 和记录仍由 ManiMux 负责。

50ms 拉伸对照把同一组点按约 0.75 秒执行：

envs/yam/.venv/bin/manimux run --config manimux/configs/experiments/pick_red_object/pi05/yam_pi05_stretched_50ms.yaml

两份配置是独立对照实验，不要同时运行。2026-08-20 的 50ms 真实运行中，模型请求和 plan 接受都正常，但 replanning 明显变慢，操作者观察到“向前抖一下又回来”；因此 50ms 只保留为失败对照，不再作为默认真机配置。

连接后先用 3.5 秒移动到 YAML start pose，这不是模型动作。当前执行器比第一次真实 rollout 快很多；第一次使用新参数只做短 rollout，并始终准备急停。

Chunk 边界诊断

普通 runtime 会在每个新 plan 接受时写一条 plan_boundary 到 episode 的 events.jsonl。它同时保存模型原始 chunk 首点、ManiMux 拼接后的首点、上一条命令和实测 关节；只增加诊断记录，不改变动作、速度或拼接算法。即使按 Ctrl-C，记录也会保留在 .partial episode 中。

完成两种待比较 policy 的短 rollout 后，分析端会自动选择不同 policy 最新的有效 episode。 也可以通过 --episode 明确指定记录，或手动离线查看：

cd /home/ubuntu/manimux
envs/yam/.venv/bin/python scripts/validation/analyze_chunk_boundaries.py

Pi05 YAM finetune + RTC

当前 step-1000 红球入盒实验仍使用同一个 finetune 配置，不需要启动第二份权重：

cd /home/ubuntu/manimux
XPolicyLab/policy/Pi_05/openpi/.venv/bin/python \
  manimux/servers/pi05.py \
  --config manimux/configs/policy/pi05/yam/finetune-pick-red-ball-box-step1000.yaml

RTC 使用独立 infra 配置。重复评测时启动一次长期 session service：

envs/yam/.venv/bin/manimux serve \
  --config manimux/configs/experiments/pick_red_object/pi05/yam_pi05_rtc_step1000.yaml

它与 step-1000 Default config 使用相同的 50 x 14 checkpoint contract、100Hz robot loop、 30Hz policy points、0.25 rad/s、0.50 rad/s² 和 3 秒 start/home。RTC pilot 使用 min_execute_policy_steps: 20、initial_delay_policy_steps: 4、beta: 9.1；运行时会根据真实 round trip 更新 delay forecast。只有 RTC scheduling 和 Pi-guided denoise condition 发生变化。

每次运行创建：

data/experiments/pi05-red-ball-box-step1000/rtc/session-*/rollout-*/

RoboGUI 在 episode 正常落盘后开放 Task result、failure tags 和 note， 保存到 rollout-*/evaluation/human-label.json。这里的 task result 与 result.json 中表示 runtime 正常收尾的 success 完全分开。

RoboGUI 通过 Prepare normal / Prepare experiment 选择模式：普通模式不显示评分步骤；实验模式结束后， 可以保存人工评测，也可以直接点击 Skip evaluation 进入下一条。跳过不会生成评分文件。 正式实验在 Top 参考布局选择 Task 和位置 01–10，并选择 Experiment repeat=1/2/3。 Prepare 固定位置、重复次数和参考图路径/hash；页面中的 task command 会真实发送给 Pi05，不只是显示文本。

serve 不加载模型、不启动相机，也不替代 RoboGUI。用户先分别启动 camera server、Pi05 model server 和 manimux-viewer，再启动一次 serve。RoboGUI 显示 service ready 后：

1. 确认 task；正式实验再选择参考图和重复次数。
2. 点击 Prepare normal rollout 或 Prepare experiment rollout；ManiMux 创建全新 episode、连接机器人并移动到 start pose。
3. 等待页面显示 PAUSED，确认真机后点击 Start rollout。
4. 需要保持当前位置时点击 Pause / Hold，随后使用 Resume rollout 继续。
5. 完成或失败后点击 Finish & Home；等待 Recorder 落盘和机器人 Home。
6. 实验模式 ON 时填写并保存人工评测；service 回到 idle 后点击下一次 Prepare new rollout。

每条正式 config 以 10Hz 异步保存各相机 MP4；编码不会阻塞控制环。结束后检查 videos/index.json 的 dropped_bundles 和 error。完整证据目录见 experiment infrastructure。

每条 episode 都创建新的 worker session，并重置 Timeline、RTC delay history、Executor、Recorder 和 RoboGUI trail；不会继承上一条 rollout 的推理状态。camera/model/viewer/service 进程保持运行。

只需要单条 rollout 或用于脚本兼容时，原 CLI 入口仍保留：

envs/yam/.venv/bin/manimux run \
  --config manimux/configs/experiments/pick_red_object/pi05/yam_pi05_rtc_step1000.yaml

停止

单次 run 在前台按一次 Ctrl-C，等待 Home 并退出。长期 serve 应先在 RoboGUI 完成当前 rollout；回到 service idle 后，再在 serve 终端按 Ctrl-C。随后才停止 RoboGUI、模型和相机。 不要使用模糊 pkill。

Pi05 base + RTC

base zero-shot 是单独实验：

server: manimux/configs/policy/pi05/yam/base.yaml
infra:  manimux/configs/experiments/pick_red_object/pi05/yam_pi05_base_rtc.yaml

它使用 50-step Pi-guided RTC，不代表 YAM 微调版的默认配置。不要用 base config 覆盖本文 的 16-step checkpoint 实验。base 权重仍位于 checkpoints/pretrained/pi05/pi05_base；它只 复用 Robocurve YAM checkpoint 内的 norm stats，因此配置会分别打印 checkpoint_source 和 norm_stats_source。