🚀 速通OpenPI 本地部署（远端推理）简易实现

📋 基本信息

• 任务环境：robosuite "Lift" 场景，使用 Panda 机械臂抓取红色方块
• 任务描述："grasp the red box"
• 效果演示：

• 代码说明：utils 和 demo.py 基于 OpenPI 的 libero 示例 修改，精简了冗余代码✂️

🛠️ 环境要求

• 操作系统: Ubuntu 20.04+ 或 macOS（含 Apple Silicon）
• Python 版本：3.10
• 依赖库：
  • moviepy==2.2.1
  • msgpack>=1.0.5
  • numpy>=1.22.4,<2.0.0
  • pillow>=9.0.0
  • pyzmq>=25.0.0（ZMQ 异步模式需要）
  • robosuite==1.5.1
  • websockets>=11.0

⚡ 快速启动指南

【服务器端】部署推理服务（显存要求 >=8G）

# 1. 安装 uv
pip install uv

# 2. 克隆 openpi 并安装依赖
git clone https://ghfast.top/https://github.com/Physical-Intelligence/openpi.git
cd openpi/
pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
export UV_DEFAULT_INDEX=https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
GIT_LFS_SKIP_SMUDGE=1 uv sync

# 3. 下载并解压模型权重（约 10GB）
mkdir -p $HOME/.cache/openpi/openpi-assets/checkpoints
wget https://www.modelscope.cn/models/masheng/pi0-fine-Tuned-Models/resolve/master/pi0_fast_libero.zip
unzip pi0_fast_libero.zip -d $HOME/.cache/openpi/openpi-assets/checkpoints/

# 4. 启动推理服务（端口 18000）
export HF_ENDPOINT=https://hf-mirror.com
uv run scripts/serve_policy.py \
    --port 18000 \
    policy:checkpoint \
    --policy.config pi0_fast_libero \
    --policy.dir ~/.cache/openpi/openpi-assets/checkpoints/pi0_fast_libero

看到 serving on 0.0.0.0:18000 表示服务就绪。

---

【本地端】运行仿真

# 1. 克隆项目并安装依赖
git clone https://github.com/qihaoqian/Pi0_ZMQ_Deploy.git
cd pi0_fast_deploy
pip install -r requirements.txt

# 2. 运行（将 <SERVER_IP> 替换为推理服务器的实际 IP）
python demo.py          # 同步版（原始）
python demo_zmq.py --host <SERVER_IP>   # ZMQ 异步版（推荐）

在命令行输入 grasp the red box 回车即可。

第一次运行可能出现段错误 (核心已转储)，重试即可消失。

生成的视频保存至 ./output/videos/。

---

🔀 ZMQ 异步推理模式（demo_zmq.py）

位于 zmq-async 分支，原理说明见下。

为什么需要异步？

原始 demo.py 使用同步 WebSocket，每次推理都会阻塞主线程：

[执行5步动作] → [等待推理 ~500ms] → [执行5步动作] → ...
              ^^^^^^^^^^^^^^^^ 机器人空转

demo_zmq.py 将推理请求与动作执行并行化：

[执行5步动作]
      ↓ 立即提交下一次推理请求（非阻塞）
[执行5步动作]  ← 推理在后台同时进行
      ↓ 取结果（通常已就绪，等待≈0ms）
[执行5步动作]  ← 推理在后台同时进行

理论加速比（以推理500ms、每步50ms为例）：

模式	每个动作块耗时
同步 WebSocket	5×50ms + 500ms = 750ms
ZMQ 异步预取	max(5×50ms, 500ms) = 500ms

架构

主线程 (sync)                        Worker 线程 (asyncio)
┌──────────────────┐  ZMQ PUSH      ┌────────────────────────────────┐
│ submit(obs)      │ ─────────────► │ 接收请求                        │
│ (立即返回)       │  tcp loopback  │ await ws.send(obs)  ──────────► OpenPI
│                  │                │ response = await ws.recv() ◄─── OpenPI
│ get_result(rid)  │ ◄───────────── │ 返回结果                        │
│ (通常≈0ms等待)   │  ZMQ PULL      └────────────────────────────────┘
└──────────────────┘

ZMQ 端口（15700/15800）仅用于本机线程间通信，不暴露到网络。

CLI 参数

python demo_zmq.py --host <SERVER_IP> [--port 18000] [--render] [--max-steps 100]

参数	默认值	说明
--host	127.0.0.1	推理服务器 IP
--port	18000	推理服务器 WebSocket 端口
--render	False	开启 MuJoCo 可视化窗口（macOS 本地运行时使用）
--max-steps	100	最大仿真步数

macOS 本地可视化

在 macOS 上运行仿真并实时查看渲染画面：

# 额外安装渲染依赖
pip install mujoco glfw

# 启动（--render 开启 MuJoCo 窗口）
# macOS 必须用 mjpython（MuJoCo 自带），否则报 launch_passive 错误
mjpython demo_zmq.py --host <SERVER_IP> --render

macOS 说明：MuJoCo 在 macOS 上要求渲染窗口运行在主线程（Cocoa 框架限制），普通 python 不满足此条件。mjpython 是 mujoco 包自带的封装解释器（位于 virtualenv 的 bin/mjpython），功能与 python 完全一致。

端口说明

端口	方向	用途
18000 TCP	本地 → 服务器	WebSocket 推理请求，需防火墙放通
15700, 15800	本机 loopback	ZMQ 线程间通信，不出网

💡 小建议

• 可通过修改 get_env() 函数切换不同仿真环境（"Stack"、"Door" 等）和机器人（"Sawyer"、"UR5e" 等）

⚠️ 注意事项

pi0 模型不支持跨机器人直接迁移，从 Panda 更换为其他机器人时需重新微调模型。

✨ 支持一下

如果觉得本项目有帮助，欢迎点亮 star 🌟、点赞收藏转发一键三连哦！