38. 跳转至

38. π₀.₅ 模型#

38.1 模型简介#

π₀.₅是Physical Intelligence团队在π₀基础上开发的升级版视觉-语言-动作（VLA）模型。该模型通过知识隔离训练（Knowledge Insulation）技术优化，在保持流匹配（Flow Matching）动作生成架构的同时，提升了模型在开放世界任务中的泛化能力。

38.2 OpenPI训练环境配置#

注意事项

  • 训练环境：Ubuntu 22.04 / 24.04
  • 推理环境：仅支持 Ubuntu 24.04

38.2.1 安装 FFmpeg#

sudo apt update
sudo apt install -y ffmpeg libsvtav1-dev

验证

安装完成后，运行以下指令：

ffmpeg -encoders | grep svtav1

应显示为：

测试图片

38.2.2 安装环境依赖#

请联系技术支持获取适配的openpi压缩包，解压后终端进入文件夹目录 

cd openpi
安装基本依赖： 
sudo apt install python3-venv clang
python3 -m pip install --user pipx
pipx install uv -i https://mirrors.aliyun.com/pypi/simple
# 建议配置终端代理（根据实际代理地址调整），否则网络问题容易导致安装失败
# export {HTTP_PROXY,HTTPS_PROXY,ALL_PROXY,http_proxy,https_proxy,all_proxy}=http://127.0.0.1:7890
# 注意由于uv会对某些包进行编译，因此不要使用conda环境
GIT_LFS_SKIP_SMUDGE=1 uv sync
GIT_LFS_SKIP_SMUDGE=1 uv pip install -e .
安装数据采集依赖，可联系售后获取数据采集包： 
uv pip install -e /path/to/your/data-collection/"[all]" -i https://pypi.mirrors.ustc.edu.cn/simple
安装推理依赖： 
#以下部分只需要在本机推理时安装
sudo apt-get install ./airbot-configure_5.1.6-1_all.deb
sudo apt-get install -y libturbojpeg gcc python3-dev v4l-utils
# 注意OpenPI官方要求Python 3.11+，请使用 Ubuntu 24.04 中的 Python 3.12 版本安装硬件驱动包
# 硬件驱动包下载链接：https://github.com/DISCOVER-Robotics/AIRBOT-Play-Hardware/releases
uv pip install airbot_hardware_py-<version>.whl

💡 小提示

依赖确认：

安装后请检查 linuxpy、pyturbojpeg 是否正确安装： 

uv pip show linuxpy 
uv pip show pyturbojpeg

若未安装，请运行： 

uv pip install linuxpy
uv pip install pyturbojpeg==1.8.2

Mujoco 编译问题： 若安装时出现编译问题（类似如下错误），请安装 mujoco 3.3.7 版本： 

MiB/42.45 MiB  × Failed to build `mujoco==2.3.7`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)

      [stdout]
      running bdist_wheel
      running build
      running build_py
      creating build/lib.linux-x86_64-cpython-312/mujoco
      copying mujoco/viewer_test.py -> build/lib.linux-x86_64-cpython-312/mujoco
      copying mujoco/render_test.py -> build/lib.linux-x86_64-cpython-312/mujoco
      copying mujoco/gl_context.py -> build/lib.linux-x86_64-cpython-312/mujoco
      copying mujoco/viewer.py -> build/lib.linux-x86_64-cpython-312/mujoco
      copying mujoco/rollout_test.py -> build/lib.linux-x86_64-cpython-312/mujoco
      copying mujoco/__init__.py -> build/lib.lin

注意事项

  1. 所有涉及到 uv 的安装，均需要在 OpenPI 项目根路径下进行（也就是包含 .venv 文件夹的路径），否则无法将包装入环境中
  2. 修改库版本后，uv run 会自动回退到 uv.lock 的版本：使用 export UV_NO_SYNC=1 临时禁用同步，或备份当前uv.lock文件，改名为uv.lock.backup后执行 uv lock --upgrade 进行更新。

38.3 显卡要求#

要训练 π₀.₅ 模型，您的 NVIDIA GPU 至少需要满足以下规格。以下估算基于单 GPU 训练场景，您也可以通过模型并行（FSDP）方式利用多 GPU 来分摊显存压力（请在训练配置中设置 FSDP_DEVICES）。请注意：当前训练脚本暂不支持多节点训练。

训练模式 显存需求 推荐显卡
推理（Inference） ≥ 8 GB RTX 3090 / 4090
微调（LoRA） ≥ 22.5 GB RTX 3090 / 4090
全参数微调（Full） ≥ 70 GB A100 (80GB) / H100

