LeRobot 安装与部署：环境、依赖与硬件准备
二、安装与部署：环境、依赖与硬件准备
LeRobot 是纯 Python 项目，安装本身不复杂，麻烦的是硬件驱动与视频编码依赖。
- 准备 Python 环境。建议用 conda 或 venv 隔离，Python 版本以官方 README 注明的要求为准，不要用系统自带的旧解释器：
conda create -n lerobot python=3.10 -y conda activate lerobot - 安装 PyTorch。先按显卡 CUDA 版本装好 PyTorch，再装 LeRobot，避免 pip 自动拉一个不匹配的版本：
具体 CUDA 版本号请以 PyTorch 官网当前给出的安装命令为准。pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 - 安装 LeRobot。最简装法只带核心依赖；要接具体硬件需要装对应的 extras：
extras 名称随版本变化，安装前先看仓库 README 的当前列表。pip install lerobot # 或从源码安装，便于改代码 git clone https://github.com/huggingface/lerobot.git cd lerobot && pip install -e ".[aloha,pusht]" - 安装 ffmpeg。LeRobot 的数据集把视频单独编码存储，缺 ffmpeg 会在写入数据集时报编码器找不到：
sudo apt install -y ffmpeg ffmpeg -version - 配置串口权限。使用 SO-100 / SO-101 这类舵机臂时，串口设备默认只有 root 可读写，不加组会导致打开串口失败：
sudo usermod -aG dialout $USER # 重新登录后生效 ls -l /dev/ttyACM* - 摄像头确认。用 OpenCV 依次打开候选索引，记下彩色相机的编号，后续采集命令要用：
python -c "import cv2; [print(i, cv2.VideoCapture(i).isOpened()) for i in range(6)]" - 验证安装。列出内置命令的帮助，确认 CLI 可用：
不同版本的子命令名可能带或不带lerobot-record --help lerobot-train --helplerobot-前缀，以--help实际输出为准。
常见报错排查。
| 报错现象 | 根因 | 处理方式 |
|---|---|---|
Permission denied: '/dev/ttyACM0' | 用户不在 dialout 组 | 加入 dialout 组并重新登录 |
| 找不到串口设备 | USB 线是充电线，或驱动未装 | 换数据线；确认 dmesg 里能看到设备枚举 |
| 视频编码失败 / ffmpeg 相关异常 | 系统缺 ffmpeg 或缺少相应编码器 | 装 ffmpeg；必要时在采集命令里指定编码参数 |
| CUDA out of memory | batch size 过大或图像分辨率过高 | 调小 batch size，或降低输入分辨率 |
| 训练时 loss 不下降 | 数据集 fps 与配置不一致，或动作未归一化 | 核对数据集的 fps 与训练配置；确认使用了正确的统计量 |
| 推理时动作方向相反 | 标定文件缺失或与当前机器人不匹配 | 重新执行标定流程，确认标定文件路径正确 |
| 数据集加载很慢 | 视频解码瓶颈，或本地磁盘 IO 不足 | 把数据集放本地 SSD；适当降低图像分辨率 |
| Hub 下载中断 | 网络受限 | 配置镜像或提前用 huggingface-cli download 拉全量 |
硬件方面，LeRobot 官方生态里最典型的是 SO-100 / SO-101 这类低成本舵机机械臂，主从双臂成对使用：主臂由人拖动产生演示动作，从臂复现并记录状态。舵机通常使用 Feetech 或 Dynamixel 系列，通信走 USB 转串口。也支持 ALOHA 双臂平台、Koch 机械臂等。摄像头一般用普通 USB 摄像头，一路拍全局、一路拍腕部特写，是常见的双路配置。
