LeRobot 項(xiàng)目架構(gòu)概覽目錄1. 系統(tǒng)設(shè)計(jì)哲學(xué)與總體數(shù)據(jù)流2. 核心模塊深度剖析2.1 數(shù)據(jù)層Data Protocol Dataset2.2 預(yù)處理與歸一化Processor Normalizer2.3 策略架構(gòu)層Policy Abstraction2.4 硬件與機(jī)器人適配層Robot Hardware Interface3. 三大主流控制循環(huán)Execution Workflows3.1 真實(shí)數(shù)據(jù)采集循環(huán)lerobot_record.py3.2 離線評(píng)估與仿真測(cè)試lerobot_eval.py3.3 真實(shí)機(jī)器人推理部署lerobot_control.py或在線評(píng)估4. 關(guān)鍵接口擴(kuò)展指南Developer Extension Cookbook4.1 新增一種自定義策略模型Custom Policy4.2 接入一種全新硬件/機(jī)械臂Custom Robot5. 常見踩坑點(diǎn)與工程最佳實(shí)踐1. 系統(tǒng)設(shè)計(jì)哲學(xué)與總體數(shù)據(jù)流LeRobot 的核心目標(biāo)是打破具身智能Embodied AI在硬件、仿真與算法模型之間的壁壘提供一個(gè)涵蓋“數(shù)據(jù)采集→ \rightarrow→訓(xùn)練→ \rightarrow→評(píng)估→ \rightarrow→真實(shí)硬件部署”的閉環(huán)端到端框架。┌────────────────────────────────────────────────────────────────────────┐ │ 數(shù)據(jù)采集 部署層 │ │ ┌────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ │ │ Camera / Sensor│ │ Robot Arm/Motors │ │ Teleop Device │ │ │ └───────┬────────┘ └────────▲─────────┘ └────────┬────────┘ │ └──────────┼───────────────────────┼────────────────────────┼───────────┘ │ 采集 Raw Obs │ 驅(qū)動(dòng) Action │ 人工示范 ▼ │ ▼ ┌──────────────────────────────────┴────────────────────────────────────┐ │ LeRobot 數(shù)據(jù)協(xié)議 │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ 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) ▼ ┌────────────────────────────────────────────────────────────────────────┐ │ 后處理與執(zhí)行控制 │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Postprocessor (Un-normalize / Safety Clipping / Action Queue) │ │ │ └───────────────────────────────┬─────────────────────────────────┘ │ └──────────────────────────────────┼────────────────────────────────────┘ │ Executable Motor Commands ▼ [Robot / Env]2. 核心模塊深度剖析2.1 數(shù)據(jù)層Data Protocol Dataset核心文件src/lerobot/datasets/lerobot_dataset.py主要職責(zé)高效存儲(chǔ)與加載基于 Hugging Face Datasets 構(gòu)建元數(shù)據(jù)與數(shù)值特征存儲(chǔ)為 Arrow/Parquet 格式高維圖像/視頻輸入采用 MP4 編解碼基于av或ffmpeg大幅減少磁盤與網(wǎng)絡(luò) I/O 開銷。時(shí)間窗口采樣Observation Horizon Action Chunking具身策略通常需要接收歷史T o b s T_{obs}Tobs?幀觀測(cè)并預(yù)測(cè)未來T a c t i o n T_{action}Taction?步動(dòng)作。LeRobotDataset在底層通過索引映射直接支持多幀開窗與采樣無需額外重構(gòu)內(nèi)存。統(tǒng)計(jì)信息統(tǒng)一管理 (meta/stats.json)自動(dòng)計(jì)算每個(gè)特征維度如關(guān)節(jié)角度、關(guān)節(jié)速度、相機(jī) RGB 圖像的mean,std,min,max為后續(xù)的 Processor 自動(dòng)歸一化提供數(shù)據(jù)基準(zhǔn)。2.2 預(yù)處理與歸一化Processor Normalizer核心文件src/lerobot/processor/*主要職責(zé)多模態(tài)數(shù)據(jù)標(biāo)準(zhǔn)化圖像歸一化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 標(biāo)準(zhǔn)化標(biāo)量與連續(xù)狀態(tài)關(guān)節(jié)位置、電機(jī)力矩的方差歸一化Mean-Std或區(qū)間歸一化Min-Max [-1, 1]。狀態(tài)持久化與可移植性Processor 狀態(tài)可序列化并隨 Policy 固化到 Hugging Face Hub 中保證訓(xùn)練階段和評(píng)估/部署階段的數(shù)據(jù)轉(zhuǎn)換邏輯完全一致。2.3 策略架構(gòu)層Policy Abstraction核心文件src/lerobot/policies/如act/,diffusion/,vq_bet/,pi0/主要職責(zé)所有策略實(shí)現(xiàn)均繼承統(tǒng)一的基類提供一致的標(biāo)準(zhǔn)接口forward(batch) - dict[str, Tensor]計(jì)算 Loss用于訓(xùn)練階段。select_action(batch) - Tensor在評(píng)估和真實(shí)機(jī)器部署階段輸入當(dāng)前觀測(cè)及歷史輸出當(dāng)前預(yù)測(cè)的動(dòng)作通常包含 Action Chunk 塊。reset()重置策略內(nèi)部的隱狀態(tài)如 RNN/Transformer 的 KV Cache、Diffusion 采樣步數(shù)計(jì)數(shù)器、或 Action Queue 動(dòng)作緩存隊(duì)列。2.4 硬件與機(jī)器人適配層Robot Hardware Interface核心文件src/lerobot/robots/,motors/,cameras/,teleoperators/主要職責(zé)硬件驅(qū)動(dòng)抽象解耦具體硬件統(tǒng)一支持 Dynamixel、Feetech 電機(jī)以及 OpenCV、RealSense 相機(jī)。機(jī)器人統(tǒng)一 APIRobot類如so100.py,koch.py,aloha.py提供標(biāo)準(zhǔn)生命周期控制connect()通信串口/網(wǎng)絡(luò)連接初始化與電機(jī)校準(zhǔn)。capture_observation() - dict同步獲取多視角相機(jī)幀與各電機(jī)編碼器狀態(tài)位置、速度、電流。send_action(action)向從動(dòng)臂Follower電機(jī)下發(fā)目標(biāo)指令。遙操作適配 (teleoperators)實(shí)現(xiàn)主動(dòng)臂Leader到從動(dòng)臂Follower的映射算法如重力補(bǔ)償、關(guān)節(jié)映射、力反饋控制。3. 三大主流控制循環(huán)Execution Workflows除了訓(xùn)練循環(huán)lerobot_train.py外LeRobot 倉(cāng)庫(kù)還定義了另外兩個(gè)核心閉環(huán)3.1 真實(shí)數(shù)據(jù)采集循環(huán)lerobot_record.py初始化主動(dòng)臂Teleop Leader與從動(dòng)臂Robot Follower驅(qū)動(dòng)。初始化相機(jī)管線Cameras。進(jìn)入實(shí)時(shí)控制幀率循環(huán)如 30 Hz 或 60 Hz讀取 Leader 姿態(tài)→ \rightarrow→映射并發(fā)送動(dòng)作至 Follower。同步采集相機(jī) RGB 幀與 Follower 反饋狀態(tài)。暫存到內(nèi)存 Buffer。示教結(jié)束后自動(dòng)編碼 MP4 視頻并寫出 Parquet 元數(shù)據(jù)構(gòu)建LeRobotDataset。[Teleop Leader] ── Read Position ── [Robot Follower] ── Execute │ Capture State Camera │ ▼ [LeRobotDataset]3.2 離線評(píng)估與仿真測(cè)試lerobot_eval.py根據(jù)配置創(chuàng)建 Gymnasium/Gym-ALOHA 等并行仿真環(huán)境make_env。從 Hugging Face Hub 或本地加載預(yù)訓(xùn)練 Policy 及 Processor。執(zhí)行 Rollout 評(píng)估循環(huán)環(huán)境env.step(action)返回obs。processor.preprocess(obs)→ \rightarrow→policy.select_action()→ \rightarrow→processor.postprocess(action)。下發(fā)action給環(huán)境直至 Episode 結(jié)束。匯總?cè)蝿?wù)成功率Success Rate與 Episode 統(tǒng)計(jì)生成渲染評(píng)估視頻。3.3 真實(shí)機(jī)器人推理部署lerobot_control.py或在線評(píng)估連接真實(shí)機(jī)械臂硬件與相機(jī)。加載 Policy 權(quán)重的同時(shí)啟動(dòng)異步推理服務(wù)RPC/Async Inference或同步推理隊(duì)列。采用動(dòng)作隊(duì)列Action Temporal Ensembling / Action Queue模式策略預(yù)測(cè)輸出長(zhǎng)度為N NN的 Action Chunk。控制主線程按硬件高頻如 50 Hz平滑消耗隊(duì)列中的 Action 節(jié)點(diǎn)緩解深度模型推理延遲造成的機(jī)器人卡頓問題。4. 關(guān)鍵接口擴(kuò)展指南Developer Extension Cookbook4.1 新增一種自定義策略模型Custom Policy在src/lerobot/policies/下新增目錄并定義三要素配置類(configuration_my_policy.py)繼承PreTrainedConfig。模型類(modeling_my_policy.py)繼承nn.Module實(shí)現(xiàn)forward、select_action和reset。注冊(cè)工廠(src/lerobot/policies/factory.py)在make_policy中添加新建策略的工廠分支。# 代碼規(guī)范示例 (modeling_my_policy.py)classMyPolicy(nn.Module):def__init__(self,config:MyPolicyConfig):super().__init__()self.configconfig# 初始化 Vision Backbone 與 Action Headdefreset(self):# 清空推理狀態(tài)如動(dòng)作隊(duì)列、歷史特征passdefforward(self,batch:dict[str,Tensor])-dict[str,Tensor]:# 訓(xùn)練過程計(jì)算并返回 lossloss...return{loss:loss}torch.no_grad()defselect_action(self,batch:dict[str,Tensor])-Tensor:# 推理過程根據(jù)觀測(cè)返回動(dòng)作序列或單步動(dòng)作action...returnaction4.2 接入一種全新硬件/機(jī)械臂Custom Robot在src/lerobot/robots/中繼承Robot基類定義硬件 Specs描述關(guān)節(jié)數(shù)、相機(jī)分辨率、控制頻次。實(shí)現(xiàn)硬件 API實(shí)現(xiàn)connect、disconnect、capture_observation和send_action。編寫校準(zhǔn)腳本在src/lerobot/scripts/下提供該機(jī)械臂的零點(diǎn)與行程校準(zhǔn)邏輯Calibration。5. 常見踩坑點(diǎn)與工程最佳實(shí)踐維度常見問題/故障現(xiàn)象解決方案與排查建議歸一化不匹配真實(shí)推理時(shí)機(jī)器人無規(guī)律抖動(dòng)或直接飛臂檢查評(píng)估腳本中的processor是否正確加載了訓(xùn)練集stats.json確保動(dòng)作值的 Un-normalization 逆轉(zhuǎn)換正常。視頻解碼瓶頸訓(xùn)練時(shí) GPU 利用率極低DataLoader 讀取卡頓確保安裝了包含硬件加速編譯的av/ffmpeg在 DataLoader 中設(shè)置合理的num_workers并將視頻幀緩存設(shè)為連續(xù)讀取塊Chunk-based reading。控制延遲過高策略模型推理時(shí)間超出控制周期如推理需 100ms而控制周期為 20ms啟用async_inference異步推理服務(wù)主線程通過隊(duì)列平滑執(zhí)行 Action Chunk推理線程后臺(tái)并發(fā)計(jì)算下一段動(dòng)作?；旌暇葦?shù)值溢出使用fp16訓(xùn)練 Diffusion Policy 時(shí)出現(xiàn) Loss NaN在 Diffusion 采樣過程或特定矩陣乘法層強(qiáng)行使用fp32或使用標(biāo)準(zhǔn)的bfloat16在 Ampere 及更新架構(gòu) GPU 上。