📚 课程目录第4章环境搭建与依赖管理

4. 环境搭建与依赖管理

在 LeRobot VLA 策略微调工程中，环境搭建不是“装几个包”这么简单，而是决定后续训练能否复现、GPU 能否被正确调用、仿真与真机能否顺利切换的基础工程。VLA 模型通常同时依赖视觉编码器、语言模型、动作解码头以及机器人数据接口，任何一层版本错配都可能导致训练中断或结果不可复现。因此，本节围绕 Python 环境、PyTorch 与 CUDA、LeRobot 安装、仿真器与硬件依赖配置，给出一条可落地的搭建路径。

核心原则：先锁定 CUDA 与 PyTorch 的匹配关系，再安装 LeRobot，最后接入仿真器与硬件。顺序颠倒会显著增加排障成本。

一、核心原理：依赖链的层次关系

LeRobot 的依赖可以理解为一条自底向上的链：操作系统与显卡驱动提供 CUDA 运行时；CUDA 决定可用的 PyTorch 版本；PyTorch 决定 torchvision、torchaudio 以及部分编译型扩展；LeRobot 再在其上依赖 Hugging Face 生态、数据集工具、仿真器接口和硬件 SDK。若底层驱动过旧，即使 pip 安装成功，运行时也会出现 CUDA driver version is insufficient 或 no kernel image is available。

因此推荐使用 conda 或 uv 创建独立虚拟环境，避免与系统 Python 混用。Python 版本建议选择 3.10 或 3.11，这两个版本对 PyTorch 2.x 与 LeRobot 的兼容性最稳定。

conda create -n lerobot python=3.10 -y
conda activate lerobot
python -V
nvidia-smi

nvidia-smi 右上角显示的 CUDA Version 是驱动支持的最高运行时版本，而不是当前安装的 CUDA Toolkit 版本。安装 PyTorch 时应以该上限为准，选择不高于它的 CUDA 版本。

二、方法流程：PyTorch、CUDA 与 LeRobot 安装

PyTorch 官方为不同 CUDA 版本提供独立索引。以 CUDA 12.1 为例，可使用如下命令安装 GPU 版 PyTorch：

pip install torch torchvision torchaudio \
  --index-url https://download.pytorch.org/whl/cu121

python -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.device_count())"

若输出 True 且设备数大于 0，说明 GPU 可用。随后安装 LeRobot。推荐从源码安装，便于后续修改策略配置与数据管线：

git clone https://github.com/huggingface/lerobot.git
cd lerobot
pip install -e ".[aloha,pusht]"
pip install -e ".[sim]"

其中 aloha、pusht 对应不同机器人数据集与策略依赖，sim 用于仿真环境。若只需基础训练，可先安装核心依赖，再按需追加。安装完成后建议执行一次导入自检：

python -c "import lerobot; print(lerobot.__version__)"
python -c "from lerobot.common.datasets import LeRobotDataset; print('dataset ok')"

三、仿真器与硬件依赖配置

仿真器方面，常见选择包括 MuJoCo、Isaac Sim 与 gym 系列环境。MuJoCo 轻量、适合快速验证策略；Isaac Sim 依赖更强的 GPU 与驱动，适合高保真并行仿真。安装 MuJoCo 时需注意 mujoco 与 dm_control 版本匹配，并设置渲染后端：

pip install mujoco
export MUJOCO_GL=egl   # 无显示器服务器推荐
python -c "import mujoco; print(mujoco.__version__)"

硬件依赖主要指真实机器人或采集设备，例如 SO-100、ALOHA、Realsense 相机与串口舵机控制板。配置时需确认 udev 规则、串口权限与相机驱动：

sudo usermod -aG dialout $USER
ls /dev/ttyACM* /dev/ttyUSB*
sudo apt install v4l-utils
v4l2-ctl --list-devices

在服务器上无图形界面时，优先使用 EGL 或 OSMesa 渲染；若仿真器报 OpenGL 错误，先检查 MUJOCO_GL 与显卡驱动，而不是反复重装 Python 包。

四、依赖版本对照与常见误区

下表给出推荐组合，实际应以官方文档与驱动上限为准：

组件	推荐版本	检查命令	常见问题
Python	3.10 / 3.11	`python -V`	3.12 部分扩展未适配
NVIDIA 驱动	≥ 535	`nvidia-smi`	驱动过旧导致 CUDA 不可用
CUDA Runtime	12.1 / 11.8	`nvcc --version`	与 PyTorch 索引不一致
PyTorch	2.2+ cu121	`torch.cuda.is_available()`	误装 CPU 版
LeRobot	源码最新稳定分支	`pip show lerobot`	依赖冲突未隔离环境
MuJoCo	3.x	`import mujoco`	渲染后端未设置

常见误区有三类。第一，直接在 base 环境安装，导致多个项目依赖互相污染；第二，只看 pip install 成功，不验证 torch.cuda.is_available()；第三，忽略仿真器渲染后端，在无头服务器上反复调试却始终黑屏。复盘时建议把环境信息固化为脚本：

python - <<'PY'
import torch, platform
print("python", platform.python_version())
print("torch", torch.__version__)
print("cuda", torch.version.cuda)
print("available", torch.cuda.is_available())
print("device", torch.cuda.get_device_name(0) if torch.cuda.is_available() else "cpu")
PY

把该脚本输出记录到实验日志中，是保证 VLA 微调可复现的重要一步。环境稳定后，后续的数据加载、策略训练与仿真评估才能在同一基线上推进。