Instructions to use Fatpaper/motionforcing-piper-rtc with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Piper
How to use Fatpaper/motionforcing-piper-rtc with Piper:
# No code snippets available yet for this library. # To use this model, check the repository files and the library's documentation. # Want to help? PRs adding snippets are welcome at: # https://github.com/huggingface/huggingface.js
- Notebooks
- Google Colab
- Kaggle
Piper 双臂三任务:π₀.₅ 与 MotionForcing 推理权重(训练时 RTC)
本仓库提供 Piper 双臂真机部署用的推理权重,共三个任务,每个任务三个模型,都用训练时 RTC(training-time RTC)训练:训练时随机把动作 chunk 开头最多 15 步(50 步的 30%)换成干净的真实动作作为前缀,25% 的样本不带前缀。同一任务的三个模型用同一份示教数据,服务都走 openpi 的 websocket 协议,请求和返回的格式相同,真机客户端不用改,换端口即可。
| 任务目录 | 示教 | π₀.₅ 训练数据(LeRobot) | 默认指令 |
|---|---|---|---|
tidy_desk |
50 条 | HITdongdong/piper_dual_tidy_desk_ros2_shifted |
Tidy up the crumpled papers and pens on the desk. |
stack_cups |
100 条 | HITdongdong/piper_dual_stack_cups_ros2_shifted_master_gripper_100ep |
Stack_the_paper_cups_together. |
fold_towel |
100 条 | HITdongdong/piper_dual_fold_towel_ros2_shifted_master_gripper_100ep |
Fold_the_towel. |
- MotionForcing 的推理代码在 GitHub 仓库
Hong-yu-Zhang/motionforcing-piper-deploy。环境、接口、延迟等细节以那里的 README 为准。 - π₀.₅ 用公开的 SANE 代码加本仓库里的补丁起服务。
1. 内容
每个任务目录下有三个模型:
| 目录 | 模型 | 服务代码 |
|---|---|---|
pi05/29999 |
π₀.₅(3.35B),训练 30k 步 | SANE 加补丁 |
ours |
MotionForcing(2.52B),我们的模型 | motionforcing-piper-deploy |
jepa_pretrain |
MotionForcing(2.52B),同一结构,初始化不同 | motionforcing-piper-deploy |
pi05/29999/:params/(JAX/Orbax 推理权重,约 12 GB)、assets/HITdongdong/<数据集名>/norm_stats.json、_CHECKPOINT_METADATA。ours/、jepa_pretrain/:config.json和两个 safetensors 分片(约 5.8 GB,骨干为 bf16,动作专家为 fp32)、norm_stats.json(归一化统计量)、serve_config.json(相机顺序、输入分辨率、动作维度和默认指令)。config.json里的rtc_max_prefix: 15表示训练时前缀最长 15 步。pi05_sane/piper_training_rtc_3tasks.patch:π₀.₅ 训练时 RTC 的 SANE 补丁,包括三个任务的训练配置。checksums.sha256:除本 README 以外全部文件的校验值。
2. 下载与校验
全部约 72 GB,可以只下载需要的任务:
huggingface-cli download Fatpaper/motionforcing-piper-rtc --include "stack_cups/*" "pi05_sane/*" "checksums.sha256" \
--local-dir ~/piper_models/motionforcing-piper-rtc
cd ~/piper_models/motionforcing-piper-rtc && grep -E " (stack_cups|pi05_sane)/" checksums.sha256 | sha256sum -c
去掉 --include 就是下载全部,然后用 sha256sum -c checksums.sha256 校验。
3. 启动服务
π₀.₅ 需要先准备打过补丁的 SANE(环境安装见 SANE 的 README):
git clone https://github.com/Linux-2023/SANE.git && cd SANE
git checkout c9d724acd746dc521a748577ebe97ec1aa133f66
git apply ~/piper_models/motionforcing-piper-rtc/pi05_sane/piper_training_rtc_3tasks.patch
GIT_LFS_SKIP_SMUDGE=1 uv sync
以叠杯子为例,另外两个任务把目录和 π₀.₅ 配置名换掉即可:
M=~/piper_models/motionforcing-piper-rtc/stack_cups
# π₀.₅:在 SANE 根目录
uv run scripts/serve_policy.py --port 8000 policy:checkpoint \
--policy.config pi05_piper_dual_stack_cups_ros2_shifted_master_gripper_100ep_training_rtc \
--policy.dir "$M/pi05/29999"
# MotionForcing:在 motionforcing-piper-deploy 仓库根目录,按其 README 配好环境
python serve_policy.py --model-dir "$M/ours" --port 8001
python serve_policy.py --model-dir "$M/jepa_pretrain" --port 8002
| 任务目录 | π₀.₅ 配置名 |
|---|---|
tidy_desk |
pi05_piper_dual_tidy_desk_ros2_shifted_training_rtc |
stack_cups |
pi05_piper_dual_stack_cups_ros2_shifted_master_gripper_100ep_training_rtc |
fold_towel |
pi05_piper_dual_fold_towel_ros2_shifted_master_gripper_100ep_training_rtc |
请求包括:
state:14 维,左臂 6 个关节加夹爪,然后是右臂,原始单位;images:cam_high、cam_left_wrist、cam_right_wrist三路 CHW uint8 图像;prompt:可省略,省略时用上表的默认指令;rtc_obs:可省略,见第 4 节。
返回 actions(50 × 14,绝对关节角和夹爪目标,单位与 state 相同)。MotionForcing 三路相机缺一路会直接报错。
4. RTC 前缀
客户端可以用 openpi-client 的 ActionChunkBroker(use_rtc=True),它会在请求里带上 rtc_obs:prev_action 是上一段还没执行、已经对齐到新 chunk 的动作,d 是这次推理期间会执行掉的步数。
- MotionForcing:服务端把
prev_action的前d行当作干净前缀钉住,和训练时的做法一致。返回的actions前d行与发来的动作逐位相同,客户端从第d步开始执行。d必须在 0 到 15 之间,d = 0等同于普通请求。 - π₀.₅:SANE 的服务收到
rtc_obs时,用的是 SANE 原有的推理时 RTC(对前缀做 guidance,是软约束),返回的前d行接近但不保证等于发来的动作。补丁只改了训练,没有给 π₀.₅ 加硬前缀推理。
发布前做过离线检查:在示教数据的若干帧上给定真实前缀后,6 个 MotionForcing 模型在第 10–19 步的动作误差都明显下降(下降约 30%–43%),前缀和新生成部分的接缝处跳变与真实动作相当;没有用训练时 RTC 训练的旧模型给前缀后误差不下降。
5. 真机测试建议
- 安全:首次运行要在可以急停、有人值守的条件下进行,客户端保留关节速度和加速度限幅。返回的是绝对目标,第一步应该接近当前关节状态;如果偏差很大,通常是相机接反或关节顺序不对,这时不要执行。
- 对比方式:同一任务的三个模型在同一批随机摆放上测相同的次数,模型之间交替进行。三个模型的客户端设置保持一致(每个 chunk 执行多少步,同步还是异步请求,是否开 RTC 以及
d取多少),并在结果里注明。MotionForcing 每次推理比 π₀.₅ 多约 110–130 ms(GB300)。
6. 许可
- π₀.₅ 权重派生自 Physical Intelligence 的
pi05_base,须遵守其上游许可条款(包括 PaliGemma 涉及的 Gemma 条款)。 - MotionForcing 权重派生自
Alibaba-DAMO-Academy/RynnBrain-2B(Apache-2.0)。推理代码按 Apache-2.0 发布(见 GitHub 仓库的LICENSE)。 - SANE 补丁修改自 SANE / openpi 的代码,遵守其原有许可。
7. 版本
- MotionForcing 代码:
Hong-yu-Zhang/motionforcing-piper-deploy提交ac1ad1e2ba45e4e9a68832dd074eac1cae234de7。 - RynnBrain-2B:
ad71236d013ae5618833fded73a32569045a8e9e,首次启动时自动下载。 - π₀.₅ 代码:SANE
c9d724acd746dc521a748577ebe97ec1aa133f66,加pi05_sane/piper_training_rtc_3tasks.patch(sha256394df7a19047519451d2f277e40f0242749abffb8921eaef2ca7608bd898db25)。
- Downloads last month
- -