openpi π₀ 项目部署运行逻辑（一）——综述
π₀ model 目前部署方式可以从 官方 或者 lerobot 部署
两个方式部署的过程简单记个笔记
这一套笔记是基于官方的流程的
Github：GitHub - Physical-Intelligence/openpi
π₀ model：Our First Generalist Policy
π₀ paper：https://www.physicalintelligence.company/download/pi0.pdf
π₀-FAST model：FAST: Efficient Robot Action Tokenization
π₀-FAST paper：https://arxiv.org/pdf/2501.09747
目录
1 openpi 综述
2 运行要求
3 安装指南
4 模型检查点
4.1 基础模型 Base Models
4.2 微调模型 Fine-Tuned Models
5 预训练模型推理
6 自定义数据微调指南
6.1 数据格式转换
6.2 配置训练参数
6.3 启动策略服务器进行推理
6.4 更多示例
7 故障排除
1 openpi 综述
openpi 托管着由 Physical Intelligence team 发布的机器人开源模型与软件包
当前仓库包含两类核心模型：
-
the π₀ model - 基于流式扩散架构的视觉-语言-动作多模态模型（VLA）
-
the π₀-FAST model - 采用 FAST 动作分词器的自回归式VLA模型
两类模型均提供了 base model checkpoints（基于10k+小时机器人数据预训练），并包含开箱即用案例及自定义数据集微调示例
PS：π₀ 最初专为 PI 自有机器人平台开发（与 ALOHA/DROID 等常见平台存在差异）。虽然期待研究者能通过适配 π₀ 开展创新实验，但并非所有移植尝试都能成功。简而言之：π₀的实际效果可能因平台而异，但欢迎测试验证！
2 运行要求
要运行本仓库中的模型，需要配备符合以下最低规格的 NVIDIA GPU（单卡估算值）。通过配置训练参数中的 fsdp_devices，可使用多卡并行模式降低单卡显存需求。请注意：当前训练脚本暂不支持多节点训练
| 运行模式 | 显存需求 | 示例GPU型号 |
|---|---|---|
| 推理 | ≥ 8 GB | RTX 4090 |
| LoRA 微调 | ≥ 22.5 GB | RTX 4090 |
| 全参数微调 | ≥ 70 GB | A100 (80GB)/H100 |
本仓库已在 Ubuntu 22.04 系统完成测试，暂不支持其他操作系统
3 安装指南
克隆仓库时请同步更新子模块：
git clone --recurse-submodules git@github.com:Physical-Intelligence/openpi.git# Or if you already cloned the repo:
git submodule update --init --recursive使用 uv 管理Python依赖，参考 uv installation instructions 安装。安装 uv 后，运行以下命令配置环境：
GIT_LFS_SKIP_SMUDGE=1 uv sync
GIT_LFS_SKIP_SMUDGE=1 uv pip install -e .NOTE：GIT_LFS_SKIP_SMUDGE=1 用于拉取 LeRobot 作为依赖项
Docker方案：作为 uv 安装的替代方案，此项目提供了使用 Docker 安装 openpi 的指南。若系统环境配置遇到问题，建议使用Docker简化安装流程。详见 Docker Setup
4 模型检查点
4.1 基础模型 Base Models
此项目提供多个预训练 base VLA model checkpoints（基于10k+小时机器人数据训练），可用于微调：
| 模型 | 用途 | 描述 | 检查点路径 |
|---|---|---|---|
| π₀ | 微调 | 基础扩散式 π₀ model 模型 | s3://openpi-assets/checkpoints/pi0_base |
| π₀-FAST | 微调 | 基础自回归式 π₀-FAST model 模型 | s3://openpi-assets/checkpoints/pi0_fast_base |
4.2 微调模型 Fine-Tuned Models
我们针对不同机器人平台和任务提供了专家级检查点。这些模型基于上述基础模型微调而成，可直接在目标机器人上运行（适配性因平台而异）。由于这些 checkpoints 微调于 ALOHA、DROID Franka 等常见机器人平台的小规模数据集，其泛化能力可能受限。尽管部分 checkpoints（尤其是DROID checkpoints）在实践中展现出较强的跨场景适应能力
| 模型 | 用途 | 描述 | 检查点路径 |
|---|---|---|---|
| π₀-FAST-DROID | 推理 | 基于DROID dataset微调，可在DROID平台上零样本执行多种桌面操作任务 | s3://openpi-assets/checkpoints/pi0_fast_droid |
| π₀-DROID | 微调 | 基于DROID dataset微调，推理速度优于π₀-FAST-DROID，但指令跟随能力稍弱 | s3://openpi-assets/checkpoints/pi0_droid |
| π₀-ALOHA-towel | 推理 | 基于内部数据微调，可在ALOHA机器人平台上零样本完成多种毛巾折叠任务 | s3://openpi-assets/checkpoints/pi0_aloha_towel |
| π₀-ALOHA-tupperware | 推理 | 基于内部数据微调，可执行食品保鲜盒开盖操作 | s3://openpi-assets/checkpoints/pi0_aloha_tupperware |
| π₀-ALOHA-pen-uncap | 推理 | 基于public ALOHA data数据微调，可实现钢笔开盖动作 | s3://openpi-assets/checkpoints/pi0_aloha_pen_uncap |
默认下载路径：checkpoints 将自动从 s3://openpi-assets 下载并缓存至 ~/.cache/openpi。可通过设置 OPENPI_DATA_HOME 环境变量修改缓存路径
5 预训练模型推理
仅需几行代码即可运行预训练模型（以 π₀-FAST-DROID 为例）：
from openpi.training import config
from openpi.policies import policy_config
from openpi.shared import downloadconfig = config.get_config("pi0_fast_droid")
checkpoint_dir = download.maybe_download("s3://openpi-assets/checkpoints/pi0_fast_droid")# Create a trained policy.
policy = policy_config.create_trained_policy(config, checkpoint_dir)# Run inference on a dummy example.
example = {"observation/exterior_image_1_left": ...,"observation/wrist_image_left": ...,..."prompt": "pick up the fork"
}
action_chunk = policy.infer(example)["actions"]也可以在 example notebook 中测试
项目中提供了详细的分步示例，用于在 DROID 和 ALOHA 机器人上运行预训练检查点的推理
远程推理：该项目提供了远程运行模型推理的 examples and code：模型可以在不同的服务器上运行，并通过 websocket 连接将 actions 传输给机器人。这使得在机器人之外使用更强大的 GPUs 并实现机器人端与计算资源解耦
无机器人测试推理：该项目提供了一个脚本来测试没有机器人的推理。该脚本将生成一个随机观察值并使用模型运行推理，详见 here
6 自定义数据微调指南
接下来，以 π₀-FAST 模型在 Libero dataset 上的微调为例，演示如何在自己的数据集上微调一个 base model。分三步说明：
- 将数据格式转换为 LeRobot dataset (用于训练)
- 配置训练参数并训练
- 启动策略服务器并运行推理
6.1 数据格式转换
运行最小示例脚本 examples/libero/convert_libero_data_to_lerobot.py 将 Libero 数据转换为 LeRobot 格式（可适配其自己数据集）。可以从 here 下载原始 Libero 数据集，并运行：
uv run examples/libero/convert_libero_data_to_lerobot.py --data_dir /path/to/your/libero/data6.2 配置训练参数
如果根据自己的数据微调 base model，需要定义数据处理和训练的配置。此项目为 Libero 提供了带有详细注释的示例配置，可以根据自己的数据集进行适配：
- LiberoInputs and LiberoOutputs：定义从 Libero 环境到模型的数据映射，反之亦然。将用于训练和推理
- LeRobotLiberoDataConfig：定义如何处理 LeRobot 数据集中的原始 Libero 数据进行训练
- TrainConfig：定义微调超参数、数据配置和权重加载器
此项目为 π₀ 和 π₀-FAST 在 Libero 数据微调配置均提供了示例
在运行训练之前，需要计算训练数据的归一化统计量。修改为自己的训练配置名称并运行以下脚本：
uv run scripts/compute_norm_stats.py --config-name pi0_fast_libero现在，可以使用以下命令开始训练（如果使用相同的配置重新运行微调，则使用 --overwrite 标志覆盖现有检查点）：
XLA_PYTHON_CLIENT_MEM_FRACTION=0.9 uv run scripts/train.py pi0_fast_libero --exp-name=my_experiment --overwrite该命令将训练进度记录到控制台，并将检查点保存到 checkpoints 目录
可以在 Weights & Biases 仪表板上监控训练进度。为了最大限度地使用GPU内存，在运行训练之前设置 XLA_PYTHON_CLIENT_MEM_FRACTION=0.9 --这能使 JAX 使用高达90%的 GPU 内存（默认值为75%）。
Note：此项目提供了从预训练中重载 state / action 归一化统计量的功能。如果是对预训练数据中已有的机器人进行新任务微调，此功能可能有所帮助。有关重载归一化统计量的详细说明，请参阅 norm_stats.md
6.3 启动策略服务器进行推理
训练完成后，可以启动策略服务器来运行推理，然后通过 Libero 评估脚本进行查询。启动模型服务器非常简单（本示例使用第 20k 次迭代的检查点，请按需修改）：
uv run scripts/serve_policy.py policy:checkpoint --policy.config=pi0_fast_libero --policy.dir=checkpoints/pi0_fast_libero/my_experiment/20000这将启动一个监听 8000 端口的服务器，等待观测数据传入。随后即可运行 Libero 评估脚本向服务器发送查询。有关如何安装 Libero 并运行评估脚本的说明，请参阅 Libero README
若需在自己的机器人运行时嵌入策略服务器调用，在 remote inference docs 中提供了最小化实现示例
6.4 更多示例
此项目在以下 README 文档中提供了更多关于如何在 ALOHA 平台上进行模型微调和推理的示例：
- ALOHA Simulator
- ALOHA Real
- UR5
7 故障排除
此项目在此汇总常见问题及其解决方案。若遇到问题，请先查阅此处。如未能找到解决方案，请在代码仓库提交 issue（提交指南参见 here）
| 问题 | 解决方案 |
|---|---|
| uv sync 因依赖冲突失败 | 尝试删除虚拟环境目录（rm -rf .venv）后重新运行 uv sync。若问题仍存，请确保已安装最新版 uv（uv self update） |
| 训练时 GPU 内存不足 | 运行训练前设置 XLA_PYTHON_CLIENT_MEM_FRACTION=0.9 以允许 JAX 使用更多 GPU 内存，或尝试在训练配置中减小批处理大小 |
| 策略服务器连接错误 | 确认服务器已在预期端口运行并监听，检查客户端与服务器间的网络连通性及防火墙设置 |
| 训练时缺失归一化统计量 | 启动训练前先运行 scripts/compute_norm_stats.py 并指定配置文件名称 |
| 数据集下载失败 | 检查网络连接。若使用 local_files_only=True，请确认数据集已本地存在。对于 HuggingFace 数据集，需确保已登录（huggingface-cli login） |
| CUDA/GPU 相关错误 | 验证 NVIDIA 驱动和 CUDA 工具包安装正确。Docker 环境下需安装 nvidia-container-toolkit，并检查 GPU 兼容性 |
| 运行示例时导入错误 | 确保已通过 uv sync 安装所有依赖并激活虚拟环境，部分示例可能在 READMEs 中列有额外要求 |
| 动作维度不匹配 | 检查数据处理转换是否与机器人预期输入/输出维度一致，核对策略类中的动作空间定义 |