项目概述

LeRobot 是 Hugging Face 开源的机器人学习框架，基于 PyTorch 提供模型、数据集与工具链，覆盖真实机器人从数据采集 → 训练 → 评估 → 部署的完整流程。

核心设计目标：

目标	说明
硬件无关	统一的 Robot / Teleoperator 抽象，解耦控制逻辑与具体硬件
数据标准化	LeRobotDataset v3（Parquet + MP4）格式，与 Hugging Face Hub 深度集成
策略即插即用	模仿学习、强化学习、VLA 等多类 SOTA 策略开箱可用
可扩展	自定义机器人、策略、环境、Processor 均可接入同一套工具链

项目目录结构

lerobot/
├── src/lerobot/          # Python 主包源码
├── tests/                # 单元与集成测试
├── docs/                 # 文档（含本文件与 HuggingFace doc-builder 源文件）
├── examples/             # 教程与端到端示例
├── benchmarks/           # 性能基准（视频编解码等）
├── docker/               # Docker 构建文件
├── media/                # README 图片与视频资源
├── .github/              # CI/CD 工作流
├── pyproject.toml        # 包定义、可选依赖、CLI 入口
├── Makefile              # 开发快捷命令
└── README.md             # 项目总览

各目录功能说明

目录	功能
src/lerobot/	框架核心实现，所有可导入的 Python 模块均在此
tests/	覆盖 policies、datasets、processor、rl、robots、motors 等模块的测试
docs/	官方文档源文件（source/ 下 .mdx）及本地架构文档
examples/	按硬件/策略/场景组织的可运行示例（record、train、eval、teleop）
benchmarks/	视频编解码器性能对比等基准脚本
docker/	用户版与内部版 Dockerfile
media/	项目宣传素材，不参与运行时逻辑

src/lerobot/ 模块全景

分层架构总览

核心抽象模块

模块	路径	职责
robots	robots/	物理机器人抽象与具体实现
teleoperators	teleoperators/	遥操作设备（Leader 臂、手柄、键盘、手机等）
policies	policies/	策略模型（IL / RL / VLA）
datasets	datasets/	LeRobotDataset v3 读写、统计、流式、在线 buffer
processor	processor/	观测/动作/策略前后处理 Pipeline
envs	envs/	仿真环境工厂（Gymnasium + Hub 远程环境）
configs	configs/	draccus 配置 dataclass 与 CLI 解析
scripts	scripts/	官方 CLI 入口脚本

基础设施模块

模块	职责
cameras	相机抽象：OpenCV、RealSense、Reachy2、ZMQ 远程相机
motors	电机总线：Feetech、Dynamixel、Damiao（CAN）
optim	优化器与学习率调度器工厂
utils	训练工具、Hub 集成、常量、可视化、控制循环辅助
model	运动学计算
transport	gRPC proto 定义与序列化工具
data_processing	SARM 子任务标注等数据处理
templates	HuggingFace Model Card 模板

分布式扩展模块

模块	职责
async_inference	远程策略推理（Policy Server + Robot Client）
rl	分布式 HILSerl（Actor / Learner、ReplayBuffer）

六大核心抽象

Robot（机器人）

文件：src/lerobot/robots/robot.py

Robot 是所有 LeRobot 兼容机器人的抽象基类，提供硬件无关的标准接口：

• 特征描述：observation_features / action_features（dict，值为 float 或图像 shape）
• 生命周期：connect() → configure() → get_observation() / send_action() → disconnect()
• 标定持久化：JSON 文件，路径 ~/.cache/huggingface/lerobot/calibration/robots/{name}/{id}.json
• 上下文管理器：with Robot(...) 自动 connect / disconnect

已支持机器人：

子模块	机器人
so_follower	SO-100 / SO-101 Follower 我使用的这个
bi_so_follower	双臂 SO Follower
koch_follower	Koch v1.1
lekiwi	LeKiwi（含 ZMQ 远程 host/client）
hope_jr	Hope Jr 手臂/手
omx_follower	OMX
reachy2	Reachy 2
openarm_follower / bi_openarm_follower	OpenArm 单/双臂
unitree_g1	Unitree G1 人形
earthrover_mini_plus	Earth Rover Mini

