π0.5（Pi0.5）适配与部署

π0.5 是 Physical Intelligence 发布的视觉-语言-动作模型，强调开放世界泛化。首期第三方模型适配只建设 π0.5，不提前放置其他模型的空目录。

当前上游存在两条实现路径：

  • Physical Intelligence 的 OpenPI；

  • Hugging Face LeRobot 中的 Pi05 Policy。

自变量正式版本需要选定并验证其中一条主路径，确保训练、推理和 SDK Adapter 使用同一 observation/action 契约。以下是适配框架，不表示相关命令已经在量子 1 号 Pro 上通过验收。

上游环境参考

OpenPI 官方说明当前测试环境为 Ubuntu 22.04；单卡推理需要大于 8 GB 显存，LoRA 微调大于 22.5 GB，Full Fine-tuning 大于 70 GB。实际需求仍会随相机、分辨率、batch size 和实现变化。

LeRobot Pi05 的上游安装：

pip install -e ".[pi]"

上游训练命令示例：

lerobot-train \
  --dataset.repo_id=your_dataset \
  --policy.type=pi05 \
  --output_dir=./outputs/pi05_training \
  --job_name=pi05_training \
  --policy.repo_id=your_repo_id \
  --policy.pretrained_path=lerobot/pi05_base \
  --policy.compile_model=true \
  --policy.gradient_checkpointing=true \
  --wandb.enable=true \
  --policy.dtype=bfloat16 \
  --policy.freeze_vision_encoder=false \
  --policy.train_expert_only=false \
  --steps=3000 \
  --policy.device=cuda \
  --batch_size=32

该命令是 LeRobot 上游参考。

自变量适配步骤

  1. 选择实现和版本：固定 OpenPI 或 LeRobot Pi05 的版本、依赖和 Checkpoint。

  2. 准备数据：使用“数据准备”中的 LeRobotDataset v3，并记录任务文本。

  3. 定义 observation 映射：将量子 1 号 Pro 的相机和 state 映射为 π0.5 输入。

  4. 定义 action 映射：明确动作维度、绝对/相对模式、姿态、夹爪、频率和 action horizon。

  5. 训练或微调：保存配置、归一化、数据版本与 Checkpoint。

  6. 离线与开环验证：检查输入输出、动作范围和推理耗时。

  7. 建立推理服务：模型可与机器人分机运行，通过 WebSocket 或正式服务接口通信。

  8. 接入 SDK Adapter：统一完成预处理、后处理、安全校验和状态反馈。

  9. 真机小范围验证：限速、限幅、短时、可急停。

映射检查

LeRobot 支持通过 rename map 处理 observation key 不一致，但它只重命名 observation，不处理 action。自变量适配仍需单独完成 action 的维度、单位和控制模式转换。

示意：

--rename_map='{ "observation.images.faceImg": "observation.images.image", "observation.images.rightImg": "observation.images.image2" }'

具体目标 key 必须以所选 π0.5 Checkpoint 的配置为准，不能直接照抄示意。

首期验收

  • 固定一套可复现环境和模型版本；

  • 自变量数据可用于训练；

  • observation/action 映射有文档并通过检查；

  • 推理可在无真机条件下完成冒烟测试；

  • 推理服务可与 SDK Client 通信；

  • Policy 输出经 Adapter 和 SDK 真机执行；

  • 异常、超时、断连和停止可控；

  • 提供至少一个完成真机验证的任务。

交付记录

完成适配后，应在项目交付记录中固化以下信息，避免环境、模型或映射变化导致结果不可复现：

  • 最终采用的 OpenPI 或 LeRobot 版本，以及对应代码仓和分支；

  • 量子 1 号 Pro 的 observation/action 映射配置；

  • 可直接复现的训练命令、推理 Client 启动方式和依赖版本；

  • 真机验收任务、测试条件、结果与已验证的安全边界。

本页内容

上游环境参考自变量适配步骤映射检查首期验收交付记录