跳到主要内容

OpenPI 环境与项目准备

KMD 的 VLA 部署由两个项目组成：

项目安装位置作用
openpi-kmdGPU 训练/推理服务器训练模型、加载 checkpoint、运行策略服务器和真机推理客户端
vlahost机器人 ROS 2 主机将 ROS 2 状态与相机话题转换为 HTTP 接口，并接收模型动作

1. 获取项目​

在 GPU 服务器下载 OpenPI KMD：

git clone https://github.com/KLMmotion/openpi-kmd.git
cd openpi-kmd

在机器人端下载 vlahost：

git clone https://github.com/KLMmotion/vlahost.git

建议记录部署时使用的 commit，后续更新代码、模型或文档时按同一版本复现。

2. 安装 openpi-kmd​

openpi-kmd 要求 Python 3.11 及以上，并使用 uv 管理环境。安装依赖：

cd openpi-kmd
uv sync

uv sync 会按照项目的 pyproject.toml 和 uv.lock 创建环境。后续命令应通过 uv run 执行，避免误用系统 Python：

uv run python --version

项目包含的主要入口：

文件用途
scripts/train_pytorch.pyPyTorch 模型训练
scripts/train.pyJAX / Flax 模型训练
scripts/compute_norm_stats.py计算状态与动作归一化统计
scripts/serve_policy_kmd_joint.py加载 KMD 16 维关节空间 checkpoint 并启动策略服务器
vla_helpers/openpi_client_policy_http_kmd_joint.py读取 vlahost 状态、调用策略并下发动作
vla_helpers/openpi_policy_shared.pyKMD 策略共用的数据处理逻辑

3. GPU 环境检查​

训练和策略服务器需要 NVIDIA GPU。同步环境后先确认 PyTorch 和 JAX 能识别 GPU：

uv run python -c "import torch; print(torch.cuda.is_available(), torch.cuda.device_count())"
uv run python -c "import jax; print(jax.devices())"

如果输出中没有 GPU，请先检查显卡驱动、CUDA 兼容性和当前用户权限，再开始训练或部署。

4. Docker 方式（可选）​

项目也提供 Docker 配置。该方式有助于隔离依赖，但不是必需项。使用 GPU 容器前需要：

  • Docker Engine，建议使用 rootless 模式。
  • NVIDIA Container Toolkit。
  • 不要使用 Snap 安装的 Docker，它与 NVIDIA Container Toolkit 存在兼容问题。
  • Docker Desktop 也不适用于该项目的 NVIDIA runtime 配置。

Ubuntu 22.04 可参考项目脚本：

scripts/docker/install_docker_ubuntu22.sh
scripts/docker/install_nvidia_container_toolkit.sh

构建并启动项目容器：

docker compose -f scripts/docker/compose.yml up --build

运行指定示例：

docker compose -f examples/<example_name>/compose.yml up --build

首次构建会下载并安装依赖，耗时较长；后续运行会复用镜像缓存。

5. 安装机器人端 vlahost​

将 vlahost 放入机器人 ROS 2 工作空间并编译：

ln -s /path/to/vlahost ~/ros_ws/src/vlahost
cd ~/ros_ws
colcon build --packages-select vlahost
source install/setup.bash

机器人端需要能够导入 rclpy、FastAPI、uvicorn、pinocchio 和项目消息包 marvin_msgs。若编译成功但节点启动时报 Python 模块缺失，应在机器人当前 ROS 2 环境中补齐对应依赖。

6. 网络要求​

  • GPU 服务器应能访问机器人 vlahost 的 HTTP 端口，默认 8000。
  • 推理客户端应能访问 OpenPI 策略服务器的 WebSocket 端口，默认 8000。
  • 当策略服务器和推理客户端运行在同一台 GPU 服务器时，--policy-host 可填写 localhost。
  • 机器人端与 GPU 服务器分开部署时，确认防火墙和交换机未阻断对应端口。

项目参考​