Hugging Face's logo

LeRobot documentation

Наборы данных

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Наборы данных

LeRobotDataset — это формат, который используют все скрипты LeRobot для чтения и записи. Он учитывает эпизоды, декодирует видеонаблюдения на лету и поддерживает обратную передачу в Hugging Face Hub.

См. Использование LeRobotDataset для формата и общих операций, Перенос больших наборов данных для миграции и Инструменты для CLI.

LeRobotDataset

класс lerobot.datasets.LeRobotDataset

< >

( repo_id: strroot: str | pathlib.Path | None = Noneepisodes: list[int] | None = Noneepisode_filter: collections.abc.Callable[[dict], bool] | None = Noneimage_transforms: collections.abc.Callable | None = Nonedelta_timestamps: dict[str, list[float]] | None = Nonetolerance_s: float = 0.0001revision: str | None = Noneforce_cache_sync: bool = Falsedownload_videos: bool = Truevideo_backend: str | None = Nonereturn_uint8: bool = Falsedepth_output_unit: str = 'mm'batch_encoding_size: int = 1rgb_encoder: lerobot.configs.video.RGBEncoderConfig | None = Nonedepth_encoder: lerobot.configs.video.DepthEncoderConfig | None = Noneencoder_threads: int | None = Nonestreaming_encoding: bool = Falseencoder_queue_maxsize: int = 30repo_type: str = 'dataset'token: str | bool | None = Nonevideo_decoder_cache_size: int | None = None )

add_frame

< >

( frame: dict )

Параметры

  • frame — словарь, сопоставляющий имена признаков их значениям для данного кадра. Обязательно должен включать ключ 'task'. Тензоры Torch преобразуются в numpy.

Исключения

RuntimeError

  • RuntimeError — если набор данных доступен только для чтения (нет писателя).

Добавьте один кадр в текущий буфер эпизода.

Делегирует вызов в DatasetWriter.add_frame. Набор данных должен находиться в режиме записи (создан с помощью create или resume).

clear_episode_buffer

< >

( delete_images: bool = True )

Параметры

  • delete_images — Если True, также удаляет временные файлы изображений, записанные на диск для текущего эпизода.

Исключения

RuntimeError

  • RuntimeError — если набор данных доступен только для чтения (нет писателя).

Отбросить текущий буфер эпизода без сохранения.

Делегирует вызов в DatasetWriter.clear_episode_buffer. Полезно для удаления неудачной или прерванной записи эпизода.

clear_image_transforms

< >

( )

Удалите преобразование, применённое к визуальным наблюдениям.

create

< >

( repo_id: strfps: intfeatures: dictroot: str | pathlib.Path | None = Nonerobot_type: str | None = Noneuse_videos: bool = Truetolerance_s: float = 0.0001image_writer_processes: int = 0image_writer_threads: int = 0video_backend: str | None = Nonebatch_encoding_size: int = 1rgb_encoder: lerobot.configs.video.RGBEncoderConfig | None = Nonedepth_encoder: lerobot.configs.video.DepthEncoderConfig | None = Nonemetadata_buffer_size: int = 10streaming_encoding: bool = Falseencoder_queue_maxsize: int = 30encoder_threads: int | None = Nonevideo_files_size_in_mb: int | None = Nonedata_files_size_in_mb: int | None = None )

