LeRobot documentation

使用数据集工具

LeRobot

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

使用数据集工具

本指南将演示如何在线或本地探索 LeRobot 数据集，并介绍 LeRobot 提供的用于修改和编辑现有数据集的工具。

在浏览器中探索数据集

查看 LeRobot 数据集内容的快捷方式是使用 LeRobot Dataset Visualizer，这是一个 Hugging Face Space，可以播放 Hub 上的任何 LeRobot 数据集，无需安装任何内容。使用 lerobot 录制的数据集默认会推送到 Hub，除非你选择退出，因此你自己的录制内容也可以在那里打开。

The LeRobot Dataset Visualizer showing episode 0 of lerobot/svla_so101_pickplace: the episode list, two synchronized camera recordings, the task, and joint charts

要在真实数据集上尝试，请打开 lerobot/svla_so101_pickplace 的第 0 集，该集展示了一只 SO-101 机械臂将乐高积木放入盒子的过程，并按照以下步骤操作：

选择一个数据集。在可视化器的首页，输入一个仓库 ID，例如 lerobot/svla_so101_pickplace，或从示例中选择一个。登录以打开您的私有数据集。
选择一个片段。侧边栏列出了所有片段，并显示数据集的总帧数、片段数量和 FPS。点击其中一个即可打开，或使用 ↑ / ↓ 逐个切换。
观看录像。 数据集中的每个摄像头都会同步播放。您可以放大其中一个，或隐藏不需要的摄像头。视频下方会显示该回合的任务，即其语言指令。
并排读取数据。在视频下方，以每个关节一条线的形式，绘制了机器人在整个回合中的状态和动作。光标会跟随播放进度移动，图例会显示当前帧（或鼠标悬停时指针下方）的每个数值。按 Space 键可播放或暂停，拖动进度条，或点击图表以跳转到该时刻。
进一步探索。 3D Replay 根据记录的关节位置（SO-100/SO-101、OpenArm 和 Unitree G1，适用于 v3.0 数据集）对机器人进行动画演示。Advanced 提供数据集统计信息、用于标记问题片段的过滤功能、首帧/末帧概览以及动作洞察。

通过 https://huggingface.co/spaces/lerobot/visualize_dataset?path=/<repo_id>/episode_<index> 直接链接到某一集，例如与团队分享一个失败案例。

在本地可视化数据集

您也可以通过我们的命令行工具在本地可视化数据集中的 episode。

来自 Hugging Face Hub：

lerobot-dataset-viz \
    --repo-id lerobot/pusht \
    --episode-index 0

对于私有或受门禁的数据集，请先使用 hf auth login 进行身份验证，或设置 HF_TOKEN 环境变量。随后，Hub 客户端会自动发现该凭据，无需传入 token 参数。

从本地文件夹：添加 --root 选项并设置 --mode local。--root 是数据集文件夹本身。例如，对于存储在 ./my_local_data_dir/lerobot/pusht 的数据集：

lerobot-dataset-viz \
    --repo-id lerobot/pusht \
    --root ./my_local_data_dir/lerobot/pusht \
    --mode local \
    --episode-index 0

执行后，该工具会打开 rerun.io，并显示所选 episode 的相机流、机器人状态和动作。

若要使用 Foxglove 替代 Rerun，请安装 viz 附加组件（其中包含 foxglove-sdk），并添加 --display-mode foxglove。这将启动一个 WebSocket 服务器（将 Foxglove 应用连接到 ws://127.0.0.1:8765），以可寻址时间线的形式提供该 episode，支持播放/暂停和拖动。

对于高级用法——包括可视化存储在远程服务器上的数据集——请运行：

lerobot-dataset-viz --help

编辑数据集

LeRobot 提供了多种用于操作数据集的工具：

删除剧集 - 从数据集中移除特定剧集
拆分数据集 - 将一个数据集拆分为多个较小的数据集
合并数据集 - 将多个数据集合并为一个。这些数据集必须具有相同的特征，并且 episode 将按照 repo_ids 中指定的顺序进行拼接。
添加特征 - 为数据集添加新特征
移除特征 - 从数据集中移除特征
修改任务 - 更改与剧集关联的自然语言任务描述
转换为视频 - 将基于图像的转换为视频格式以实现高效存储（RGB 和深度相机使用独立的编码器进行编码）
重新编码视频 - 使用新的编码器设置重新编码现有视频数据集的 RGB 和/或深度流
显示数据集信息 - 显示数据集的摘要信息，例如 episode 数量等。

核心实现在 lerobot.datasets.dataset_tools 中。一个详细说明如何使用 tools API 的示例脚本位于 examples/dataset/use_dataset_tools.py。

