LeRobot 机器人学习库实战指南：统一机器人接口、标准化数据集与端到端策略训练

LeRobot（Hugging Face 开源的 PyTorch 机器人学习库）以"让机器人的端到端学习更易用"为目标，把统一机器人控制接口、标准化数据集格式（LeRobotDataset）、SOTA 策略模型训练、真机/仿真评估串成一条完整链路。本文以仓库 README.md 为骨架，结合 src/lerobot 源码，带你掌握：从 pip install lerobot 到用一行命令训练 ACT/Pi0 等策略、再到在 LIBERO 仿真或自研机器人上部署推理的完整实战路径。

一、LeRobot 是什么：定位与设计哲学

LeRobot 的目标是为真实世界机器人提供 PyTorch 生态下的模型、数据集与工具，核心是降低入门门槛，让每个人都能基于共享数据集与预训练模型做出贡献。其技术路线由四个支柱构成（对应 README.md 开篇）：

• 硬件无关的统一接口：一个 Python 原生的 Robot 抽象类，标准化从低成本机械臂（SO-100）到人形机器人的控制协议；
• 标准化、可扩展的数据集格式：LeRobotDataset 采用 Parquet + MP4（或图片）存储，托管于 Hugging Face Hub，支持大规模数据的存储、流式加载与可视化；
• 可部署到真机的 SOTA 策略：覆盖模仿学习、强化学习、VLA（视觉-语言-动作）模型、世界模型与奖励模型；
• 开源生态支持：通过命名前缀插件机制，第三方机器人、遥操作设备、相机可被自动发现。

从代码结构看，这一设计落地为清晰的模块划分：src/lerobot/robots（机器人）、src/lerobot/datasets（数据集）、src/lerobot/policies（策略）、src/lerobot/envs（仿真环境）与 src/lerobot/scripts（CLI 入口），并通过 src/lerobot/processor 中的可组合处理器完成"数据集 → 策略 → 机器人"之间的数据变换。

二、快速开始：安装与系统自检

LeRobot 可直接从 PyPI 安装：

pip install lerobot
lerobot-info

lerobot-info 是安装后的第一步自检工具，其实现位于 src/lerobot/scripts/lerobot_info.py，它会以 Markdown 列表形式输出：

• 运行环境：LeRobot 版本、平台、Python 版本、HuggingFace Hub / Transformers / Datasets / NumPy / FFmpeg 版本；
• GPU 能力：PyTorch 版本、Torchcodec 版本、是否 CUDA 可用、CUDA 版本、当前 GPU 型号；
• 可用命令：通过读取包元数据的 console_scripts 入口，列出环境内已注册的全部 LeRobot CLI。

从 src/lerobot/scripts/lerobot_info.py 可以看出，该脚本在 torch 未安装时也能安全降级为 "N/A"，方便在裸环境中先排查问题。若需要详细安装指引（含硬件驱动、ffmpeg 等前置依赖），参见仓库文档 docs/source/installation.mdx。完整 CLI 命令清单（lerobot-record、lerobot-train、lerobot-eval、lerobot-teleoperate、lerobot-calibrate、lerobot-find-port、lerobot-setup-motors、lerobot-replay 等）定义于 pyproject.toml。

安装注意事项：lerobot-info 只做系统信息汇总；训练、记录等命令依赖对应 extras。例如 SO-100/SO-101 的舵机驱动需安装 feetech 相关依赖，具体 extras 组合以 docs/source/installation.mdx 为准。

三、机器人控制：统一 Robot 接口与受支持硬件

LeRobot 通过统一的 Robot 抽象类解耦"控制逻辑"与"硬件细节"，其接口契约定义于 src/lerobot/robots/robot.py，所有机器人子类必须实现以下抽象成员：

成员	类型	职责
observation_features	property	描述观测的结构与类型（标量类型或数组形状），与 get_observation 返回结构一致
action_features	property	描述期望动作的结构与类型，与 send_action 入参结构一致
is_connected	property	是否已连接；未连接时调用读写接口应报错
connect(calibrate=True)	method	建立与硬件的通信，可选择连接后自动校准
is_calibrated / calibrate()	method	校准状态查询与校准执行（无校准需求的硬件应为 no-op）
configure()	method	一次性或运行时配置（电机参数、控制模式、初始状态等）
get_observation()	method	返回扁平的观测字典
send_action(action)	method	发送动作，返回实际下发（可能被安全限幅）的动作
disconnect()	method	断开连接并清理资源

此外，基类还通过 __enter__/__exit__/__del__ 提供了上下文管理器与析构安全网（robot.py），确保即使发生异常也能自动 disconnect 释放资源。

README 给出的最小使用范式如下（以自定义机器人 MyRobot 为例，实际替换为具体机器人类型）：

from lerobot.robots.myrobot import MyRobot

# Connect to a robot
robot = MyRobot(config=...)
robot.connect()

