Contactar Ventas
Volver a Blog

Comienza con abrazarFace LeRobot para el aprendizaje de robots reales

Guía práctica para la instalación de LeRobot <unk>, la recopilación de datos, la formación de ACT o la política de difusión, la evaluación y el intercambio de conjuntos de datos.

Parte de: [Guía de recogida de datos de robots]

[← Blog] T19)

LeRobot hace que la línea completa de la recopilación de datos a la política entrenada sea más accesible que cualquier marco anterior. Aquí está cómo usarlo de extremo a extremo.

¿Qué es LeRobot?

LeRobot es la biblioteca de aprendizaje de robots de HuggingFace: un formato de conjunto de datos estandarizado, una creciente colección de modelos pre-entrenados y guiones de entrenamiento para ACT, políticas de difusión y políticas TD-MPC2 todos licenciados por el MIT con un enfoque en el despliegue de robots reales en lugar de una investigación de simulación. El diferenciador clave de los marcos anteriores es la estandarización: un conjunto de datos recopilado con LeRobot en cualquier robot soportado puede ser entrenado por cualquier script de entrenamiento de LeRobot, sin cargadores de datos personalizados o conversión de formato.

A principios de 2025, LeRobot tiene una comunidad Discord activa con más de 8.000 miembros, actualizaciones semanales de investigación del equipo central y contribuciones crecientes de grupos de investigación en zoológicos. Se ha convertido en el estándar de facto para el intercambio de datos de aprendizaje de robots de código abierto.

Instalación y soporte de hardware

  • Instalación: pip instalar lerobot. Requiere Python 3.10+, PyTorch 2.1+. Dependencias de hardware opcionales instaladas por separado (por ejemplo, pip instalar lerobot[so100] para soporte de brazo SO-100).
  • ** SO-100 brazo ($300):** La plataforma de soporte de bajo costo primaria. 5-DOF líder + brazo de teleoperación siguiente de Koch Robotics.
  • ** ALOHA bimanual:** Stanford ALOHA y ALOHA 2 configuraciones incluidas. 14 DOF total (7 por brazo), destinado a la investigación de manipulación bimanual.
  • OpenArm: Soportado a través de un adaptador comunitario. Configuración RCSV OpenArm 7-DOF disponible a través del paquete de integración LeRobot de RCSV.

Flujo de trabajo de recopilación de datos

La recopilación de datos produce un conjunto de datos HDF5 + MP4 estandarizado automáticamente:

  • ** Paso 1 Configurar robot:** Editar la configuración YAML para su robot (por ejemplo, lerobot/configs/robot/so100.yaml) con sus puertos de serie e índices de cámara.
  • ** Paso 2 Registro conjunto de datos:** python lerobot/scripts/record_dataset.py --robot-path lerobot/configs/robot/so100.yaml --num-episodes 50 --dataset-id my_task_v1. El guión maneja la sincronización de cuadros a través de cámaras, la escritura de episodios HDF5 y la generación de miniaturas de episodios en tiempo real.
  • ** Paso 3 Revisión de episodios: ** ** Python lerobot/scripts/visualize_dataset.py --dataset-id my_task_v1** abre un espectador de episodios interactivo.
  • ** Paso 4 Empujar al hub (opcional):** python lerobot/scripts/push_dataset_to_hub.py --dataset-id my_task_v1 se carga a HuggingFace Hub para compartir o a la plataforma de datos de RCSV para almacenamiento administrado.

Formación en materia de políticas

Policy Command Training Time (200 demos, 1× GPU) Best For
ACT (Action Chunking with Transformers) --policy act ~4 hours Fast-moving tasks, reliable baseline
Diffusion Policy --policy diffusion ~12 hours Precisión tasks, multimodal behavior
TD-MPC2 --policy tdmpc ~8 hours Tasks with clear reward structure

