LeRobot documentation

LeRobotDataset v3.0

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

LeRobotDataset v3.0

LeRobotDataset v3.0 es un formato estandarizado para datos de aprendizaje de robots. Proporciona acceso unificado a datos de series temporales multimodales, señales sensoriomotoras y vídeo de múltiples cámaras, así como metadatos ricos para indexación, búsqueda y visualización en Hugging Face Hub.

Para ver qué contiene un dataset en este formato antes de leer sobre su estructura, ábralo en el LeRobot Dataset Visualizer: grabaciones de cámara, gráficos de estado y acción sincronizados, y cada episodio, en el navegador. Consulte Explore a Dataset in the Browser.

Esta documentación te guiará para:

  • Comprender el diseño y la estructura de directorios de v3.0
  • Registrar un conjunto de datos y subirlo al Hub
  • Cargar conjuntos de datos para el entrenamiento con LeRobotDataset
  • Transmite conjuntos de datos sin descargarlos usando StreamingLeRobotDataset
  • Aplicar transformaciones de imagen para la aumentación de datos durante el entrenamiento
  • Migrar los conjuntos de datos existentes de v2.1 a v3.0
  • Experimenta con otros formatos e implementaciones de LeRobotDataset, como Lance

Novedades en v3

  • Almacenamiento basado en archivos: Muchos episodios por archivo Parquet/MP4 (la v2 usaba un archivo por episodio).
  • Metadatos relacionales: Los límites de los episodios y las búsquedas se resuelven a través de metadatos, no de nombres de archivo.
  • Streaming nativo del Hub: Consume datasets directamente del Hub con StreamingLeRobotDataset.
  • Menor presión sobre el sistema de archivos: Menos archivos, pero más grandes ⇒ inicialización más rápida y menos problemas a gran escala.
  • Organización unificada: Estructura de directorios limpia con plantillas de rutas consistentes en datos y videos.
  • Backends de almacenamiento de conjuntos de datos: Los conjuntos de datos también se pueden almacenar como tablas de LanceDB para acceso aleatorio e indexación directamente desde el almacenamiento de objetos (ver backend de conjuntos de datos de LanceDB).

Instalación

LeRobotDataset v3.0 está incluido en lerobot >= 0.4.0. Siga la Guía de instalación para instalarlo.

Registrar un conjunto de datos

Ejecuta el siguiente comando para registrar un conjunto de datos con el SO-101 y subirlo al Hub:

lerobot-record \
  --robot.type=so101_follower \
  --robot.port=/dev/tty.usbmodem585A0076841 \
  --robot.id=my_awesome_follower_arm \
  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}}" \
  --teleop.type=so101_leader \
  --teleop.port=/dev/tty.usbmodem58760431551 \
  --teleop.id=my_awesome_leader_arm \
  --display_data=true \
  --dataset.repo_id=${HF_USER}/record-test \
  --dataset.num_episodes=5 \
  --dataset.single_task="Grab the black cube" \
  --dataset.streaming_encoding=true \
  --dataset.encoder_threads=2
# Optional: --dataset.rgb_encoder.vcodec=auto

Consulte la guía de grabación para obtener más detalles.

Diseño del formato

Un principio central de v3 es desacoplar el almacenamiento de la API de usuario: los datos se almacenan de forma eficiente (pocos archivos grandes), mientras que la API pública expone un acceso intuitivo a nivel de episodio.

v3 tiene tres pilares:

  1. Datos tabulares: señales de baja dimensión y alta frecuencia (estados, acciones, marcas de tiempo) almacenadas en Apache Parquet. El acceso es mediante mapeo de memoria o en flujo a través de la pila datasets.
  2. Datos visuales: Marcos de cámara concatenados y codificados en MP4. Los marcos del mismo episodio se agrupan; los videos se dividen por cámara para tamaños prácticos.
  3. Metadatos: registros JSON/Parquet que describen el esquema (nombres de características, dtypes, formas), tasas de fotogramas, estadísticas de normalización y segmentación de episodios (desplazamientos de inicio/fin en los archivos Parquet/MP4 compartidos).

Para escalar a millones de episodios, las filas tabulares y los fotogramas de vídeo de varios episodios se concatenan en archivos más grandes. Las vistas específicas de cada episodio se reconstruyen mediante metadatos, no mediante los límites de los archivos.

LeRobotDataset v3 diagram
De conjuntos de datos basados en episodios a conjuntos de datos basados en archivos

