Ubuntu 20.04 系统下 Pi0 具身智能开发环境搭建

想试试最近火热的具身智能模型，比如 Pi0 或者 Spirit v1.5，自己动手搭建一个开发环境？这篇文章就是为你准备的。

我最近也在折腾这块，发现网上很多教程要么太零散，要么跳过了关键的排错步骤，让人卡在某个环节半天过不去。今天我就把自己在 Ubuntu 20.04 系统上，从零开始配置 Pi0 开发环境的完整流程，包括踩过的坑和解决方法，都整理出来。目标很简单：让你能顺利跑起来，看到效果。

整个过程主要分三大块：先把 CUDA 驱动和工具装好，这是 GPU 加速的基础；然后配置 ROS 环境，因为很多机器人仿真和工具链依赖它；最后，我们通过一个预置的镜像来快速部署 Pi0 环境，并验证它是否工作正常。

1. 准备工作：系统检查与基础依赖

在开始安装各种“大件”之前，我们先确保系统处于一个干净、稳定的状态。Ubuntu 20.04 是一个长期支持版本，社区支持好，兼容性也不错，很适合作为开发起点。

1.1 系统更新与基础工具

首先，打开你的终端，我们执行一次全面的系统更新，并安装一些后续步骤会用到的工具。

# 更新软件包列表并升级所有已安装的包
sudo apt update && sudo apt upgrade -y

# 安装一些基础编译工具和依赖
sudo apt install -y build-essential cmake git wget curl software-properties-common

build-essential 包含了 GCC、G++ 等编译套件，cmake 是很多项目的构建工具，git 用于拉取代码，curl 和 wget 用于下载文件，这些都是标配。

1.2 确认显卡型号与驱动

具身智能模型训练和推理通常需要 GPU 加速，所以一块 NVIDIA 显卡是必要的。我们先确认一下你的显卡型号。

# 查看 NVIDIA 显卡信息（如果已安装驱动）
nvidia-smi

如果这条命令报错，说明 NVIDIA 驱动还没装。我们可以用 lspci 命令先看看显卡型号。

# 查看 PCI 设备，过滤出 NVIDIA 显卡
lspci | grep -i nvidia

记下你的显卡型号（比如 GeForce RTX 4090），这关系到后面选择哪个版本的驱动和 CUDA。

2. CUDA 与 cuDNN 安装：GPU 加速基石

CUDA 是 NVIDIA 推出的并行计算平台，cuDNN 是针对深度神经网络的 GPU 加速库。它们是运行大多数 AI 框架（如 PyTorch, TensorFlow）的底层基础。

2.1 安装 NVIDIA 显卡驱动

Ubuntu 20.04 自带的“附加驱动”工具可以比较方便地安装驱动，但为了和后续的 CUDA 版本更好匹配，我推荐直接从 NVIDIA 官网下载安装。

首先，移除任何可能存在的旧版 NVIDIA 驱动。

sudo apt purge -y *nvidia* *cuda* *cudnn*
sudo apt autoremove -y

然后，添加 NVIDIA 的官方驱动仓库并安装。这里我们选择版本为 535 的驱动，这是一个比较稳定且兼容性广的版本。

# 添加 NVIDIA 驱动 PPA
sudo add-apt-repository ppa:graphics-drivers/ppa -y
sudo apt update

# 安装驱动（这里以 535 版本为例，你可以根据你的显卡和 CUDA 需求调整）
sudo apt install -y nvidia-driver-535

安装完成后，必须重启系统。

sudo reboot

重启后，再次运行 nvidia-smi，你应该能看到类似下面的输出，显示了显卡型号、驱动版本和 CUDA 版本（这里显示的是驱动支持的最高 CUDA 版本，不代表已安装）。

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.154.05   Driver Version: 535.154.05   CUDA Version: 12.2     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  NVIDIA GeForce ...  On   | 00000000:01:00.0  On |                  N/A |
|  0%   45C    P8    15W / 350W |    200MiB / 24576MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+

2.2 安装 CUDA Toolkit 11.8

Pi0 及其相关的 VLA 模型生态，目前对 CUDA 11.x 系列的支持最为成熟和稳定。我们选择 CUDA 11.8 这个长期支持版本。

前往 NVIDIA 官网的 CUDA Toolkit 11.8 下载页面，根据你的系统选择“Linux” -> “x86_64” -> “Ubuntu” -> “20.04” -> “runfile (local)”。

在终端中，使用 wget 下载安装包，然后执行安装。

# 下载 CUDA 11.8 安装包（文件较大，请耐心等待）
wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run

# 赋予执行权限并运行安装程序
sudo sh cuda_11.8.0_520.61.05_linux.run

安装过程中会有一个交互界面：

1. 输入 accept 同意协议。
2. 在组件选择界面，取消勾选 Driver，因为我们已经安装了驱动。确保 CUDA Toolkit 11.8 是选中的。
3. 其他选项保持默认，选择 Install 开始安装。

