LeRobot 完全指南：Hugging Face 开源机器人学习框架 2026

LeRobot 是 Hugging Face 在 2024 年推出的开源机器人学习框架，旨在降低机器人学习的门槛。它提供了从数据收集、策略训练到部署的完整工具链，让开发者可以像训练 LLM 一样训练机器人策略。2026 年，LeRobot 已经成为机器人学习领域最活跃的开源项目之一。

本文将系统性地讲解 LeRobot 的核心概念、安装配置、数据管理、模型训练和实际部署，帮助你快速上手这个强大的框架。

如果你还不了解 什么是 Embodied AI，建议先阅读基础概念。LeRobot 属于具身智能技术栈的一部分，完整的开发环境搭建可以参考 开发环境搭建指南。

如果你还不了解 什么是 Embodied AI，建议先阅读基础概念。LeRobot 属于具身智能技术栈的一部分，完整的开发环境搭建可以参考 开发环境搭建指南。

你将学到：

• ✅ LeRobot 架构设计与核心概念
• ✅ 完整安装配置（支持 GPU 加速）
• ✅ 数据集管理与可视化
• ✅ 训练机械臂抓取策略（模仿学习 + 强化学习）
• ✅ Sim2Real 迁移与真实机器人部署

1. LeRobot 架构与核心概念

1.1 为什么需要 LeRobot？

传统的机器人学习流程存在几个痛点：

1. 数据格式不统一：不同机器人、不同研究团队的数据格式各异，难以复用
2. 训练流程碎片化：从数据收集到策略部署需要拼接多个工具
3. 复现困难：论文代码质量参差不齐，难以复现结果
4. 缺乏社区生态：没有类似 Hugging Face 的模型共享平台

LeRobot 通过以下方式解决这些问题：

• 统一数据格式：基于 Hugging Face Datasets，标准化机器人数据
• 端到端流程：数据收集 → 训练 → 评估 → 部署一站式完成
• 预训练模型：提供多种预训练策略，开箱即用
• 社区驱动：共享数据集、模型、配置，促进复现和协作

1.2 核心组件

LeRobot 由以下几个核心组件构成：

1. LeRobot Dataset

基于 Hugging Face Datasets 格式，存储机器人演示数据：

from lerobot.common.datasets.lerobot_dataset import LeRobotDataset

# 加载数据集
dataset = LeRobotDataset("lerobot/pusht")

# 查看数据集信息
print(dataset)
# Dataset: pusht
# Episodes: 100
# Frames: 5000
# Features: ['observation.image', 'observation.state', 'action']

# 访问单个 episode
episode = dataset[0]
print(episode.keys())
# ['observation.image', 'observation.state', 'action', 'episode', 'index']

2. LeRobot Policy

策略网络，支持多种算法：

• ACT (Action Chunking with Transformers)：基于 Transformer 的动作分块预测
• Diffusion Policy：基于扩散模型的动作生成
• VQ-BeT：基于向量量化的行为克隆
• TD-MPC2：基于模型的强化学习

from lerobot.common.policies.act.modeling_act import ACTPolicy

# 加载预训练策略
policy = ACTPolicy.from_pretrained("lerobot/act_pusht")

# 推理
observation = {
    "observation.image": image_tensor,
    "observation.state": state_tensor
}
action = policy.select_action(observation)

3. LeRobot Environment

基于 Gymnasium 的机器人环境接口：

import gymnasium as gym
import lerobot

# 加载环境
env = gym.make("lerobot/PushT-v0")

# 重置
obs, info = env.reset()

# 执行动作
action = policy.select_action(obs)
next_obs, reward, terminated, truncated, info = env.step(action)

1.3 支持的机器人

LeRobot 原生支持以下机器人：

• SO-100：低成本开源机械臂（详见 043 文章）
• Koch v1.1：改进版开源机械臂
• ALoha：双臂遥操作系统
• PushT：平面推动任务（仿真）
• XArm：UFACTORY 机械臂

你也可以通过自定义接口集成自己的机器人。如果你使用宇树 Go2 机器狗，可以参考 Go2 ROS2 开发指南 进行集成。