Teleoperator（遥操作器）

文件：src/lerobot/teleoperators/teleoperator.py

与 Robot 对称的遥操作设备接口：

• get_action() → 返回 RobotAction
• send_feedback() ← 力反馈/状态回传
• action_features / feedback_features
• 同样支持标定 JSON 持久化

已支持设备：so_leader、bi_so_leader、koch_leader、omx_leader、openarm_leader、bi_openarm_leader、gamepad、keyboard、phone、homunculus、reachy2_teleoperator、unitree_g1

Policy（策略）

文件：src/lerobot/policies/pretrained.py、src/lerobot/policies/factory.py

• 基类：PreTrainedPolicy(nn.Module, HubMixin) — select_action()、forward()、from_pretrained()
• 配置：PreTrainedConfig(draccus.ChoiceRegistry) — 特征维度、设备、AMP 等
• 工厂：make_policy(cfg, ds_meta|env_cfg) 从数据集元数据或环境推断特征
• Processor 配对：make_pre_post_processors() 为每种策略创建 pre/post pipeline

策略分类：

类别	策略
模仿学习 (IL)	ACT、Diffusion、VQ-BeT
强化学习 (RL)	SAC、TDMPC、HIL-SERL（含 reward_classifier）
视觉-语言-动作 (VLA)	Pi0、Pi0.5、Pi0-FAST、SmolVLA、GR00T N1.5、XVLA、Wall-X
推理辅助	RTC（Real-Time Chunking）

Dataset（数据集）

文件：src/lerobot/datasets/lerobot_dataset.py

LeRobotDataset v3.0 格式：

• 存储结构：Parquet（状态/动作/元数据）+ MP4 视频（或原始图像）
• Hub 集成：repo_id 可从 Hugging Face Hub 下载/上传
• 核心类：
  • LeRobotDatasetMetadata — 元数据、统计、episode 信息
  • LeRobotDataset(torch.utils.data.Dataset) — 训练/录制用，支持 delta_timestamps、视频解码、图像增强
• 编解码：h264 / hevc / libsvtav1

辅助模块：

文件	用途
factory.py	make_dataset() 训练用数据集构建
dataset_tools.py	删 episode、合并、拆分、特征编辑
streaming_dataset.py	流式训练数据集
online_buffer.py	在线 RL buffer
compute_stats.py / aggregate.py	归一化统计
video_utils.py	MP4 编解码
transforms.py	图像增强
v30/	v2.1 → v3.0 迁移工具

Processor（数据处理器）

文件：src/lerobot/processor/pipeline.py、src/lerobot/processor/core.py

通用顺序数据处理框架，将机器人原始数据与策略张量之间的转换标准化：

• ProcessorStep — 单步变换（注册表 ProcessorStepRegistry）
• DataProcessorPipeline — 链式组合，支持 Hub 保存/加载
• 专用 Pipeline：
  • RobotProcessorPipeline — 机器人观测/动作
  • PolicyProcessorPipeline — 策略输入/输出
• Transition 模型：EnvTransition 含 observation、action、reward、done、truncated、info、complementary_data

关键 Processor 步骤：

文件	用途
normalize_processor.py	归一化/反归一化
policy_robot_bridge.py	策略张量 ↔ 机器人 dict
hil_processor.py	HILSerl 干预/奖励/裁剪
env_processor.py	LIBERO / IsaacLab Arena 环境处理
factory.py	默认 Processor 组合

Simulation Environment（仿真环境）

我使用Nvidia Issac Sim来做仿真, 通讯方式通过ROS2

文件：src/lerobot/envs/factory.py、src/lerobot/envs/configs.py

• 配置：EnvConfig(draccus.ChoiceRegistry) — pusht、aloha、libero、metaworld、isaaclab_arena、Hub 远程环境
• 工厂：make_env(cfg, n_envs) → {suite_name: {task_id: VectorEnv}}
• Hub 环境：下载远程 env.py 中的 make_env()（需 trust_remote_code=True）

端到端数据流

主流程：record → dataset → train → eval → deploy

Processor 链在 record 中的位置

lerobot_record.py 中 record_loop() 的数据流：