LeRobot documentation

Использование инструментов для работы с наборами данных

LeRobot

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.6.1).

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, которое воспроизводит любой набор данных LeRobot с Hub без необходимости установки чего-либо. Наборы данных, которые вы записываете с помощью 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

Чтобы попробовать это на реальном наборе данных, откройте эпизод 0 из lerobot/svla_so101_pickplace, где манипулятор SO-101 кладёт деталь Лего в коробку, и следуйте инструкциям:

Выберите набор данных. На главной странице визуализатора введите идентификатор репозитория, например 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>, например, чтобы поделиться с командой случаем сбоя.

Визуализация набора данных локально

Вы также можете локально визуализировать эпизоды из набора данных с помощью нашего инструмента командной строки.

Из Hugging Face Hub:

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

Для частного или защищённого набора данных сначала выполните аутентификацию с помощью hf auth login или задайте переменную окружения HF_TOKEN. Затем клиент Hub автоматически обнаружит учётные данные; аргумент с токеном не требуется.

Из локальной папки: добавьте опцию --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 и отображает потоки с камер, состояния робота и действия для выбранного эпизода.

Чтобы использовать Foxglove вместо Rerun, установите дополнительный пакет viz (он включает foxglove-sdk) и добавьте --display-mode foxglove. Это запустит WebSocket-сервер (подключите приложение Foxglove к ws://127.0.0.1:8765), который предоставляет эпизод в виде интерактивной временной шкалы, по которой можно перемещаться, а также воспроизводить и ставить на паузу.

Для расширенного использования — включая визуализацию наборов данных, хранящихся на удалённом сервере — выполните:

lerobot-dataset-viz --help

Редактирование наборов данных

LeRobot предоставляет несколько утилит для работы с наборами данных:

Удалить эпизоды — удалить конкретные эпизоды из набора данных
Разделение набора данных — Разделение набора данных на несколько более мелких
Объединение наборов данных — объединение нескольких наборов данных в один. Наборы данных должны иметь идентичные признаки, а эпизоды конкатенируются в порядке, указанном в repo_ids
Добавить признаки — добавить новые признаки в набор данных
Удаление признаков — Удаление признаков из набора данных
Изменение задач — изменение описаний задач на естественном языке, связанных с эпизодами
Конвертировать в видео — преобразование наборов данных на основе изображений в формат видео для эффективного хранения (камеры RGB и глубины кодируются отдельными кодировщиками)
Перекодирование видео — перекодирование потоков RGB и/или глубины существующего набора данных видео с новыми настройками кодировщика
Показать информацию о наборах данных — Выводит сводную информацию о наборах данных, например, количество эпизодов и т. д.

Основная реализация находится в lerobot.datasets.dataset_tools. Пример скрипта, демонстрирующий использование API инструментов, доступен в examples/dataset/use_dataset_tools.py.

Инструмент командной строки: lerobot-edit-dataset

lerobot-edit-dataset — это скрипт командной строки для редактирования наборов данных. С его помощью можно удалять эпизоды, разделять наборы данных, объединять их, удалять признаки, изменять задачи, конвертировать наборы данных с изображениями в формат видео, перекодировать видео, пересчитывать статистику и отображать информацию о наборе данных. Добавление признаков доступно только через 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]}'

На имена разбиений не накладывается никаких ограничений, они определяются пользователем. Полученные наборы данных сохраняются под идентификатором репозитория с добавлением имени разбиения, например, 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']"

Изменение задач

Изменяйте описания задач на естественном языке, привязанные к эпизодам. Это полезно для исправления опечаток, унификации формулировок или повторной разметки эпизодов.

modify_tasks изменяет набор данных на месте (обновляет meta/tasks.parquet, столбец task_index в файлах данных, столбец tasks в метаданных эпизодов и total_tasks в meta/info.json). Параметры --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: Соответствие между индексом эпизода и строкой задачи.
task_replacements: Соответствие между существующими строками задач и их заменами, применяемое к эпизодам, текущая задача которых совпадает с ключом. Каждый ключ должен быть существующей задачей в наборе данных.

Режимы можно комбинировать в одном запуске. Для каждого эпизода задача разрешается со следующим приоритетом:

episode_tasks > task_replacements > new_task > исходная задача

Необходимо указать хотя бы один из параметров new_task, episode_tasks или task_replacements. Если в итоге у эпизода не окажется задачи, будет выброшена ошибка.

Конвертация в видео

Преобразование набора данных на основе изображений в формат видео с созданием нового LeRobotDataset, в котором изображения хранятся в виде видео. Это полезно для снижения требований к хранилищу и улучшения производительности загрузки данных. Новый набор данных будет иметь точно такую же структуру, как и исходный, но с изображениями, закодированными в виде MP4-файлов в соответствующем формате LeRobot.

# 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. Все эпизоды, статистика и задачи сохраняются.

Перекодирование видео

Перекодировать видео из существующего набора данных с другими настройками кодировщика, не возвращаясь к исходным кадрам. Для 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 сохраняются — повторное кодирование изменяет только кодек/качество хранимого потока, но не способ деквантования глубины при загрузке.

Показать информацию о наборах данных

Показывает информацию о наборах данных, например, количество эпизодов, количество кадров, размер файла и т. д. Изменения в наборе данных не вносятся


# 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

←Портинг больших наборов данных Языковые столбцы и рецепты→