# Physical Intelligence openpi（π0 / π0-FAST）自有遥操作数据微调与真机推理指南

> 原文链接：https://robotics.hellobike.com/tutorials/openpi-pi0-finetune-franka-aloha-guide
> 频道：tutorials | 更新日期：2026-10-14 | 标签：OpenPI, π0, 微调, Franka
> 核心摘要：克隆 openpi、准备多相机 HDF5/LeRobot 数据、启动 π0-FAST 微调并在 Franka 类臂上跑推理节点的最小命令路径。

openpi 的 π0 系列面向多模态动作 chunk 预测，微调阶段最耗时间的是数据对齐而非反向传播本身。本指南以桌面操作、单 FR3 加两路以上固定相机为例；若你使用 ALOHA 双机，请直接 fork 官方 aloha config，不要混用关节索引。

# 环境

```bash
git clone https://github.com/Physical-Intelligence/openpi.git
cd openpi
python -m venv .venv && source .venv/bin/activate
pip install -e .
```

CUDA 与 JAX/PyTorch 版本以仓库 `pyproject.toml` 为准。凭证用 Hugging Face CLI 登录，勿写入 shell 脚本或 Markdown。openpi 同时依赖图像预处理与动作归一化统计量，第一次训练前务必跑通官方提供的 stats 计算脚本，否则真机推理会出现夹爪一直全开或关节饱和。FR3 与 ALOHA 的关节顺序不同，转换数据时不要只改名字而不改 axis 符号。

## 数据布局

openpi 期望多路 RGB + 低维 proprio + action 序列。若数据来自 LeRobot，先按仓库 `examples/aloha` 转换脚本生成 shard。检查相机时间戳对齐，误差应小于单帧间隔一半。每段 episode 建议 8–20 秒，太短会导致 π0 学不到接触相位，太长则 GPU 内存爆。相机固定曝光，避免自动增益导致 sim2real 色偏。proprio 至少包含关节角与夹爪宽度；若有力矩读数可一并写入，但要在 config 里声明维度。数据集切 train/val 按 episode 分，不要随机帧级拆分，否则相邻帧泄漏会虚高验证指标。

## 微调 π0-FAST

```bash
python scripts/train.py \
  --config pi0_fast_aloha \
  --exp_name my_fr3_pick \
  --data_dir ./data/shards
```

监控 loss 与 action MSE；过拟合时可减步数或加 dropout（见 config 注释）。π0-FAST 相对完整 π0 训练更快，但对外参敏感的桌面任务仍建议至少 20k step。保存 checkpoint 时记录 config 哈希与 stats 路径，部署时必须成对加载。多卡训练按 README 设置环境变量，单卡 24GB 通常需减 batch 或启用 gradient checkpoint。

## 真机推理

```bash
python scripts/serve_policy.py \
  --checkpoint checkpoints/my_fr3_pick \
  --port 8000
```

Franka 侧独立进程订阅观测、POST 到本地 serve 端点，再将返回关节增量经速率限制写入 `libfranka` 接口。首次运行降低速度缩放系数，工作空间限位保持开启。

排障：推理延迟高时减输入分辨率；夹爪通道需与训练归一化一致。若机械臂抖动，先查控制频率是否低于 30Hz，再查 action 是否被重复积分。FR3 碰撞检测触发后需人工复位，推理 loop 应监听错误状态并自动 pause。与 ROS 2 集成时，用独立线程收相机，避免 DDS 回调阻塞 HTTP 推理。记录一次 bag 对比训练集首帧与真机首帧的像素分布，差异过大时优先做颜色增广再微调，而不是盲目加大模型。

## 评估与安全收尾

离线用 held-out episode 算 action L1 只是下限，真机至少做十次起停，观察有无漂移累积。Franka 的 reflex 触发后，策略输出应立即切断并在 UI 提示复位。把 stats、config、checkpoint 路径写入实验日志，方便复现。若计划换相机镜头，重新标定外参并重算 stats，否则 π0 会把旧内参 bias 学进权重。完成评估后再提高速度缩放，每次只改 10%，避免一次拉满导致撞击。长期维护时，把 LeRobot 数据集版本号与 openpi commit 写进同一 metadata 文件，否则半年后很难解释某次成功率下降是否来自数据漂移。上线前用同一 checkpoint 在仿真渲染器里跑一遍，可快速排除坐标系符号错误。仿真通过后再接真机，成功率通常高一截。

## 原始参考来源 (Sources)

- [openpi](https://github.com/Physical-Intelligence/openpi)
- [libfranka](https://frankaemika.github.io/docs/)