# openpi：在 LIBERO 上准备 π0 / π0-FAST 微调基座并评估

> 原文链接：https://robotics.hellobike.com/tutorials/openpi-pi0-libero-finetune
> 频道：tutorials | 更新日期：2026-10-22 | 标签：openpi, LIBERO, π0, π0-FAST, Docker, 机器人微调
> 核心摘要：本文按 openpi 与 LIBERO 示例整理可执行流程：完成仓库与依赖安装，确认 π0 / π0-FAST 微调基座 checkpoint，使用 Docker 或本地环境启动 LIBERO 评估，并加载自定义 checkpoint 与任务套件。

# openpi：在 LIBERO 上准备 π0 / π0-FAST 微调基座并评估

> 本文依据以下官方文档整理：[raw.githubusercontent.com/Physical-Intelligence/openpi/main/](https://raw.githubusercontent.com/Physical-Intelligence/openpi/main/README.md)、[raw.githubusercontent.com/Physical-Intelligence/openpi/main/](https://raw.githubusercontent.com/Physical-Intelligence/openpi/main/examples/libero/README.md)。命令与版本以文档当前版本为准。

## 前置条件

- NVIDIA GPU：Inference 需要 > 8 GB，Fine-Tuning (LoRA) 需要 > 22.5 GB，Fine-Tuning (Full) 需要 > 70 GB
- 系统：Ubuntu 22.04；文档说明当前不支持其他操作系统
- 已安装 uv，用于管理 Python dependencies
- 仓库子模块已初始化；LIBERO 示例要求 git submodules initialized
- 推荐使用 Docker 运行 LIBERO 示例

## 1. 克隆 openpi 并初始化子模块

openpi 克隆时需要带上 submodules；如果已经克隆过仓库，则在仓库内执行子模块初始化命令。LIBERO 示例也明确要求初始化 git submodules。

```bash
git clone --recurse-submodules git@github.com:Physical-Intelligence/openpi.git

## Or if you already cloned the repo:
git submodule update --init --recursive
```

## 2. 安装 openpi Python 环境

openpi 使用 uv 管理 Python dependencies。uv 安装完成后，在仓库中同步依赖并以 editable 方式安装。文档说明 `GIT_LFS_SKIP_SMUDGE=1` 是拉取 LeRobot dependency 所需。

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

## 3. 确认 π0 / π0-FAST 微调基座

文档提供可用于 fine-tuning 的 base VLA model checkpoints：π0 对应 `gs://openpi-assets/checkpoints/pi0_base`，π0-FAST 对应 `gs://openpi-assets/checkpoints/pi0_fast_base`。这些 checkpoints 已在 10k+ hours of robot data 上预训练，可作为微调起点。

## 4. 用 Docker 启动 LIBERO 评估

LIBERO 示例推荐 Docker。先授予 Docker 访问 X11 server 的权限，再用默认 checkpoint 和 task suite 启动。若 Mujoco 出现 egl errors，文档给出 glx 启动方式。

```bash
## Grant access to the X11 server:
sudo xhost +local:docker

## To run with the default checkpoint and task suite:
SERVER_ARGS="--env LIBERO" docker compose -f examples/libero/compose.yml up --build

## To run with glx for Mujoco instead (use this if you have egl errors):
MUJOCO_GL=glx SERVER_ARGS="--env LIBERO" docker compose -f examples/libero/compose.yml up --build
```

## 5. 加载自定义 checkpoint 或切换任务套件

可通过额外的 `SERVER_ARGS` 自定义加载的 checkpoint，通过额外的 `CLIENT_ARGS` 设置 LIBERO task suite。示例要求 custom checkpoint 位于 top-level `openpi/` directory。

```bash
## To load a custom checkpoint (located in the top-level openpi/ directory):
export SERVER_ARGS="--env LIBERO policy:checkpoint --policy.config pi05_libero --policy.dir ./my_custom_checkpoint"

## To run the libero_10 task suite:
export CLIENT_ARGS="--args.task-suite-name libero_10"
```

## 6. 不使用 Docker 时启动仿真与服务端

文档不推荐 without Docker，但给出了两终端流程。Terminal window 1 创建环境并运行 simulation；如有 egl errors，可改用 glx 命令。

```bash
## Create virtual environment
uv venv --python 3.8 examples/libero/.venv
source examples/libero/.venv/bin/activate
uv pip sync examples/libero/requirements.txt third_party/libero/requirements.txt --extra-index-url https://download.pytorch.org/whl/cu113 --index-strategy=unsafe-best-match
uv pip install -e packages/openpi-client
uv pip install -e third_party/libero
export PYTHONPATH=$PYTHONPATH:$PWD/third_party/libero

## Run the simulation
python examples/libero/main.py

## To run with glx for Mujoco instead (use this if you have egl errors):
MUJOCO_GL=glx python examples/libero/main.py
```

Terminal window 2 运行 server：

```bash
## Run the server
uv run scripts/serve_policy.py --env LIBERO
```

## 验证是否跑通

LIBERO 评估能够启动 simulation 与 server，或 Docker compose 能完成构建并运行。若要复现实验表中结果，文档说明可评估 `gs://openpi-assets/checkpoints/pi05_libero/`；该 checkpoint 使用 `pi05_libero` config 在 openpi 中训练，表中 Average 为 96.85。

## 文档里点名的注意事项

- `GIT_LFS_SKIP_SMUDGE=1` is needed to pull LeRobot as a dependency.
- openpi repo has been tested with Ubuntu 22.04, and does not currently support other operating systems.
- current training script does not yet support multi-node training.
- When updating requirements.txt in examples/libero, `--extra-index-url https://download.pytorch.org/whl/cu113` must be added to the `uv pip compile` command.
- LIBERO Docker 运行前需要 `sudo xhost +local:docker` 授予 X11 server 访问权限。
- 如遇 Mujoco egl errors，文档建议使用 `MUJOCO_GL=glx`。
- custom checkpoint 示例要求 checkpoint located in the top-level openpi/ directory。

## 相关 SDK 条目

- [openpi](/sdks/openpi)

## 原始参考来源 (Sources)

- [raw.githubusercontent.com/Physical-Intelligence/openpi/main/README.md](https://raw.githubusercontent.com/Physical-Intelligence/openpi/main/README.md)
- [raw.githubusercontent.com/Physical-Intelligence/openpi/main/examples/libero/README.md](https://raw.githubusercontent.com/Physical-Intelligence/openpi/main/examples/libero/README.md)