安装 LeRobot
LeRobot v0.5.0 的运行环境有两种获取方式：使用预构建 GPU 镜像，或在本地按官方源码安装。仅需训练时使用镜像；需要修改策略配置、调试数据映射或接入自定义机器人接口时使用源码安装。
适用角色与前提
适用角色
| 角色 | 关注点 |
|---|---|
| 算法工程师 | 源码安装、策略配置、数据集加载 |
| 训练运维 | GPU 镜像、容器运行时、挂载与端口 |
前置条件
| 项 | 要求 |
|---|---|
| 操作系统 | 源码安装以 Ubuntu 22.04 为例 |
| Python | 源码安装使用 Python 3.12 及以上；官方 v0.5.0 的 requires-python 声明为 >=3.12 |
| GPU | 训练需 NVIDIA GPU 与 NVIDIA 容器运行时 |
| 视频解码 | 需要 ffmpeg；官方默认解码后端 TorchCodec 依赖它，不支持的平台回退 pyav |
| 构建工具 | git、git-lfs、build-essential、cmake、ninja-build、python3-dev 与 FFmpeg 开发库 |
| 磁盘 | 可容纳数据集、依赖与 checkpoint |
操作步骤
- 确认宿主机可在容器内访问 GPU。
docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubuntu22.04 nvidia-smi
- 使用镜像时，拉取并进入平台 LeRobot 训练镜像（默认
lerobot:latest），把数据集与输出目录挂载为独立目录。
docker run --rm -it --gpus all --shm-size 16g \
-v /path/to/lerobot_dataset:/data/input \
-v /path/to/output:/outputs \
lerobot:latest \
bash
- 校验容器内训练入口。
/lerobot/.venv/bin/lerobot-train --help
- 源码安装时，先安装系统依赖。
sudo apt-get update
sudo apt-get install -y \
git git-lfs curl build-essential cmake pkg-config ninja-build \
ffmpeg python3-dev \
libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev \
libswscale-dev libswresample-dev libavfilter-dev
- 创建 Python 3.12 环境。
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip setuptools wheel
- 从官方 tag 安装 LeRobot v0.5.0。
git clone https://github.com/huggingface/lerobot.git
cd lerobot
git checkout v0.5.0
pip install -e ".[all]"
- 验证安装。三个命令均返回帮助信息后，再启动训练。
lerobot-train --help
lerobot-dataset-viz --help
lerobot-info
结果校验
| 校验项 | 方法 | 通过标准 |
|---|---|---|
| GPU 可见 | 容器内执行 nvidia-smi | 列出 GPU 型号与驱动 |
| 训练入口可用 | 执行 lerobot-train --help | 输出参数帮助，无导入错误 |
| 可视化入口可用 | 执行 lerobot-dataset-viz --help | 输出参数帮助 |
| 数据集可读取 | 以 LeRobotDataset 加载数据集根目录 | 返回帧数与 episode 数，无异常 |
| 视频可解码 | 打开含 MP4 的数据集 | 帧可解码 |
异常处置
| 现象 | 可能原因 | 处置 | 责任方 |
|---|---|---|---|
| 依赖解析失败 | Python 版本低于声明 | 改用 Python 3.12 及以上 | 算法工程师 |
| 视频读取失败 | 缺少 ffmpeg | 安装 ffmpeg 后重新安装依赖 | 算法工程师 |
| 容器内看不到 GPU | 未安装 NVIDIA 容器运行时，或未加 --gpus | 安装 nvidia-container-toolkit，运行时加 --gpus all | 训练运维 |
| 镜像拉取慢 | Docker Hub 网络受限 | 改用部署配置的镜像地址 | 训练运维 |
| PyTorch CUDA wheel 下载失败 | 未指定与驱动匹配的 CUDA 版本 | 先按 PyTorch 官方源安装匹配版本，再安装 LeRobot | 算法工程师 |
| 找不到数据集根目录 | 挂载层级不对 | 挂载到含 meta/info.json 的目录，命令中的 --dataset.root 指向该目录 | 算法工程师 |