3. 数据采集环境搭建
数据采集是 LeRobot 工作流的起点，而环境搭建决定了后续采集能否稳定、可复现地运行。本节围绕一条主线展开：先准备隔离的 Python 环境，再安装 LeRobot 及其依赖，最后完成硬件连接与驱动检查。整个过程的核心原则是版本可控、依赖隔离、链路可验证。只要这三步做到位，后续的遥操作采集、相机录制与数据集写入就会顺畅很多。
一、核心原理：为什么环境搭建要分三层
LeRobot 采集环境可以理解为三层结构：运行时层（Python 解释器与虚拟环境）、软件层（LeRobot 包及其依赖，如 PyTorch、NumPy、OpenCV、串口库等）、硬件层（机械臂、相机、遥操作主臂、USB/串口连接与驱动）。三层之间是逐层依赖的关系：运行时层决定软件层能否安装成功，软件层决定硬件层能否被正确调用。任何一层出问题，都会表现为“采集脚本报错”或“设备无响应”。
因此，推荐使用 conda 或 venv 创建独立环境，避免与系统 Python 或其他项目冲突。Python 版本建议选择 3.10 或 3.11，这两个版本对 PyTorch 与 LeRobot 的兼容性较好。安装 LeRobot 时优先从源码安装，便于后续切换到特定分支或提交版本，保证采集行为可复现。
二、方法流程：从零到可采集
- 创建并激活虚拟环境：使用 conda 创建独立环境，指定 Python 3.10。
- 安装 LeRobot：克隆源码仓库，进入目录后以可编辑模式安装。
- 安装依赖：根据是否有 NVIDIA GPU 选择 PyTorch 安装命令，再补齐 OpenCV、pyserial 等采集必需库。
- 连接硬件：接入从动臂、主臂与相机，确认串口与视频设备节点。
- 驱动与权限检查：将当前用户加入 dialout 组，检查设备权限与串口通信。
- 最小验证：运行 LeRobot 命令，确认环境与设备均可用。
# 1. 创建并激活环境
conda create -n lerobot python=3.10 -y
conda activate lerobot
# 2. 获取并安装 LeRobot
git clone https://github.com/huggingface/lerobot.git
cd lerobot
pip install -e .
# 3. 安装 PyTorch（示例：CUDA 12.1）
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
# 4. 采集常用依赖
pip install opencv-python pyserial numpy
# 5. 硬件与权限检查
ls /dev/ttyUSB* /dev/video*
sudo usermod -aG dialout $USER
sudo udevadm control --reload-rules && sudo udevadm trigger
# 6. 最小验证
python -c "import lerobot, torch, cv2; print('env ok')"
三、案例场景：一台 SO-100 采集站的搭建
假设我们使用一台 Ubuntu 22.04 主机，连接 SO-100 从动臂、SO-100 主臂和一台 USB 相机。按上述流程操作后，ls /dev/ttyUSB* 应看到两个串口设备，ls /dev/video* 应看到相机节点。若串口只出现一个，通常是 USB 转串口线未插紧或供电不足；若相机节点缺失，可尝试更换 USB 口或检查 v4l2-ctl --list-devices 输出。
随后运行 LeRobot 的设备枚举或遥操作测试命令，观察主臂动作是否能映射到从臂。若主臂无响应，优先检查串口号是否写错、波特率是否匹配、用户是否在 dialout 组中。完成这一步后，即可进入正式的数据采集环节。
四、常见误区与复盘清单
| 误区 | 典型表现 | 排查与修正 |
|---|---|---|
| 直接使用系统 Python | 依赖冲突，安装报错 | 改用 conda/venv 隔离环境 |
| PyTorch 与 CUDA 版本不匹配 | torch.cuda.is_available() 为 False | 按官方索引重新安装对应版本 |
| 串口号写错或权限不足 | Permission denied / 设备无响应 | 确认 /dev/ttyUSB* 并加入 dialout 组 |
| 相机被其他程序占用 | OpenCV 无法读取帧 | 关闭占用进程，重新插拔相机 |
| 未做最小验证就正式采集 | 采集中途报错，数据不完整 | 先跑通枚举与遥操作测试 |
完成本节的环境搭建后，你已经具备了一个可运行、可验证的 LeRobot 采集基础。接下来只需在此基础上接入具体的采集流程，即可开始录制第一条机器人数据。