38.3.0.1 重要说明#

  1. 配置参考：上表为 Physical Intelligence 官方提供的参考配置。
  2. 微调建议：数据量较少时，推荐使用 LoRA 微调，既节省资源也能达到较好效果。
  3. 推理兼容性：
    • LoRA 微调模型支持在 8 GB 显存 的笔记本上推理
    • 全参数微调模型无法在 8 GB 显存设备上加载（通常表现为程序崩溃）
  4. 资源问题排查：
    • 若 LoRA 模型加载时崩溃，请检查系统资源是否充足
    • 可尝试关闭不必要的程序释放资源
  5. 多显卡使用：
    • OpenPI 默认使用所有可用 GPU 进行训练
    • 如需限制，请在训练前指定，例如：export CUDA_VISIBLE_DEVICES=1

38.4 微调#

38.4.1 配置训练参数#

# NOTE: 这是 Airbot 的示例配置文件，请先新建 data 文件夹，将此文件移入其中并重命名为 config.py。

# 任务名称：需要与 lerobot_play 采集的数据存储的文件夹名称保持一致
TASK_NAME = "你的任务名称"

# 机器人类型：单臂 1-1，双臂 ptk
ROBOT_TYPE = "ptk"

# ==================== 框架保留配置（无需修改） ====================
# 以下三项均为框架接口预留，当前版本实际未调用，但需保持存在
FOLDERS = ["fold_clothes"] 

STATE_TOPICS = [
    "/left/follow/arm/joint_state/position",
    "/left/follow/eef/joint_state/position",
    "/right/follow/arm/joint_state/position",
    "/right/follow/eef/joint_state/position",
]

ACTION_TOPICS = [
    "/left/lead/arm/joint_state/position",
    "/left/lead/eef/joint_state/position",
    "/right/lead/arm/joint_state/position",
    "/right/lead/eef/joint_state/position",
]

# ==================== 实际使用配置 ====================
# 以下配置项实际会被使用，请根据实际情况调整
# 相机配置：key 对应 openpi 中默认相机名称，value 对应数据采集时使用的相机名称
# 注意：名称格式必须为 "observation.images.xxx"，且与数据采集配置文件中的相机名称同步
CAMERA_TOPICS = {
    # key 名称只能在 ["base_0_rgb", "left_wrist_0_rgb", "right_wrist_0_rgb"] 中，数量不超过 3
    "base_0_rgb": "observation.images.env_camera",
    "left_wrist_0_rgb": "observation.images.left_hand_camera",
    "right_wrist_0_rgb": "observation.images.right_hand_camera",
}

FPS = 20

# OpenPI 要求将所有动作（除末端执行器外）转换为 delta 动作
# DELTA_ACTION_MASK 是一个元组，例如 (6, -1) 表示前 6 个关节应转换为 delta 动作，最后一个关节（末端执行器）不转换
DELTA_ACTION_MASK = (6, -1, 6, -1)

# ==================== 可选配置 ====================

# 模型配置
BASE_MODEL = "pi05"       # 当前仅支持 pi0 和 pi05
USING_LORA = True         # 是否使用 LoRA 微调
OVER_WRITE = False        # 是否覆盖现有 checkpoint 文件夹（继续训练请设为 False）
EXP_NAME = "pi05_fold_t"  # checkpoint 保存的文件夹名称
BATCH_SIZE = 32           # 训练时的 batch size
NUM_WORKERS = 2           # 数据加载的进程数量
NUM_TRAIN_STEPS = 30_000  # 训练的 steps
LOG_INTERVAL = 100        # 打印日志的 steps 间隔
SAVE_INTERVAL = 2500      # 保存 checkpoint 的 steps 间隔
KEEP_PERIOD = 10000       # 最终需维持的 checkpoints 对应的 steps 间隔
RESUME = True             # 是否从上次检查点继续训练
LOG_METHOD = "wandb"      # 日志记录方式：可选 "wandb"、"mlflow"、"none"
FSDP_DEVICES = 1          # 保持默认，当单显卡无法加载整个模型时可调整
DEFAULT_PROMPT = "fold the t-shirt"  # 默认 prompt，设为 None 则使用数据集中的任务描述

38.4.2 计算数据统计学信息#

训练时数据归一化需要用到数据的统计学信息，执行如下命令进行计算： 

CUDA_VISIBLE_DEVICES=0 uv run examples/airbot/compute_norm_stats.py --config-path data/yout_task/config.py
生成的统计信息会保存在assets目录中。若没有生成统计学信息数据，训练会报错并自动终止。