Параметры

  • repo_id — Идентификатор репозитория, обычно '{hf_user}/{dataset_name}'.
  • fps — Количество кадров в секунду, используемое при сборе данных.
  • features — словарь спецификации признаков, сопоставляющий имена признаков с их метаданными типа/формы.
  • root — Локальная директория для хранения набора данных. По умолчанию $HF_LEROBOT_HOME/{repo_id}.
  • robot_type — Необязательная строка с типом робота, хранящаяся в метаданных.
  • use_videos — если True, визуальные модальности сохраняются в формате MP4-видео. Если False, они сохраняются в виде изображений.
  • tolerance_s — Допустимое отклонение синхронизации временных меток в секундах.
  • image_writer_processes — Количество подпроцессов для асинхронной записи изображений. 0 означает использование только потоков.
  • image_writer_threads — Количество потоков для асинхронной записи изображений.
  • video_backend — Бэкенд декодирования видео (используется при чтении обратно).
  • batch_encoding_size — количество эпизодов, накапливаемых перед пакетным кодированием видео. 1 означает немедленное кодирование.
  • rgb_encoder — Настройки видеокодирования для камер (кодек, качество и т. д.). Если None, используется rgb_encoder_defaults().
  • depth_encoder — Настройки видеокодека для камер глубины (кодек, качество и т. д.). Если None, используется depth_encoder_defaults().
  • encoder_threads — количество потоков кодировщика (глобально). None позволяет кодеку принимать решение.
  • metadata_buffer_size — количество записей метаданных эпизодов, которые буферизуются перед записью в parquet.
  • streaming_encoding — Если True, кадры видео кодируются в реальном времени во время захвата, а не записываются сначала как изображения.
  • encoder_queue_maxsize — Максимальное количество буферизованных кадров на камеру при использовании потокового кодирования.

Создайте новый LeRobotDataset с нуля для записи данных.

Возвращает набор данных в режиме записи с активным DatasetWriter. Используйте add_frame / save_episode для заполнения, а затем finalize по завершении.

finalize

< >

( )

Очистите все ожидающие операции и закройте писатели.

Должен вызываться после сбора/конвертации данных, иначе метаданные футера не будут записаны в файлы parquet, и набор данных окажется недействительным.

Идемпотентный — безопасен для многократного вызова. del в DatasetWriter служит страховкой на случай, если этот метод не был вызван явно.

get_raw_item

< >

( idx )

Получить необработанный кадр без применения преобразований изображения.

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

has_pending_frames

< >

( )

Проверьте, есть ли несохранённые кадры в буфере эпизода.

push_to_hub

< >

( branch: str | None = Nonetags: list | None = Nonelicense: str | None = 'apache-2.0'tag_version: bool = Truepush_videos: bool = Trueprivate: bool | None = Noneallow_patterns: list[str] | str | None = Noneupload_large_folder: bool = False**card_kwargs )

Параметры

  • branch — Необязательная ветка для отправки. Если она не существует, будет создана из текущего ревизии.
  • tags — Необязательный список тегов для карточки набора данных.
  • license — Идентификатор лицензии для карточки набора данных.
  • tag_version — Если True, создаёт Git-тег для текущей версии кодовой базы.
  • push_videos — если False, пропустить загрузку каталога videos/.
  • private — Если True, создаётся приватный репозиторий. Если None (значение по умолчанию), используется настройка по умолчанию для организации на Hub (влияет только на организации).
  • allow_patterns — глобальный шаблон (или шаблоны), ограничивающий, какие файлы загружать.
  • upload_large_folder — оставлено для обратной совместимости и игнорируется. upload_folder обрабатывает наборы данных любого размера.
  • **card_kwargs — Дополнительные именованные аргументы, передаваемые при создании карточки набора данных.

Загрузите набор данных в Hugging Face Hub.

Создаёт репозиторий, если он не существует, загружает все файлы набора данных (по желанию, исключая видео), генерирует карточку набора данных и помечает ревизию текущей версией кодовой базы.

resume

< >

( repo_id: strroot: str | pathlib.Path | None = Nonetolerance_s: float = 0.0001revision: str | None = Noneforce_cache_sync: bool = Falsevideo_backend: str | None = Nonebatch_encoding_size: int = 1rgb_encoder: lerobot.configs.video.RGBEncoderConfig | None = Nonedepth_encoder: lerobot.configs.video.DepthEncoderConfig | None = Noneencoder_threads: int | None = Noneimage_writer_processes: int = 0image_writer_threads: int = 0streaming_encoding: bool = Falseencoder_queue_maxsize: int = 30token: str | bool | None = None )

