openpi 完整指南：5 分钟跑通 VLA 机器人模型推理，附微调全流程

openpi 完整指南：5 分钟跑通 VLA 机器人模型推理，附微调全流程

【免费下载链接】openpi项目地址: https://gitcode.com/GitHub_Trending/op/openpi

openpi 是 Physical Intelligence 开源的视觉-语言-动作（VLA）机器人模型库，内置 π₀、π₀-FAST、π₀.₅ 三个经过 10000+ 小时机器人数据预训练的模型。它解决的核心问题是：让你不必从零训练，就能在自己的机器人或仿真环境上直接推理，或用少量自有数据微调出一个听话的操纵策略。下文按"先跑通、再选型、后微调"的路径展开。

能力速览：openpi 能帮你做什么

• 无机器人验证模型：用 simple_client 示例 生成随机观察数据跑一遍完整推理链路，先确认环境和 GPU 没问题
• 真机部署：提供 DROID、ALOHA、UR5 等平台的端到端示例，模型跑在 GPU 服务器上，机器人侧只装一个轻量 client
• 从零微调：把自有数据转成 LeRobot 格式后，按官方配置模板微调 π₀ 系列基座模型，训练脚本与检查点管理开箱即用
• 远程推理：模型和机器人环境解耦，通过 WebSocket 流式下发动作块，方便用更强的服务器 GPU

最快上手路径：openpi 安装与首次运行

环境要求只有一个硬门槛：NVIDIA GPU 显存 > 8 GB（RTX 4090 即可推理），系统为 Ubuntu 22.04。依赖用 uv 管理，安装三步：

git clone --recurse-submodules https://gitcode.com/GitHub_Trending/op/openpi cd openpi GIT_LFS_SKIP_SMUDGE=1 uv sync GIT_LFS_SKIP_SMUDGE=1 uv pip install -e .

⚠️易错点：GIT_LFS_SKIP_SMUDGE=1不能省，它是 LeRobot 依赖正确拉取的前提；clone 时漏了--recurse-submodules的话，补一句git submodule update --init --recursive即可。

装完后不碰真机也能验证整条链路，开两个终端：

# 终端 1：启动策略服务器 uv run scripts/serve_policy.py --env DROID # 终端 2：发送随机观察并打印推理速率 uv run examples/simple_client/main.py --env DROID

如果终端 2 持续打印推理帧率，说明环境、GPU、检查点下载全部正常。

选型指南：三个模型怎么选

openpi 提供三族模型和一批专家检查点，按你的场景对号入座：

专家检查点（如 π₀-ALOHA-towel 叠毛巾、π₀-ALOHA-pupperware 开饭盒）是特定任务零样本示例，官方明说"不保证泛化到你的机器"，建议只当参考实现看。基座检查点首次使用时会自动从gs://openpi-assets下载到~/.cache/openpi。

实战演示：openpi 策略推理最小示例

下面用 π₀.₅-DROID 做一次完整推理，核心只有 5 行：

from openpi.training import config as _config from openpi.policies import policy_config from openpi.shared import download config = _config.get_config("pi05_droid") checkpoint_dir = download.maybe_download("gs://openpi-assets/checkpoints/pi05_droid") policy = policy_config.create_trained_policy(config, checkpoint_dir) example = { "observation/exterior_image_1_left": ..., # uint8 HWC image "observation/wrist_image_left": ..., "prompt": "pick up the fork", } action_chunk = policy.infer(example)["actions"] # shape: (horizon, action_dim)

关键参数说明：get_config的名字必须和检查点匹配（pi05_droid对应 π₀.₅-DROID，pi0_fast_droid对应 FAST 版），配错会因权重结构不符直接报错；prompt是唯一影响任务行为的输入，模型对场景布置、相机角度的容忍度较高，但对指令本身执行得较严格。完整可交互版本见 examples/inference.ipynb。

用自己的数据定制：从采集到上线三段式

第一步：数据准备（转 LeRobot 格式）

训练只认 LeRobot v2.0 数据集。以 LIBERO 为例：

uv run examples/libero/convert_libero_data_to_lerobot.py --data_dir /path/to/your/data

自有数据只需仿照 examples/libero/convert_libero_data_to_lerobot.py 或 ALOHA 版转换脚本改字段映射。

第二步：训练配置与启动

要写三个配置，都在 src/openpi/training/config.py 里有 LIBERO 模板：Inputs/Outputs类定义"环境 ↔ 模型"的张量映射，DataConfig定义原始数据处理，TrainConfig定义超参和权重加载。训练前必须先算归一化统计，再启动训练：

uv run scripts/compute_norm_stats.py --config-name pi05_libero XLA_PYTHON_CLIENT_MEM_FRACTION=0.9 uv run scripts/train.py pi05_libero --exp-name=my_experiment --overwrite

💡提示：如果你的机器人正好是预训练混合集里的平台（ALOHA、DROID、UR5e 等），可以在配置里加AssetsConfig直接加载预训练归一化统计，详见 docs/norm_stats.md。官方建议新旧两套统计各训一次，取效果好的那个。

第三步：部署上线

训练产出在checkpoints/目录，起一个策略服务器即可对外服务（默认监听 8000 端口）：

uv run scripts/serve_policy.py policy:checkpoint --policy.config=pi05_libero --policy.dir=checkpoints/pi05_libero/my_experiment/20000

之后机器人侧或评测脚本用openpi-client包里的WebsocketClientPolicy连上来发观察、收动作块即可，LIBERO 的完整评测可走 Docker 一键跑：examples/libero/README.md。

工程化选项：什么时候才需要这些

• PyTorch 后端：官方已提供 π₀ 和 π₀.₅ 的 PyTorch 实现（LIBERO 上验证过推理与微调），但暂不支持 π₀-FAST、LoRA、混合精度和 FSDP。只有当你的团队维护栈以 PyTorch 为主、或需要 torch.compile 生态时才切换，用examples/convert_jax_model_to_pytorch.py转一次检查点即可，API 与 JAX 版完全一致
• 远程推理：模型跑在服务器、机器人端只装轻量 client，是官方推荐架构（docs/remote_inference.md），DROID 这种控制端没大 GPU 的平台基本必用
• 多卡并行：JAX 训练配置里设fsdp_devices做全分片数据并行，用速度换显存，全参微调显存吃紧时才开；注意 JAX 训练暂不支持多节点，PyTorch 版可以用 torchrun 多节点
• Docker 部署：不想碰系统级 ROS 依赖时，用 docs/docker.md 里的 compose 文件一键起环境，首次构建较慢但后续有缓存

踩坑速查：常见问题与解法

更多细节（策略服务器连不上、动作维度不匹配等）在 README 的 Troubleshooting 一节 有完整表格。

下一步做什么

openpi 适合两类人：手里有 ALOHA/DROID/UR5 级别硬件、想把 VLA 策略落到真机的工程师，以及想在标准基准上复现或对比 VLA 模型的研究者。建议路径是先跑 simple_client 验证环境，再用 DROID 或 LIBERO 专家检查点体验零样本效果，最后按三段式流程微调自己的数据——如果你的平台不在官方支持列表里，UR5 示例（examples/ur5）是目前最完整的自定义接入参考。

【免费下载链接】openpi项目地址: https://gitcode.com/GitHub_Trending/op/openpi