Estructura del directorio (simplificada)

  • meta/info.json: esquema canónico (características, formas/tipos de datos), FPS, versión del código base y plantillas de ruta para localizar los fragmentos de datos/vídeo.
  • meta/stats.json: estadísticas globales de las características (media/desviación estándar/mínimo/máximo) utilizadas para la normalización; expuestas como dataset.meta.stats.
  • meta/tasks.parquet: descripciones de tareas en lenguaje natural mapeadas a IDs enteros para políticas condicionadas por tarea.
  • meta/episodes/: registros por episodio (longitudes, tareas, desplazamientos) almacenados como Parquet por lotes para escalabilidad.
  • data/: fragmentos Parquet cuadro a cuadro; cada archivo suele contener muchos episodios.
  • videos/: fragmentos MP4 por cámara; cada archivo suele contener muchos episodios.

Cargar un conjunto de datos para el entrenamiento

LeRobotDataset devuelve diccionarios de Python de tensores de PyTorch e integra con torch.utils.data.DataLoader. A continuación se muestra un ejemplo de código que ilustra su uso:

import torch
from lerobot.datasets import LeRobotDataset

repo_id = "yaak-ai/L2D-v3"

# 1) Load from the Hub (cached locally)
dataset = LeRobotDataset(repo_id)

# 2) Random access by index
sample = dataset[100]
print(sample)
# {
#   'observation.state': tensor([...]),
#   'action': tensor([...]),
#   'observation.images.front_left': tensor([C, H, W]),
#   'timestamp': tensor(1.234),
#   ...
# }

# 3) Temporal windows via delta_timestamps (seconds relative to t)
delta_timestamps = {
    "observation.images.front_left": [-0.2, -0.1, 0.0]  # 0.2s and 0.1s before current frame
}

dataset = LeRobotDataset(repo_id, delta_timestamps=delta_timestamps)

# Accessing an index now returns a stack for the specified key(s)
sample = dataset[100]
print(sample["observation.images.front_left"].shape)  # [T, C, H, W], where T=3

# 4) Wrap with a DataLoader for training
batch_size = 16
data_loader = torch.utils.data.DataLoader(dataset, batch_size=batch_size)

device = "cuda" if torch.cuda.is_available() else "cpu"
for batch in data_loader:
    observations = batch["observation.state"].to(device)
    actions = batch["action"].to(device)
    images = batch["observation.images.front_left"].to(device)
    # model.forward(batch)

Transmitir un conjunto de datos durante el entrenamiento

Establezca --dataset.streaming=true para entrenar sin descargar primero los archivos Parquet y de video del conjunto de datos. Los episodios se obtienen al vuelo en un pool de memoria acotado, y cada cuadro seleccionado se visita exactamente una vez por época:

lerobot-train \
  --dataset.repo_id=yaak-ai/L2D-v3 \
  --dataset.streaming=true \
  --policy.type=act \
  --output_dir=outputs/train/act_streaming

El mismo lector está disponible en Python, para conjuntos de datos del Hub y para conjuntos de datos almacenados en un HF Storage Bucket:

from lerobot.datasets import StreamingLeRobotDataset

dataset = StreamingLeRobotDataset("yaak-ai/L2D-v3")
bucket_dataset = StreamingLeRobotDataset("my-org/my-bucket", repo_type="bucket")

Desde la CLI, seleccione un bucket con --dataset.repo_type=bucket o --dataset.root=hf://buckets/my-org/my-bucket.

Consulte Training Dataset Streaming para ver cómo los workers y los shards se mapean a la concurrencia de streaming, el índice lateral MP4, la configuración de memoria, la reanudación y la solución de problemas.

StreamingLeRobotDataset
Transmite directamente desde el Hub para entrenar sobre la marcha.

Transformaciones de imagen

Las transformaciones de imagen son aumentos de datos aplicados a los fotogramas de la cámara durante el entrenamiento para mejorar la robustez y la generalización del modelo. LeRobot admite diversas transformaciones, incluidos ajustes de brillo, contraste, saturación, tono y nitidez.

Uso de transformaciones durante la creación/grabación del conjunto de datos

Actualmente, las transformaciones se aplican solo durante el entrenamiento, no durante la grabación. Al crear o grabar un conjunto de datos, las imágenes sin procesar se almacenan sin transformaciones. Esto permite experimentar con diferentes aumentaciones más adelante sin necesidad de volver a grabar los datos.