Comando de entrenamiento ACT: python lerobot/scripts/train.py --acto de política --dataset-id my_task_v1 --training.num_epochs 100. Monitorear la tasa de evaluación/éxito en el registro de TensorBoard. Objetivo >70% antes de desplegar. La política de difusión requiere más computación, pero generalmente logra un mejor rendimiento en tareas de precisión con comportamiento multimodal (por ejemplo, tareas donde hay múltiples enfoques válidos para agarrar un objeto).

El modelo de zoológico y las pruebas de tiro cero

LeRobot mantiene un zoológico modelo pre-entrenado en HuggingFace Hub. Disponible a partir de principios de 2025: políticas de ACT y difusión entrenadas en SO-100 para tareas de pick-place, apilamiento e inserción; políticas ALOHA para limpieza y ensamblaje bimanual. Estos pueden usarse para pruebas de tiro cero en su hardware una útil verificación de la cordura de que su robot está calibrado correctamente antes de recopilar sus propios datos.

Para ejecutar una política pre-entrenada: python lerobot/scripts/eval.py --pre-entrenado-política-nombre-o-camino lerobot/act_so100_pick_place --robot-camino lerobot/configs/robot/so100.yaml.

Formatos de conjunto de datos de LeRobot

Comprender el formato del conjunto de datos es esencial para las integraciones personalizadas. Los conjuntos de datos de LeRobot utilizan una combinación de archivos Parquet (para datos estructurados) y videos MP4 (para observaciones de cámaras):

my_dataset_v1/
  meta/
    info.json          # Dataset metadata (robot type, fps, features)
    episodes.jsonl     # Per-episode metadata (length, task description)
    tasks.jsonl        # Task definitions
  data/
    chunk-000/
      episode_000000.parquet   # State + action data per episode
      episode_000001.parquet
      ...
  videos/
    chunk-000/
      observation.images.top/
        episode_000000.mp4     # Camera feed per episode
      observation.images.wrist/
        episode_000000.mp4

Cada archivo de Parquet contiene columnas para: T5 (ángulos conjuntos + agarre), T6 (posiciones conjuntas de objetivo), T7, T8 y T9. Las observaciones de la cámara se almacenan como videos MP4 (encodados en H.264) con índices de cuadros alineados con los datos de Parquet.

Para cargar un conjunto de datos de forma programática:

from lerobot.common.datasets.lerobot_dataset import LeRobotDataset

# Load from local path or HuggingFace Hub
dataset = LeRobotDataset("lerobot/aloha_sim_insertion_human_image")

# Access episode data
episode = dataset[0]  # First frame of first episode
print(episode.keys())
# dict_keys(['observation.images.top', 'observation.state',
#            'action', 'episode_index', 'frame_index', 'timestamp'])

# Get all frames for episode 5
ep5_frames = [dataset[i] for i in dataset.episode_data_index["from"][5]:
                                    dataset.episode_data_index["to"][5]]

Entrenamiento ACT con LeRobot: paso a paso

Un comando completo de entrenamiento con los hiperparámetros clave explicó:

# Train ACT on your custom dataset
python lerobot/scripts/train.py \
  --policy.type=act \
  --dataset.repo_id=my_org/my_task_v1 \
  --dataset.episodes=[0,1,2,3,4,5,6,7,8,9] \   # Specific episodes
  --training.num_epochs=2000 \
  --training.batch_size=8 \
  --policy.chunk_size=100 \         # Action chunk length
  --policy.kl_weight=10 \           # CVAE KL divergence weight
  --policy.n_action_steps=100 \     # Steps to execute per chunk
  --training.lr=1e-5 \              # Learning rate
  --training.save_freq=500 \        # Checkpoint every 500 epochs
  --output_dir=outputs/act_my_task

Los hiperparámetros clave para ajustar:

  • chunk_size: 50-100 para la mayoría de las tareas. Los trozos más grandes reducen el error de composición pero hacen que el problema de predicción sea más difícil.
  • kl_weight: Controla la regularización de la CVAE. Demasiado bajo (1): el espacio latente se desploma, el comportamiento multimodal se pierde. Demasiado alto (100): la política ignora las observaciones.
  • Carta de aprendizaje: 1e-5 para ajuste fino, 1e-4 para formación desde cero.