命令行工具：lerobot-edit-dataset

lerobot-edit-dataset 是一个用于编辑数据集的命令行脚本。它可以用于删除 episode、拆分数据集、合并数据集、移除特征、修改任务、将图像数据集转换为视频格式、重新编码视频、重新计算统计信息以及显示数据集信息。添加特征仅可通过 Python API（lerobot.datasets.dataset_tools）实现。

运行 lerobot-edit-dataset --help 以获取有关每个操作配置的更多信息。

使用示例

删除剧集

从数据集中移除特定剧集。这对于过滤掉不需要的数据非常有用。

# Delete episodes 0, 2, and 5 (modifies original dataset)
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type delete_episodes \
    --operation.episode_indices "[0, 2, 5]"

# Delete episodes and save to a new dataset (preserves original dataset)
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --new_repo_id lerobot/pusht_after_deletion \
    --operation.type delete_episodes \
    --operation.episode_indices "[0, 2, 5]"

拆分数据集

将数据集划分为多个子集。

# Split by fractions (e.g. 60% train, 20% val, 20% test)
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type split \
    --operation.splits '{"train": 0.6, "val": 0.2, "test": 0.2}'

# Split by specific episode indices
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type split \
    --operation.splits '{"task1": [0, 1, 2, 3], "task2": [4, 5]}'

对拆分名称没有限制，可以由用户自行确定。生成的数据集会以仓库 ID 加上拆分名称的形式保存，例如 lerobot/pusht_train、lerobot/pusht_task1、lerobot/pusht_task2。

合并数据集

将多个数据集合并为一个数据集。

# Merge train and validation splits back into one dataset
lerobot-edit-dataset \
    --new_repo_id lerobot/pusht_merged \
    --operation.type merge \
    --operation.repo_ids "['lerobot/pusht_train', 'lerobot/pusht_val']"

移除功能

从数据集中移除特征。

# Remove a camera feature
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type remove_feature \
    --operation.feature_names "['observation.images.top']"

修改任务

更改附加到 episode 的自然语言任务描述。这在修正拼写错误、统一措辞或重新标记 episode 时非常有用。

modify_tasks 会就地修改数据集（更新 meta/tasks.parquet、数据文件中的 task_index 列、episode 元数据中的 tasks 列，以及 meta/info.json 中的 total_tasks）。此操作会忽略 --new_repo_id 和 --new_root 参数。

# Set a single task for all episodes
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type modify_tasks \
    --operation.new_task "Pick up the cube and place it"

# Set different tasks for specific episodes
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type modify_tasks \
    --operation.episode_tasks '{"0": "Task A", "1": "Task B", "2": "Task A"}'

# Replace existing task strings wherever they appear
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type modify_tasks \
    --operation.task_replacements '{"Pick up the red cube": "Lift the red cube"}'

# Combine modes in a single run
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type modify_tasks \
    --operation.new_task "Default task" \
    --operation.task_replacements '{"Pick up the red cube": "Lift the red cube"}' \
    --operation.episode_tasks '{"5": "Special task for episode 5"}'

参数：

new_task：用作默认值的单个任务字符串，适用于未被其他配置覆盖的回合。
episode_tasks：从 episode 索引到任务字符串的映射。
task_replacements：从现有任务字符串到其替换项的映射，应用于当前任务与某个键匹配的 episode。每个键都必须是数据集中现有的任务。

这些模式可以在单次运行中组合使用。在每个回合中，任务将按照以下优先级解决：

episode_tasks > task_replacements > new_task > 原始任务

必须指定 new_task、episode_tasks 或 task_replacements 中的至少一个。如果某个 episode 最终没有任务，则会引发错误。

转换为视频

将基于图像的转换为视频格式，创建一个新数据集，其中图像以视频形式存储。这有助于降低存储需求并提升数据加载性能。新数据集的结构与原始数据集完全相同，但图像会以符合 LeRobot 规范的 MP4 视频格式进行编码。

# Local-only: Save to a custom output directory (no hub push)
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_image_to_video \
    --operation.output_dir /path/to/output/pusht_video

# Save with new repo_id (local storage)
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --new_repo_id lerobot/pusht_video \
    --operation.type convert_image_to_video

# Convert and push to Hugging Face Hub
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --new_repo_id lerobot/pusht_video \
    --operation.type convert_image_to_video \
    --push_to_hub true

# Convert with custom video codec and quality settings
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_image_to_video \
    --operation.output_dir outputs/pusht_video \
    --operation.rgb_encoder.vcodec libsvtav1 \
    --operation.rgb_encoder.pix_fmt yuv420p \
    --operation.rgb_encoder.g 2 \
    --operation.rgb_encoder.crf 30