Agregar transformaciones a conjuntos de datos existentes (API)

Use el parámetro image_transforms al cargar un conjunto de datos para el entrenamiento:

from lerobot.datasets import LeRobotDataset
from lerobot.transforms import ImageTransforms, ImageTransformsConfig, ImageTransformConfig

# Option 1: Use default transform configuration (disabled by default)
transforms_config = ImageTransformsConfig(
    enable=True,  # Enable transforms
    max_num_transforms=3,  # Apply up to 3 transforms per frame
    random_order=False,  # Apply in standard order
)
transforms = ImageTransforms(transforms_config)

dataset = LeRobotDataset(
    repo_id="your-username/your-dataset",
    image_transforms=transforms
)

# Option 2: Create custom transform configuration
custom_transforms_config = ImageTransformsConfig(
    enable=True,
    max_num_transforms=2,
    random_order=True,
    tfs={
        "brightness": ImageTransformConfig(
            weight=1.0,
            type="ColorJitter",
            kwargs={"brightness": (0.7, 1.3)}  # Adjust brightness range
        ),
        "contrast": ImageTransformConfig(
            weight=2.0,  # Higher weight = more likely to be selected
            type="ColorJitter",
            kwargs={"contrast": (0.8, 1.2)}
        ),
        "sharpness": ImageTransformConfig(
            weight=0.5,  # Lower weight = less likely to be selected
            type="SharpnessJitter",
            kwargs={"sharpness": (0.3, 2.0)}
        ),
    }
)

dataset = LeRobotDataset(
    repo_id="your-username/your-dataset",
    image_transforms=ImageTransforms(custom_transforms_config)
)

# Option 3: Use pure torchvision transforms
from torchvision.transforms import v2

torchvision_transforms = v2.Compose([
    v2.ColorJitter(brightness=0.2, contrast=0.2, saturation=0.2, hue=0.1),
    v2.GaussianBlur(kernel_size=3, sigma=(0.1, 2.0)),
])

dataset = LeRobotDataset(
    repo_id="your-username/your-dataset",
    image_transforms=torchvision_transforms
)

Tipos de transformaciones disponibles

El type de una transformación puede ser cualquier clase de torchvision.transforms.v2, por ejemplo:

  • ColorJitter: Ajusta el brillo, el contraste, la saturación y el tono
  • SharpnessJitter: Ajusta aleatoriamente la nitidez de la imagen
  • RandomAffine, RandomRotation: jitter geométrico
  • GaussianNoise, MotionBlur, JPEGCompression, GaussianPatchBrightness, RandomShadow, CoarseDropout, GammaCorrection, PlanckianJitter: Efectos de cámara e iluminación vistos en robots reales
  • Identity: Sin transformación (útil para pruebas)

Cualquier otra clase de torchvision.transforms.v2 también puede especificarse como type (por ejemplo, RandomResizedCrop o GaussianBlur); se aplica una muestra a la vez. También puede pasar una transformación de torchvision directamente al parámetro image_transforms.

Ahora todas las transformaciones se procesan por lotes, y las mismas transformaciones por lotes se ejecutan en ambos backends. Las clases por muestra (SharpnessJitter, GaussianNoise, MotionBlur, GaussianPatchBrightness, RandomShadow, CoarseDropout, GammaCorrection, PlanckianJitter, RandomSubsetApply) y make_transform_from_config siguen siendo importables como interfaces obsoletas sobre sus reemplazos Batched* y emiten una advertencia al usarse; se eliminarán en una versión futura. ImageTransforms es un torch.nn.Module simple que toma un tensor de (C, H, W) o (T, C, H, W). Las configuraciones que nombran una transformación por type no se ven afectadas.

Cambio de comportamiento para las recetas existentes. El entrenamiento lee los fotogramas como uint8, y las transformaciones de LeRobot distintas de ColorJitter, RandomAffine y RandomRotation solían devolver la entrada no flotante sin cambios. Por lo tanto, las recetas que habilitaban GaussianNoise, MotionBlur, GaussianPatchBrightness, RandomShadow, CoarseDropout, GammaCorrection o PlanckianJitter se estaban entrenando sin ellas. Ahora se aplican en ambos backends, por lo que una receta de este tipo se entrena de manera diferente a como lo hacía antes: obtiene la aumentación que solicitó. Las transformaciones que ya se estaban aplicando no cambian, salvo por el redondeo, ya que la ruta por lotes calcula en flotante y redondea una sola vez al final, en lugar de después de cada transformación.

