openpi 完整上手指南：从安装到微调，5 条命令跑通 VLA 模型

openpi 完整上手指南：从安装到微调，5 条命令跑通 VLA 模型

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

openpi 是 Physical Intelligence 团队开源的机器人智能体工具包，内置 π₀、π₀-FAST、π₀.₅ 三种 VLA（视觉-语言-动作）模型，基础检查点均用上万小时机器人数据预训练。你可以直接加载专家检查点做推理，也可以用自己的数据微调基础检查点，再通过 WebSocket 策略服务接上真机。本文按“安装 → 选模型 → 微调”的顺序走一遍。

一、openpi 能干什么：三个真实场景

openpi 不是一个单点 demo，而是一套从“数据 → 模型 → 机器人”的工具链。典型用法有三类：

• 自有机器人上跑推理，但机器人本体算力不够：把模型放到 GPU 服务器，动作经 WebSocket 流式传回机器人，机器人端只需轻量 openpi-client，两套环境天然隔离。客户端怎么嵌入，见 docs/remote_inference.md。
• 手头没机器人，只想验证链路：examples/simple_client 脚本会生成随机观察发给服务，并打印真实推理频率，方便压测。
• 想让模型学会你的任务：仓库自带 LIBERO 微调全流程示例，数据与配置换成自己的即可复用。

二、openpi 安装：uv 两条命令 + Docker 备选

系统要求是 Ubuntu 22.04（官方唯一测试过的系统）加一张 NVIDIA GPU。显存先对号入座：

模式	最低显存	参考显卡
推理	> 8 GB	RTX 4090
微调（LoRA）	> 22.5 GB	RTX 4090
全参微调	> 70 GB	A100 80GB / H100

原生路线分两步，克隆加 uv：

git clone --recurse-submodules https://gitcode.com/GitHub_Trending/op/openpi

GIT_LFS_SKIP_SMUDGE=1 uv sync GIT_LFS_SKIP_SMUDGE=1 uv pip install -e .

提示：第二条必须带GIT_LFS_SKIP_SMUDGE=1环境变量，否则拉 LeRobot（数据读取依赖）会报错；已有仓库时跑git submodule update --init --recursive补齐子模块。

系统配置卡壳时可切到官方 Docker 备选，还能绕开 ROS 安装：

docker compose -f scripts/docker/compose.yml up --build

Docker 的 rootless 模式、NVIDIA toolkit 等前置细节见 docs/docker.md。

三、检查点选型表：基础版微调，专家版推理

结论先行：base（基础）检查点拿来做微调，fine-tuned（专家）检查点直接推理。架构差异各一句话：

• π₀：流匹配（flow matching）头生成动作序列。
• π₀-FAST：基于 FAST 动作分词器自回归产出动作，推理更快。
• π₀.₅：π₀ 的升级版，用知识绝缘训练改善开放世界泛化；当前仓库对它的训练与推理仅支持流匹配头。

检查点会从gs://openpi-assets自动下载并缓存到~/.cache/openpi，可用OPENPI_DATA_HOME换缓存位置。选型表：

检查点	类别	用途	路径
π₀	基础	微调起点	gs://openpi-assets/checkpoints/pi0_base
π₀-FAST	基础	微调起点	gs://openpi-assets/checkpoints/pi0_fast_base
π₀.₅	基础	微调起点	gs://openpi-assets/checkpoints/pi05_base
π₀-FAST-DROID	专家	推理：桌面操作 0-shot 泛化好	gs://openpi-assets/checkpoints/pi0_fast_droid
π₀-DROID	专家	微调/推理：更快，但语言跟随弱一些	gs://openpi-assets/checkpoints/pi0_droid
π₀-ALOHA-towel / tupperware / pen-uncap	专家	推理：叠毛巾、开饭盒、拔笔盖	gs://openpi-assets/checkpoints/pi0_aloha_*
π₀.₅-LIBERO	专家	推理：LIBERO 基准 SOTA	gs://openpi-assets/checkpoints/pi05_libero
π₀.₅-DROID	专家	推理/微调：速度快且语言跟随好	gs://openpi-assets/checkpoints/pi05_droid

