最完整LeRobot入门指南：从安装到部署AI驱动机器人系统

2026-02-04 04:37:38作者：申梦珏Efrain

1. 痛点与解决方案：为什么选择LeRobot？

你是否在构建机器人系统时遇到以下挑战：

多传感器数据同步与处理复杂
策略训练与硬件控制脱节
开源方案碎片化难以整合
实时性与精度难以平衡

LeRobot作为基于PyTorch的机器人学习框架，通过统一接口解决了从数据采集到策略部署的全流程问题。本文将带你从零开始构建一个AI驱动的移动机械臂系统，掌握工业级机器人控制的核心技术。

读完本文你将获得：

完整的LeRobot环境搭建流程
多模态数据采集与处理方法
6种强化学习策略的实现与对比
真实机器人部署与优化技巧
性能调优与故障排查指南

2. 环境搭建：从源码到运行

2.1 系统要求与依赖

操作系统	Python版本	必需依赖	推荐配置
Ubuntu 20.04+/macOS 12+	3.10	PyTorch 2.0+, FFmpeg	NVIDIA GPU (≥8GB VRAM)

2.2 源码安装流程

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/le/lerobot
cd lerobot

# 创建并激活虚拟环境
conda create -y -n lerobot python=3.10
conda activate lerobot

# 安装基础依赖
conda install ffmpeg -c conda-forge
pip install -e .

# 根据硬件安装特定组件
pip install -e ".[feetech]"  # SO100/SO101电机支持
pip install -e ".[aloha,pusht]"  # 仿真环境支持

故障排除：如遇PyAV安装错误，需手动安装FFmpeg开发库：
sudo apt-get install libavformat-dev libavcodec-dev libswscale-dev

2.3 环境验证

# 验证安装
import lerobot
from lerobot.datasets import LeRobotDatasetMetadata

# 查看可用数据集
print(lerobot.available_datasets)

# 加载数据集元信息
ds_meta = LeRobotDatasetMetadata("lerobot/pusht")
print(f"数据集信息: {ds_meta}")

3. 核心架构解析：数据-策略-执行闭环

3.1 框架整体架构

flowchart TD
    A[数据采集] -->|传感器/仿真| B[LeRobotDataset]
    B -->|预处理/增强| C[策略训练]
    C -->|Diffusion/TDMPC等| D[模型评估]
    D -->|仿真验证| E[机器人部署]
    E -->|实时控制| F[反馈优化]
    F -->|新数据| A

LeRobot采用模块化设计，主要包含：

数据层：统一格式的多模态数据集
策略层：6种强化学习算法实现
执行层：硬件抽象与实时控制
工具链：训练、评估、部署全流程支持

3.2 关键组件详解

3.2.1 数据集模块

LeRobotDataset支持多模态数据处理，核心特性包括：

# 示例：加载并处理数据集
from lerobot.datasets import LeRobotDataset

# 加载指定 episodes
dataset = LeRobotDataset("lerobot/pusht", episodes=[0, 10, 23])

# 时间序列数据采样
delta_timestamps = {
    "observation.image": [-1.0, -0.5, 0],  # 多时间戳图像
    "observation.state": [-0.2, 0],        # 状态数据
    "action": [0, 0.1, 0.2]                # 动作序列
}
dataset = LeRobotDataset("lerobot/pusht", delta_timestamps=delta_timestamps)

# 数据加载器
dataloader = torch.utils.data.DataLoader(
    dataset, batch_size=32, shuffle=True, num_workers=4
)

3.2.2 策略模块

LeRobot实现多种最先进的机器人策略，包括：

策略类型	适用场景	核心优势	代表论文
Diffusion	图像输入任务	高鲁棒性	Diffusion Policy
TDMPC	动态控制任务	实时性好	TD-MPC
ACT	复杂操作任务	长时序建模	ACT
SAC	连续控制任务	样本效率高	SAC
VQBeT	多模态任务	模态融合好	VQ-BeT
PI0	语言指导任务	语义理解强	PI0

策略基类定义：

class PreTrainedPolicy(nn.Module):
    def __init__(self, config, dataset_stats):
        super().__init__()
        self.config = config
        self.dataset_stats = dataset_stats
        
    def forward(self, batch):
        # 前向传播计算损失
        raise NotImplementedError
        
    def select_action(self, batch):
        # 推理时选择动作
        raise NotImplementedError
        
    def reset(self):
        # 重置策略状态（用于序列决策）
        pass

4. 实战教程：构建AI驱动的移动机械臂

以LeKiwi机器人为例，完整实现从数据采集到策略部署的全流程。

4.1 LeKiwi机器人简介