Параметры

  • repo_id — Идентификатор репозитория существующего набора данных.
  • root — Локальный каталог набора данных. Если указан, загрузки из Hub материализуются непосредственно в этот каталог. Если не указан, загрузки из Hub используют кэш снимков, безопасный для ревизий, в каталоге $HF_LEROBOT_HOME/hub.
  • tolerance_s — Допустимое отклонение синхронизации временных меток в секундах.
  • revision — ревизия Git (ветка, тег или хэш коммита). По умолчанию используется тег текущей версии кодовой базы.
  • force_cache_sync — Если True, повторно скачивает метаданные с Hub, даже если локальный кэш существует.
  • video_backend — Бэкенд декодирования видео для чтения данных.
  • batch_encoding_size — количество эпизодов, накапливаемых перед пакетным кодированием видео.
  • rgb_encoder — Настройки видеокодирования для камер (кодек, качество и т. д.). Если None, используется rgb_encoder_defaults().
  • depth_encoder — Настройки видеокодека для камер глубины (кодек, качество и т. д.). Если None, используется depth_encoder_defaults().
  • encoder_threads — количество потоков кодировщика (глобально). None позволяет кодеку принимать решение.
  • image_writer_processes — Подпроцессы для асинхронной записи изображений.
  • image_writer_threads — Потоки для асинхронной записи изображений.
  • streaming_encoding — Если True, кодирует видео в реальном времени во время захвата.
  • encoder_queue_maxsize — Максимальное количество буферизованных кадров на камеру для потоковой передачи.
  • token — токен аутентификации, используемый при необходимости загрузки метаданных с Hub. Токен не сохраняется в экземпляре набора данных.

Возобновить запись в существующий набор данных.

Загружает метаданные из существующего набора данных (локального или из Hub) и создаёт DatasetWriter для добавления новых эпизодов. Базовый набор данных HF не загружается, пока не будет вызван finalize и данные не будут прочитаны.

save_episode

< >

( episode_data: dict | None = Noneparallel_encoding: bool = True )

Параметры

  • episode_data — Необязательный заранее созданный словарь эпизода. Если None, используется внутренний буфер эпизода, заполняемый методом add_frame.
  • parallel_encoding — Если True и существует несколько камер, кодирует видео параллельно с использованием пула процессов.

Исключения

RuntimeError

  • RuntimeError — если набор данных доступен только для чтения (нет писателя).

Сохранить текущий буфер эпизода на диск.

Делегирует вызов в DatasetWriter.save_episode. Кодирует видео, записывает данные в parquet и обновляет метаданные. После этого буфер эпизодов сбрасывается.

select_columns

< >

( column_names: str | list[str] )

Выберите конкретные столбцы из базового набора данных.

Полезно для извлечения последовательностей действий во время воспроизведения без загрузки всех признаков. Возвращает datasets.Dataset, содержащий только запрошенные столбцы.

set_image_transforms

< >

( image_transforms: collections.abc.Callable | None )

Замените преобразование, применяемое к визуальным наблюдениям.

LeRobotDatasetMetadata

класс lerobot.datasets.LeRobotDatasetMetadata

< >

( repo_id: strroot: str | pathlib.Path | None = Nonerevision: str | None = Noneforce_cache_sync: bool = Falsemetadata_buffer_size: int = 10repo_type: typing.Literal['dataset', 'bucket'] = 'dataset'token: str | bool | None = None )

Контейнер метаданных для набора данных LeRobot.

Управляет файлами info.json, stats.json, tasks.parquet и episodes/ в формате parquet, которые описывают структуру, содержимое и статистику набора данных.

create

< >

( repo_id: strfps: intfeatures: dictrobot_type: str | None = Noneroot: str | pathlib.Path | None = Noneuse_videos: bool = Truemetadata_buffer_size: int = 10chunks_size: int | None = Nonedata_files_size_in_mb: int | None = Nonevideo_files_size_in_mb: int | None = None )