# Convert a dataset that includes depth maps, customizing the depth encoder
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_image_to_video \
    --operation.output_dir outputs/pusht_video \
    --operation.depth_encoder.depth_min 0.01 \
    --operation.depth_encoder.depth_max 10.0 \
    --operation.depth_encoder.use_log true

# Convert only specific episodes
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_image_to_video \
    --operation.output_dir outputs/pusht_video \
    --operation.episode_indices "[0, 1, 2, 5, 10]"

# Convert with multiple workers for parallel processing
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_image_to_video \
    --operation.output_dir outputs/pusht_video \
    --operation.num_workers 8

# For memory-constrained systems, users can now specify limits:
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type convert_image_to_video \
    --operation.max_episodes_per_batch 50 \
    --operation.max_frames_per_batch 10000

参数：

output_dir：自定义输出目录（可选 - 默认使用 new_repo_id 或 {repo_id}_video）
rgb_encoder：应用于 RGB 摄像头的视频编码器设置——所有子字段均可通过 --operation.rgb_encoder.<field> 访问。有关更多详细信息，请参阅视频编码参数。
depth_encoder：应用于深度图相机（例如来自 Intel RealSense）的视频编码器设置。除了标准的编码器字段外，它还暴露了深度量化参数（depth_min、depth_max、shift、use_log），可通过 --operation.depth_encoder.<field> 访问。这些量化设置会持久化到数据集元数据中，以便在加载时将深度反量化回物理单位。有关详细信息，请参阅 Depth streams 部分。
episode_indices：要转换的特定剧集列表（默认：所有剧集）
num_workers：用于处理的并行工作进程数量（默认值：4）

注意：生成的数据集将是一个标准的 LeRobotDataset，其中所有摄像头均编码为 videos/ 目录中的视频，parquet 文件仅包含元数据（不含原始图像数据）。深度图摄像头会被自动检测并路由至 depth_encoder，而 RGB 摄像头则使用 rgb_encoder。所有 episode、stats 和 tasks 均会保留。

重新编码视频

使用不同的编码器设置重新编码现有视频数据集中的视频，而无需返回原始帧。RGB 视频使用 rgb_encoder，深度视频使用 depth_encoder。在命令行中，这两个编码器始终具有设置（默认值，除非您更改它们），因此，如果您未配置某种流类型，则除非该流类型已经使用默认设置，否则将使用默认设置对其进行重新编码。

# Re-encode all RGB videos with new settings (saves to lerobot/pusht_reencoded by default)
lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --operation.type reencode_videos \
    --operation.rgb_encoder.vcodec h264 \
    --operation.rgb_encoder.pix_fmt yuv420p \
    --operation.rgb_encoder.crf 23

# Re-encode both RGB and depth videos in a dataset with depth maps
lerobot-edit-dataset \
    --repo_id lerobot/pusht_depth \
    --operation.type reencode_videos \
    --operation.rgb_encoder.vcodec h264 \
    --operation.depth_encoder.crf 50

参数：

rgb_encoder：应用于每个 RGB 视频的编码器设置。
depth_encoder：应用于每个深度视频的编码器设置。

若要仅重新编码一种流类型而保持另一种不变，请使用 Python API 并将另一个编码器参数设为 None，例如 reencode_dataset(dataset, rgb_encoder=..., depth_encoder=None)。

num_workers：用于处理的并行工作进程数量。

在重新编码深度视频时，现有的深度量化参数（depth_min、depth_max、shift、use_log）以及 is_depth_map 标志会被保留——重新编码仅更改存储流的编解码器/质量，而不影响加载时深度的反量化方式。

显示数据集的信息

显示数据集的信息，例如 episode 数量、frame 数量、文件大小等。不会对数据集进行任何更改


# Show dataset information without feature details
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type info

# Show dataset information with feature details
lerobot-edit-dataset \
    --repo_id lerobot/pusht_image \
    --operation.type info \
    --operation.show_features true

参数：

show_features：是否同时显示特征详情（默认值：false）。

推送到 Hub

在任何命令中添加 --push_to_hub true 标志，即可自动将生成的数据集上传到 Hugging Face Hub：

lerobot-edit-dataset \
    --repo_id lerobot/pusht \
    --new_repo_id lerobot/pusht_after_deletion \
    --operation.type delete_episodes \
    --operation.episode_indices "[0, 2, 5]" \
    --push_to_hub true

此外，还有一个用于为数据集添加功能的工具，该功能尚未在lerobot-edit-dataset中涵盖。

Update on GitHub

←移植大型数据集语言列和配方→