企业官网建设流程全解析

openpi Docker部署实战：一条命令让VLA机器人策略推理跑起来

【免费下载链接】openpi项目地址: https://gitcode.com/GitHub_Trending/op/openpi

配依赖配到一半，JAX、LeRobot、transformers 互相打架，终端报错刷了一屏——这是第一次做 openpi 环境搭建时最常见的劝退时刻。openpi 是 Physical Intelligence 团队开源的 VLA（视觉-语言-动作）机器人策略模型仓库，内置 π₀ / π₀-FAST / π₀.₅ 三类模型和预训练权重，装好之后你可以在自己的 GPU 上跑策略推理，也可以微调出属于自己机械臂的模型。照这篇走完，你会得到一台能起 openpi 推理服务、能被客户端连通的机器。

一、openpi 装好之后能干什么

先对齐预期，免得装完不知道拿它做什么。openpi 的工作模式是"服务端出动作，客户端送观测"：

• 服务端：加载一个 checkpoint（模型权重），监听 8000 端口，收到图像和 prompt 后返回一段动作序列（action chunk）。
• 客户端：可以是仿真器（ALOHA 仿真、LIBERO 基准），也可以是真实机器人或一个随机生成观测的测试脚本。

仓库里同时提供两类权重：基座模型（适合微调）和针对 DROID、ALOHA、LIBERO 平台的专家模型（适合直接推理）。权重首次运行时会自动下载到~/.cache/openpi缓存，不用手动搬运。

想直接体验而不接机器人，examples/simple_client/ 里的测试客户端就是为此准备的，后面验证环节会用到。

二、动手前核对系统条件

这一步是确认你的机器够不够格，避免装到一半发现硬件不达标。

openpi 官方只在Ubuntu 22.04上测试过，其他系统不在支持范围。GPU 方面按用途对照这张表（来自仓库 README 的显存估算）：

# 确认系统版本和 GPU 是否被驱动识别 lsb_release -a && nvidia-smi

nvidia-smi能打印出 GPU 型号和驱动版本，说明驱动这一层是通的。

⚠️ 显存不够不是死路：训练时可以用--fsdp-devices <n>把模型切到多卡，牺牲速度换显存。

系统条件确认后，下面开始装最省事的那条路：Docker。

三、两条脚本装好 Docker 和 NVIDIA 容器支持

这一步是把宿主机准备妥当，让容器既能跑又能摸到 GPU。

Docker 负责隔离环境，NVIDIA 容器工具包（nvidia-container-toolkit）负责把宿主机 GPU 暴露给容器——少了后者，容器里nvidia-smi就是一张白板。openpi 把这两件事做成了现成脚本，直接执行：

# 安装 Docker 引擎（官方源 + 用户组 + 开机自启） bash scripts/docker/install_docker_ubuntu22.sh # 安装 NVIDIA 容器工具包并配置 Docker 运行时 bash scripts/docker/install_nvidia_container_toolkit.sh

两个注意点，都写在 docs/docker.md 里：

⚠️ Docker 必须是 rootless 模式安装；用snap装的 Docker 和 Docker Desktop 都与 NVIDIA 工具包不兼容，如果之前装过，先sudo snap remove docker或sudo apt remove docker-desktop卸掉。

脚本跑完后会提示重启，重启一次让 docker 用户组权限生效。

四、克隆仓库并构建启动容器

这一步是把 openpi 拉下来并让第一个容器跑起来。

# 克隆仓库，--recurse-submodules 不能省，仿真相关代码在子模块里 git clone --recurse-submodules https://gitcode.com/GitHub_Trending/op/openpi cd openpi # 构建镜像并启动推理服务容器（首次约 10-20 分钟，之后走缓存） docker compose -f scripts/docker/compose.yml up --build

这条命令做三件事：基于scripts/docker/serve_policy.Dockerfile（预装 CUDA 12.2 + uv 依赖）构建镜像，把仓库目录挂载进容器，然后执行策略服务脚本。

如果你要跑的只是某个示例（比如 ALOHA 仿真），可以直接用示例自带的编排文件，它会把"服务端 + 客户端"两个容器一起拉起：

# 以 aloha_sim 为例，一条命令起仿真和策略服务 export SERVER_ARGS="--env ALOHA_SIM" docker compose -f examples/aloha_sim/compose.yml up --build

⚠️ 没有 GPU 的机器上，记得把 compose 文件里的deploy.resources.reservations那段注释掉，否则容器会因申请不到 GPU 而启动失败。

构建完成后终端会挂在服务日志上，此时服务应已在 8000 端口监听。接下来验证它真的能干活。

五、跑通验证：不接机器人先推一次理

这一步是确认整条链路——容器、GPU、模型权重——全部就绪。

最轻量的验证是 simple_client：它随机造一份观测发给服务端，并打印推理速率。开两个终端：

# 终端 1：起策略服务（默认加载预训练权重，首次会自动下载 checkpoint） uv run scripts/serve_policy.py --env DROID # 终端 2：起测试客户端，向服务端要动作 uv run examples/simple_client/main.py --env DROID

客户端能持续收到动作并打印推理频率，说明环境已经真正跑通。首次运行会自动拉取模型权重，耗时取决于网速，进度会显示在日志里。

容器连不上 GPU 的三步排查

如果服务启动时报 CUDA 相关错误，按顺序查：

1. 宿主机上nvidia-smi是否正常输出；
2. dpkg -l | grep nvidia-container-toolkit确认工具包已装；
3. docker info | grep -i nvidia确认 Docker 已注册 NVIDIA 运行时。

三步都过仍报错，检查宿主机驱动版本与 CUDA 镜像（12.2）的兼容性。另有一条官方排障建议：系统级 CUDA 库有时反而会造成冲突，openpi 依赖的 CUDA 由 uv 在虚拟环境内安装，必要时可以卸载系统级 CUDA。

验证跑通后，剩下的就是遇到报错时怎么自救。

六、常见报错对照自救

这一步是把新手期最高频的几类错误一次讲清，遇到时直接对号入座。

更多问题可以翻 README 末尾的 Troubleshooting 表，它按"现象 → 解法"组织，覆盖面比这里更全。

环境稳定之后，就可以往里填你自己的任务和模型了。

七、跑通之后可以做什么

三条由浅入深的路线，按需取用：

1. 换示例玩：把examples/aloha_sim/换成 examples/libero/（LIBERO 基准评测）或examples/droid/（DROID 平台推理），每个目录的 README 都有独立的一条命令启动方式。
2. 微调自己的模型：用examples/libero/convert_libero_data_to_lerobot.py把自有数据转成 LeRobot 格式，然后在src/openpi/training/config.py里加一个训练配置，参考 docs/norm_stats.md 处理归一化统计，训练完成后用scripts/serve_policy.py指向新 checkpoint 即可服务。
3. 把推理搬到远端：模型跑在 GPU 服务器上、机器人端只跑轻量客户端，通过 WebSocket 传动作——docs/remote_inference.md 给了完整的部署思路和代码示例，这是真实机器人项目最常用的拓扑。

如果这篇指南帮你把 openpi 顺利跑起来了，欢迎点个收藏，下期聊聊用 openpi 微调 LIBERO 模型的完整流程。

【免费下载链接】openpi项目地址: https://gitcode.com/GitHub_Trending/op/openpi