LeKiwi是一款低成本移动机械臂，包含：

3自由度全向移动底盘
5自由度机械臂+夹爪
双摄像头（前视+腕部）
Feetech STS3215伺服电机

classDiagram
    class LeKiwi {
        +config : LeKiwiConfig
        +bus : FeetechMotorsBus
        +cameras : dict
        +connect()
        +get_observation()
        +send_action(action)
        +disconnect()
    }
    class FeetechMotorsBus {
        +sync_read(reg, motors)
        +sync_write(reg, values)
        +enable_torque()
        +disable_torque()
    }
    LeKiwi --> FeetechMotorsBus

4.2 硬件连接与配置

4.2.1 配置文件

# src/lerobot/robots/lekiwi/config_lekiwi.py
@dataclass
class LeKiwiConfig(RobotConfig):
    port: str = "/dev/ttyACM0"  # 电机总线端口
    max_relative_target: float = 0.1  # 安全位置限制
    cameras: dict = field(default_factory=lekiwi_cameras_config)
    use_degrees: bool = False  # 角度单位选择

4.2.2 连接机器人

from lerobot.robots.lekiwi import LeKiwi
from lerobot.robots.lekiwi.config_lekiwi import LeKiwiConfig

# 初始化配置
config = LeKiwiConfig(
    port="/dev/ttyACM0",
    max_relative_target=0.15
)

# 创建机器人实例
robot = LeKiwi(config)

# 连接硬件
robot.connect(calibrate=True)

# 检查连接状态
print(f"机器人连接状态: {robot.is_connected}")

4.3 数据采集

使用游戏手柄进行遥操作并采集数据：

from lerobot.teleoperators.gamepad import GamepadTeleop
from lerobot.teleoperators.gamepad.config import GamepadTeleopConfig

# 初始化遥操作器
teleop_config = GamepadTeleopConfig(use_gripper=True)
teleop = GamepadTeleop(teleop_config)
teleop.connect()

# 数据采集循环
observations = []
actions = []
while True:
    # 获取遥操作指令
    action = teleop.get_action()
    
    # 发送指令到机器人
    robot.send_action(action)
    
    # 获取观测
    obs = robot.get_observation()
    
    # 存储数据
    observations.append(obs)
    actions.append(action)
    
    # 按'q'退出
    if action.get('quit', False):
        break

# 断开连接
robot.disconnect()
teleop.disconnect()

4.4 策略训练

以Diffusion策略为例，训练推箱子任务：

4.4.1 训练脚本

# examples/3_train_policy.py
from lerobot.policies.diffusion import DiffusionPolicy, DiffusionConfig
from lerobot.datasets import LeRobotDataset, LeRobotDatasetMetadata

# 数据集元信息
dataset_metadata = LeRobotDatasetMetadata("lerobot/pusht")
features = dataset_to_policy_features(dataset_metadata.features)

# 配置策略
cfg = DiffusionConfig(
    input_features={k: ft for k, ft in features.items() if ft.type != FeatureType.ACTION},
    output_features={k: ft for k, ft in features.items() if ft.type == FeatureType.ACTION}
)

# 初始化策略
policy = DiffusionPolicy(cfg, dataset_stats=dataset_metadata.stats)
policy.to(device)

# 训练循环
optimizer = torch.optim.Adam(policy.parameters(), lr=1e-4)
dataloader = torch.utils.data.DataLoader(dataset, batch_size=64, shuffle=True)

for step, batch in enumerate(dataloader):
    batch = {k: v.to(device) for k, v in batch.items()}
    loss, _ = policy.forward(batch)
    loss.backward()
    optimizer.step()
    optimizer.zero_grad()
    
    if step % 100 == 0:
        print(f"Step {step}, Loss: {loss.item():.4f}")

4.4.2 使用训练脚本

LeRobot提供命令行工具简化训练流程：

# 基础训练命令
lerobot-train \
    --dataset.repo_id=lerobot/pusht \
    --policy.type=diffusion \
    --env.type=pusht \
    --output_dir=outputs/train/diffusion_pusht

# 恢复训练
lerobot-train \
    --config_path=outputs/train/diffusion_pusht/checkpoints/last/pretrained_model/ \
    --resume=true \
    --steps=200000

# 微调预训练模型
lerobot-train \
    --policy.path=lerobot/diffusion_pusht \
    --dataset.repo_id=lerobot/pusht_custom \
    --env.type=pusht \
    --output_dir=outputs/train/diffusion_pusht_finetune

4.5 策略评估

4.5.1 仿真评估

# examples/2_evaluate_pretrained_policy.py
import gym
import imageio
import torch
from lerobot.policies.diffusion import DiffusionPolicy