安装完成后，需要将 CUDA 路径添加到系统环境变量中。

# 编辑 ~/.bashrc 文件
echo 'export PATH=/usr/local/cuda-11.8/bin${PATH:+:${PATH}}' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}' >> ~/.bashrc

# 使环境变量生效
source ~/.bashrc

验证 CUDA 是否安装成功：

nvcc --version

你应该能看到输出中包含 release 11.8 的字样。

2.3 安装 cuDNN

cuDNN 需要注册 NVIDIA 开发者账号才能下载。登录后，在 cuDNN 下载页面 找到对应 CUDA 11.x 的版本（例如 cuDNN v8.9.x for CUDA 11.x），选择“Local Installer for Linux (x86_64)”的 .tar 格式文件下载。

假设你下载的文件名为 cudnn-linux-x86_64-8.9.x.x_cuda11-archive.tar.xz，执行以下命令安装：

# 解压下载的文件
tar -xvf cudnn-linux-x86_64-8.9.x.x_cuda11-archive.tar.xz

# 复制头文件和库文件到 CUDA 目录
sudo cp cudnn-linux-x86_64-8.9.x.x_cuda11-archive/include/cudnn*.h /usr/local/cuda-11.8/include
sudo cp -P cudnn-linux-x86_64-8.9.x.x_cuda11-archive/lib/libcudnn* /usr/local/cuda-11.8/lib64

# 修改文件权限
sudo chmod a+r /usr/local/cuda-11.8/include/cudnn*.h /usr/local/cuda-11.8/lib64/libcudnn*

至此，GPU 计算的基础环境就搭建好了。

3. ROS Noetic 安装与配置

机器人操作系统（ROS）是机器人开发的事实标准，提供了大量用于仿真、感知、控制的工具和库。Pi0 等具身模型虽然不一定直接依赖 ROS 运行，但整个开发、测试和与真实机器人交互的生态链与 ROS 紧密相连。我们安装 ROS 1 的最后一个版本——Noetic，它原生支持 Ubuntu 20.04。

3.1 安装 ROS Noetic

按照 ROS 官方 Wiki 的步骤进行：

# 1. 设置软件源
sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'

# 2. 添加密钥
sudo apt install curl -y
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -

# 3. 安装
sudo apt update
sudo apt install -y ros-noetic-desktop-full

# 4. 初始化 rosdep
sudo rosdep init
rosdep update

3.2 设置环境变量

为了让终端能识别 ROS 命令，需要将它的环境变量添加到 ~/.bashrc。

echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc
source ~/.bashrc

3.3 创建工作空间并安装常用工具

ROS 项目通常在自己的工作空间（workspace）中开发。我们创建一个，并安装一些后续可能用到的工具包。

# 创建并初始化一个 catkin 工作空间
mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/
catkin_make

# 将这个工作空间的环境变量也加入 bashrc
echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc
source ~/.bashrc

# 安装一些有用的 ROS 工具
sudo apt install -y python3-rosinstall python3-rosinstall-generator python3-wstool build-essential
sudo apt install -y ros-noetic-rviz ros-noetic-moveit ros-noetic-ros-control ros-noetic-gazebo-ros-pkgs

现在，你可以通过运行 roscore 来测试 ROS 核心是否成功启动。按 Ctrl+C 可以停止。

4. Pi0 具身智能环境快速部署

前面两步搭建了底层基础，现在我们来部署具体的 Pi0 开发环境。为了避开复杂的源码编译和依赖解决，我们使用一个预配置好的 Docker 镜像，这是最快、最不容易出错的方式。

4.1 安装 Docker 与 NVIDIA Container Toolkit

Docker 可以让我们在一个隔离的、环境一致的容器中运行应用。

# 1. 卸载旧版本 Docker（如果有）
sudo apt remove -y docker docker-engine docker.io containerd runc

# 2. 安装依赖，添加 Docker 官方 GPG 密钥
sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 3. 设置 Docker 仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 4. 安装 Docker Engine
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 5. 将当前用户加入 docker 组，避免每次使用 sudo
sudo usermod -aG docker $USER
# **重要：需要注销并重新登录，或者重启系统，此更改才会生效**

重新登录后，验证 Docker 安装：

docker run hello-world

接下来，安装 NVIDIA Container Toolkit，让 Docker 容器也能使用宿主机的 GPU。

# 添加 NVIDIA Container Toolkit 仓库
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

# 安装 nvidia-container-toolkit
sudo apt update
sudo apt install -y nvidia-container-toolkit

# 重启 Docker 服务
sudo systemctl restart docker

验证 GPU 在 Docker 中是否可用：

docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu20.04 nvidia-smi

这个命令应该会输出和宿主机上 nvidia-smi 类似的信息。

4.2 拉取并运行 Pi0 预置镜像

现在，我们可以拉取一个已经集成了 Pi0 模型、相关依赖和示例代码的 Docker 镜像。假设这个镜像名为 pi0-embodied-ai:v1（具体名称请根据你获取的镜像信息调整）。

