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）在硬件、仿真与算法模型之间的壁垒，提供一个涵盖“数据采集 $\to$ 训练 $\to$ 评估 $\to$ 真实硬件部署”的闭环端到端框架。

 ┌────────────────────────────────────────────────────────────────────────┐
 │                           数据采集 & 部署层                            │
 │  ┌────────────────┐     ┌──────────────────┐     ┌─────────────────┐  │
 │  │ 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_{obs}$ 帧观测，并预测未来 $T_{action}$ 步动作。LeRobotDataset 在底层通过索引映射直接支持多帧开窗与采样，无需额外重构内存。
• 统计信息统一管理 (meta/stats.json)：自动计算每个特征维度（如关节角度、关节速度、相机 RGB 图像）的 mean, std, min, max，为后续的 Processor 自动归一化提供数据基准。

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

• 核心文件：src/lerobot/processor/*
• 主要职责：
• 多模态数据标准化：图像归一化（${\mathbb{R}}^{[0,255]}\to {\mathbb{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 姿态 $\to$ 映射并发送动作至 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) $\to$ policy.select_action() $\to$ 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$ 的 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)
class MyPolicy(nn.Module):
    def __init__(self, config: MyPolicyConfig):
        super().__init__()
        self.config = config
        # 初始化 Vision Backbone 与 Action Head

    def reset(self):
        # 清空推理状态（如动作队列、历史特征）
        pass

    def forward(self, batch: dict[str, Tensor]) -> dict[str, Tensor]:
        # 训练过程：计算并返回 loss
        loss = ...
        return {"loss": loss}

    @torch.no_grad()
    def select_action(self, batch: dict[str, Tensor]) -> Tensor:
        # 推理过程：根据观测返回动作序列或单步动作
        action = ...
        return action

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

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

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

---

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

维度	常见问题/故障现象	解决方案与排查建议
归一化不匹配	真实推理时机器人无规律抖动或直接飞臂	检查评估脚本中的 processor 是否正确加载了训练集 stats.json，确保动作值的 Un-normalization 逆转换正常。
视频解码瓶颈	训练时 GPU 利用率极低，DataLoader 读取卡顿	确保安装了包含硬件加速编译的 av / ffmpeg；在 DataLoader 中设置合理的 num_workers，并将视频帧缓存设为连续读取块（Chunk-based reading）。
控制延迟过高	策略模型推理时间超出控制周期（如推理需 100ms，而控制周期为 20ms）	启用 async_inference（异步推理服务），主线程通过队列平滑执行 Action Chunk，推理线程后台并发计算下一段动作。
混合精度数值溢出	使用 fp16 训练 Diffusion Policy 时出现 Loss NaN	在 Diffusion 采样过程或特定矩阵乘法层强行使用 fp32；或使用标准的 bfloat16（在 Ampere 及更新架构 GPU 上）。