3. 开发环境搭建
LeRobot 的实机部署对运行环境非常敏感：同一份源码，在 Python 版本、PyTorch 与 CUDA 版本、驱动版本不匹配时，往往会在导入阶段或首次连接机械臂时直接失败。因此，环境搭建不是“装几个包”的机械操作，而是把驱动层、CUDA 运行时、PyTorch 计算后端、LeRobot 源码与硬件 SDK 五层对齐的过程。本节按“先隔离、再对齐、后验证”的顺序，给出可复现的搭建路径。
一、核心原理：五层依赖必须版本对齐
LeRobot 运行在 Python 之上，但真正决定能否跑通实机的是底层链路。可以把它理解为一条自下而上的依赖链：GPU 驱动决定可支持的最高 CUDA 版本；CUDA 运行时决定 PyTorch 能编译出哪个 cu 版本；PyTorch 版本又决定 LeRobot 与部分策略库（如 diffusers、transformers）的兼容范围；最后，硬件 SDK（如 Feetech/Dynamixel 串口驱动、相机 SDK）决定实机通信是否可用。任何一层“越级”都会在运行时报错。
关键结论：不要先装 LeRobot 再补 CUDA。正确顺序是先确定 GPU 驱动 → 选定 CUDA → 安装匹配的 PyTorch → 再安装 LeRobot 及其依赖。
二、方法流程：从零到可运行的四步
- 创建隔离环境。推荐 Python 3.10（LeRobot 对 3.10/3.11 支持最稳），使用 conda 或 venv 隔离，避免污染系统 Python。
- 安装匹配的 PyTorch。先查驱动支持的 CUDA 上限，再选择对应 cu 版本的 PyTorch 安装命令。
- 克隆并编译 LeRobot 源码。使用可编辑安装，便于后续修改策略与硬件接口。
- 验证硬件链路。检查串口设备、权限、相机枚举，再运行最小实机脚本。
# 1. 创建环境
conda create -n lerobot python=3.10 -y
conda activate lerobot
# 2. 安装 PyTorch（示例：CUDA 12.1）
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 .
# 4. 验证
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
python -c "import lerobot; print(lerobot.__version__)"三、CUDA 配置与常见问题对照
CUDA 配置的核心是“驱动版本 ≥ 运行时版本 ≥ PyTorch 编译版本”。下表列出实机部署中最常见的报错与处理方式，可作为排障清单使用。
| 现象 / 报错 | 根因 | 处理方式 |
|---|---|---|
| torch.cuda.is_available() 返回 False | PyTorch 装成 CPU 版，或 CUDA 与驱动不匹配 | 重装对应 cu 版本 PyTorch，核对 nvidia-smi 的 CUDA Version |
| CUDA error: no kernel image is available | PyTorch 编译架构与 GPU 算力不匹配 | 安装支持该算力的 PyTorch 版本，或设置 TORCH_CUDA_ARCH_LIST 重新编译 |
| ImportError: libcudart.so 找不到 | CUDA 运行时未加入 LD_LIBRARY_PATH | 在 ~/.bashrc 中导出 CUDA_HOME 与 LD_LIBRARY_PATH |
| Permission denied: /dev/ttyACM0 | 当前用户不在 dialout 组 | sudo usermod -aG dialout $USER 后重新登录 |
| pip install -e . 卡在编译依赖 | 缺少 build 工具或网络超时 | 先升级 pip/setuptools/wheel，必要时配置国内镜像源 |
四、案例与复盘：一次典型的“能训练不能实机”故障
某团队在服务器上完成了 ACT 策略训练，loss 正常下降，但把模型搬到实机工控机后，脚本在连接机械臂时卡死。排查发现：工控机上 LeRobot 是用系统 Python 安装的，PyTorch 为 CPU 版，且串口权限未配置。训练端与部署端环境不一致，导致“训练能跑、实机不能动”。
复盘要点：训练机与实机必须使用同一份 requirements 锁定文件；部署前先跑
python -c "import torch;print(torch.cuda.is_available())" 与串口回环测试，再加载策略。环境问题应在加载模型之前暴露，而不是在机械臂动作时暴露。
建议：把环境搭建过程写成
setup.sh 并纳入版本管理，记录 Python、PyTorch、CUDA、LeRobot commit 四个版本号。这样在换机、重装或多人协作时，可以快速复现同一环境，减少“我这里能跑”的沟通成本。