# 拉取镜像（请替换为实际的镜像仓库地址和标签）
# 例如：docker pull your-registry/pi0-embodied-ai:v1
# 这里假设你已经将镜像文件下载到本地并加载，或者从某个仓库拉取
# docker pull csdn-mirror/pi0-embodied-ai:latest

# 为了演示，我们假设你已经有了镜像，直接运行一个交互式容器
# --gpus all: 将GPU透传给容器
# -it: 交互式终端
# --rm: 容器退出后自动删除
# -v $(pwd)/workspace:/workspace: 将宿主机的当前目录下的workspace文件夹挂载到容器的/workspace，方便文件交换
docker run --gpus all -it --rm -v $(pwd)/workspace:/workspace --name pi0-dev csdn-mirror/pi0-embodied-ai:latest /bin/bash

成功运行后，你的终端提示符会变成容器的提示符（如 root@container-id:/#）。

4.3 在容器内验证环境

进入容器后，我们可以快速验证几个关键点。

# 1. 验证 GPU 和 CUDA
nvidia-smi
python3 -c "import torch; print(f'PyTorch版本: {torch.__version__}'); print(f'CUDA是否可用: {torch.cuda.is_available()}'); print(f'当前CUDA设备: {torch.cuda.current_device()}')"

# 2. 检查 Pi0 相关代码和模型（假设镜像已预置在 /app 目录）
ls -la /app
# 可能会看到类似 pi0_inference.py, requirements.txt, README.md 等文件

# 3. 尝试运行一个简单的示例脚本（请根据镜像内的实际文件调整）
cd /app
# 通常会有个 requirements.txt，可以先安装Python依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 运行一个最简单的推理示例
# python pi0_demo.py --task \"pick up the red block\"

如果以上步骤都没有报错，并且模型能加载并给出响应（可能是动作序列或状态信息），那么恭喜你，Pi0 的本地开发环境就已经成功搭建并运行起来了！

5. 常见问题排错指南

搭建过程中难免会遇到问题，这里汇总了几个我遇到过的典型问题及其解决方法。

5.1 NVIDIA-SMI 可以运行，但 torch.cuda.is_available() 返回 False

这通常是 PyTorch 版本与 CUDA 版本不匹配导致的。

• 解决方法：在容器内或你的 Python 环境中，使用与 CUDA 11.8 兼容的 PyTorch 版本。访问 PyTorch 官网，找到对应 CUDA 11.8 的安装命令。例如：

  pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 --index-url https://download.pytorch.org/whl/cu118
  

5.2 Docker 容器内无法找到 GPU (nvidia-smi: command not found)

这通常是 NVIDIA Container Toolkit 没有正确安装或配置。

• 解决方法：
  1. 确保宿主机已按照步骤 4.1 正确安装并重启了 Docker。
  2. 运行 docker run 时一定要加上 --gpus all 参数。
  3. 在宿主机上运行 dpkg -l | grep nvidia-container-toolkit 确认其已安装。
  4. 检查 /etc/docker/daemon.json 文件，确保其包含 "runtimes": {"nvidia": ...} 的配置。安装工具包时通常会自动配置。

5.3 运行示例代码时出现模型文件下载错误或缺失

预置镜像可能不包含巨大的模型权重文件，或者需要从网络下载。

• 解决方法：
  1. 检查镜像的文档或 /app 目录下的 README，看模型文件应放置在哪里。
  2. 根据文档提供的链接（如 Hugging Face Model Hub），手动下载模型权重文件（.bin 或 .safetensors 文件），并通过挂载的卷（如 /workspace）放入容器内正确路径。
  3. 有时需要设置环境变量指定模型路径，如 export MODEL_PATH=/workspace/pi0_model。

5.4 内存不足（OOM）错误

运行较大的具身模型可能需要可观的 GPU 显存和系统内存。

• 解决方法：
  1. 关闭其他占用 GPU 的程序。
  2. 在运行 Docker 容器时，可以使用 --shm-size 参数增加共享内存，例如 --shm-size=8g。
  3. 如果模型支持，尝试在代码中减小批量大小（batch size）。
  4. 考虑使用模型量化技术或使用更小的模型变体。

---

整体走下来，感觉在 Ubuntu 20.04 上搭建这套环境，核心就是耐心和顺序。先稳扎稳打把 CUDA 和驱动配好，这是所有加速的基础，出问题也最容易排查。ROS 的安装相对标准化，跟着官方指南走基本没问题。最后用 Docker 镜像来部署 Pi0 环境，真的是省心省力，避免了无数潜在的依赖冲突。

环境搭好只是第一步，后面怎么用模型、怎么结合自己的机器人做实验，才是更有趣的部分。希望这篇详细的指南能帮你顺利跨过环境配置这个门槛。如果在实际操作中遇到这里没覆盖的问题，多看看错误日志，善用搜索引擎，大部分都能找到答案。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。