LeRobot 实战指南：一条命令链跑通机器人数据采集与策略训练
【免费下载链接】lerobot🤗 LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot
当你需要让机械臂学会一个抓取任务时，流程通常是：遥操作演示 → 录制数据集 → 训练策略 → 部署回机器人。LeRobot 是 Hugging Face 开源的端到端机器人学习框架，把这条链路封装成了一套 CLI 命令和统一 API：你不需要自己写串口驱动或视频解码，lerobot-record、lerobot-train、lerobot-rollout各管一环，数据集、策略模型、硬件配置都通过配置文件描述。
一、LeRobot 解决什么问题
硬件抽象层——src/lerobot/robots/下注册了 SO-100/SO-101、LeKiwi、OpenARM、Koch、Reachy2、Unitree G1 等十余种机器人，串口、相机、舵机总线全部封装在统一接口后面。换一台机器臂，你只需要改--robot.type和端口参数，训练代码一行不动。
统一数据集格式——LeRobotDataset把视觉数据存成 MP4 视频、状态动作存成 Parquet 列式文件，再配 JSON 元数据。这种"视频 + 列式数据"的混合结构让几小时演示数据的读取速度远快于逐帧图像，且可以直接托管到 Hugging Face Hub 做版本管理。
策略即插即用——src/lerobot/policies/注册了 20 余个策略实现，从经典的 ACT、Diffusion Policy 到 pi0/pi05、SmolVLA、GR00T 等视觉-语言-动作模型，全部通过同一个工厂函数按名字实例化，预处理器/后处理器管线随策略配置自动重建。
覆盖完整工具链——标定（lerobot-calibrate）、遥操作（lerobot-teleoperate）、标注（lerobot-annotate）、评估（lerobot-eval）都是独立命令，组合起来就是一条从硬件到模型的流水线。
视觉-语言-动作模型在 LeRobot 中的数据处理流程，源码见
src/lerobot/policies/
二、三步完成环境搭建与验证
第 1 步：创建环境。官方文档要求 Python ≥ 3.12（uv 路径）；conda 用户按docs/source/installation.mdx建 3.12 环境：
# 创建独立 conda 环境并激活 conda create -y -n lerobot python=3.12 conda activate lerobot第 2 步：按工作流装 extras。基础包故意做得很轻，硬件、训练、可视化依赖都拆成了 extras，装哪些取决于你要跑什么命令：
# 从源码安装（PyPI 安装则去掉 -e . 换成 lerobot） pip install -e ".[core_scripts]" # 录数据/回放/标定 pip install -e ".[training]" # 训练策略（含 accelerate、wandb）第 3 步：验证安装。lerobot-info是唯一一个"不装依赖也能跑"的脚本，会打印版本、Python、CUDA、GPU 型号，是排查环境问题的第一现场：
# 打印系统与环境摘要，确认 CUDA 可用 lerobot-info三个平台的差异点：
| 平台 | 视频解码 | 额外操作 |
|---|---|---|
| Linux x86_64 | TorchCodec（GPU 解码） | 需装 ffmpeg：conda install ffmpeg -c conda-forge |
| Apple Silicon | TorchCodec（MPS） | 无额外操作 |
| macOS Intel / Linux ARM | 自动回退 pyav | 可跳过 ffmpeg |
WSL 用户注意：遥操作依赖 evdev，需
conda install evdev -c conda-forge，详见docs/source/installation.mdx。
三、核心模块拆解：机器人、数据集、策略工厂
硬件抽象层：一个工厂函数实例化所有机器人
# 从配置对象构建机器人，type 字段决定具体实现 from lerobot.robots import RobotConfig, make_robot_from_config cfg = RobotConfig(type="so101_follower", port="/dev/ttyACM0", id="my_arm") robot = make_robot_from_config(cfg) # 自动查注册表、连接串口、加载标定文件所有机器人类型都通过@RobotConfig.register_subclass("so101_follower")这样的装饰器注册（见src/lerobot/robots/so_follower/config_so_follower.py），注册表同时支持第三方插件，所以"支持的机器人"清单实际比仓库里的目录更多。
数据集层：LeRobotDataset
视频存 MP4、状态动作存 Parquet，lerobot/datasets/lerobot_dataset.py里的LeRobotDataset把它们拼成一个标准torch.utils.data.Dataset：按 episode 索引、支持流式编码、内置特征统计量（均值/标准差/分位数，供策略归一化用）。录制时的编码参数（如--dataset.rgb_encoder.crf=23）在这里被消费。
策略工厂：按名字注册，按名字实例化
# 名字 → 配置类 → 策略类，全程无需手动 import 模型 from lerobot.policies.factory import get_policy_class, make_policy_config policy_cls = get_policy_class("act") # "act"/"diffusion"/"pi05" 等注册名 config = make_policy_config("act", hidden_dim=512)内置策略按形态大致分三类：
| 策略名 | 类型 | 特点 |
|---|---|---|
act、vqbet | 行为克隆 | 轻量，机械臂任务首选起点 |
diffusion、multi_task_dit | 扩散策略 | 多模态动作分布建模 |
pi0、pi05、smolvla、groot | 视觉-语言-动作 | 支持语言指令，模型较重 |
另有tdmpc（模型预测控制）、hilserl（HIL-SERL 强化学习，见src/lerobot/rl/）。
四、实战工作流：从遥操作到部署的 5 条命令
以 SO-101 双臂为例，一条完整链路的命令序列（串口名请替换成你机器上的实际值）：
- 找设备：
lerobot-find-port定位串口（拔掉 USB 线按回车即可识别），lerobot-find-cameras验证相机输出。 - 标定（每台机器做一次）：
# 舵机标定，id 命名后续命令必须保持一致 lerobot-calibrate --robot.type=so101_follower \ --robot.port=/dev/ttyACM0 --robot.id=my_follower_arm - 录制数据集：
# 遥操作录制 30 个 episode，完成后上传 Hub lerobot-record --robot.type=so101_follower \ --robot.port=/dev/ttyACM0 --robot.id=my_follower_arm \ --teleop.type=so101_leader --teleop.port=/dev/ttyACM1 --teleop.id=my_leader_arm \ --dataset.repo_id=${HF_USER}/so101_demo --dataset.num_episodes=30 \ --dataset.single_task="put the red brick in a bowl" --display_data=true录制中按
→保存并进入下一段、←丢弃重来、ESC停止并上传。 - 训练策略：
# 用 ACT 策略训练 20000 步，结果保存到 outputs/train/ lerobot-train --dataset.repo_id=${HF_USER}/so101_demo \ --policy.type=act --policy.device=cuda --steps=20000 \ --output_dir=outputs/train/act_so101 --job_name=act_so101 - 部署回机器人：
# base 策略做 60 秒推理，相机配置必须与录制时一致 lerobot-rollout --strategy.type=base \ --policy.path=outputs/train/act_so101 \ --robot.type=so101_follower --robot.port=/dev/ttyACM0 \ --task="put the red brick in a bowl" --duration=60
没有本地 GPU 时，给lerobot-train加--job.target=a10g-small，训练会跑在 Hugging Face Jobs 的远端实例上；中断的训练用--config_path=<检查点> --resume=true续跑。
五、高频报错速查：现象→原因→解法
串口连接失败
SerialException: /dev/ttyACM0 could not be opened- 确认设备确实插在预期端口：
lerobot-find-port。 - Linux 下把用户加入
dialout组后重新登录：sudo usermod -aG dialout $USER。 - 检查
--robot.port与标定/录制时用的是否同一个口。
视频解码不可用
TorchCodec is not available on this platform框架会自动回退到 pyav 解码，功能不受影响，只是没有 GPU 加速。若需要 TorchCodec：macOS Intel、Linux ARM 目前不支持（见官方文档）；Linux x86 上确认conda install ffmpeg -c conda-forge已执行，再用lerobot-info核对 ffmpeg 版本。
训练显存不足
torch.cuda.OutOfMemoryError: CUDA out of memory- 先降
--batch_size，这是收益最大的旋钮。 - 换成更轻的起点：
pi05换smolvla，diffusion换act。 - 仍不够就加
--job.target=<flavor>挪到更大的远端 GPU。
推理时观测 key 不匹配
现象：lerobot-rollout启动即报特征不一致，提示缺少observation.images.xxx。原因是 rollout 时的相机名与录制时不一致——相机配置必须逐字匹配（名称、分辨率、fps），这是跨设备部署最常见的坑。
SO-100 在真实任务中的执行画面，对应
examples/so100_to_so100_EE/示例目录
六、生态、社区与演进方向
- 示例仓库：
examples/下有 lekiwi、omx、phone_to_so100、isaac_teleop_to_so101 等完整工作流，examples/notebooks/quickstart.ipynb是官方推荐的交互式入口。 - 命令速查：
docs/source/cheat-sheet.mdx汇总了全部 CLI 命令及参数，忘参数时翻这里最快。 - 硬件接入：
docs/source/integrate_hardware.mdx说明如何按src/lerobot/robots/的模板写自己的机器人驱动。 - 评测与基准：
src/lerobot/envs/内置 LIBERO、Meta-World、RoboCasa、RoboTwin 等仿真环境，配合lerobot-eval做策略评估。 - 演进方向：流式视频编码、HIL-SERL 强化学习管线、多 GPU 训练（
src/lerobot/distributed/）是近期迭代最活跃的三块；路线图细节建议查阅官方文档确认。
进阶阅读：想理解策略注册与预处理器机制，直接读src/lerobot/policies/factory.py的get_policy_class和src/lerobot/processor/pipeline.py。
七、行动路线图：从复现到贡献
- 克隆仓库并跑通
pip install -e ".[core_scripts]"+lerobot-info。 - 选一个
examples/示例（无硬件可从examples/notebooks/quickstart.ipynb开始）复现一遍。 - 用
lerobot-record+lerobot-train在自己的数据上训练一个act策略。 - 跑通
lerobot-eval在仿真环境里评估它。 - 从
docs/source/的文档勘误或CONTRIBUTING.md指引的第一个 issue 开始贡献。
LeRobot 的价值在于把"机器人学习"从硬件工程拉回到算法迭代本身——装好环境，今天就跑通第一条记录命令。
【免费下载链接】lerobot🤗 LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