Параметры

  • repo_id — Идентификатор репозитория (например, 'user/my_dataset').
  • fps — Количество кадров в секунду, используемое при сборе данных.
  • features — словарь спецификации признаков, сопоставляющий имена признаков с их метаданными типа/формы.
  • robot_type — Необязательная строка с типом робота, хранящаяся в метаданных.
  • root — Локальная директория для набора данных. По умолчанию $HF_LEROBOT_HOME/{repo_id}. Директория не должна существовать.
  • use_videos — если True, визуальные модальности кодируются в виде MP4-видео.
  • metadata_buffer_size — количество записей метаданных эпизодов, которые буферизуются перед записью в parquet.
  • chunks_size — максимальное количество файлов в каталоге чанка. None использует значение по умолчанию.
  • data_files_size_in_mb — максимальный размер файла parquet в МБ. None использует значение по умолчанию.
  • video_files_size_in_mb — максимальный размер видеофайла в МБ. None использует значение по умолчанию.

Создайте метаданные для нового набора данных LeRobot с нуля.

Инициализирует файл info.json на диске с предоставленной схемой признаков и настройками набора данных. Данные эпизодов пока не записываются.

ensure_readable

< >

( )

Гарантируйте, что метаданные полностью загружены для операций чтения.

Идемпотентность — если метаданные уже находятся в памяти, это просто проверка is None. Вызывайте этот метод перед переходом от режима записи к режиму чтения в том же экземпляре.

filter_episodes

< >

( predicate: Callablecandidates: list[int] | None = None )

Параметры

  • predicate — Предикат по строкам метаданных эпизодов, используемый для выбора эпизодов.
  • candidates — Необязательный список индексов эпизодов для ограничения области оценки.

Фильтруйте эпизоды, метаданные которых удовлетворяют заданному предикату.

finalize

< >

( )

Очистить буфер метаданных и закрыть паркет-записыватель.

Идемпотентный — безопасно вызывать несколько раз.

get_chunk_settings

< >

( )

Получить текущие настройки размера фрагмента и файла.

get_data_file_path

< >

( ep_index: int )

Параметры

  • ep_index — Индекс эпизода, начинающийся с нуля.

Исключения

IndexError

  • IndexError — если ep_index выходит за пределы диапазона.

Возвращает относительный путь к файлу parquet для указанного индекса эпизода.

get_task_index

< >

( task: str )

По заданной задаче на естественном языке возвращает её task_index, если такая задача уже существует в наборе данных, иначе возвращает None.

get_video_file_path

< >

( ep_index: intvid_key: str )

Параметры

  • ep_index — Индекс эпизода, начинающийся с нуля.
  • vid_key — ключ признака, идентифицирующий видеопоток (например, 'observation.images.laptop').

Исключения

IndexError или ValueError

  • IndexError — если ep_index выходит за пределы диапазона.
  • ValueError — если в наборе данных нет видео (отсутствует шаблон video_path).

Возвращает относительный путь к файлу видео для указанной серии и ключа видео.

rescale_depth_stats

< >

( output_unit: str )

Масштабируйте статистику признаков глубины на месте из их записанной единицы в output_unit.

Статистика глубины хранится в единицах, в которых были записаны кадры (features[key]["info"]["depth_unit"]), тогда как при чтении кадры возвращаются в output_unit. Это преобразует записи статистики с указанием единиц, чтобы статистика соответствовала кадрам, которые видят потребители.

save_episode

< >

( episode_index: intepisode_length: intepisode_tasks: listepisode_stats: dictepisode_metadata: dict )

Параметры

  • episode_index — Индекс эпизода, сохраняемого в данный момент, начиная с нуля.
  • episode_length — Количество кадров в этом эпизоде.
  • episode_tasks — список описаний задач для этого эпизода.
  • episode_stats — Статистика по каждой характеристике для этого эпизода.
  • episode_metadata — Дополнительные метаданные (индексы чанков/файлов, диапазоны кадров, временные метки видео и т. д.).

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

Записывает метаданные эпизода в буферизованный паркет-райтер, увеличивает счётчики общего числа эпизодов/кадров в info.json и объединяет статистику эпизода с накопленной статистикой набора данных.

save_episode_tasks

< >

( tasks: list )

Параметры

  • tasks — список уникальных описаний задач на естественном языке.

Исключения

ValueError

  • ValueError — если tasks содержит дубликаты.

Зарегистрируйте задачи для текущего эпизода и сохраните их на диске.