# Read observation and send action
obs = robot.get_observation()
action = model.select_action(obs)
robot.send_action(action)

原生支持的硬件

LeRobot 代码库内原生集成了以下硬件（README.md "Robots & Control" 一节）：

SO100、LeKiwi、Koch、HopeJR、OMX、EarthRover、Reachy2、Gamepads、Keyboards、Phones、OpenARM、Unitree G1、reBot B601。

从源码结构看，src/lerobot/robots 目录下每个子目录对应一类机器人（如 so_follower、koch_follower、lekiwi、unitree_g1、openarm_follower 等），src/lerobot/teleoperators 则对应遥操作端（so_leader、gamepad、keyboard、phone、homunculus 等），两者共用同一套 Robot 契约。

如果你有自研硬件，只需实现 Robot 接口，即可直接复用 LeRobot 的数据采集、训练与可视化工具链。详细接入教程见 docs/source/integrate_hardware.mdx。

四、LeRobotDataset：标准化机器人数据集格式

针对机器人领域"数据碎片化"问题，LeRobot 定义了 LeRobotDataset 格式，核心设计（README.md "LeRobot Dataset" 一节）：

• 结构：视觉数据用同步的 MP4 视频（或图片）存储，状态/动作数据用 Parquet 文件存储；
• HF Hub 集成：数据集托管于 Hugging Face Hub，可直接浏览、下载海量机器人数据集；
• 工具链：支持删除 episode、按索引/比例切分、增删 feature、合并多个数据集等操作。

从 Hub 加载数据集

from lerobot.datasets.lerobot_dataset import LeRobotDataset

# Load a dataset from the Hub
dataset = LeRobotDataset("lerobot/aloha_mobile_cabinet")

# Access data (automatically handles video decoding)
episode_index = 0
print(f"{dataset[episode_index]['action'].shape=}\n")

其底层实现位于 src/lerobot/datasets/lerobot_dataset.py：LeRobotDataset 继承自 torch.utils.data.Dataset，封装了三类内容——metadata（info 记录形状/键名/fps，stats 记录各模态归一化统计量，tasks 记录各任务 prompt，供任务条件训练使用）、data（由 datasets.Dataset 支撑、从 Parquet 读取）、videos（可选，帧加载与 Parquet 数据保持同步）。一个典型数据集的目录结构为：

.
├── data
│   ├── chunk-000
│   │   ├── file-000.parquet
│   │   ├── file-001.parquet
│   │   └── ...
│   └── ...
└── videos
    ├── chunk-000
    │   ├── observation.images.top.mp4
    │   └── ...
    └── ...

两种实例化模式

从 lerobot_dataset.py 的类文档可以确认，LeRobotDataset 支持两种加载方式：

1. 数据集已存在：本地磁盘（传入 root，可离线使用），或位于 Hugging Face Hub（传入 repo_id 自动下载）；旧版 v2.1 数据集会被提示用 scripts/convert_dataset_v21_to_v30.py 转换到 v3.0；
2. 数据集不存在：通过 create 类方法创建空数据集，用于录制新数据或把已有数据移植为 LeRobotDataset 格式。

数据集工具（合并、切分、增删 feature 等）的完整命令在 docs/source/using_dataset_tools.mdx 与 docs/source/lerobot-dataset-v3.mdx 中有详细说明，对应实现位于 src/lerobot/datasets/dataset_tools.py。

五、SOTA 策略模型与训练

LeRobot 用纯 PyTorch 实现了覆盖模仿学习、强化学习、VLA 模型、世界模型、奖励模型的 SOTA 策略，并提供训练过程的可观测与检视工具。训练一个策略只需运行一个脚本配置（README.md "SoTA Models" 一节）：

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

从 src/lerobot/scripts/lerobot_train.py 的实现看，lerobot-train 支持分布式训练：可用 torchrun --nproc-per-node=8 启动多卡训练，所有并行/加速参数都挂在配置上（--parallelism.*、--accelerator.*），例如 --parallelism.dp_shard=8 --accelerator.mixed_precision=bf16，保证一次运行可从 train_config.json 完整复现。

模型分类总览

Category	Models
Imitation Learning	ACT、Diffusion、VQ-BeT、Multitask DiT Policy
Reinforcement Learning	HIL-SERL、TDMPC 及即将推出的 QC-FQL
VLAs Models	Pi0、Pi0Fast、Pi0.5、GR00T N1.7、SmolVLA、XVLA、EO-1、MolmoAct2、WALL-OSS、EVO1
World Models	VLA-JEPA、LingBot-VA、FastWAM
Reward Models	SARM、TOPReward、Robometer

每一类策略的详细配置、训练与部署指南可进入上述文档阅读；GPU/RAM 需求与预期训练时长参见 docs/source/hardware_guide.mdx。

接入自定义策略