1.4 算法对比

算法	类型	适用场景	数据需求	推理速度	复杂度
ACT	模仿学习	抓取、推动	50+ episodes	快 (30Hz)	中
Diffusion Policy	模仿学习	复杂操作	100+ episodes	中 (15Hz)	高
VQ-BeT	模仿学习	多模态任务	50+ episodes	快 (25Hz)	中
TD-MPC2	强化学习	探索型任务	在线学习	慢 (10Hz)	高

选择建议：

• 简单抓取任务 → ACT
• 复杂多步操作 → Diffusion Policy
• 需要探索奖励 → TD-MPC2

2. 安装配置

2.1 系统要求

• 操作系统：Ubuntu 20.04/22.04（推荐），Windows/macOS（部分功能）
• Python：3.10+
• GPU：NVIDIA GPU（推荐 RTX 3060 以上），CUDA 11.8+
• 内存：16GB+（推荐 32GB）
• 存储：50GB+（数据集和模型占用空间大）

2.2 安装步骤

步骤 1：创建虚拟环境

# 使用 conda（推荐）
conda create -n lerobot python=3.10
conda activate lerobot

# 或使用 venv
python3.10 -m venv ~/lerobot-env
source ~/lerobot-env/bin/activate

步骤 2：安装 PyTorch（CUDA 11.8）

# 检查 CUDA 版本
nvidia-smi

# 安装 PyTorch（根据你的 CUDA 版本选择）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# 验证安装
python -c "import torch; print(torch.cuda.is_available())"
# 应输出 True

步骤 3：安装 LeRobot

# 从 PyPI 安装（稳定版）
pip install lerobot

# 或从源码安装（最新功能）
git clone https://github.com/huggingface/lerobot.git
cd lerobot
pip install -e .

# 安装额外依赖（用于可视化、视频处理等）
pip install "lerobot[video,visualization]"

步骤 4：验证安装

# 运行测试脚本
python -c "import lerobot; print(lerobot.__version__)"

# 下载示例数据集
python -m lerobot.download_dataset --repo-id=lerobot/pusht

# 可视化数据集
python -m lerobot.visualize_dataset --repo-id=lerobot/pusht

2.3 常见问题排查

问题 1：CUDA out of memory

# 减小 batch size
python -m lerobot.train --batch_size=16  # 默认 64

# 使用梯度累积
python -m lerobot.train --gradient_accumulation_steps=4

问题 2：数据集下载慢

# 使用 Hugging Face 镜像
export HF_ENDPOINT=https://hf-mirror.com
python -m lerobot.download_dataset --repo-id=lerobot/pusht

问题 3：OpenGL 渲染错误（无头服务器）

# 安装虚拟显示
sudo apt install xvfb
export DISPLAY=:99
Xvfb :99 -screen 0 1024x768x24 &

3. 数据集管理

3.1 数据集结构

LeRobot 数据集采用 Hugging Face Datasets 格式，存储在本地或 Hugging Face Hub：

lerobot_pusht/
├── data/
│   ├── chunk-000/
│   │   ├── episode_000000.parquet
│   │   ├── episode_000001.parquet
│   │   └── ...
│   └── chunk-001/
│       └── ...
├── videos/
│   ├── chunk-000/
│   │   ├── observation.image_episode_000000.mp4
│   │   └── ...
│   └── ...
├── meta/
│   ├── info.json          # 数据集元信息
│   ├── episodes.jsonl     # Episode 列表
│   └── tasks.jsonl        # 任务描述
└── README.md

info.json 示例：

{
  "codebase_version": "v2.0",
  "robot_type": "so100",
  "total_episodes": 100,
  "total_frames": 5000,
  "total_tasks": 1,
  "total_videos": 100,
  "total_chunks": 1,
  "chunks_size": 100,
  "fps": 30,
  "splits": {
    "train": "0:90",
    "eval": "90:100"
  },
  "data_path": "data/chunk-{episode_chunk:03d}/episode_{episode_index:06d}.parquet",
  "video_path": "videos/chunk-{episode_chunk:03d}/observation.{key}_episode_{episode_index:06d}.mp4",
  "features": {
    "observation.image": {
      "dtype": "video",
      "shape": [480, 640, 3],
      "names": ["height", "width", "channels"]
    },
    "observation.state": {
      "dtype": "float32",
      "shape": [6],
      "names": ["joint_0", "joint_1", "joint_2", "joint_3", "joint_4", "joint_5"]
    },
    "action": {
      "dtype": "float32",
      "shape": [6],
      "names": ["joint_0", "joint_1", "joint_2", "joint_3", "joint_4", "joint_5"]
    }
  }
}

3.2 加载与探索数据集

from lerobot.common.datasets.lerobot_dataset import LeRobotDataset
import matplotlib.pyplot as plt

# 加载数据集
dataset = LeRobotDataset("lerobot/pusht")

# 基本信息
print(f"总 episode 数: {dataset.num_episodes}")
print(f"总 frame 数: {dataset.num_frames}")
print(f"FPS: {dataset.fps}")

# 查看特征
for key, feature in dataset.features.items():
    print(f"{key}: {feature}")

# 访问单个样本
sample = dataset[0]
print(sample["observation.state"])  # 关节角度
print(sample["action"])  # 动作

# 可视化图像
plt.imshow(sample["observation.image"])
plt.axis("off")
plt.show()

# 遍历 episode
for episode_index in range(dataset.num_episodes):
    episode = dataset.get_episode(episode_index)
    print(f"Episode {episode_index}: {len(episode)} frames")

3.3 自定义数据集

如果你有自己的机器人数据，可以转换为 LeRobot 格式：

from lerobot.common.datasets.lerobot_dataset import LeRobotDataset
from pathlib import Path
import json

# 创建数据集目录
dataset_dir = Path("my_dataset")
dataset_dir.mkdir(exist_ok=True)
(dataset_dir / "data" / "chunk-000").mkdir(parents=True, exist_ok=True)
(dataset_dir / "videos" / "chunk-000").mkdir(parents=True, exist_ok=True)
(dataset_dir / "meta").mkdir(exist_ok=True)

# 准备数据
episodes = []
for episode_idx in range(10):
    episode_data = {
        "observation.state": [],  # 关节角度序列
        "action": [],  # 动作序列
        "episode": episode_idx,
    }
    
    # 填充数据（从你的数据源加载）
    for frame_idx in range(100):
        episode_data["observation.state"].append([0.0] * 6)  # 示例
        episode_data["action"].append([0.0] * 6)  # 示例
    
    # 保存为 parquet
    import pandas as pd
    df = pd.DataFrame(episode_data)
    df.to_parquet(dataset_dir / "data" / "chunk-000" / f"episode_{episode_idx:06d}.parquet")
    
    episodes.append({
        "episode_index": episode_idx,
        "tasks": ["pick up the red block"]
    })

# 创建元信息
info = {
    "codebase_version": "v2.0",
    "robot_type": "custom",
    "total_episodes": 10,
    "total_frames": 1000,
    "total_tasks": 1,
    "total_videos": 0,
    "total_chunks": 1,
    "chunks_size": 100,
    "fps": 30,
    "splits": {"train": "0:8", "eval": "8:10"},
    "data_path": "data/chunk-{episode_chunk:03d}/episode_{episode_index:06d}.parquet",
    "video_path": "",
    "features": {
        "observation.state": {
            "dtype": "float32",
            "shape": [6],
            "names": ["j0", "j1", "j2", "j3", "j4", "j5"]
        },
        "action": {
            "dtype": "float32",
            "shape": [6],
            "names": ["j0", "j1", "j2", "j3", "j4", "j5"]
        }
    }
}

with open(dataset_dir / "meta" / "info.json", "w") as f:
    json.dump(info, f, indent=2)

with open(dataset_dir / "meta" / "episodes.jsonl", "w") as f:
    for ep in episodes:
        f.write(json.dumps(ep) + "\n")

with open(dataset_dir / "meta" / "tasks.jsonl", "w") as f:
    f.write(json.dumps({"task": "pick up the red block"}) + "\n")

# 加载验证
dataset = LeRobotDataset(str(dataset_dir))
print(dataset)

3.4 上传到 Hugging Face Hub

# 登录 Hugging Face
huggingface-cli login

# 上传数据集
python -m lerobot.upload_dataset \
  --dataset-dir=my_dataset \
  --repo-id=your-username/my-robot-dataset

4. 训练策略

4.1 模仿学习：ACT (Action Chunking with Transformers)

ACT 是目前最流行的模仿学习算法之一，通过 Transformer 预测未来多步动作。

训练配置（config.yaml）：

# 数据集
dataset: lerobot/pusht
fps: 10

# 模型
policy: act
input_features:
  observation.image:
    type: visual
    shape: [3, 480, 640]
  observation.state:
    type: state
    shape: [2]
output_features:
  action:
    type: action
    shape: [2]

# 训练参数
batch_size: 64
steps: 10000
learning_rate: 0.0001
weight_decay: 0.0001

# ACT 特定参数
num_queries: 10  # 预测未来 10 步
num_encoder_layers: 4
num_decoder_layers: 4
dim_model: 512

# 保存与评估
save_freq: 1000
eval_freq: 1000
eval_episodes: 10

# 输出
output_dir: outputs/act_pusht

开始训练：

python -m lerobot.train \
  --config-path=configs/act/pusht.yaml

# 或使用命令行参数覆盖
python -m lerobot.train \
  --config-path=configs/act/pusht.yaml \
  --batch_size=32 \
  --steps=5000

监控训练：

# 使用 TensorBoard
tensorboard --logdir=outputs/act_pusht/checkpoints

# 或查看日志
tail -f outputs/act_pusht/training.log

4.2 扩散策略：Diffusion Policy

Diffusion Policy 通过扩散模型生成动作，适合复杂的多模态分布。

# configs/diffusion/pusht.yaml
policy: diffusion
input_features:
  observation.image:
    type: visual
    shape: [3, 480, 640]
  observation.state:
    type: state
    shape: [2]
output_features:
  action:
    type: action
    shape: [2]

# 扩散模型参数
num_diffusion_iters: 100
noise_schedule: cosine
prediction_type: epsilon

# 训练参数
batch_size: 256
steps: 5000
learning_rate: 0.0001

python -m lerobot.train --config-path=configs/diffusion/pusht.yaml

4.3 强化学习：TD-MPC2

TD-MPC2 是基于模型的强化学习算法，适合需要探索的任务。

# configs/tdmpc2/pusht.yaml
policy: tdmpc2
input_features:
  observation.image:
    type: visual
    shape: [3, 480, 640]
  observation.state:
    type: state
    shape: [2]
output_features:
  action:
    type: action
    shape: [2]

# TD-MPC2 参数
horizon: 5  # 预测步长
num_samples: 512  # 采样数
num_elites: 50
num_iterations: 6

# 训练参数
batch_size: 256
steps: 100000
replay_buffer_size: 1000000

python -m lerobot.train --config-path=configs/tdmpc2/pusht.yaml

4.4 评估与可视化

from lerobot.common.policies.act.modeling_act import ACTPolicy
from lerobot.common.envs.lerobot_env import LeRobotEnv
import imageio

# 加载策略和环境
policy = ACTPolicy.from_pretrained("outputs/act_pusht/checkpoints/last")
env = LeRobotEnv("lerobot/PushT-v0")

# 评估
total_reward = 0
frames = []

obs, info = env.reset()
for _ in range(300):
    action = policy.select_action(obs)
    obs, reward, terminated, truncated, info = env.step(action)
    total_reward += reward
    
    # 记录帧
    frames.append(env.render())
    
    if terminated or truncated:
        break

print(f"Total reward: {total_reward}")

# 保存视频
imageio.mimsave("eval.mp4", frames, fps=30)

5. 实际部署

5.1 连接真实机器人

以 SO-100 机械臂为例：

from lerobot.common.robot_devices.robots.so100 import SO100Robot
from lerobot.common.policies.act.modeling_act import ACTPolicy

# 初始化机器人
robot = SO100Robot(port="/dev/ttyUSB0")
robot.connect()

# 加载策略
policy = ACTPolicy.from_pretrained("outputs/act_so100_pick/checkpoints/last")

# 控制循环
import time

try:
    while True:
        # 读取观测
        obs = {
            "observation.image": robot.get_image(),
            "observation.state": robot.get_joint_positions()
        }
        
        # 预测动作
        action = policy.select_action(obs)
        
        # 执行动作
        robot.set_joint_positions(action)
        
        time.sleep(0.033)  # 30 Hz
        
except KeyboardInterrupt:
    robot.disconnect()

5.2 Sim2Real 迁移

Sim2Real 的关键是域随机化（Domain Randomization）：

# 训练时添加域随机化
env:
  name: lerobot/PushT-v0
  domain_randomization:
    # 视觉随机化
    camera_noise:
      position: [0.01, 0.01, 0.01]
      rotation: 0.05
    lighting:
      intensity: [0.8, 1.2]
      color: [0.9, 1.1]
    
    # 物理随机化
    object_mass: [0.8, 1.2]
    friction: [0.8, 1.2]
    
    # 动力学随机化
    joint_noise: 0.01
    action_delay: [0, 2]  # 帧数

6. 最佳实践

6.1 数据收集建议

1. 数据量：至少 50 个 episode（简单任务），复杂任务需要 200+
2. 多样性：覆盖不同的初始条件、光照、物体位置
3. 质量：确保演示成功且流畅，避免失败样本
4. 标注：为每个 episode 添加清晰的任务描述

6.2 训练技巧

1. 从预训练模型开始：使用 Hugging Face Hub 上的预训练策略
2. 逐步增加复杂度：先在仿真中验证，再迁移到真实环境
3. 监控损失曲线：训练损失应稳定下降，避免过拟合
4. 使用数据增强：颜色抖动、随机裁剪、时间掩码

6.3 部署注意事项

1. 安全限制：设置关节速度、力矩上限
2. 异常处理：检测异常状态，及时停止
3. 性能优化：使用 ONNX 或 TensorRT 加速推理
4. 日志记录：记录每次执行的观测、动作、结果

总结

LeRobot 为机器人学习提供了完整的工具链，从数据管理到策略训练再到部署，大大降低了入门门槛。通过本教程，你应该已经掌握了：

• LeRobot 的架构设计和核心概念
• 完整的安装配置流程
• 数据集管理和自定义方法
• 多种训练算法（ACT、Diffusion、TD-MPC2）
• 实际部署和 Sim2Real 迁移技巧

下一步，你可以：

1. 尝试训练自己的机器人策略
2. 贡献代码或数据集到 LeRobot 社区
3. 探索更复杂的任务（双臂操作、移动操作）
4. 结合 ROS2 通信框架 实现多机器人协同
5. 了解 Embodied AI 技术栈全景 中的仿真工具链

FAQ

LeRobot 支持哪些机器人硬件？

LeRobot 原生支持 SO-100、Koch v1.1、ALoha 双臂系统、XArm 等开源机械臂，也支持 PushT 等仿真环境。你可以通过自定义接口集成任何机器人。

LeRobot 和 Stable Baselines3 有什么区别？

Stable Baselines3 是通用的强化学习库，而 LeRobot 专注于机器人学习，提供从数据收集到部署的完整流程，并内置了模仿学习算法（ACT、Diffusion Policy）和机器人数据格式。

没有 GPU 可以训练 LeRobot 吗？

可以运行小规模实验，但推荐 NVIDIA GPU（RTX 3060 以上）。CPU 训练速度慢 10-50 倍，仅适合调试代码。

如何收集自己的训练数据？

使用 LeRobot 的遥操作接口记录演示数据，每个 episode 保存为 Parquet 格式。建议至少收集 50 个成功 episode 用于简单任务。

参考资料

• LeRobot 官方文档：https://github.com/huggingface/lerobot
• Hugging Face Datasets：https://huggingface.co/docs/datasets
• ACT 论文：https://arxiv.org/abs/2304.13705
• Diffusion Policy：https://arxiv.org/abs/2303.04137