LeRobot 项目架构概览

LeRobot 项目架构概览

目录

• 1. 系统设计哲学与总体数据流
• 2. 核心模块深度剖析
  • 2.1 数据层（Data Protocol & Dataset）
  • 2.2 预处理与归一化（Processor & Normalizer）
  • 2.3 策略架构层（Policy Abstraction）
  • 2.4 硬件与机器人适配层（Robot & Hardware Interface）
• 3. 三大主流控制循环（Execution Workflows）
  • 3.1 真实数据采集循环（lerobot_record.py）
  • 3.2 离线评估与仿真测试（lerobot_eval.py）
  • 3.3 真实机器人推理部署（lerobot_control.py或在线评估）
• 4. 关键接口扩展指南（Developer Extension Cookbook）
  • 4.1 新增一种自定义策略模型（Custom Policy）
  • 4.2 接入一种全新硬件/机械臂（Custom Robot）
• 5. 常见踩坑点与工程最佳实践

1. 系统设计哲学与总体数据流

LeRobot 的核心目标是打破具身智能（Embodied AI）在硬件、仿真与算法模型之间的壁垒，提供一个涵盖“数据采集→ \rightarrow→训练→ \rightarrow→评估→ \rightarrow→真实硬件部署”的闭环端到端框架。

┌────────────────────────────────────────────────────────────────────────┐ │ 数据采集 & 部署层 │ │ ┌────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ │ │ Camera / Sensor│ │ Robot Arm/Motors │ │ Teleop Device │ │ │ └───────┬────────┘ └────────▲─────────┘ └────────┬────────┘ │ └──────────┼───────────────────────┼────────────────────────┼───────────┘ │ 采集 Raw Obs │ 驱动 Action │ 人工示范 ▼ │ ▼ ┌──────────────────────────────────┴────────────────────────────────────┐ │ LeRobot 数据协议 │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ LeRobotDataset (HuggingFace Hub / Video Streams / Parquet) │ │ │ └───────────────────────────────┬─────────────────────────────────┘ │ └──────────────────────────────────┼────────────────────────────────────┘ │ 批次加载 (Batch) ▼ ┌────────────────────────────────────────────────────────────────────────┐ │ 处理与模型层 │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Data Processor (Normalization: Mean-Std / Min-Max / Delta) │ │ │ └───────────────────────────────┬─────────────────────────────────┘ │ │ │ Preprocessed Tensor │ ▼ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Policy (ACT, Diffusion, VQ-BeT, PI0, TDMPC...) │ │ │ └───────────────────────────────┬─────────────────────────────────┘ │ └──────────────────────────────────┼────────────────────────────────────┘ │ Action Predictions (Action Chunk) ▼ ┌────────────────────────────────────────────────────────────────────────┐ │ 后处理与执行控制 │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Postprocessor (Un-normalize / Safety Clipping / Action Queue) │ │ │ └───────────────────────────────┬─────────────────────────────────┘ │ └──────────────────────────────────┼────────────────────────────────────┘ │ Executable Motor Commands ▼ [Robot / Env]

2. 核心模块深度剖析

2.1 数据层（Data Protocol & Dataset）

• 核心文件：src/lerobot/datasets/lerobot_dataset.py
• 主要职责：
• 高效存储与加载：基于 Hugging Face Datasets 构建，元数据与数值特征存储为 Arrow/Parquet 格式，高维图像/视频输入采用 MP4 编解码（基于av或ffmpeg），大幅减少磁盘与网络 I/O 开销。
• 时间窗口采样（Observation Horizon & Action Chunking）：具身策略通常需要接收历史T o b s T_{obs}Tobs​帧观测，并预测未来T a c t i o n T_{action}Taction​步动作。LeRobotDataset在底层通过索引映射直接支持多帧开窗与采样，无需额外重构内存。
• 统计信息统一管理 (meta/stats.json)：自动计算每个特征维度（如关节角度、关节速度、相机 RGB 图像）的mean,std,min,max，为后续的 Processor 自动归一化提供数据基准。

2.2 预处理与归一化（Processor & Normalizer）

