1万4颗星！机械臂可以接大模型了！面向真实世界机器人的尖端人工智能LeRobot

作者


项目介绍

🤗 LeRobot 旨在为 PyTorch 中的真实世界机器人提供模型、数据集和工具。目标是降低机器人技术的入门门槛，让每个人都能通过共享数据集和预训练模型做出贡献并从中受益。

🤗 LeRobot 包含已证明可迁移到真实世界的尖端方法，重点关注模仿学习和强化学习。

🤗 LeRobot 已经提供了一组预训练模型、人类收集的演示数据集和仿真环境，无需组装机器人即可开始使用。未来几周，计划为最经济实惠且功能强大的机器人增加更多真实世界机器人支持。

🤗 LeRobot 在 Hugging Face 社区页面上托管预训练模型和数据集：huggingface.co/lerobot


安装

下载源代码：

ounter(lineounter(linegit clone https://github.com/huggingface/lerobot.gitcd lerobot

创建 Python 3.10 虚拟环境并激活，例如使用 miniconda：

ounter(lineounter(lineconda create -y -n lerobot python=3.10conda activate lerobot

使用 miniconda 时，在环境中安装 ffmpeg：

ounter(lineconda install ffmpeg -c conda-forge

注意： 这通常会为你的平台安装 ffmpeg 7.X，并使用 libsvtav1 编码器编译。如果不支持 libsvtav1（可通过 ffmpeg -encoders 检查支持的编码器），你可以：

  • [任何平台] 显式安装 ffmpeg 7.X：
ounter(lineconda install ffmpeg=7.1.1 -c conda-forge
  • [仅限 Linux] 安装 ffmpeg 构建依赖 并 从源码编译带 libsvtav1 的 ffmpeg，确保使用对应的 ffmpeg 二进制文件（可通过 which ffmpeg 检查）。

安装 🤗 LeRobot：

ounter(linepip install -e .

注意： 如果遇到构建错误，可能需要安装额外的依赖（cmake、build-essential 和 ffmpeg libs）。在 Linux 上运行：sudo apt-get install cmake build-essential python3-dev pkg-config libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev pkg-config。其他系统请参考：编译 PyAV

对于仿真，🤗 LeRobot 提供了可通过 extras 安装的 gymnasium 环境：

  • aloha
  • xarm
  • pusht

例如，安装带 aloha 和 pusht 的 🤗 LeRobot：

ounter(linepip install -e ".[aloha, pusht]"

使用 Weights and Biases 进行实验跟踪，登录：

ounter(linewandb login

（注意：你还需要在配置中启用 WandB。见下文。）

快速入门

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line.├── examples             # 包含演示示例，从这里开始学习 LeRobot|   └── advanced         # 包含更多高级示例├── lerobot|   ├── configs          # 包含配置类，可通过命令行覆盖所有选项|   ├── 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 工具

可视化数据集

查看 示例 1，了解如何使用我们的数据集类，该类会自动从 Hugging Face hub 下载数据。

你也可以通过命令行执行脚本来可视化 hub 上的数据集中的片段：

ounter(lineounter(lineounter(linepython lerobot/scripts/visualize_dataset.py \    --repo-id lerobot/pusht \    --episode-index 0

或从本地文件夹中的数据集，使用 root 选项和 --local-files-only（以下情况下数据集将在 ./my_local_data_dir/lerobot/pusht 中搜索）：

ounter(lineounter(lineounter(lineounter(lineounter(linepython lerobot/scripts/visualize_dataset.py \    --repo-id lerobot/pusht \    --root ./my_local_data_dir \    --local-files-only 1 \    --episode-index 0

它将打开 rerun.io 并显示摄像头流、机器人状态和动作，如下所示：


LeRobotDataset 格式

LeRobotDataset 格式的数据集非常易于使用。它可以从 Hugging Face hub 或本地文件夹加载，例如 dataset = LeRobotDataset("lerobot/aloha_static_coffee")，并且可以像任何 Hugging Face 和 PyTorch 数据集一样索引。例如 dataset[0] 将从数据集中检索单个时间帧，包含观察结果和动作，作为 PyTorch 张量，可直接输入模型。

LeRobotDataset 的一个特点是，我们可以基于与索引帧的时间关系检索多个帧，通过设置 delta_timestamps 为相对于索引帧的相对时间列表。例如，使用 delta_timestamps = {"observation.image": [-1, -0.5, -0.2, 0]}，可以检索给定索引的 4 帧：索引帧之前的 1 秒、0.5 秒和 0.2 秒的 3 帧，以及索引帧本身（对应 0 条目）。更多关于 delta_timestamps 的细节见示例 1_load_lerobot_dataset.py。

在底层，LeRobotDataset 格式使用了多种序列化数据的方式，如果你计划更紧密地使用此格式，了解这些方式会很有帮助。我们尝试创建一个灵活而简单的数据集格式，涵盖强化学习和机器人技术中的大多数特征和特性，重点关注摄像头和机器人状态，但可以轻松扩展到其他类型的感官输入，只要它们可以用张量表示。

以下是典型 LeRobotDataset 的重要细节和内部结构组织（通过 dataset = LeRobotDataset("lerobot/aloha_static_coffee") 实例化）。具体特征因数据集而异，但主要方面不变：

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(line数据集属性：  ├ hf_dataset: 一个 Hugging Face 数据集（基于 Arrow/parquet）。典型特征示例：  │  ├ observation.images.cam_high (VideoFrame):  │  │   VideoFrame = {'path': mp4 视频路径, 'timestamp' (float32): 视频中的时间戳}  │  ├ observation.state (list of float32): 手臂关节位置（例如）  │  ... (更多观察结果)  │  ├ action (list of float32): 手臂关节目标位置（例如）  │  ├ episode_index (int64): 此样本的片段索引  │  ├ frame_index (int64): 此样本在片段中的帧索引；每个片段从 0 开始  │  ├ timestamp (float32): 片段中的时间戳  │  ├ next.done (bool): 表示片段结束；每个片段的最后一帧为 True  │  └ index (int64): 整个数据集中的通用索引  ├ episode_data_index: 包含每个片段的起始和结束索引的 2 个张量  │  ├ from (1D int64 tensor): 每个片段的第一帧索引 — 形状 (num episodes,)，从 0 开始  │  └ to: (1D int64 tensor): 每个片段的最后一帧索引 — 形状 (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", ...]`）

LeRobotDataset 使用多种广泛使用的文件格式序列化其各部分：

  • hf_dataset 使用 Hugging Face 数据集库序列化为 parquet
  • 视频存储为 mp4 格式以节省空间
  • 元数据存储为纯 json/jsonl 文件

数据集可以无缝上传/下载到 HuggingFace hub。要在本地数据集上工作，如果不在默认的 ~/.cache/huggingface/lerobot 位置，可以使用 root 参数指定其位置。

评估预训练策略

查看 示例 2，了解如何从 Hugging Face hub 下载预训练策略，并在其对应环境中运行评估。

我们还提供了一个更强大的脚本来在同一个 rollout 中并行评估多个环境。以下是使用 lerobot/diffusion_pusht 上的预训练模型的示例：

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(linepython lerobot/scripts/eval.py \    --policy.path=lerobot/diffusion_pusht \    --env.type=pusht \    --eval.batch_size=10 \    --eval.n_episodes=10 \    --policy.use_amp=false \    --policy.device=cuda

注意：训练自己的策略后，可以重新评估检查点：

ounter(linepython lerobot/scripts/eval.py --policy.path={OUTPUT_DIR}/checkpoints/last/pretrained_model

更多说明见 python lerobot/scripts/eval.py --help。

训练自己的策略

查看 示例 3，了解如何使用我们的核心库在 Python 中训练模型，以及 示例 4，了解如何从命令行使用我们的训练脚本。

要使用 wandb 记录训练和评估曲线，确保已运行 wandb login 作为一次性设置步骤。然后，在运行上述训练命令时，通过添加 --wandb.enable=true 在配置中启用 WandB。

wandb 日志的链接也会以黄色显示在终端中。以下是它们在浏览器中的样子。请同时查看 这里 了解日志中常用指标的解释。


注意：为了效率，训练期间每个检查点仅在少量片段上评估。可以使用 --eval.n_episodes=500 在比默认更多的片段上评估。或者，训练后，你可能希望在更多片段上重新评估最佳检查点或更改评估设置。更多说明见 python lerobot/scripts/eval.py --help。

复现最先进成果（SOTA）

我们在 hub 页面 上提供了一些预训练策略，可以达到最先进的性能。你可以通过从它们的运行中加载配置来复现训练。只需运行：

ounter(linepython lerobot/scripts/train.py --config_path=lerobot/diffusion_pusht

即可复现 Diffusion Policy 在 PushT 任务上的 SOTA 结果。

添加预训练策略

训练策略后，你可以使用类似 ${hf_user}/${repo_name} 的 hub id 将其上传到 Hugging Face hub（例如 lerobot/diffusion_pusht）。

首先需要找到实验目录中的检查点文件夹（例如 outputs/train/2024-05-05/20-21-12_aloha_act_default/checkpoints/002500）。其中有一个 pretrained_model 目录，应包含：

  • config.json: 策略配置的序列化版本（遵循策略的数据类配置）。
  • model.safetensors: 一组 torch.nn.Module 参数，以 Hugging Face Safetensors 格式保存。
  • train_config.json: 包含训练使用的所有参数的统一配置。策略配置应与 config.json 完全一致。这对于评估你的策略或复现性非常有用。

将这些上传到 hub，运行：

ounter(linehuggingface-cli upload ${hf_user}/${repo_name} path/to/pretrained_model

查看 eval.py 了解其他人如何使用你的策略。

通过性能分析改进代码

分析策略评估代码的示例：

ounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(lineounter(linefrom torch.profiler import profile, record_function, ProfilerActivity
def trace_handler(prof):    prof.export_chrome_trace(f"tmp/trace_schedule_{prof.step_num}.json")
with profile(    activities=[ProfilerActivity.CPU, ProfilerActivity.CUDA],    schedule=torch.profiler.schedule(        wait=2,        warmup=2,        active=3,    ),    on_trace_ready=trace_handler) as prof:    with record_function("eval_policy"):        for i in range(num_episodes):            prof.step()            # 插入要分析的代码，可能是 eval_policy 函数的整个主体

项目地址

https://github.com/huggingface/lerobot



扫码加入技术交流群，备注「开发语言-城市-昵称」

（文：GitHubStore）

发表评论

×

下载每时AI手机APP

 

和大家一起交流AI最新资讯！

立即前往