# 加载预训练策略
policy = DiffusionPolicy.from_pretrained("lerobot/diffusion_pusht")
policy.to("cuda")

# 创建评估环境
env = gym.make("gym_pusht/PushT-v0", obs_type="pixels_agent_pos")
observation, info = env.reset(seed=42)

# 评估循环
frames = []
rewards = []
done = False

while not done:
    # 准备输入
    state = torch.from_numpy(observation["agent_pos"]).float().unsqueeze(0).to("cuda")
    image = torch.from_numpy(observation["pixels"]).float().permute(2, 0, 1).unsqueeze(0).to("cuda") / 255.0
    
    # 策略推理
    with torch.inference_mode():
        action = policy.select_action({"observation.state": state, "observation.image": image})
    
    # 执行动作
    observation, reward, terminated, truncated, _ = env.step(action.squeeze().cpu().numpy())
    
    rewards.append(reward)
    frames.append(env.render())
    done = terminated or truncated

# 保存视频
imageio.mimsave("evaluation.mp4", frames, fps=30)
print(f"总奖励: {sum(rewards)}, 成功: {terminated}")

4.5.2 评估指标

训练过程中会记录多种关键指标：

指标	含义	重要性
loss	策略损失	优化进度
grad_norm	梯度范数	训练稳定性
∑rwrd	总奖励	任务完成度
success	成功率	策略有效性
update_s	更新耗时	训练效率
data_s	数据加载耗时	数据管道效率

4.6 真实机器人部署

将训练好的策略部署到真实机器人：

from lerobot.policies.diffusion import DiffusionPolicy
import torch

# 加载策略
policy = DiffusionPolicy.from_pretrained("outputs/train/diffusion_pusht")
policy.to("cuda")
policy.eval()

# 部署循环
robot.connect()
try:
    policy.reset()
    observation = robot.get_observation()
    done = False
    
    while not done:
        # 准备输入
        state = torch.tensor(observation["agent_pos"], dtype=torch.float32).unsqueeze(0).to("cuda")
        image = torch.tensor(observation["front"], dtype=torch.float32).permute(2, 0, 1).unsqueeze(0).to("cuda") / 255.0
        
        # 推理
        with torch.inference_mode():
            action = policy.select_action({"observation.state": state, "observation.image": image})
        
        # 执行动作
        robot.send_action(action.squeeze().cpu().numpy())
        
        # 获取新观测
        observation = robot.get_observation()
        
        # 检查任务完成
        if check_success(observation):
            done = True
            
finally:
    robot.stop_base()
    robot.disconnect()

5. 高级主题：优化与定制

5.1 策略选择指南

不同策略适用场景对比：

 radarChart
    title 策略性能对比
    axis 实时性,样本效率,精度,鲁棒性,硬件需求
    angleLines yes
    category 实时性,样本效率,精度,鲁棒性,硬件需求
    Diffusion [60, 70, 90, 85, 80]
    TDMPC [95, 85, 80, 75, 60]
    ACT [70, 65, 85, 80, 75]
    SAC [85, 90, 75, 70, 50]
    VQBeT [65, 60, 85, 80, 70]
    PI0 [60, 55, 90, 85, 85]

5.2 性能优化技巧

5.2.1 数据加载优化

# 优化数据加载
dataloader = torch.utils.data.DataLoader(
    dataset,
    batch_size=64,
    num_workers=4,  # 根据CPU核心数调整
    pin_memory=True,  # 加速CPU到GPU传输
    prefetch_factor=2,  # 预加载数据
    persistent_workers=True  # 保持worker进程
)

5.2.2 模型优化

# 混合精度训练
scaler = torch.cuda.amp.GradScaler()

with torch.cuda.amp.autocast():
    loss, _ = policy(batch)

scaler.scale(loss).backward()
scaler.step(optimizer)
scaler.update()

5.2.3 推理优化

# 推理优化
policy.eval()
with torch.inference_mode(), torch.cuda.amp.autocast():
    action = policy.select_action(batch)

5.3 常见问题与解决方案

5.3.1 电机控制问题

问题	原因	解决方案
电机抖动	增益参数不当	调整P/I/D参数，降低响应速度
位置误差	校准数据过时	重新校准机器人，更新校准文件
通信失败	端口冲突或连接不良	检查USB连接，更换端口

5.3.2 策略训练问题

问题	诊断	解决方案
损失不收敛	学习率不当或数据问题	调整学习率，检查数据分布
过拟合	数据不足或模型过强	增加数据，添加正则化，早停
策略不稳定	探索不足或奖励设计问题	调整探索策略，优化奖励函数