OpenPI：具身基础模型的开源微调框架¶

一句话定位：Physical Intelligence 开源的具身基础模型框架，提供预训练 VLA checkpoint 和配套微调管线，核心设计是 Mixture of Experts 双专家架构 + 三层 Transform 数据管线，将任意机器人数据映射到固定观测结构⁴。

模型架构：双专家 + 双动作头¶

Mixture of Experts 设计¶

π₀ 不是单一 Transformer，而是两个专家的混合¹：

两个专家共享 attention 但各自拥有独立的 FFN 权重。动作预测有专属参数容量，不被视觉/语言任务稀释——消融实验显示这比共享全部权重的标准 Transformer 效果更好。

三种模型变体¶

π₀ 和 π₀.₅ 通过 Flow Matching 从噪声逐步去噪出动作序列（action chunk，默认 50 步未来动作）；π₀-FAST 将连续动作离散化为 token 后自回归生成，省去多步采样。

数据管线：三层 Transform 架构¶

核心设计问题：不同机器人平台的数据 schema 千差万别，但模型需要固定格式的输入。解决方案是三层 Transform 管线，逐步将任意 LeRobot 数据映射到模型的固定观测结构：

flowchart LR
    A["LeRobot 原始数据<br/>schema 自由"] -->|"① RepackTransform<br/>key 重命名"| B["中间格式"]
    B -->|"② data_transforms<br/>XXXInputs 类"| C["固定观测结构"]
    C -->|"③ model_transforms<br/>自动处理"| D["模型输入"]

① RepackTransform — key 重命名¶

纯粹的 key 映射，将 LeRobot 返回的 feature name 重命名为下游 Inputs 类期望的格式。不同数据集的 LeRobot schema 不同，这一层吸收差异：

中间 key 的命名没有标准，各数据集配置各写各的——只要和下一层的 Inputs 类内部一致即可。

② data_transforms — 结构组装¶

每种机器人平台实现一个 XXXInputs 类，将重命名后的数据组装成模型的固定观测结构：

• 将多个图像字段嵌套到 image dict 的固定槽位
• 生成 image_mask（标记哪些摄像头有真实数据，缺失的用零数组 + False mask 填充）
• 图像格式转换（LeRobot 的 float32 CHW → 模型的 uint8 HWC）
• 拼接 state 向量（如将 joint_position + gripper_position 合并）

即使 LeRobot feature key 完全与模型一致，这一层仍不可省略——平铺 → 嵌套的结构转换和 image_mask 生成无法跳过。

③ model_transforms — 自动处理¶

框架自动执行，无需用户编写：

固定观测结构：位置即语义¶

OpenPI 将通用的四元组数据类型（图像、本体感知、动作、语言指令）映射到一组硬编码的固定槽位：

OpenPI 固定槽位¶

π₀-FAST 在 model_transforms 阶段额外生成 token_ar_mask（标记自回归 token）和 token_loss_mask（标记计入 loss 的 token），对原始数据无额外要求——三种模型接收完全相同的原始数据。

位置-语义绑定¶

模型不读 key 名字符串，而是按固定位置处理输入。10k+ 小时预训练中每个位置始终对应同一语义，模型权重中编码了这种绑定。微调时必须保持一致的数据路由——全局视角图像必须进入 base_0_rgb 槽位，腕部摄像头必须进入对应的 wrist 槽位，颠倒放置会导致预训练 prior 完全失效。

action_dim 与维度约定¶

action_dim（默认 32）是模型内部工作的向量维度。实际维度不足时自动零填充，推理时截取前 N 维。预训练中各维度的含义：

维度顺序和物理量类型（弧度 vs 米、关节空间 vs 笛卡尔空间、绝对 vs delta → 数据类型详解）需要与预训练保持一致。偏离越远，预训练 prior 帮助越有限。

归一化策略¶

训练前必须对 state/actions 做归一化。OpenPI 特有的设计：

• 模型间差异：π₀ 用 z-score，π₀.₅ / π₀-FAST 用分位数归一化（硬编码，由 model_type 决定）
• 复用预训练统计量：预训练提供了 9 种平台（ALOHA、DROID-Franka、UR5e 等）的 norm_stats.json，匹配的平台直接从 checkpoint assets 加载；新平台用 compute_norm_stats.py 重新计算
• 小数据集注意：分位数归一化在小数据集上可能裁切有效数据导致性能下降，此时可切换为 z-score

硬件需求¶

仅测试 Ubuntu 22.04。JAX 后端不支持多机训练；PyTorch 后端通过 torchrun 支持多机 DDP 但功能不完整（不支持 LoRA、FSDP、混合精度、EMA）。

参考资料¶