四、第一次推理：最小可运行代码

推理链路只有 3 步：拿配置、取检查点、建 policy 调infer：

from openpi.training import config as _config from openpi.policies import policy_config from openpi.shared import download

config = _config.get_config("pi05_droid") ckpt = download.maybe_download("gs://openpi-assets/checkpoints/pi05_droid") policy = policy_config.create_trained_policy(config, ckpt) actions = policy.infer(example)["actions"]

example是一个 dict：两张观察图（observation/exterior_image_1_left、observation/wrist_image_left）加一条语言指令prompt，完整版可对照 examples/inference.ipynb。

提示：openpi 部署时也可把模型放更强的 GPU 服务器，动作经 WebSocket 流式推给机器人，机器人端不用承担推理负载。

五、openpi 微调三步走：数据、训练、策略服务

以 LIBERO 示例链路为参照，自己的数据同样三步。

第一步，数据转换。把原始数据变成 LeRobot 数据集（openpi 训练用的数据格式）：

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

提示：只微调 LIBERO 的话这步可跳过，示例配置已指向转换好的数据集。

第二步，算归一化统计再训练。归一化统计把状态/动作各维度拉到标准区间，必须先算：

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

数据映射在 LiberoInputs / LiberoOutputs，超参、数据与权重加载在 TrainConfig，两处都要按自己的任务改。检查点落在checkpoints/目录；XLA_PYTHON_CLIENT_MEM_FRACTION=0.9让 JAX 用满 90% 显存（默认 75%）。

第三步，起策略服务。指向训练好的检查点（以 20,000 步为例）：

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

服务默认监听 8000 端口，机器人端或评测脚本把观察发过去即可拿到动作。

六、PyTorch 路线：检查点转换与多卡训练

2025 年 9 月起，openpi 提供 π₀ 与 π₀.₅ 的 PyTorch 版本，已在 LIBERO 上验证；暂不支持 π₀-FAST、混合精度、FSDP（全分片数据并行）、LoRA 和 EMA。

步骤 1，打 transformers 补丁（覆盖 .venv 里 3 个文件，支持 AdaRMS 等改动）：

cp -r ./src/openpi/models_pytorch/transformers_replace/* .venv/lib/python3.11/site-packages/transformers/

提示：uv 默认 hardlink 模式下改动会写进 uv 缓存并长期保留，彻底回滚执行uv cache clean transformers；动手前用uv pip show transformers确认版本是 4.53.2。

步骤 2，把 JAX 检查点转成 PyTorch 格式：

uv run examples/convert_jax_model_to_pytorch.py --checkpoint_dir /path/to/jax/checkpoint \ --config_name <config name> --output_path /path/to/pytorch/checkpoint

步骤 3，训练，单卡与多卡各一条命令：

uv run scripts/train_pytorch.py debug --exp_name pytorch_test

uv run torchrun --standalone --nnodes=1 --nproc_per_node=2 scripts/train_pytorch.py pi0_aloha_sim --exp_name pytorch_ddp_test

PyTorch 版与 JAX 共用同一套 API 和策略服务，检查点路径换成转换后的目录就行。

七、排错速查表：从症状到动作

卡住时先查表，再翻源码：

症状	动作
uv sync依赖冲突	删掉.venv重跑uv sync；仍不行先uv self update
训练 OOM	设XLA_PYTHON_CLIENT_MEM_FRACTION=0.9或更高；加--fsdp-devices <n>分片降显存；或关闭 EMA
策略服务连接失败	确认服务已起并监听 8000 端口；检查客户端与服务端之间的网络与防火墙
训练报 norm stats 缺失	先跑scripts/compute_norm_stats.py，配置名与训练一致
训练 loss 发散	查norm_stats.json里 q01 / q99 / std，个别维度数值过小会把归一化结果放大，手动修正该维度统计

结语

跑通 LIBERO 全流程后，下一步有两件事：把数据和配置换成自己的机器人平台，或者把模型放到更强的 GPU 上远程接真机。examples/aloha_sim、examples/aloha_real、examples/droid、examples/ur5各有一份分平台文档，按需挑一份对照执行即可。🚀

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