LeRobot机器人控制框架实战指南：三步跑通数据采集-训练-评测闭环

LeRobot机器人控制框架实战指南：三步跑通数据采集-训练-评测闭环

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

对熟悉 PyTorch、但不想碰机器人硬件驱动的工程师来说，进入端到端机器人学习的最大成本不在算法，而在串口、摄像头、数据格式对齐这些琐碎工作上。LeRobot 是 Hugging Face 开源的实境机器人学习框架，把采集、数据集管理、策略训练、仿真评测整条链路收敛到统一的 Python 接口上，让算法开发者可以直接面向接口写代码，而不必先成为硬件工程师。这篇文章基于仓库结构讲清楚三件事：LeRobot 解决什么问题、三步如何跑起来、核心模块的机制是什么。

它是什么，解决什么问题

LeRobot 的目标是"为真实世界机器人提供模型、数据集与工具"（当前版本 0.6.2，要求 Python 3.12+），覆盖模仿学习、强化学习、视觉-语言-动作（VLA）模型三大类任务。价值点可以压缩成三条：

• 硬件无关的统一控制接口：从 SO-100 低成本机械臂到 Unitree G1 人形机器人，都走同一组connect / get_observation / send_action调用，控制逻辑与硬件解耦
• LeRobotDataset 标准数据格式：MP4 视频（或图像）与 Parquet 状态/动作数据按帧同步存储，托管在 Hugging Face Hub 上，数千个现成数据集可以直接复用
• 开箱即训的策略库：ACT、Diffusion、TDMPC、Pi0、GR00T、SmolVLA 等全部纯 PyTorch 实现，命令行指定名字即可训练或部署

三步跑起来

第一步，安装。官方推荐直接从 PyPI 安装，lerobot[training]这个 extra 会把数据集依赖、accelerate、wandb 一并带上：

# 安装（Python >= 3.12），training 额外包含 dataset 依赖 pip install "lerobot[training]" # 验证安装状态与运行环境 lerobot-info

第二步，验证硬件。手头有设备的话，跑lerobot-find-port扫描串口、lerobot-find-cameras枚举摄像头，两者都是随包注册的子命令，无需额外安装。

第三步，最小可运行示例。没有硬件也能先把数据侧跑通——加载公开的 aloha_mobile_cabinet 数据集，视频解码由框架自动处理：

from lerobot.datasets.lerobot_dataset import LeRobotDataset # 从 Hugging Face Hub 加载数据集，视频解码自动完成 dataset = LeRobotDataset("lerobot/aloha_mobile_cabinet") print(dataset[0]["action"].shape) # 打印第一帧动作的 shape

训练同理，一条命令即可启动 ACT 策略训练：lerobot-train --policy.type=act --dataset.repo_id=lerobot/aloha_mobile_cabinet；多机多卡只需改用torchrun启动并追加--parallelism.*参数，全部配置可从train_config.json完整复现。

核心机制拆解

机器人抽象接口：把驱动细节挡在门外

它解决的问题是：每种电机、每种摄像头协议都不同，控制逻辑直接写硬件等于被硬件绑架。实现方式是 src/lerobot/robots/ 中的Robot抽象类——它定义了生命周期（connect/disconnect，支持上下文管理器自动断开）、数据接口（get_observation/send_action）和元数据接口（observation_features声明各特征的 shape 与类型）。各机器人子类只填通信细节，电机标定数据持久化为 JSON，初始化时自动加载，标定一次长期有效。电机通信层再单独下沉到 src/lerobot/motors/，Dynamixel、Feetech 等各有独立实现。

LeRobotDataset：视频与状态按帧对齐

它解决的问题是机器人数据的天然碎片化——图像一路流、状态/动作一路流，分开存会导致训练时对齐困难。实现方式是 v3.0 格式：状态与动作按 chunk 切分存 Parquet，视频存 MP4，二者靠帧索引对齐；meta/目录同时存放归一化统计量 stats 与任务 prompt（用于任务条件训练）。LeRobotDataset继承torch.utils.data.Dataset，加载后可以直接进 DataLoader，支持本地root加载与 Hub 按repo_id下载两种模式，老版 v2.1 格式可用 src/lerobot/scripts/convert_dataset_v21_to_v30.py 转换。细节见 src/lerobot/datasets/。

策略工厂与处理器管线：一条命令线拼出完整数据通路

它解决的问题是每个策略的输入输出约定都不同（归一化策略、观测键名、delta 动作等），写死在模型里就会把模型与数据集耦合。实现分两层：src/lerobot/policies/factory.py 的get_policy_class按注册名做约定式解析（找到 draccus 注册的 config，再映射到同名modeling_*模块里的<X>Policy类），新增策略无需改工厂代码；src/lerobot/processor/ 用ProcessorPipeline把归一化、键重命名、相对动作等ProcessorStep串成前/后处理器，整条管线随模型一起序列化，checkpoint 落盘后自动恢复。

上图为库内 VLA 策略的结构示意：视觉-语言模型提供语义骨干，状态与动作编码经注意力机制融合后输出动作序列。

一个真实使用场景

以 SO-100 遥操作数据采集闭环为例：工程师用主臂（leader）做手动操作，从臂（follower）同步执行，lerobot-record把摄像头画面、关节状态、动作指令按 LeRobotDataset 格式写入库；采够若干 episode 后，用lerobot-train训练选定类型的策略，再用lerobot-eval在仿真里评测（支持 LIBERO、MetaWorld 等标准基准）或直接部署到真机 rollout。全程不需要手写一行驱动代码，开发者的角色被压缩成"数据提供者 + 算法选择者"。

踩坑与调优速查

现象	处理办法
pip install lerobot依赖解析失败	要求 Python >= 3.12 且 torch >= 2.7，用干净的虚拟环境安装，避免与旧版 torch 共存
lerobot-record找不到串口	先跑lerobot-find-port确认设备枚举；Linux 下检查用户是否在 dialout 组
摄像头打不开	lerobot-find-cameras查设备列表与占用情况，确认视频设备组权限
加载老数据集报错	库默认读取 v3.0 格式，先运行 convert_dataset_v21_to_v30.py 转换
训练显存吃紧 / 速度慢	追加--accelerator.mixed_precision=bf16开混合精度；多卡用--parallelism.dp_shard=N，参考 docs/source/multi_gpu_training.mdx

下一步去哪儿

• 想加自己的策略：先读 docs/source/bring_your_own_policies.mdx，再对照 src/lerobot/policies/act/ 的目录结构（config + modeling + processor）动手
• 想在代码级搭训练流程：参考 examples/training/train_policy.py
• 想接自己的仿真环境：读 docs/source/envhub.mdx，了解环境的注册、评测与分发方式

硬件侧的集成入口在 docs/source/integrate_hardware.mdx——这个框架的价值在于把"写驱动"压缩成"填配置"，跑通一次遥操作到训练的闭环之后，剩下的路径基本都是工程选择而非技术门槛。

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