Pi0 与 Pi0.5 模型微调：基于 OpenPI 的官方工作流
Pi0 和 Pi0.5 是由 Physical Intelligence 开发的视觉-语言-动作（VLA）模型。如果你正打算使用艾欧数据平台导出的数据来微调这些模型，本指南将带你走通基于官方 OpenPI 框架的完整流程。
为什么选择 OpenPI 而不是 LeRobot 框架？
虽然 LeRobot 支持 Pi0 等多个主流模型，但对于 Pi0 系列，我们强烈建议使用 OpenPI 官方提供的训练框架。
它基于 JAX 开发，原生支持多卡高性能训练，能够更好地发挥 Pi0 的潜力。
1. 准备工作：导出与放置数据
首先，我们需要在艾欧平台将标注好的数据转换为 OpenPI 能够识别的格式。
导出流程
- 格式选择：在导出页面，选择 LeRobot v2.1 标准格式。
- 本地解压：下载生成的
.tar.gz文件并解压。 - 目录规范：为了让 OpenPI 顺利找到数据，请将其移动到 Hugging Face 的本地缓存目录。例如：
# 准备目录
mkdir -p ~/.cache/huggingface/lerobot/local/mylerobot
# 将解压出的文件（包含 meta.json, data/ 等）移入
mv /path/to/extracted/data/* ~/.cache/huggingface/lerobot/local/mylerobot/
字段映射参考（以 Aloha 三相机为例）
在后续的配置中，你需要确保代码中的 Key 与数据中的字段对齐。默认情况下，我们建议使用：
cam_high: 顶部视角cam_left_wrist: 左手腕视角cam_right_wrist: 右手腕视角state: 机器人当前状态action: 目标动作（注意：ALOHA 在 OpenPI 默认配置中为 14 维，如果你的数据维度不同，请务必参考下方的“深度排坑”部分）。
2. 核心：如何选择合适的训练配置？
OpenPI 的训练逻辑是高度模板化的。选择配置时，本质上是在选择一个“最接近你机器人”的策略模板，然后对其进行微调。
| 你的需求场景 | 推荐路径 | 关注重点 |
|---|---|---|
| 快速验证 / 链路调通 | 仿真路径 (LIBERO / ALOHA Sim) | 重点在于 Inputs/Outputs 的快速对齐，成本最低。 |
| 实机部署 (双臂 Aloha) | ALOHA Real | 必须对齐相机 Key、动作维度以及夹爪的控制逻辑。 |
| 单臂 / 工业机器人 | 参考 UR5 示例 | 优先解决控制接口的兼容性，再考虑训练效果。 |
| 追求极致泛化 | 基于 DROID 数据对齐 | 学习 DROID 的归一化 (Norm Stats) 策略。 |
简单来说： 如果你是第一次跑，先用仿真配置调通流程；如果要上机，选 ALOHA Real 并严格对齐 state/action 维度。
技术排坑：关于 14 维 vs 16 维动作向量
这是一个非常容易被忽视的“坑”。OpenPI 的默认 ALOHA 策略（aloha_policy.py）硬编码了 14 维 结构：
- 默认结构：
[左臂6关节, 左夹爪1, 右臂6关节, 右夹爪1]= 14 维。 - 常见问题：如果你使用的是 7 轴机械臂（如
[7, 1, 7, 1]），总维度会变成 16。此时如果不修改代码，多出的维度会被静默截断，导致训练出的模型完全无法控制最后两个关节。
修改建议：
- 检查你的
action向量定义。 - 在
aloha_policy.py中，将所有的:14切片改为你的实际维度（如:16）。 - 同步修改
_joint_flip_mask的长度，确保正负号反转逻辑与你的硬件一致。
3. 编写训练配置
现在，我们需要在 openpi/src/openpi/training/config.py 中定义你的微调任务。
# 示例：为你的机器人添加自定义配置
TrainConfig(
name="pi0_aloha_mylerobot",
model=pi0_config.Pi0Config(),
data=LeRobotAlohaDataConfig(
repo_id="local/mylerobot", # 指向之前放置数据的目录
assets=AssetsConfig(
assets_dir="/home/user/code/openpi/assets/pi0_aloha_mylerobot",
),
default_prompt="fold the clothes", # 任务描述，非常重要
repack_transforms=_transforms.Group(
inputs=[
_transforms.RepackTransform(
{
"images": {
"cam_high": "observation.images.cam_high",
"cam_left_wrist": "observation.images.cam_left_wrist",
"cam_right_wrist": "observation.images.cam_right_wrist",
},
"state": "observation.state",
"actions": "action",
}
)
]
),
),
weight_loader=weight_loaders.CheckpointWeightLoader("gs://openpi-assets/checkpoints/pi0_base/params"),
num_train_steps=20_000,
)
4. 开始训练：计算统计信息与运行
在启动训练前，务必执行归一化统计。否则，模型接收到的数值范围会混乱。
第一步：计算 Norm Stats
uv run scripts/compute_norm_stats.py --config-name pi0_aloha_mylerobot
第二步：启动微调
我们推荐使用 JAX 模式以获得最高性能。
单卡模式：
export XLA_PYTHON_CLIENT_MEM_FRACTION=0.9
CUDA_VISIBLE_DEVICES=0 uv run scripts/train.py pi0_aloha_mylerobot \
--exp-name=my_first_experiment \
--overwrite
多卡并行 (FSDP)：
uv run scripts/train.py pi0_aloha_mylerobot --exp-name=multi_gpu_run --fsdp-devices 4
5. 推理与部署
微调完成后，你可以启动策略服务器，让机器人“跑起来”。
# 启动推理服务器，默认端口 8000
uv run scripts/serve_policy.py policy:checkpoint \
--policy.config=pi0_aloha_mylerobot \
--policy.dir=experiments/my_first_experiment/checkpoints/last
6. 常见问题排查 (FAQ)
- Q: 显存炸了 (OOM)？
- 调小
batch_size，或者确认XLA_PYTHON_CLIENT_MEM_FRACTION是否设置正确。多卡 FSDP 也是缓解显存压力的有效手段。
- 调小
- Q: 模型动作很诡异，或者关节完全不动？
- 检查
RepackTransform的映射是否正确。 - 强烈建议回头看上方的 14 维 vs 16 维 深度排坑部分，检查维度是否被静默截断。
- 检查
- Q: 训练 Loss 根本不降？
- 检查
default_prompt是否准确。 - 确认
compute_norm_stats生成的统计文件是否生效。
- 检查