38.4.3 模型训练#

执行训练命令：

XLA_PYTHON_CLIENT_MEM_FRACTION=0.9 uv run examples/airbot/airbot_train.py --config-path data/your_task/

38.4.3.1 参数说明#

  • XLA_PYTHON_CLIENT_MEM_FRACTION=0.9：配置 JAX 使用最多 90% 的 GPU 显存（默认仅使用 75%）
  • --config-path：配置文件路径或所在目录（指向包含 config.py 的文件夹）

38.4.3.2 常见报错与解决方法#

Orbax Checkpoint 报错 

AttributeError: module 'orbax.checkpoint.future' has no attribute 'CommitFutureAwaitingContractedSignals

解决方案：请打开 openpi/.venv/lib/python3.12/site-packages/orbax/checkpoint/future.py，手动添加： 

from orbax.checkpoint._src.futures.future import CommitFutureAwaitingContractedSignals

Pydantic 版本兼容性错误

pydantic._internal._generate_schema.InvalidSchemaError
  • 原因：numpydantic 与 pydantic 版本不兼容。lerobot==0.4.0 的默认依赖可能与 OpenPI 官方仓库冲突。
  • 解决方案：以 OpenPI 官方配置的依赖版本为准。

libtorchcodec 加载失败息

RuntimeError: Could not load libtorchcodec.
Likely causes:
1. FFmpeg is not properly installed in your environment. We support
   versions 4, 5, 6 and 7.
2. The PyTorch version (2.7.1+cu126) is not compatible with
   this version of TorchCodec. Refer to the version compatibility
   table:
   https://github.com/pytorch/torchcodec?tab=readme-ov-file#installing-torchcodec.
3. Another runtime dependency; see exceptions below.

The following exceptions were raised as we tried to load libtorchcodec:

[start of libtorchcodec loading traceback]
FFmpeg version 7: libavutil.so.59: cannot open shared object file: No such file or directory
FFmpeg version 6: libavutil.so.58: cannot open shared object file: No such file or directory
FFmpeg version 5: libavutil.so.57: cannot open shared object file: No such file or directory
FFmpeg version 4: libavutil.so.56: cannot open shared object file: No such file or directory
[end of libtorchcodec loading traceback]

解决方案：

  1. 验证 FFmpeg 安装：确保系统已安装 FFmpeg。
  2. 检查 PyTorch 兼容性：参考 TorchCodec 官方兼容表。
  3. 配置库路径： 
    # 查找 FFmpeg 库文件位置
find /usr -name "libavutil.so*" 2>/dev/null
find /usr/local -name "libavutil.so*" 2>/dev/null

# 将实际路径加入 LD_LIBRARY_PATH（示例）
export LD_LIBRARY_PATH=/path/to/your/ffmpeg_lib:$LD_LIBRARY_PATH
    💡 注意：请将 /path/to/your/ffmpeg_lib 替换为你实际查找到的路径。

梯度爆炸 / Loss 异常

训练过程中 loss 值突然变得极大或出现 NaN，导致模型无法正常收敛

解决方案：

  • 检查数据集的统计信息中是否存在绝对值过大的异常值（通常在 action 中）
  • 定位并删除有问题的数据

NCCL 多卡通信错误

jaxlib.xla_extension.XlaRuntimeError: INTERNAL: NCCL operation ncclGroupEnd() failed: unhandled cuda error

临时解决方案（使用单卡）： 

import os
os.environ['CUDA_VISIBLE_DEVICES'] = '1'  # 指定使用 GPU 1

38.4.3.3 训练参数配置说明#

参数 默认值 说明与建议
NUM_TRAIN_STEPS 30000 训练迭代步数：数据集越大，所需步数越多。通常应保证数据集被完整训练 2-3 个 epoch。
BATCH_SIZE 32 批大小：根据显存灵活调整。在 24GB 显存（如 RTX 4090）上训练 π₀.₅ 时，建议降至 24。
NUM_WORKERS 2 数据加载进程数：若训练速度受数据加载限制，可适当提高此值。
SAVE_INTERVAL 1000 检查点保存间隔：保证可以找到较新的检查点继续训练。但如果这个值太低，会出现频繁存储检查点而降低训练速度的情况。
warmup_steps 1000 学习率预热步数：学习率线性预热阶段，小规模数据可减小或取消预热。
peak_lr 2e-5 峰值学习率：首次训练（不是基于已经训练的模型进一步微调），可以适当调大学习率以加快训练速度。判断标准：loss 不出现 NaN 且正常收敛即为合适。
decay_steps 30000 学习率衰减持续步数（余弦衰减的持续时间）。
decay_lr 2e-6 衰减后学习率：若与 peak_lr 相同，则表示不进行衰减。

