Linux环境下用LeRobot实现主从臂数据采集：从配置到避坑全流程
机器人技术正在经历一场由开源工具推动的革命。在众多创新项目中，Hugging Face推出的LeRobot以其端到端学习框架和易用性脱颖而出，成为机器人开发者的新宠。本文将带您深入探索如何在Linux系统中配置LeRobot环境，完成主从臂数据采集的全流程操作，并分享实际项目中积累的避坑经验。
1. 环境准备与基础配置
1.1 系统要求与依赖安装
LeRobot对Linux环境有特定要求，推荐使用Ubuntu 20.04或更高版本。以下是基础环境配置步骤：
# 克隆项目仓库 git clone https://github.com/huggingface/lerobot.git ~/lerobot # 创建Python虚拟环境 conda create -y -n lerobot python=3.10 conda activate lerobot # 安装核心依赖 cd lerobot && pip install -e ".[feetech]"需要特别注意的依赖项包括：
- FFmpeg：用于视频流处理
- OpenCV 4.10.0+：计算机视觉支持
- Git LFS：大文件存储管理
1.2 硬件连接检查
主从臂配置需要确保：
- USB转串口设备被正确识别
- 各关节舵机供电稳定
- 控制板与计算机的通信正常
使用以下命令验证设备连接：
ls /dev/ttyUSB* dmesg | grep -i usb2. 数据采集核心流程
2.1 初始化采集参数
LeRobot的数据采集脚本提供丰富的配置选项，关键参数包括：
| 参数 | 说明 | 推荐值 |
|---|---|---|
| --fps | 采集帧率 | 30 |
| --warmup-time-s | 设备预热时间 | 5 |
| --episode-time-s | 单次采集时长 | 40 |
| --reset-time-s | 复位等待时间 | 10 |
2.2 执行数据采集
基础采集命令结构：
python lerobot/scripts/control_robot.py record \ --robot-path lerobot/configs/robot/so100.yaml \ --fps 30 \ --repo-id ${HF_USER}/so100_test \ --num-episodes 2 \ --push-to-hub 1提示：首次运行时建议添加
--verbose参数查看详细日志
2.3 高级采集模式
对于复杂任务，可以使用任务描述参数：
--single-task "Pick up and place the red block to the right zone"这会让系统记录完整的任务上下文信息，对后续模型训练至关重要。
3. 数据管理与上传
3.1 本地数据管理
采集的数据默认存储在data/目录下，结构如下：
data/ └── so100_test/ ├── episode_0/ │ ├── images/ │ ├── actions.npy │ └── meta.json └── episode_1/3.2 数据上传策略
上传到Hugging Face Hub时，有两种模式可选：
- 增量上传（推荐）：
--push-to-hub 1 --resume 1 - 覆盖上传：
--push-to-hub 1 --force-override 1
4. 常见问题解决方案
4.1 设备识别问题
若出现舵机无法识别的情况，检查：
- 电源供电是否充足
- 串口权限设置（通常需要将用户加入dialout组）
sudo usermod -a -G dialout $USER4.2 数据同步异常
当遇到数据上传失败时，可以尝试：
- 验证Hugging Face凭证：
huggingface-cli whoami - 检查网络连接：
ping huggingface.co - 使用本地缓存模式测试：
--local-files-only 1
4.3 性能优化技巧
对于高频率采集（>30fps），建议：
- 使用SSD存储
- 关闭不必要的后台进程
- 降低图像分辨率（通过修改config文件）
5. 数据可视化与回放
LeRobot提供强大的数据可视化工具：
python lerobot/scripts/visualize_dataset_html.py \ --repo-id ${HF_USER}/so100_test回放特定episode的命令示例：
python lerobot/scripts/control_robot.py replay \ --robot-path lerobot/configs/robot/so100.yaml \ --episode 0 \ --speed 0.5 # 控制回放速度在实际项目中，我们发现合理设置--warmup-time-s参数能显著提高首次采集的稳定性。对于SO100主从臂配置，5秒的预热时间足够让所有舵机达到理想工作状态。