Formación de la política de difusión con LeRobot

# Train Diffusion Policy
python lerobot/scripts/train.py \
  --policy.type=diffusion \
  --dataset.repo_id=my_org/my_task_v1 \
  --training.num_epochs=4000 \
  --training.batch_size=64 \
  --policy.n_action_steps=8 \       # Prediction horizon
  --policy.n_obs_steps=2 \          # Observation history length
  --policy.num_inference_steps=10 \ # DDIM steps (10 for speed)
  --training.lr=1e-4 \
  --output_dir=outputs/dp_my_task

La política de difusión se desarrolla 2-3 veces más lentamente que ACT pero a menudo logra un mejor rendimiento en tareas de precisión.

Empujar los conjuntos de datos a HuggingFace Hub

# Push your dataset to HuggingFace Hub for sharing
huggingface-cli login  # One-time authentication
python lerobot/scripts/push_dataset_to_hub.py \
  --local-dir outputs/my_task_v1 \
  --repo-id my_org/my_task_v1 \
  --tags "openarm,pick-place,tabletop"

Los conjuntos de datos en HuggingFace Hub son inmediatamente utilizables por cualquier persona con LeRobot instalado. Agregar etiquetas descriptivas hace que su conjunto de datos sea descubrible. Los conjuntos de datos de RCSV están disponibles en el Hub bajo la organización T11.

Errores y soluciones comunes

Error Cause Fix
RuntimeError: CUDA out of memory Batch size too large for GPU VRAM Reduce batch_size to 4 or 2; use gradient accumulation
ValueError: mismatched state dim Robot config does not match dataset DOF Check robot YAML: state_dim must match observation.state columns
Camera not found at index N USB camera enumeration changed Run v4l2-ctl --list-devices and update camera_index in YAML
Serial port permission denied User not in dialout group sudo usermod -aG dialout $USER then log out/in
Policy outputs all zeros KL collapse in ACT training Increase kl_weight to 50; use KL warmup schedule
Video frames out of sync with state USB bandwidth saturation Use USB3 cameras on separate USB controllers; reduce resolution to 480p

Indicadores de rendimiento

El rendimiento esperado para las tareas estándar utilizando las implementaciones de referencia de LeRobot:

Task Platform Demos ACT Success DP Success
Pick-place (single object) SO-100 50 75-85% 70-80%
Stacking (2 blocks) SO-100 100 60-75% 65-80%
Bimanual handover ALOHA 200 80-90% 75-85%
Insertion (peg-in-hole) OpenArm 200 50-65% 60-75%

Comunidad y recursos

  • Disconsolación: 8.000+ miembros, canales activos de ayuda y #showcase.
  • HuggingFace Hub: hf.co/lerobot -- creciente colección de conjuntos de datos y modelos. Filtra por tipo de robot o tarea.
  • ** Actualizaciones semanales:** El equipo principal de HuggingFace publica actualizaciones de investigación en el blog de HuggingFace cada 1-2 semanas.
  • ** Integración de RCSV:** La [plataforma de datos] de RCSV (T20) acepta conjuntos de datos en formato LeRobot para el almacenamiento administrado, la anotación y la exportación de tuberías de entrenamiento. Nuestro [servicio de recopilación de datos] (T21) entrega conjuntos de datos en formato LeRobot por defecto.

Lectura relacionada

Guía de aprendizaje de imitación · PULÍTICA ACT vs. Difusión · Abrir el cuerpo X · Comparación del brazo robótico · Annotación de datos · Servicios de datos · Plataforma RCSV

Recopilación de datos compatible con LeRobot

RCSV ofrece resultados de recopilación de datos en formato LeRobot, listos para utilizar con scripts de capacitación de políticas de ACT o difusión.

[Explorar los Servicios de Datos]