Opciones de configuración

  • enable: Habilitar/deshabilitar transformaciones (predeterminado: False)
  • max_num_transforms: Número máximo de transformaciones aplicadas por fotograma (predeterminado: 3)
  • random_order: Aplicar transformaciones en orden aleatorio en lugar del orden estándar (predeterminado: False)
  • weight: Probabilidad de muestreo para cada transformación (mayor = más probable; si la suma de los pesos no es 1, se normalizarán)
  • kwargs: Parámetros específicos de la transformación (p. ej., rango de brillo)
  • backend: dónde se ejecutan las transformaciones durante el entrenamiento, "dataloader" (predeterminado) o "gpu"; consulte más abajo
  • gpu_compile: En el backend "gpu", torch.compile las transformaciones por lotes (predeterminado: True)
  • gpu_chunk_size: En el backend "gpu", aumenta este número de muestras a la vez para limitar la memoria transitoria (valor predeterminado: 32)

Ejecutar transformaciones en la GPU

Por defecto, las transformaciones se ejecutan por muestra en los workers del DataLoader. Con varias cámaras, esto suele ser lo más costoso que hacen los workers, y la GPU termina esperando datos. Establezca backend=gpu para que los workers solo decodifiquen y apliquen las mismas transformaciones a cada lote en el dispositivo de la política:

lerobot-train \
  --dataset.repo_id=your-username/your-dataset \
  --dataset.image_transforms.enable=true \
  --dataset.image_transforms.backend=gpu \
  --policy.type=act \
  --policy.device=cuda

La aleatorización no cambia: cada muestra extrae sus propias transformaciones y parámetros, y los fotogramas del historial de una cámara los comparten. El aumento de datos se aplica solo a los lotes de entrenamiento, antes del preprocesador de la política; los lotes de evaluación, los despliegues y los puntos de control guardados no se modifican.

Cosas que debes saber:

  • Requiere un acelerador; --policy.device=cpu se rechaza. También se rechaza un conjunto de datos construido a mano con su propio callable image_transforms, ya que estos se ejecutan en los workers.
  • Admite todos los tipos de transformaciones que admite el backend del dataloader. Los tipos sin una implementación por lotes (JPEGCompression, y las clases de torchvision distintas de ColorJitter, RandomAffine, RandomRotation y Identity) se aplican una muestra a la vez dentro del lote, por lo que no obtienen la aceleración; JPEGCompression también realiza un recorrido de ida y vuelta a través de la CPU. Se rechaza una transformación que cambia el tamaño del cuadro en un lote de más de una muestra.
  • Reproducible desde --seed, con cada proceso sembrado de manera diferente. La aumentación no consume el flujo aleatorio de la política, y gpu_compile y gpu_chunk_size no cambian lo que se aplica.
  • Ambos backends ejecutan las mismas transformaciones por lotes en float y redondean una sola vez al final, por lo que una muestra aumentada en uno es igual a la misma muestra aumentada en el otro, siempre que se utilicen los mismos parámetros.
  • gpu_compile tiene un coste de 15 a 30 s una vez por forma de imagen. La memoria pico es de aproximadamente dos copias en coma flotante de las imágenes del lote más algunas copias de un fragmento; reduzca gpu_chunk_size si la memoria es limitada. random_order=true multiplica el tiempo de transformación por max_num_transforms.

Migrar de v2.1 a v3.0

Un conversor agrega los archivos por episodio en fragmentos más grandes y escribe los desplazamientos/metadatos de los episodios. Convierta su conjunto de datos siguiendo las instrucciones a continuación.

# Convert an existing v2.1 dataset hosted on the Hub:
python -m lerobot.scripts.convert_dataset_v21_to_v30 --repo-id=<HF_USER/DATASET_ID>