• 核心文件：src/lerobot/processor/*
• 主要职责：
• 多模态数据标准化：图像归一化（R [ 0 , 255 ] → R [ 0.0 , 1.0 ] \mathbb{R}^{[0, 255]} \rightarrow \mathbb{R}^{[0.0, 1.0]}R[0,255]→R[0.0,1.0]或 ImageNet 标准化），标量与连续状态（关节位置、电机力矩）的方差归一化（Mean-Std）或区间归一化（Min-Max [-1, 1]）。
• 状态持久化与可移植性：Processor 状态可序列化并随 Policy 固化到 Hugging Face Hub 中，保证训练阶段和评估/部署阶段的数据转换逻辑完全一致。

2.3 策略架构层（Policy Abstraction）

• 核心文件：src/lerobot/policies/（如act/,diffusion/,vq_bet/,pi0/）
• 主要职责：
  所有策略实现均继承统一的基类，提供一致的标准接口：
• forward(batch) -> dict[str, Tensor]：计算 Loss，用于训练阶段。
• select_action(batch) -> Tensor：在评估和真实机器部署阶段输入当前观测（及历史），输出当前预测的动作（通常包含 Action Chunk 块）。
• reset()：重置策略内部的隐状态（如 RNN/Transformer 的 KV Cache、Diffusion 采样步数计数器、或 Action Queue 动作缓存队列）。

2.4 硬件与机器人适配层（Robot & Hardware Interface）

• 核心文件：src/lerobot/robots/,motors/,cameras/,teleoperators/

• 主要职责：

• 硬件驱动抽象：解耦具体硬件，统一支持 Dynamixel、Feetech 电机，以及 OpenCV、RealSense 相机。

• 机器人统一 API：Robot类（如so100.py,koch.py,aloha.py）提供标准生命周期控制：

• connect()：通信串口/网络连接初始化与电机校准。

• capture_observation() -> dict：同步获取多视角相机帧与各电机编码器状态（位置、速度、电流）。

• send_action(action)：向从动臂（Follower）电机下发目标指令。

• 遥操作适配 (teleoperators)：实现主动臂（Leader）到从动臂（Follower）的映射算法（如重力补偿、关节映射、力反馈控制）。

3. 三大主流控制循环（Execution Workflows）

除了训练循环（lerobot_train.py）外，LeRobot 仓库还定义了另外两个核心闭环：

3.1 真实数据采集循环（lerobot_record.py）

1. 初始化主动臂（Teleop Leader）与从动臂（Robot Follower）驱动。
2. 初始化相机管线（Cameras）。
3. 进入实时控制帧率循环（如 30 Hz 或 60 Hz）：

• 读取 Leader 姿态→ \rightarrow→映射并发送动作至 Follower。
• 同步采集相机 RGB 帧与 Follower 反馈状态。
• 暂存到内存 Buffer。

4. 示教结束后，自动编码 MP4 视频并写出 Parquet 元数据，构建LeRobotDataset。

[Teleop Leader] ──> Read Position ──> [Robot Follower] ──> Execute │ Capture State & Camera │ ▼ [LeRobotDataset]

3.2 离线评估与仿真测试（lerobot_eval.py）

1. 根据配置创建 Gymnasium/Gym-ALOHA 等并行仿真环境（make_env）。
2. 从 Hugging Face Hub 或本地加载预训练 Policy 及 Processor。
3. 执行 Rollout 评估循环：

• 环境env.step(action)返回obs。
• processor.preprocess(obs)→ \rightarrow→policy.select_action()→ \rightarrow→processor.postprocess(action)。
• 下发action给环境，直至 Episode 结束。

4. 汇总任务成功率（Success Rate）与 Episode 统计，生成渲染评估视频。

3.3 真实机器人推理部署（lerobot_control.py或在线评估）

1. 连接真实机械臂硬件与相机。
2. 加载 Policy 权重的同时启动异步推理服务（RPC/Async Inference）或同步推理队列。
3. 采用动作队列（Action Temporal Ensembling / Action Queue）模式：

• 策略预测输出长度为N NN的 Action Chunk。
• 控制主线程按硬件高频（如 50 Hz）平滑消耗队列中的 Action 节点，缓解深度模型推理延迟造成的机器人卡顿问题。

4. 关键接口扩展指南（Developer Extension Cookbook）

4.1 新增一种自定义策略模型（Custom Policy）

在src/lerobot/policies/下新增目录并定义三要素：

1. 配置类(configuration_my_policy.py)：继承PreTrainedConfig。
2. 模型类(modeling_my_policy.py)：继承nn.Module，实现forward、select_action和reset。
3. 注册工厂(src/lerobot/policies/factory.py)：在make_policy中添加新建策略的工厂分支。

# 代码规范示例 (modeling_my_policy.py)classMyPolicy(nn.Module):def__init__(self,config:MyPolicyConfig):super().__init__()self.config=config# 初始化 Vision Backbone 与 Action Headdefreset(self):# 清空推理状态（如动作队列、历史特征）passdefforward(self,batch:dict[str,Tensor])->dict[str,Tensor]:# 训练过程：计算并返回 lossloss=...return{"loss":loss}@torch.no_grad()defselect_action(self,batch:dict[str,Tensor])->Tensor:# 推理过程：根据观测返回动作序列或单步动作action=...returnaction

4.2 接入一种全新硬件/机械臂（Custom Robot）

在src/lerobot/robots/中继承Robot基类：

1. 定义硬件 Specs：描述关节数、相机分辨率、控制频次。
2. 实现硬件 API：实现connect、disconnect、capture_observation和send_action。
3. 编写校准脚本：在src/lerobot/scripts/下提供该机械臂的零点与行程校准逻辑（Calibration）。

5. 常见踩坑点与工程最佳实践