LeRobot新手入门指南：3条命令跑通端到端机器人学习

LeRobot新手入门指南：3条命令跑通端到端机器人学习

【免费下载链接】lerobot🤗 LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot

LeRobot 是 Hugging Face 开源的 PyTorch 机器人学习框架，覆盖机器人数据采集、策略训练、真机部署的完整链路，适合想入门具身智能但被硬件细节劝退的开发者。读完这篇 LeRobot 入门教程，你能独立加载一个标准机器人数据集，并启动一次真实策略的训练。

🤖 为什么值得从 LeRobot 学机器人

想象一下：你桌上有一台 SO-100 桌面机械臂，希望它学会"抓取杯子"。传统路线是手动写控制逻辑、标定运动学、调参，链路长且结果难以泛化。更直接的思路是演示学习——你手动演示几十遍，让模型自己从数据中学到动作规律，这正是 LeRobot 主打的端到端学习路线。

再想象另一个场景：你拿到几份别人录制的操作数据，一份是视频，一份是关节角度日志，字段名互不相同，根本没法合并训练。机器人社区的数据长期是碎片化的，LeRobot 用统一的LeRobotDataset 格式解决了这个问题：视觉数据存 MP4 视频（或图片），状态和动作存 Parquet 表格，两者按帧严格对齐，Hub 上已有数千个现成数据集可直接调用。

📦 最小运行：装好环境，加载第一个数据集

1. 环境准备：Python 3.12 与安装 LeRobot

LeRobot 要求 Python ≥ 3.12（见 pyproject.toml）。如果视频解码出错，可能还需要ffmpeg——它负责把数据集里的 MP4 解码成图像，部分平台会自动降级用 pyav 兜底。

git clone https://gitcode.com/GitHub_Trending/le/lerobot cd lerobot pip install -e ".[dataset]"

.[dataset]这个 extra 装的是数据集读写所需的依赖（datasets、pyarrow、视频解码库等）。装完可以运行lerobot-info查看系统信息摘要，确认 PyTorch、ffmpeg 版本都在。

2. 最小运行：加载 aloha_mobile_cabinet 数据集

from lerobot.datasets.lerobot_dataset import LeRobotDataset dataset = LeRobotDataset("lerobot/aloha_mobile_cabinet") print(dataset[0]["action"].shape)

第一次加载时会自动从 Hugging Face Hub 下载并缓存到本地。这里选aloha_mobile_cabinet是因为它是一个经典的双臂操作任务数据集，官方示例训练默认就用它。

3. 结果验证：确认动作数据的形状

如果终端打印出类似(1, 14)的形状，说明视频解码、数据索引、特征字段都工作正常——这个数据集里"action"是双臂各关节的 14 维目标角度。再随手取一个键看看还有没有observation.state、task（任务描述）等字段，你就已经摸到了 LeRobotDataset 的完整结构。

⚙️ LeRobot 内部：四个值得理解的设计概念

LeRobotDataset（标准数据集格式）：上面用到的核心。视频/图片负责"看得见"，Parquet 负责"读得动"，加载器自动完成视频解码，代码里你只拿到对齐好的张量和数值。格式细节在 docs/source/lerobot-dataset-v3.mdx。

Robot 统一接口：所有真机都被抽象成同一个Robot类——connect()连接、get_observation()读传感器、send_action()下发动作。换一台机器人只需换配置和类名，上层控制逻辑一行不用改。SO100、LeKiwi、Koch、Unitree G1、Reachy2 等设备都已内置支持。

Policy（策略模型）：LeRobot 用纯 PyTorch 实现了主流策略，按用途分五类：

VLA 即 Vision-Language-Action 模型，简单说就是"看懂画面、听懂指令、直接输出动作"的端到端模型，右图就是这类策略的典型架构：视觉语言主干编码观察，注意力模块生成动作序列。

Processor（处理器管线）：喂给策略之前，观测和动作要经过归一化、重命名、设备搬运等一系列加工。LeRobot 把这些做成可组合的处理器链，挂在策略的前后处理位置，新手训练时无需关心，调优时可以逐层查看。实现都在 src/lerobot/processor/。

🔧 实战：训练并评估一个 ACT 策略

挑最典型的一条完整链路走一遍：输入是 Hub 上的aloha_mobile_cabinet数据集，处理是 ACT 策略的训练循环，输出是可复用的模型检查点。

输入 → 处理：训练就是一个配置驱动的脚本，指定策略类型和数据集即可：

lerobot-train \ --policy.type=act \ --dataset.repo_id=lerobot/aloha_mobile_cabinet

训练过程中按步保存检查点到本地，配置会写入train_config.json，之后可用--config_path指向任意检查点加--resume=true断点续训；也可以把训好的模型直接推送到 Hub 与他人共享。

处理 → 输出：模型训好后，下一步通常是评估。LeRobot 内置了 LIBERO、MetaWorld 等仿真基准，一条命令即可跑：

lerobot-eval \ --policy.path=lerobot/pi0_libero_finetuned \ --env.type=libero \ --env.task=libero_object \ --eval.n_episodes=10

这里的--policy.path也可以指向你自己刚训出的本地检查点目录，n_episodes控制评测回合数，跑完会输出成功率等指标。真机评测则走同一套接口，只是把仿真环境换成机器人。

❓ 自救手册：新手最容易卡住的四个问题

问：pip 安装报错或功能缺失？先确认 Python 版本 ≥ 3.12，再按需补装 extra：录制/回放真机数据装.[core_scripts]，训练装.[training]，全都要装.[all]。extra 清单在 pyproject.toml 里都有注释。

问：加载数据集时报视频解码错误？通常是缺ffmpeg，用包管理器装一个即可；部分平台（如 Intel 版 macOS、Linux ARM）TorchCodec 不提供 wheel，框架会自动回退到 pyav，无需额外操作。

问：连不上机器人或摄像头？确认装了硬件相关 extra（如.[feetech]、.[hardware]），然后按顺序排查：USB 是否插稳、系统是否给当前用户开放了串口/摄像头权限（Linux 上常需把用户加入 dialout/video 组）、驱动是否就绪。lerobot-find-cameras和lerobot-find-port可以帮你定位设备。

问：显存不够训不起来？换更小的策略（如 SmolVLA 这类轻量 VLA），训练配置里开启 bf16 混合精度；官方文档 docs/source/hardware_guide.mdx 给出了每个策略的 GPU 显存和训练时长参考。

LeRobot 把"采数据、训策略、上真机"压进了同一套工具和格式里，新手最大的收益是可以用几行代码接触到原本需要搭一套系统才能做的事。沿着下面的入口继续挖，可以覆盖从数据集到策略的全部细节：

• 官方文档：docs/source/
• 策略模型实现：src/lerobot/policies/
• 数据集模块：src/lerobot/datasets/
• 训练示例脚本：examples/training/train_policy.py
• 贡献指南：CONTRIBUTING.md

【免费下载链接】lerobot🤗 LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot