LeRobot 入门实践教程
LeRobot 项目旨在为机器人端到端深度学习提供全栈的工具链。目前该项目支持了少数经典的具身智能端到端深度学习的简单案例，其中包含算法和模型实现、简单仿真环境实现、人类采集的简单数据集和预训练的模型权重。本教程以 ACT 和 Diffusion Policy 为例，介绍 LeRobot 的使用全流程，更详细准确的信息应当参考项目源码和手册：https://github.com/huggingface/lerobot。
安装 conda
# 检查机器是否安装Conda，如果返回了版本号，说明Conda已经成功安装
conda --version
# 如果机器上未安装Conda, 请按照以下步骤安装：
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
sh Miniconda3-latest-Linux-x86_64.sh
# 再次检查
conda --version克隆项目源码
git clone https://github.com/huggingface/lerobot.git
cd lerobot创建 conda 虚拟环境并指定 python 版本为 3.10
conda create -y -n lerobot python=3.10
conda activate lerobot安装 LeRobot 库
pip install -e ".[aloha, pusht]"HuggingFace 镜像源
# 如果你使用的是其它 shell 请将 ~/.bashrc 替换为相应的运行配置文件，如 zsh 应当是 ~/.zshrc
echo "export HF_ENDPOINT=https://hf-mirror.com" >> ~/.bashrc
source ~/.bashrc├── examples # 包含演示示例，这里可以深入了解LeRobot的细节(建议仔细阅读)
| └── advanced # 包含更多示例，适合那些已经掌握LeRobot基础的人
├── lerobot
| ├── configs # 包含 Hydra YAML 文件，里面包含可以在命令行中覆盖的所有选项
| | ├── default.yaml # 默认选中的配置，加载 pusht 环境和扩散策略
| | ├── env # 各种仿真环境及其数据集：aloha.yaml, pusht.yaml, xarm.yaml
| | └── policy # 各种策略：act.yaml, diffusion.yaml, tdmpc.yaml
| ├── common # 包含类和实用工具
| | ├── datasets # 各种人类示范数据集：aloha, pusht, xarm
| | ├── envs # 各种仿真环境：aloha, pusht, xarm
| | ├── policies # 各种策略：act, diffusion, tdmpc
| | ├── robot_devices # 各种真实设备：dynamixel 电机、opencv 摄像头、koch 机器人
| | └── utils # 各种实用工具
| └── scripts # 包含通过命令行执行的功能
| ├── eval.py # 加载策略并在环境中进行评估
| ├── train.py # 通过模仿学习和/或强化学习训练策略
| ├── control_robot.py # 遥控真实机器人、记录数据、运行策略
| ├── push_dataset_to_hub.py # 将数据集转换为 LeRobot 数据集格式并上传到 Hugging Face hub
| └── visualize_dataset.py # 加载数据集并渲染其示范数据
├── outputs # 包含脚本执行结果：日志、视频、模型检查点
└── tests # 包含用于持续集成的 pytest 工具
LeRobot 作为 HuggingFace 的子项目，延续了 HuggingFace 管理数据集仓库和模型仓库的接口和办法。对于任何一个 HuggingFace 的数据集仓库或者模型仓库，都可以用以下方式进行下载：1️⃣使用 huggingface 的 Python API 下载至缓存目录 2️⃣使用 git lfs 工具下载 3️⃣网页点击下载。
对于第一种下载方式，HuggingFace 默认的缓存路径是 ~/.cache/huggingface 而 LeRobot 默认的缓存路径是 ~/.cache/huggingface/lerobot，可以通过如下设置环境变量的方式修改默认的缓存路径。
export HF_HOME={your_cache_dir}/huggingface
export LEROBOT_HOME=$HF_HOME/lerobot将上面的代码添加至你的 shell 配置文件中，如果你使用的是 bash，那么添加至 ~/.bashrc 中，如果你使用的是 zsh，那么添加至 ~/.zshrc 中。添加完成后，请重启开启一个终端，或者执行 source ~/.bashrc 或 souorce ~/.zshrc。
请仔细阅读并执行：examples/1_load_lerobot_dataset.py
其中包含了以下内容的示例代码：
- 获取 LeRobot 所有数据集的名字列表
- 获取某个数据集的元数据（总轨迹数、平均每条轨迹的帧数、平均每秒帧数和机器人类型等等）
- 下载某个数据集
- 构造一个 LeRobot 数据集对象，并了解重要的参数
- 将一个 LeRobot 数据集封装为一个 PyTorch 的 DataLoader 对象
Rerun 是一个用于机器学习、计算机视觉和机器人研究的可视化工具，专为在调试和分析过程中实时查看多模态数据和结果而设计。
LeRobot 提供了基于 ReRun 工具的数据集可视化脚本，详见 lerobot/scripts/visualize_dataset.py
# --repo-id 表示数据集的唯一标识
# --episode-index 表示轨迹编号
# 更多参数说明请参考脚本源码或者运行 python lerobot/scripts/visualize_dataset.py --help
# 可视化 lerobot/pusht 数据集
python lerobot/scripts/visualize_dataset.py \
--repo-id lerobot/pusht \
--episode-index 0
# 可视化 lerobot/aloha_sim_transfer_cube_human 数据集
python lerobot/scripts/visualize_dataset.py \
--repo-id lerobot/aloha_sim_transfer_cube_human \
--episode-index 0pusht 数据集是 Diffusion Policy 官方测试使用的仿真任务，aloga_sim 是 ACT 官方测试使用的仿真任务，在 LeRobot 项目中，设计了统一的代码接口，允许用户方便地在其中任意的仿真任务上呀验证任意算法。
运行如上代码，应当看到如下窗口。
| PushT | AlohaSim |
|---|---|
 |
 |
dataset attributes:
├── hf_dataset: Hugging Face 数据集（Arrow/parquet）
│ ├── observation.images.cam_high (VideoFrame)
│ │ └── VideoFrame = {'path': 视频文件的路径，'timestamp' (float32): 视频中的时间戳}
│ ├── observation.state (list of float32): 臂关节的位置
│ ├── ... (更多的观察数据)
│ ├── action (list of float32): 臂关节的目标位置
│ ├── episode_index (int64): 该样本所在的 episode 索引
│ ├── frame_index (int64): 该样本在 episode 中的帧索引；对于每个 episode 从 0 开始
│ ├── timestamp (float32): episode 中的时间戳
│ ├── next.done (bool): 指示 episode 是否结束；每个 episode 的最后一帧为 True
│ └── index (int64): 整个数据集中的通用索引
├── episode_data_index: 包含两个张量，表示每个 episode 的开始和结束索引
│ ├── from (1D int64 tensor): 每个 episode 的第一帧索引 — 形状为 (num episodes,) 从 0 开始
│ └── to (1D int64 tensor): 每个 episode 的最后一帧索引 — 形状为 (num episodes,)
├── stats: 字典，包含每个特征的统计数据（最大值、均值、最小值、标准差）
│ └── observation.images.cam_high: {'max': 与该特征维度相同的张量（例如，图像为 `(c, 1, 1)`，状态为 `(c,)` 等）}
├── info: 字典，包含数据集元数据
│ ├── codebase_version (str): 用于跟踪创建数据集时使用的代码库版本
│ ├── fps (float): 数据集的帧率（每秒帧数）
│ ├── video (bool): 指示帧是否被编码为 MP4 视频文件以节省空间，或以 PNG 文件存储
│ └── encoding (dict): 如果是视频，记录使用 ffmpeg 编码视频时的主要选项
├── videos_dir (Path): 存储/访问 MP4 视频或 PNG 图像的路径
└── camera_keys (list of string): 用于访问数据集返回项中的相机特征的键（例如 `["observation.images.cam_high", ...]`）
请仔细阅读并执行：examples/2_evaluate_pretrained_policy.py
其中包含了以下内容的示例代码：
- 加载一个预训练好的模型（本地或云端）
- 创建一个可互动的仿真环境
- 模型与仿真环境交互并保存测试视频
尝试将第 26 行代码替换为如下代码重新执行，观察模型未经训练时的表现，与预训练好的效果进行对比：
from lerobot.common.datasets.lerobot_dataset import LeRobotDataset
from lerobot.common.policies.diffusion.modeling_diffusion import DiffusionConfig
cfg = DiffusionConfig()
delta_timestamps = {
"observation.image": [-0.1, 0.0],
"observation.state": [-0.1, 0.0],
"action": [-0.1, 0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3, 1.4],
}
dataset = LeRobotDataset("lerobot/pusht", delta_timestamps=delta_timestamps)
policy = DiffusionPolicy(cfg, dataset_stats=dataset.meta.stats)请仔细阅读并执行：examples/3_train_policy.py
其中包含了端到端模仿学习训练一个模型的示例代码
训练完成后用 examples/2_evaluate_pretrained_policy.py 测试训练后保存的模型（需要修改模型加载路径），并观察效果
可以发现虽然运行了正确的代码，但是并没有得到理想的结果，接下来我们借助一些工具（监控工具 WandB 和脚本化参数工具 Hydra，帮助我们调整训练超参数，从而复现最优效果。
WandB（Weights & Biases）是一个用于机器学习实验跟踪、可视化、和协作的工具，帮助研究人员和开发者更有效地记录、分析和优化他们的模型训练过程。
- 注册账号并登录：https://wandb.ai/
- 在用户设置中创建自己的 API keys
- 以下两种二选一，使得本地运行的实验能够登入 WandB 服务器的个人空间
- 在命令行中执行
wandb login并按照提示输入 API Key - 配置如下环境变量
# WandB Config export WANDB_API_KEY=<你的 API Key> export WANDB_USER_EMAIL=<你的 WandB 注册邮箱> export WANDB_USERNAME=<你的 WandB 用户名>
- 在命令行中执行
以下脚本的参数能够保证复现出最优结果
请比较复现出最优结果的脚本基于原来的代码做出来哪些调整？
# 在 Aloha Sim Insertion 仿真任务上训练 ACT
python lerobot/scripts/train.py \
policy=act \
env=aloha \
env.task=AlohaInsertion-v0 \
dataset_repo_id=lerobot/aloha_sim_insertion_human \
wandb.enable=true \
hydra.job.name=ACT-Aloha-Insertion
# 在 Push-T 仿真任务上训练 ACT
cp ./examples/advanced/1_train_act_pusht/act_pusht.yaml ./configs/policy/
python lerobot/scripts/train.py \
policy=act_pusht \
env=pusht \
dataset_repo_id=lerobot/pusht \
wandb.enable=true \
hydra.job.name=ACT-PushT# 在 Push-T 仿真任务上训练 Diffusion Policy
python lerobot/scripts/train.py \
policy=diffusion \
env=pusht \
dataset_repo_id=lerobot/pusht \
wandb.enable=true \
hydra.job.name=DP-PushT
# 在 Aloha Sim Insertion 仿真任务上训练 Diffusion Policy
# 由于 Lerobot 未提供 diffusion_aloha.yaml，可以使用本仓库修改好的 ./yaml/diffusion_aloha.yaml
python lerobot/scripts/train.py \
policy=diffusion_aloha \
env=aloha \
env.task=AlohaInsertion-v0 \
dataset_repo_id=lerobot/aloha_sim_insertion_human \
wandb.enable=true \
hydra.job.name=DP-Aloha-Insertion网页登录wandb，并进入对应的 Lerobot 项目，将会出现以下界面，观察模型的训练过程：
# 与 4.1 类似，将预训练的 lerobot/diffusion_pusht 换成自己的模型路径
python lerobot/scripts/eval.py \
-p {OUTPUT_DIR}/checkpoints/last/pretrained_model \
eval.n_episodes=10 \
eval.batch_size=10
## e.g. OUTPUT_DIR 为 outputs/train/2025-01-06/01-12-47_pusht_diffusion_DP-PushT
python lerobot/scripts/eval.py \
-p outputs/train/2025-01-06/01-12-47_pusht_diffusion_DP-PushT/checkpoints/last/pretrained_model \
eval.n_episodes=10 \
eval.batch_size=10 录制且上传到 Hub：
# HF_USER为Huggingface用户名，DATASET_NAME为定义的任务数据集名称
export HF_USER=xxx
export DATASET_NAME=xxx
python lerobot/scripts/control_robot.py \
record \
--repo-id $HF_USER/$DATASET_NAME \
--single-task $DATASET_NAME \
--fps 30 \
--tags tutorial \
--warmup-time-s 3 \
--episode-time-s 30 \
--reset-time-s 3 \
--num-episodes 50# HF_USER为Huggingface用户名，DATASET_NAME为定义的任务数据集名称
export HF_USER=xxx
export DATASET_NAME=xxx
python lerobot/scripts/train.py \
dataset_repo_id=$HF_USER/$DATASET_NAME \
hydra.run.dir=outputs/train/$DATASET_NAME# HF_USER为Huggingface用户名，DATASET_NAME为定义的任务数据集名称, CHECK_POINT为对应保存子目录
export HF_USER=xxx
export DATASET_NAME=xxx
export CHECK_POINT=xxxxx
python lerobot/scripts/control_robot.py \
record \
-p outputs/train/$DATASET_NAME/checkpoints/$CHECK_POINT/pretrained_model \
--repo-id $HF_USER/eval_$DATASET_NAME \
--single-task eval_$DATASET_NAME \
--fps 30 \
--warmup-time-s 3 \
--reset-time-s 3 \
--episode-time-s 120 \
--num-episodes 10 \
--push-to-hub 0