openpi 机器人智能体 VLA模型完整指南

openpi 机器人智能体 VLA模型完整指南

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

openpi 是物理智能（Physical Intelligence）团队发布的开源机器人智能体项目，含三种 VLA（视觉-语言-动作）模型，经过 10,000+ 小时机器人数据预训练，支持开箱即用推理与自有数据集微调，适合机器人研究者与开发者。🚀

项目速览

这一步先搞清楚仓库里有什么：读完后你知道该选哪个模型、该下载哪类检查点。

三种模型 + 两档检查点：

• 基础检查点（3 个：pi0_base、pi0_fast_base、pi05_base）：经过 10,000+ 小时机器人数据预训练，作为微调起点。
• 专家检查点（7 个，如pi05_droid、pi0_fast_droid、pi05_libero、pi0_aloha_towel等）：针对特定机器人/任务微调，可直接在目标机器人上跑推理。
• 检查点默认自动从gs://openpi-assets下载并缓存到~/.cache/openpi，用OPENPI_DATA_HOME环境变量可改缓存位置。

快速上手

这一步解决"从拉代码到跑通首次推理"，完成后你会看到客户端终端不断打印推理速率，服务器在 8000 端口监听。

环境要求先核对一遍：

最短路径，四步：

1. 克隆仓库。--recurse-submodules用来同时拉取third_party/下 ALOHA、LIBERO 等第三方代码，漏了后续示例会报错：

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

2. 构建 Python 环境。GIT_LFS_SKIP_SMUDGE=1是为了正确拉取 LeRobot 这个依赖（跳过 LFS 大文件下载）：

   GIT_LFS_SKIP_SMUDGE=1 uv sync

3. 以可编辑模式安装 openpi 包本体：

   GIT_LFS_SKIP_SMUDGE=1 uv pip install -e .

4. 无机器人推理测试，开两个终端。--env DROID指定加载 DROID 预置检查点：
   • 终端 1：uv run examples/simple_client/main.py --env DROID（生成随机观察、打印推理速率）
   • 终端 2：uv run scripts/serve_policy.py --env DROID

系统环境实在理不顺时，可改用 Docker 安装，步骤见仓库docs/docker.md。

核心能力拆解

这一节把三种模型和检查点体系拆成四小块，看完选型不再纠结。

π₀：适合当微调底座的稳定款

• 一句话定位：flow-based VLA 模型，直接生成动作轨迹。
• 适用场景：在自己的机器人数据上微调；或直接用pi0_droid、pi0_aloha_towel等专家检查点跑实机。
• 与相近组件的区别：相比 π₀-FAST，推理更快，但官方提示语言指令跟随可能稍弱。

π₀-FAST：主打速度的自回归 VLA

• 一句话定位：基于 FAST 动作 tokenizer 的自回归 VLA，先把动作离散成 token 再逐个生成。
• 适用场景：DROID 桌面操作；pi0_fast_droid在新场景中可 0-shot 完成大范围简单桌面操作任务。
• 与相近组件的区别：语言跟随比 π₀ 好；但当前 PyTorch 版本尚未支持该模型，只能用 JAX 跑。

π₀.₅：面向开放世界泛化的升级版

• 一句话定位：π₀ 的升级版本，通过"知识绝缘"训练法减少对预训练分布的依赖，提升对新场景任务的泛化。
• 适用场景：pi05_libero在 LIBERO 基准上取得最先进成绩；pi05_droid在 DROID 平台上兼顾速度与语言跟随。
• 与相近组件的区别：本仓库中 π₀.₅ 的训练与推理目前只支持流匹配头，选型时注意这条限制。

检查点分档：基础档微调、专家档直接推理

• 一句话定位：基础档（3 个）面向微调，专家档（7 个）面向直接部署，共 10 个官方检查点。
• 适用场景：有自有数据集选基础档；想"先上实机看看"，优先试 DROID 系列——官方观察到其泛化相对广泛。
• 与相近组件的区别：专家检查点在较小数据集（ALOHA、DROID Franka 构型等）上微调，README 明确提示在你自己的平台上"可能有效也可能无效"。

一个例子走通全流程

这个例子不依赖真机，走"图像 + 语言输入 → 动作序列输出"的标准链路，跑通一次你就完全掌握推理接口长什么样。

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": ..., # 外部相机图像 "observation/wrist_image_left": ..., # 腕部相机图像 "prompt": "pick up the fork", # 语言指令 } action_chunk = policy.infer(example)["actions"]

白话解释：输入字典就是两路相机图像加一句指令；maybe_download首次运行时自动下载检查点并缓存，之后直接命中缓存；create_trained_policy一次性完成"加载配置 + 加载权重 + 搭建输入输出变换管线"。返回的action_chunk是形状为（动作步数, 动作维度）的序列，可逐步下发给机器人执行。仓库里还有可交互的 notebook 版本：examples/inference.ipynb。

进阶玩法

按四种最常见的使用场景组织，每条只给入口命令和一句说明。

想用自己的数据微调

以 LIBERO 为例的完整链路（换成你的数据，主要改 训练配置 里的数据映射）：

1. 把数据转成 LeRobot 格式，可参照转换脚本改：

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

2. 训练前先算归一化统计量（把状态/动作归一到可比范围，缺了会直接报错）：

   uv run scripts/compute_norm_stats.py --config-name pi05_libero

3. 启动训练。--overwrite允许重跑时覆盖同名旧检查点；前置的XLA_PYTHON_CLIENT_MEM_FRACTION=0.9让 JAX 最多用 90% 显存（默认 75%）：

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

4. 起策略服务器，默认监听 8000 端口：

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

若你的机器人恰好属于预训练覆盖的机型，可考虑直接复用预训练归一化统计量，细节见docs/norm_stats.md。

想部署到远程服务器

模型跑在大显存 GPU 上，经 WebSocket 把动作流回传机器人，两端环境彻底解耦：

uv run scripts/serve_policy.py --env DROID # 服务器端 cd packages/openpi-client && pip install -e . # 机器人端装轻量客户端

客户端如何构造观察、如何复用动作块（无需每步都请求模型），完整示例见 docs/remote_inference.md。

想从 JAX 切到 PyTorch

先转换检查点（推理 API 不变，只把检查点路径换成转换后的目录）：

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

注意两件事：其一，PyTorch 版目前不支持 π₀-FAST、混合精度、FSDP、LoRA 与 EMA 权重；其二，使用需先把src/openpi/models_pytorch/transformers_replace/下的补丁覆盖进 transformers 库，想完整回滚要执行uv cache clean transformers。多卡单节点训练示例：

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

想直接跑 LIBERO 基准

用官方 Docker 编排，一条命令同时拉起策略服务器与评测脚本：

SERVER_ARGS="--env LIBERO" docker compose -f examples/libero/compose.yml up --build

避坑速查

以下 5 个问题来自官方故障排查表，出现现象后直接对照解决列，多数情况不用再翻文档。

下一步建议：先用examples/simple_client走通无机器人推理，确认输入输出格式无误；再照 LIBERO 示例把自己数据集的微调流程跑一遍。若机器人端算力吃紧，就把模型挪到服务器，用远程推理方案回传动作。🎯

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