与硬件类似，你可以实现自己的策略并复用 LeRobot 的数据采集、训练与可视化工具，再把模型分享到 HF Hub。策略侧的接入指南见 docs/source/bring_your_own_policies.mdx；从代码结构看，所有策略均继承自 src/lerobot/policies/pretrained.py 中的 PreTrainedPolicy，并经由 src/lerobot/policies/factory.py 统一创建。

六、推理与评估：真机部署与仿真基准

使用统一的评估脚本，即可在仿真或真实硬件上评测策略。LeRobot 支持 LIBERO、MetaWorld 等标准基准：

# Evaluate a policy on the LIBERO benchmark
lerobot-eval \
  --policy.path=lerobot/pi0_libero_finetuned \
  --env.type=libero \
  --env.task=libero_object \
  --eval.n_episodes=10

评估脚本实现位于 src/lerobot/scripts/lerobot_eval.py，仿真环境（LIBERO、MetaWorld、RoboCasa 等）定义于 src/lerobot/envs。如果你想实现自己的仿真环境或基准，并将其通过 Hugging Face Hub 分发，可参考 docs/source/envhub.mdx（EnvHub 文档）以及 docs/source/adding_benchmarks.mdx。

七、第三方硬件生态：命名前缀插件自动发现

除了原生硬件，社区还维护着一个持续增长的插件生态，覆盖 UFACTORY xArm、Universal Robots UR5e、Franka、AgileX Piper、Trossen WidowX、ARX5、I2RT YAM、GELLO、SpaceMouse、Meta Quest、ROS 2 桥接、触觉/深度相机等（完整列表见 docs/source/third_party_robots.mdx 与 docs/source/third_party_sensors.mdx）。

插件的自动发现机制如下（README.md "Third-Party Hardware" 一节）：

LeRobot 会导入环境中任何以 lerobot_robot_、lerobot_teleoperator_ 或 lerobot_camera_ 前缀命名的已安装包。安装后，即可直接在 CLI 中使用它注册的 type。

其底层实现位于 src/lerobot/utils/import_utils.py 的 register_third_party_plugins()：该函数用 importlib.metadata 扫描环境中所有发行版（含 editable 安装），凡包名以 lerobot_robot_、lerobot_camera_、lerobot_teleoperator_、lerobot_policy_、lerobot_env_ 或 lerobot_strategy_ 开头即尝试导入，并记录成功/失败日志。该函数会被 lerobot-record、lerobot-train、lerobot-eval、lerobot-teleoperate、lerobot-calibrate、lerobot-replay、lerobot-rollout、lerobot-setup-motors 等所有主要 CLI 在入口处调用，因此第三方能力在命令行中"即装即用"：

pip install lerobot_robot_<name> lerobot_teleoperator_<name>

lerobot-record \
  --robot.type=<robot_name> \
  --teleop.type=<teleoperator_name> \
  --dataset.repo_id=${HF_USER}/my-dataset

八、生态资源与引用方式

围绕 LeRobot 还有以下官方生态资源（README.md "Resources" 一节）：

• Documentation：完整的教程与 API 指南（对应本仓库 docs/source/index.mdx）；
• LeLab：基于浏览器的 Web 界面，无需 CLI 即可完成 SO 机械臂的遥操作、校准、数据集录制、回放与训练；
• Robot Learning Tutorial：免费的动手实战课程；
• T-Shirt Folding Experiment：用 LeRobot 叠 T 恤的端到端演示。

引用

若在项目中使用 LeRobot，请按以下格式引用（README.md "Citation" 一节）：

@misc{cadene2024lerobot,
    author = {Cadene, Remi and Alibert, Simon and Soare, Alexander and Gallouedec, Quentin and Zouitine, Adil and Palma, Steven and Kooijmans, Pepijn and Aractingi, Michel and Shukor, Mustafa and Aubakirova, Dana and Russi, Martino and Capuano, Francesco and Pascal, Caroline and Choghari, Jade and Meftah, Khalil and Ellerbach, Maxime and Moss, Jess and Wolf, Thomas},
    title = {LeRobot: State-of-the-art Machine Learning for Real-World Robotics in Pytorch},
    howpublished = "\url{https://github.com/huggingface/lerobot}",
    year = {2024}
}

小结

LeRobot 的价值在于把"真实机器人学习"的全流程收敛为一套可复制的标准范式：Robot 抽象类让硬件接入有规可循，LeRobotDataset 让数据共享有统一格式，lerobot-train/lerobot-eval 让训练与评估下沉为一条命令，命名前缀插件机制则让整个生态可以持续生长。上手路径清晰：先 pip install lerobot && lerobot-info 自检环境，再用 lerobot-record 录制（或直接从 Hub 加载）数据集，接着用 lerobot-train --policy.type=act 训练策略，最后用 lerobot-eval 在 LIBERO 仿真或真机上验证闭环。