Qué hace

  • Agrega archivos parquet: episode_000000.parquet, episode_000001.parquet, … → file-000.parquet, …
  • Agrega archivos mp4: episode_000000.mp4, episode_000001.mp4, … → file-000.mp4, …
  • Actualiza meta/episodes/* (Parquet por bloques) con las longitudes por episodio, las tareas y los desplazamientos de bytes/frames.

Problemas comunes

Siempre llama a finalize() antes de hacer push

Al crear o grabar conjuntos de datos, debes llamar a dataset.finalize() para cerrar correctamente los escritores de parquet. Consulta la PR #1903 para más detalles.

from lerobot.datasets import LeRobotDataset

# Create dataset and record episodes
dataset = LeRobotDataset.create(...)

for episode in range(num_episodes):
    # Record frames
    for frame in episode_data:
        dataset.add_frame(frame)
    dataset.save_episode()

# Call finalize() when done recording and before push_to_hub()
dataset.finalize()  # Closes parquet writers, writes metadata footers
dataset.push_to_hub()

¿Por qué es necesario?

Dataset v3.0 utiliza escritura incremental de parquet con metadatos en búfer para mejorar la eficiencia. El método finalize():

  • Descarga los metadatos de episodio en búfer al disco
  • Cierra los escritores de parquet para escribir los metadatos del pie de página; de lo contrario, los archivos parquet estarán corruptos
  • Garantiza que el conjunto de datos sea válido para su carga

Si no llamas a finalize(), tus archivos parquet estarán incompletos y el conjunto de datos no se cargará correctamente.

Otros formatos e implementaciones

Backend de conjuntos de datos de LanceDB

Un conjunto de datos v3 también puede almacenarse como tablas de LanceDB. LanceDB es un data lakehouse multimodal construido sobre el formato Lance para patrones de acceso de IA: acceso aleatorio rápido a cualquier fila y sus bytes de video, e índices escalares, vectoriales y de texto completo en las mismas tablas, de modo que el EDA, la minería, la curaduría y el entrenamiento se ejecutan directamente desde el almacenamiento de objetos. El diseño mantiene meta/ sin cambios y añade una tabla frames para los datos tabulares y una tabla videos que contiene los MP4 como blobs. "storage_format": "lance" en meta/info.json selecciona el lector; la API de LeRobotDataset, los elementos y el pipeline de entrenamiento permanecen sin cambios.

  • Entrena directamente desde el Hub o desde los buckets de almacenamiento de HF con las GPUs alimentadas. Los fotogramas aleatorios se leen in situ, solo los bytes que necesita cada lote, de modo que cada lote es un barajado global y no se descarga nada previamente.
  • Convierte al costo aproximado de una copia de archivo. Los videos no se recodifican, por lo que los elementos son idénticos a nivel de bits a la fuente. DROID convierte en 34 minutos.
  • Ingeniería de características sin copia. Añade columnas como puntuaciones, incrustaciones o etiquetas corregidas a las tablas que lee el entrenador, sin reescribir los vídeos ni copiar el conjunto de datos, y luego filtra y busca en ellas mediante los índices. El lector ignora las columnas que no conoce.

Para ver cómo funciona, los benchmarks y ejemplos, consulte la guía de LanceDB LeRobot.

Las características de cámara deben estar respaldadas por video. Los conjuntos de datos que almacenan los fotogramas de la cámara como imágenes no son compatibles con el lector y deben recodificarse como video antes de la conversión.

Leer conjuntos de datos Lance requiere el extra lancedb (pip install "lerobot[lancedb]"). El formato es de solo lectura: registre y edite conjuntos de datos en el formato predeterminado y luego conviértalos con el paquete lerobot-lancedb:

pip install "lerobot-lancedb"
lerobot-lance-convert --repo-id lerobot/pusht --out ./pusht-lance  # or --root <local dataset dir>

La carga utiliza la misma clase:

from lerobot.datasets import LeRobotDataset

# Hub dataset repo
dataset = LeRobotDataset("lance-format/pusht-lance")

# HF Storage Bucket, read in place
dataset = LeRobotDataset("my-org/pusht-lance", repo_type="bucket")

# the same bucket as a root URI (other object store URIs work the same way)
dataset = LeRobotDataset("lerobot/pusht", root="hf://buckets/my-org/pusht-lance")

Las opciones de HF Storage Bucket funcionan en lerobot-train:

lerobot-train \
  --dataset.repo_id=my-org/pusht-lance \
  --dataset.repo_type=bucket \
  --policy.type=act

La visualización funciona con ambos visores. lerobot-dataset-viz --repo-id lance-format/pusht-lance --episode-index 0 abre un episodio en Rerun como de costumbre, y --display-mode foxglove lo sirve a Foxglove a través de WebSocket. En cualquier caso, solo se obtienen los fotogramas en pantalla, sin exportación ni descarga de MCAP.

Update on GitHub