Новые задачи, которые ещё не существуют в наборе данных, получают последовательные индексы задач и добавляются в файл задач в формате parquet.

update_chunk_settings

< >

( chunks_size: int | None = Nonedata_files_size_in_mb: int | None = Nonevideo_files_size_in_mb: int | None = None )

Параметры

  • chunks_size — Максимальное количество файлов в каталоге чанка. Если None, сохраняет текущее значение.
  • data_files_size_in_mb — Максимальный размер файлов данных в формате parquet в МБ. Если значение равно None, сохраняется текущее значение.
  • video_files_size_in_mb — Максимальный размер видеофайлов в МБ. Если None, сохраняет текущее значение.

Обновите настройки размера чанка и файла после создания набора данных.

Это позволяет пользователям настраивать организацию хранения без изменения конструктора. Эти параметры управляют тем, как эпизоды разбиваются на блоки, и максимальным размером файлов до создания новых.

update_video_info

< >

( video_key: str | None = Nonevideo_encoder: lerobot.configs.video.VideoEncoderConfig | None = Nonepreserve_keys: collections.abc.Iterable[str] | None = None )

Параметры

  • video_key — если указано, обновляется только этот ключ видео. В противном случае обновляются все ключи видео в наборе данных.
  • video_encoder — Конфигурация энкодера, используемая для создания видео. Если она указана, её поля записываются как записи video.<field> наряду с записями video.*, полученными из потока (см. get_video_info).
  • preserve_keys — ключи, значения которых сохраняются, а не пересчитываются. None (по умолчанию) пересчитывает все ключи.

Заполните или обновите информацию о видео по каждому признаку в info.json.

Warning: эта функция записывает информацию из видео первого эпизода, неявно предполагая, что все видео были закодированы одинаково. Кроме того, это означает, что предполагается существование первого эпизода.

Всегда повторно анализирует видео и перезаписывает существующие данные для каждого пересчитанного ключа. preserve_keys содержит список ключей, значения которых необходимо сохранить (например, встроенные в данные записи, такие как is_depth_map и параметры квантования глубины), а не пересчитывать.

MultiLeRobotDataset

класс lerobot.datasets.MultiLeRobotDataset

< >

( repo_ids: listroot: str | pathlib.Path | None = Noneepisodes: dict | None = Noneimage_transforms: collections.abc.Callable | None = Nonedelta_timestamps: dict[str, list[float]] | None = Nonetolerances_s: dict | None = Nonedownload_videos: bool = Truevideo_backend: str | None = Nonetoken: str | bool | None = None )

Набор данных, состоящий из нескольких базовых LeRobotDataset.

Базовые LeRobotDataset фактически конкатенируются, и этот класс во многом повторяет структуру API LeRobotDataset.

clear_image_transforms

< >

( )

Удалите transform из этого набора данных и его дочерних элементов.

set_image_transforms

< >

( image_transforms: collections.abc.Callable | None )

Замените transform для этого набора данных и его дочерних элементов.

StreamingLeRobotDataset

класс lerobot.datasets.StreamingLeRobotDataset

< >

( repo_id: strroot: str | pathlib.Path | None = Noneepisodes: list[int] | None = Noneimage_transforms: collections.abc.Callable[[torch.Tensor], torch.Tensor] | None = Nonedelta_timestamps: dict[str, list[float]] | None = Nonetolerance_s: float = 0.0001revision: str | None = Noneforce_cache_sync: bool = Falsestreaming: bool | None = Nonebuffer_size: int = 1000max_num_shards: int = 16seed: int = 42rng: numpy.random._generator.Generator | None = Noneshuffle: bool = Truereturn_uint8: bool = Falsedepth_output_unit: str = 'mm'video_backend: str | None = Nonedata_root: str | pathlib.Path | None = Noneepisode_pool_size: int | None = Noneprefetch_episodes: int = 8byte_budget_gb: float = 8.0repeat: bool = Falserepo_type: typing.Literal['dataset', 'bucket'] = 'dataset'token: str | bool | None = Nonedecode_threads: int = 2decoded_queue_size: int = 8video_decoder_cache_size: int | None = Nonenative_http_connections: int | None = Nonenative_http_subranges: int = 1sidecar_lock_timeout_s: float = 1800sampling_strategy: lerobot.streaming.episode_pool.StreamingSamplingStrategy | str = <StreamingSamplingStrategy.REMAINING: 'remaining'> )

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

