LeRobot 项目架构概览目录1. 系统设计哲学与总体数据流2. 核心模块深度剖析2.1 数据层Data Protocol Dataset2.2 预处理与归一化Processor Normalizer2.3 策略架构层Policy Abstraction2.4 硬件与机器人适配层Robot Hardware Interface3. 三大主流控制循环Execution Workflows3.1 真实数据采集循环lerobot_record.py3.2 离线评估与仿真测试lerobot_eval.py3.3 真实机器人推理部署lerobot_control.py或在线评估4. 关键接口扩展指南Developer Extension Cookbook4.1 新增一种自定义策略模型Custom Policy4.2 接入一种全新硬件/机械臂Custom Robot5. 常见踩坑点与工程最佳实践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 相机。机器人统一 APIRobot类如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初始化主动臂Teleop Leader与从动臂Robot Follower驱动。初始化相机管线Cameras。进入实时控制帧率循环如 30 Hz 或 60 Hz读取 Leader 姿态→ \rightarrow→映射并发送动作至 Follower。同步采集相机 RGB 帧与 Follower 反馈状态。暂存到内存 Buffer。示教结束后自动编码 MP4 视频并写出 Parquet 元数据构建LeRobotDataset。[Teleop Leader] ── Read Position ── [Robot Follower] ── Execute │ Capture State Camera │ ▼ [LeRobotDataset]3.2 离线评估与仿真测试lerobot_eval.py根据配置创建 Gymnasium/Gym-ALOHA 等并行仿真环境make_env。从 Hugging Face Hub 或本地加载预训练 Policy 及 Processor。执行 Rollout 评估循环环境env.step(action)返回obs。processor.preprocess(obs)→ \rightarrow→policy.select_action()→ \rightarrow→processor.postprocess(action)。下发action给环境直至 Episode 结束。汇总任务成功率Success Rate与 Episode 统计生成渲染评估视频。3.3 真实机器人推理部署lerobot_control.py或在线评估连接真实机械臂硬件与相机。加载 Policy 权重的同时启动异步推理服务RPC/Async Inference或同步推理队列。采用动作队列Action Temporal Ensembling / Action Queue模式策略预测输出长度为N NN的 Action Chunk。控制主线程按硬件高频如 50 Hz平滑消耗队列中的 Action 节点缓解深度模型推理延迟造成的机器人卡顿问题。4. 关键接口扩展指南Developer Extension Cookbook4.1 新增一种自定义策略模型Custom Policy在src/lerobot/policies/下新增目录并定义三要素配置类(configuration_my_policy.py)继承PreTrainedConfig。模型类(modeling_my_policy.py)继承nn.Module实现forward、select_action和reset。注册工厂(src/lerobot/policies/factory.py)在make_policy中添加新建策略的工厂分支。# 代码规范示例 (modeling_my_policy.py)classMyPolicy(nn.Module):def__init__(self,config:MyPolicyConfig):super().__init__()self.configconfig# 初始化 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...returnaction4.2 接入一种全新硬件/机械臂Custom Robot在src/lerobot/robots/中继承Robot基类定义硬件 Specs描述关节数、相机分辨率、控制频次。实现硬件 API实现connect、disconnect、capture_observation和send_action。编写校准脚本在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 上。 LeRobot 项目架构概览
LeRobot 项目架构概览目录1. 系统设计哲学与总体数据流2. 核心模块深度剖析2.1 数据层Data Protocol Dataset2.2 预处理与归一化Processor Normalizer2.3 策略架构层Policy Abstraction2.4 硬件与机器人适配层Robot Hardware Interface3. 三大主流控制循环Execution Workflows3.1 真实数据采集循环lerobot_record.py3.2 离线评估与仿真测试lerobot_eval.py3.3 真实机器人推理部署lerobot_control.py或在线评估4. 关键接口扩展指南Developer Extension Cookbook4.1 新增一种自定义策略模型Custom Policy4.2 接入一种全新硬件/机械臂Custom Robot5. 常见踩坑点与工程最佳实践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 相机。机器人统一 APIRobot类如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初始化主动臂Teleop Leader与从动臂Robot Follower驱动。初始化相机管线Cameras。进入实时控制帧率循环如 30 Hz 或 60 Hz读取 Leader 姿态→ \rightarrow→映射并发送动作至 Follower。同步采集相机 RGB 帧与 Follower 反馈状态。暂存到内存 Buffer。示教结束后自动编码 MP4 视频并写出 Parquet 元数据构建LeRobotDataset。[Teleop Leader] ── Read Position ── [Robot Follower] ── Execute │ Capture State Camera │ ▼ [LeRobotDataset]3.2 离线评估与仿真测试lerobot_eval.py根据配置创建 Gymnasium/Gym-ALOHA 等并行仿真环境make_env。从 Hugging Face Hub 或本地加载预训练 Policy 及 Processor。执行 Rollout 评估循环环境env.step(action)返回obs。processor.preprocess(obs)→ \rightarrow→policy.select_action()→ \rightarrow→processor.postprocess(action)。下发action给环境直至 Episode 结束。汇总任务成功率Success Rate与 Episode 统计生成渲染评估视频。3.3 真实机器人推理部署lerobot_control.py或在线评估连接真实机械臂硬件与相机。加载 Policy 权重的同时启动异步推理服务RPC/Async Inference或同步推理队列。采用动作队列Action Temporal Ensembling / Action Queue模式策略预测输出长度为N NN的 Action Chunk。控制主线程按硬件高频如 50 Hz平滑消耗队列中的 Action 节点缓解深度模型推理延迟造成的机器人卡顿问题。4. 关键接口扩展指南Developer Extension Cookbook4.1 新增一种自定义策略模型Custom Policy在src/lerobot/policies/下新增目录并定义三要素配置类(configuration_my_policy.py)继承PreTrainedConfig。模型类(modeling_my_policy.py)继承nn.Module实现forward、select_action和reset。注册工厂(src/lerobot/policies/factory.py)在make_policy中添加新建策略的工厂分支。# 代码规范示例 (modeling_my_policy.py)classMyPolicy(nn.Module):def__init__(self,config:MyPolicyConfig):super().__init__()self.configconfig# 初始化 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...returnaction4.2 接入一种全新硬件/机械臂Custom Robot在src/lerobot/robots/中继承Robot基类定义硬件 Specs描述关节数、相机分辨率、控制频次。实现硬件 API实现connect、disconnect、capture_observation和send_action。编写校准脚本在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 上。