2. 环境搭建
LeRobot 是建立在 Python 与 PyTorch 之上的机器人模仿学习工程框架，它的运行依赖一条完整的软件栈：从 Python 解释器、包管理工具，到 PyTorch 与 CUDA 运行时，再到 LeRobot 源码、机器人 SDK 与硬件通信接口。环境搭建的目标不是“装上就行”，而是让版本、驱动、设备权限与硬件接口形成一条可复现、可诊断的链路。本节按“基础解释器 → 深度学习后端 → 源码与依赖 → 硬件接口”的顺序展开，并给出常见故障的排查思路。
一、核心原理：环境是一条分层依赖链
LeRobot 的运行链路可以理解为四层：最底层是操作系统与硬件驱动（USB、串口、CAN、摄像头、GPU 驱动）；其上是 Python 运行时与虚拟环境；再上是 PyTorch、NumPy、OpenCV 等计算与感知库；最上层才是 LeRobot 源码及其机器人适配模块。任何一层版本错配，都会在上层表现为“导入失败”“设备打不开”或“训练时显存报错”。因此搭建时应自下而上逐层验证，而不是一次性安装全部依赖。
二、方法流程：四步完成可复现环境
- 准备 Python 运行时。推荐 Python 3.10 或 3.11，避免使用过新的 3.13 造成部分轮子缺失。使用虚拟环境隔离依赖，不要污染系统 Python。
- 安装 PyTorch 后端。根据是否有 NVIDIA GPU 选择 CPU 版或 CUDA 版，并让 torch 与 CUDA 驱动版本匹配。
- 获取 LeRobot 源码并安装依赖。克隆仓库后以可编辑模式安装，便于后续修改机器人适配代码。
- 配置硬件接口与权限。确认串口、相机、CAN 设备节点存在，并把当前用户加入相应设备组。
# 1. 创建并激活虚拟环境
python3.10 -m venv ~/lerobot-env
source ~/lerobot-env/bin/activate
# 2. 安装 PyTorch（CUDA 12.1 示例，CPU 版去掉 --index-url 行）
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
# 3. 获取 LeRobot 源码并以可编辑模式安装
git clone https://github.com/huggingface/lerobot.git
cd lerobot
pip install -e ".[aloha,pusht]"
# 4. 验证关键依赖
python -c "import torch, lerobot; print(torch.__version__, torch.cuda.is_available())"setup_env.sh 脚本，并在 README 中记录 Python、PyTorch、CUDA 与 LeRobot 的提交哈希，形成可复现的环境快照。三、依赖管理与硬件接口配置要点
LeRobot 的依赖分为核心依赖与可选依赖（extras）。核心依赖保证数据集与策略可运行，可选依赖对应具体机器人平台，例如 aloha、pusht、koch 等。安装时按需选择，避免一次性安装全部 extras 导致版本冲突。硬件接口方面，Linux 下串口设备通常为 /dev/ttyACM* 或 /dev/ttyUSB*，相机为 /dev/video*，CAN 总线需先加载 can 模块并配置比特率。
| 配置对象 | 典型值 / 命令 | 验证方式 |
|---|---|---|
| Python 版本 | 3.10 / 3.11 | python --version |
| PyTorch + CUDA | torch 2.x + cu121 | torch.cuda.is_available() |
| LeRobot 安装 | pip install -e ".[aloha]" | python -c "import lerobot" |
| 机械臂串口 | /dev/ttyACM0 | ls /dev/ttyACM* |
| 相机设备 | /dev/video0 | v4l2-ctl --list-devices |
| 设备权限 | sudo usermod -aG dialout $USER | 重新登录后 groups |
四、案例与误区复盘
一个常见场景是：用户安装完 LeRobot 后运行遥操作脚本，报错 Permission denied: '/dev/ttyACM0'。这并非代码问题，而是当前用户不在 dialout 组。执行 sudo usermod -aG dialout $USER 后重新登录即可解决。另一个高频问题是 torch.cuda.is_available() 返回 False，通常由三种原因造成：安装了 CPU 版 torch、CUDA 驱动版本低于 torch 要求、或虚拟环境未激活导致调用了系统 Python。
sudo pip install 安装 LeRobot 依赖，这会把包写入系统目录并造成权限混乱；也不要在多个虚拟环境之间混用同一份源码目录，否则 pip install -e 的路径记录会互相覆盖。复盘时建议按“解释器 → PyTorch → LeRobot → 设备节点 → 权限”的顺序逐层检查，每层只用一个最小命令验证，例如 python -c "import torch"、ls /dev/ttyACM*、groups。把每一步的输出记录到环境日志中，后续换机或重装时可直接对照，显著降低重复排障成本。