Lerobot repository解析

项目概述

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

核心设计目标：

项目目录结构

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/模块全景

分层架构总览

核心抽象模块

基础设施模块

分布式扩展模块

六大核心抽象

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

已支持机器人：

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

策略分类：

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

辅助模块：

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 步骤：

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()的数据流：