Метаданные кэшируются локально, при этом каждый ранг читает только строки Parquet и диапазоны байтов MP4, необходимые для полных эпизодов, за которые он отвечает. При наличии N воркеров DataLoader каждый воркер владеет непересекающейся, сбалансированной по кадрам частью эпизодов ранга, имеет собственный пул эпизодов и 1/N от бюджета байтов. У каждого процесса есть собственный Python GIL, поэтому N воркеров декодируют и собирают образцы параллельно. Владельство эпизодов не пересекается, и каждый выбранный кадр возвращается ровно один раз за итерацию. MP4-файлы-спутники разрешаются автоматически и создаются в локальном кэше с ключом ревизии, если отсутствуют.

Пример:

Базовое использование:

from lerobot.datasets.streaming_dataset import StreamingLeRobotDataset

# Create a streaming dataset with delta timestamps
delta_timestamps = {
    "observation.image": [-1.0, -0.5, 0.0],  # 1 sec ago, 0.5 sec ago, current
    "action": [0.0, 0.1, 0.2],  # current, 0.1 sec future, 0.2 sec future
}

dataset = StreamingLeRobotDataset(
    repo_id="your-dataset-repo-id",
    delta_timestamps=delta_timestamps,
)

# Iterate over the dataset
for i, item in enumerate(dataset):
    print(f"Sample {i}: Episode {item['episode_index']} Frame {item['frame_index']}")
    # item will contain stacked frames according to delta_timestamps
    if i >= 10:
        break

load_state_dict

< >

( state: dict )

Параметры

  • state (dict[str, int]) — Локальные для ранга номер эпохи, смещение выборки и размер батча. Если ключи отсутствуют, значения по умолчанию равны 0, 0 и 1.

Исключения

ValueError

  • ValueError — если эпоха или смещение отрицательные, либо размер батча не является положительным.

Восстановить позицию якоря следующего итератора без получения пропущенных образцов.

Note: Для воспроизведения порядка якорей необходимы один и тот же набор данных, seed, sampler, настройки пула, распределённая топология и количество workers в DataLoader. При использовании нескольких workers смещение представляет собой смещение rank в целых батчах размера batch_size; каждый worker вычисляет свою часть, поскольку DataLoader получает батчи от своих workers по очереди. Случайные преобразования изображений этим методом не восстанавливаются.

num_episodes_for_rank

< >

( rank: intworld_size: int )

Возвращает количество полных эпизодов, за которыми закреплён один ранг обучения.

num_frames_for_rank

< >

( rank: intworld_size: intnum_workers: int )

Возвращает кадры, принадлежащие одному рангу обучения, при сбалансированном шардировании целых эпизодов.

set_data_parallel_shard

< >

( rank: intworld_size: int )

Зафиксируйте ранг и размер мира для параллелизма данных до torch.distributed и окружения.

Созданный рабочий процесс DataLoader не имеет инициализированного torch.distributed; значения передаются в него через pickle.

set_epoch

< >

( epoch: int )

Параметры

  • epoch (int) — Эпоха покрытия, используемая для инициализации плана следующей выборки, если включено перемешивание.

Исключения

ValueError

  • ValueError — если значение epoch отрицательное.

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

state_dict

< >

( ) → dict[str, int]

Возвращает

dict[str, int]

Эпоха, смещение по выданным образцам и размер батча для возобновления.

Возвращает текущую позицию итератора в пределах локального ранга.

Note: При предварительной загрузке данных с помощью DataLoader выданные образцы могут ещё не быть использованы в процессе обучения. Конвейер обучения восстанавливает свою позицию на основе завершённых шагов. При использовании нескольких рабочих процессов DataLoader каждый процесс хранит только собственную позицию.

Update on GitHub

←Двигатели Политики→