LeRobot 安装与设置
本文档提供 LeRobot 框架的技术安装说明，涵盖环境搭建、依赖管理和可选功能安装。
安装方法概览
LeRobot 可以通过 PyPI 或源码安装。包使用 可选扩展系统（在 pyproject.toml 中定义）来最小化核心安装的体积，同时支持庞大的硬件、仿真环境和策略架构生态。
环境要求
Python 版本
LeRobot 需要 Python >= 3.12。同时明确声明支持 Python 3.13。
系统依赖
- FFmpeg：对
LeRobotDataset中的视频解码至关重要。框架默认使用TorchCodec，需要ffmpeg头文件和二进制文件 - 平台特定驱动：真实机器人交互通常需要串口通信（
pyserial）或 USB 访问（libusb）
环境搭建
Conda（推荐通用使用）
推荐使用 miniforge 以确保一致的依赖解析：
conda create -y -n lerobot python=3.12
conda activate lerobot
如果在 Windows Subsystem for Linux（WSL）内安装，必须通过 conda-forge 安装 evdev（用于硬件控制的 pynput 所需）。
UV（推荐性能/Docker 场景）
uv 用于项目的快速环境实例化：
uv venv
uv pip install lerobot[all]
重要：仅在 PyTorch >= 2.10（TorchCodec >= 0.10）时支持系统级 ffmpeg（通过 apt 或 brew）。
安装步骤
从 PyPI 安装
基础包仅包含轻量级核心 ML 依赖：
pip install lerobot从源码安装（可编辑模式）
推荐研究人员和贡献者使用，可立即测试本地更改：
git clone https://github.com/huggingface/lerobot
cd lerobot
pip install -e ".[all]"可选依赖组
LeRobot 使用多层扩展系统管理其庞大的依赖树。
功能级扩展
| 扩展名 | 包含包 | 用途 |
|---|---|---|
[dataset] | datasets, av, torchcodec, jsonlines | 核心数据加载和 v3 格式支持 |
[training] | [dataset], accelerate, wandb | 策略训练和实验跟踪 |
[hardware] | pynput, pyserial, deepdiff | 真实机器人和遥操作控制 |
[viz] | rerun-sdk | 通过 Rerun 实时可视化 |
组合扩展
| 扩展名 | 用途 | CLI 命令 |
|---|---|---|
[corescripts] | 数据集探索 | lerobot-dataset-viz, lerobot-imgtransform-viz |
策略和仿真扩展
许多策略架构和仿真环境需要第三方 SDK，需单独安装以避免版本冲突：
- Pi0 / Pi0.5：
pip install “lerobot[pi]” - SmolVLA：
pip install “lerobot[smolvla]”
视频解码：TorchCodec 和 FFmpeg
LeRobot 利用 TorchCodec 实现高效的多线程视频解码。
TorchCodec 兼容性：
- 支持：Linux (x8664)、macOS (Apple Silicon)、Windows（PyTorch >= 2.8） * 不支持：Linux ARM (aarch64)、macOS Intel (x8664)
- 回退：在不支持的平台上，系统自动回退到
pyav
libsvtav1 编码器是 LeRobotDataset 格式的首选编解码器。
Docker 安装
LeRobot 提供多种 Docker 配置：
- Dockerfile.user：基于 Python Slim，适用于一般实验
- Dockerfile.internal：用于 Hugging Face 内部 CI，包含 NVIDIA CUDA 支持
- Dockerfile.benchmark.robotwin：RoboTwin 2.0 集成测试专用镜像
评论