38.4.3.4 注意事项#

  1. 模型路径配置
    如需基于已训练模型继续训练：

    • 打开 examples/airbot/airbot_data_config.py
    • 修改 checkpoint_path = "gs://openpi-assets/checkpoints/pi05_base/params"为你的本地路径（需以 params 文件夹结尾），如checkpoints/your_task/20000/params

  2. 学习率参数修改
    学习率相关参数需在 examples/airbot/airbot_data_config.py 的 TrainConfig → lr_schedule 下修改。

  3. 首次训练准备

    • 确保良好网络环境以下载官方预训练模型
    • 预留足够存储空间（模型较大）

  4. 模型存储说明 ：首次训练会自动下载 π₀.₅ base 模型，该基础模型文件较大，需要足够的空间来存储。

    • 模型路径：在airbot_data_config.py中gs://openpi-assets/checkpoints/pi05_base/params
    • 如果需要基于已经训练的模型继续训练，请将 gs://openpi-assets/checkpoints/pi05_base/params替换成本地模型路径。

38.4.3.5 训练输出#

训练完成后生成的 checkpoints 文件结构如下：

Checkpoints 文件结构

38.5 同步推理#

38.5.1 开始推理#

38.5.1.1 1. 修改配置文件#

在推理前，先打开 examples/airbot/robot_config.py，根据实际任务类型调整相关参数：

⚠️ 以下示例均基于 CAN 接口名为 can_left / can_right，请根据你系统中实际的 CAN 设备名称进行修改。

任务类型配置：

  • 双臂任务：保持默认配置
  • 单臂任务：将 robot_groups 改为 "left"，robot_interface 改为 "can_left"，相机名称保留 ["base_0_rgb", "left_wrist_0_rgb"]

相机相关配置（适用于所有任务）：

  • 请根据实际相机 index 修改 camera-index 参数，传入参数顺序为：环境相机、左臂相机、右臂相机，请参考相机设备查询
  • 不要随意改变相机名称 ["base_0_rgb", "left_wrist_0_rgb", "right_wrist_0_rgb"]。如只需两个摄像头，保留 ["base_0_rgb", "left_wrist_0_rgb"]，与训练时保持一致

38.5.1.2 2. 执行推理命令#

单臂任务：

uv run examples/airbot/airbot_inference_sync_ah.py policy-config:local-policy-config \
    --policy-config.config-path data/1-1-example \
    --policy-config.checkpoint-dir checkpoints/1-1-example/9000

双臂任务：

uv run examples/airbot/airbot_inference_sync_ah.py policy-config:local-policy-config \
    --policy-config.config-path data/ptk_example \
    --policy-config.checkpoint-dir checkpoints/ptk_example/9000 \

参数说明：

参数 说明 注意事项
robot_ports 机器人端口号 根据实际启动情况修改
checkpoint-dir 权重文件路径 根据实际路径修改
camera-index 相机序号 顺序必须为：环境相机 → 左臂相机 → 右臂相机
reset-action 机器人初始位置 参考数据采集时示教臂的初始位置

注意事项

  • 推理性能：24GB 显存（RTX 4090）：推理一次约 110ms
  • 首次推理： 时间较长属于正常现象
  • 依赖版本： 如出现参数解析错误，检查 tyro 版本是否为 0.9.22

38.5.2 常见问题#

38.5.2.1 问题描述#

遇到错误： jaxlib.xla_extension.XlaRuntimeError: UNIMPLEMENTED: /home/cytham/workspace/openpi/.venv/lib/python3.11/site-packages/nvidia/cuda_nvcc/bin/ptxas ptxas too old. Falling back to the driver to compile.

38.5.2.2 解决方案#

 # 首先备份旧的ptxas (可选，但建议)
  cd /home/cytham/workspace/openpi/.venv/lib/python3.11/site-packages/nvidia/cuda_nvcc/bin/
  mv ptxas ptxas.old_backup

  # 创建符号链接，指向系统的新ptxas
  ln -sf /usr/local/cuda-12.9/bin/ptxas ptxas

  # 验证链接是否创建成功
  ls -l ptxas # 应该显示类似：ptxas -> /usr/local/cuda-12.9/bin/ptxas