MÓDULO 2.2

🤗 LeRobot: pipeline de extremo a extremo

El framework open-source de HuggingFace que democratiza la robótica: recolección, entrenamiento y deploy en una sola herramienta. Con 12k stars en GitHub y más de 58k datasets, LeRobot es el punto de entrada más accesible para trabajar con VLA en la práctica.

Temas

~50

Minutos

Técnico

Nivel

Práctico

Tipo

Diagrama ilustrativo — flujo end-to-end de LeRobot: recolección → dataset → entrenamiento → evaluación → deploy.

🤗 LeRobot: 12k estrellas, 58k+ datasets

LeRobot es el framework open-source de HuggingFace para robótica end-to-end. Lanzada en 2024, unifica la recopilación de datos, el entrenamiento de políticas y el deploy en robots reales en una sola herramienta con documentación extensa y una comunidad activa.

🏗️ Qué resuelve LeRobot

Antes de LeRobot, cada laboratorio tenía su pipeline ad hoc: scripts de recopilación propietarios, formatos de dataset incompatibles y pipelines de entrenamiento aislados. LeRobot estandariza todo con una API coherente — desde el hardware hasta el modelo entrenado — y publica todo en HuggingFace Hub para su reutilización.

✓ Lo que incluye LeRobot

✓Scripts de recopilación con teleoperación (lerobot/record)
✓Políticas preimplementadas: ACT, Diffusion Policy, TDMPC, VQ-BeT
✓Integración nativa con HuggingFace Hub (58k+ datasets)
✓Compatibilidad con varios robots: SO-100, Koch v1.1, Aloha
✓Visualizador de episodios y métricas de evaluación

✗ Lo que LeRobot no hace

✗No es un simulador: se necesita MuJoCo/Isaac Sim para sim-to-real
✗No reemplaza a ROS2 para el control de bajo nivel en producción
✗No entrena modelos de visión desde cero (usa backbones preentrenados)
✗No garantiza seguridad en entornos no controlados

⚡ Instalación rápida

pip install lerobot

# Verificar instalação
python -c "import lerobot; print(lerobot.__version__)"

# Listar políticas disponíveis
python -c "from lerobot.common.policies import *; print('ACT, Diffusion, TDMPC, VQ-BeT')"

Conceptos clave

LeRobotDataset

Clase principal que encapsula un dataset en formato RLDS con video, acciones y metadatos sincronizados.

lerobot/scripts/train.py

Script unificado de entrenamiento que carga una configuración YAML y guarda checkpoints automáticamente.

Integración con el hub

Push y pull de datasets y modelos directamente desde HuggingFace Hub con huggingface-cli login.

Compatibilidad con múltiples robots

Configuraciones listas para SO-100, Koch v1.1 y Aloha; agrega un robot nuevo mediante YAML de calibración.

🎮 Recolección de datos mediante teleoperación

La teleoperación es la técnica mediante la cual una persona controla el robot a distancia para generar demostraciones de calidad. LeRobot graba de forma sincronizada el video de las cámaras y las posiciones de los actuadores, y genera episodios con timestamps alineados que alimentan el entrenamiento supervisado.

💡 Regla de los 50-100 episodios

Para tareas simples (pick-and-place, apilar bloques), 50-100 episodios de alta calidad superan a 500 episodios malos. La consistencia y la cobertura de variaciones (ángulos, posiciones del objeto) importan más que el volumen bruto.

🖥️ Grabando episodios con LeRobot

# Calibração do robô (uma vez)
python lerobot/scripts/control_robot.py calibrate \
  --robot-path lerobot/configs/robot/so100.yaml

# Gravar dataset de demonstrações
python lerobot/scripts/control_robot.py record \
  --robot-path lerobot/configs/robot/so100.yaml \
  --fps 30 \
  --repo-id seu-usuario/pick-place-dataset \
  --num-episodes 50 \
  --warmup-time-s 5

# Replay para validar qualidade
python lerobot/scripts/control_robot.py replay \
  --robot-path lerobot/configs/robot/so100.yaml \
  --repo-id seu-usuario/pick-place-dataset \
  --episode 0

✓ Setup leader-follower ideal

✓2 cámaras: una global y otra en la muñeca del robot
✓Captura sincronizada a 30 Hz de cámaras + actuadores
✓Calibración intrínseca/extrínseca antes de cada sesión
✓Verificar la reproducción de cada episodio antes de continuar

✗ Errores comunes en la recopilación

✗Movimientos bruscos o vacilaciones en la demostración
✗Cámaras con enfoque deficiente o iluminación inconsistente
✗Objetos siempre en la misma posición (poca variación)
✗No filtrar los episodios fallidos antes del entrenamiento

Conceptos clave

Líder-seguidor

El robot "leader" (controlado por una persona) controla al "follower" (que ejecuta). Ambos tienen sensores para capturar el estado real.

Grabación de episodios

Cada demostración es un episodio: una secuencia de observaciones (imágenes + posiciones) y acciones con marcas de tiempo alineadas.

Filtrado de calidad de datos

Eliminar episodios en los que el robot falló, tuvo movimientos anómalos o la cámara quedó obstruida.

🧠 Políticas: ACT, Diffusion Policy, TDMPC

LeRobot implementa múltiples arquitecturas de políticas, cada una con distintos compromisos entre velocidad de inferencia, calidad del movimiento y complejidad de entrenamiento. Elegir la política adecuada para tu tarea es tan importante como la calidad de los datos.

Evolución de las arquitecturas de políticas

ACT — Action Chunking with Transformers (2023)

Predice k acciones a la vez (action chunk) en lugar de una por vez. Reduce los errores de acumulación. Inferencia rápida (~10ms), ideal para control en tiempo real a 50Hz.

chunk_size=100 Transformer encoder-decoder

Diffusion Policy (2023)

Modela distribuciones de acción con DDPM. Captura la multimodalidad (varias formas de resolver la tarea). La inferencia es más lenta (10-100 denoising steps), pero produce movimientos más suaves.

num_inference_steps=10 UNet condicional

TDMPC — TD-MPC2 (2024)

Modelo del mundo + planificación: aprende un modelo de la dinámica del entorno y usa MPC (Model Predictive Control) para planificar acciones. Mejora la generalización, pero requiere más datos y capacidad de cómputo.

horizon=5 Modelo latente del mundo

💡 ¿Qué política elegir?

Empieza con ACT para tareas de manipulación simples: es la opción más rápida para iterar. Usa Diffusion Policy cuando necesites movimientos multimodales (p. ej., una tarea que puede resolverse de múltiples formas). Reserva TDMPC para tareas de horizonte largo con sim-to-real.

Conceptos clave

Action chunking

Predecir varias acciones futuras a la vez para reducir los errores de acumulación en la ejecución secuencial.

DDPM (Denoising Diffusion)

Proceso de denoising progresivo que genera muestras de alta calidad de distribuciones de acción complejas.

VQ-BeT

Tokenización vectorial discreta de acciones: trata las acciones como tokens, lo que permite usar arquitecturas de LLM.

Multimodalidad

Capacidad de aprender múltiples formas de resolver una tarea, en lugar de un "promedio" de todas las demostraciones.

⚙️ Entrenamiento en GPU: configuración YAML y checkpoints

LeRobot usa archivos YAML con Hydra para la configuración jerárquica de entrenamientos. Cada run guarda checkpoints automáticamente y se puede reanudar, lo que permite iterar rápidamente sin repetir trabajo.

🚀 Iniciando un entrenamiento

# Treinar ACT no seu dataset
python lerobot/scripts/train.py \
  policy=act \
  env=aloha \
  dataset_repo_id=seu-usuario/pick-place-dataset \
  training.num_steps=80000 \
  training.batch_size=8 \
  wandb.enable=true \
  hydra.run.dir=outputs/train/act_pick_place

# Retomar do checkpoint
python lerobot/scripts/train.py \
  resume=true \
  resume_path=outputs/train/act_pick_place/checkpoints/last

# Multi-GPU com DDP (2 GPUs)
torchrun --nproc_per_node=2 lerobot/scripts/train.py \
  policy=diffusion \
  dataset_repo_id=seu-usuario/pick-place-dataset

Diagrama ilustrativo — flujo de entrenamiento: YAML → GPU → checkpoint → métricas de W&B.

Conceptos clave

Acumulación de gradientes

Acumular gradientes durante N batches antes de la actualización — permite un tamaño de batch efectivo mayor que el que permite la VRAM.

Mixed precision (BF16)

Usar BFloat16 para forward/backward y FP32 para actualizar los pesos: 2x más rápido con una memoria similar.

DDP (DistributedDataParallel)

Estrategia de PyTorch para varias GPU: cada GPU procesa un mini-batch y los gradientes se sincronizan mediante AllReduce.

resume_from_checkpoint

Reanudar el entrenamiento desde un checkpoint guardado, conservando el estado del optimizador y del scheduler de learning rate.

📊 Weights & Biases: seguimiento de experimentos

W&B es la plataforma estándar para rastrear experimentos de ML. LeRobot tiene integración nativa — Basta con agregar wandb.enable=true en el YAML de config para tener métricas, curvas de loss y videos de evaluación centralizados.

💡 Sin tracking = caja negra

Entrenar VLAs sin tracking estructurado es avanzar a ciegas. Necesitas saber: ¿qué run tuvo el mejor success rate? ¿Qué learning rate divergió? ¿En qué step dejó de mejorar el modelo? W&B responde todo esto con gráficos comparativos side-by-side.

📈 Configuración de W&B en LeRobot

# Autenticar no W&B
wandb login

# No YAML de config (config/default.yaml)
wandb:
  enable: true
  project: "lerobot-experiments"
  entity: "seu-usuario"
  name: "act-pick-place-v1"

# Ou via override na linha de comando
python lerobot/scripts/train.py \
  policy=act \
  wandb.enable=true \
  wandb.project=lerobot-experiments \
  wandb.name=act_run_001

# Sweeps para hyperparameter search
wandb sweep sweep_config.yaml
wandb agent usuario/projeto/sweep_id

✓ Métricas esenciales que debes monitorear

✓train/loss — debe disminuir monótonamente (con ruido)
✓eval/success_rate — porcentaje de episodios exitosos
✓eval/video — videos grabados del robot en evaluación
✓Learning rate schedule — confirmar que disminuye según lo esperado

✗ Señales de alerta en el dashboard

✗La pérdida aumenta abruptamente — posible tasa de aprendizaje alta
✗Tasa de éxito estancada después de 20k steps — dataset insuficiente
✗La norma del gradient explota: agregar gradient clipping
✗Utilización de GPU por debajo del 70%: cuello de botella en la carga de datos

Conceptos clave

wandb.Sweep

Búsqueda automática de hyperparameters: define el espacio de búsqueda (lr, batch_size) y W&B programa y rastrea todas las runs.

Model Registry

Controlar las versiones de los checkpoints de modelos con etiquetas semánticas (best, staging, production) para garantizar la trazabilidad.

Tables para trayectorias

Registrar secuencias de acciones y observaciones como tablas de W&B para el análisis cualitativo de comportamientos.

wandb.config

Registrar automáticamente todos los hiperparámetros de la ejecución para garantizar la reproducibilidad y comparar experimentos.

🐳 Docker y reproducibilidad en robótica

La reproducibilidad es uno de los mayores problemas de la investigación en robótica. Las versiones de los drivers de CUDA, las dependencias de Python y las configuraciones de hardware crean entornos frágiles. Docker crea contenedores para todo — un Dockerfile garantiza que cualquier persona (o servidor de CI) pueda reproducir tu entrenamiento exactamente.

💡 NVIDIA NGC: contenedores listos para usar

NVIDIA mantiene el NGC (NVIDIA GPU Cloud) con contenedores PyTorch+CUDA optimizados para diversas GPU. LeRobot proporciona Dockerfiles que extienden estos contenedores: no necesitas configurar CUDA manualmente.

🐳 Dockerfile multietapa para LeRobot

# Etapa 1: base com CUDA
FROM nvcr.io/nvidia/pytorch:24.01-py3 AS base
WORKDIR /workspace

# Etapa 2: dependências
FROM base AS deps
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
RUN pip install lerobot

# Etapa 3: código
FROM deps AS runtime
COPY . .
ENV HF_HOME=/workspace/.cache/huggingface

# Rodar treinamento com GPU passthrough
# docker run --gpus all -v /data/datasets:/workspace/datasets \
#   -v /data/checkpoints:/workspace/outputs \
#   lerobot-train:latest \
#   python lerobot/scripts/train.py policy=act ...

✓ Buenas prácticas de Docker para robótica

✓Dockerfile multi-stage para separar la compilación del runtime
✓Crear datasets como volúmenes (-v) — no copiar a la imagen
✓Fijar la versión del contenedor base (:24.01 no :latest)
✓Usar devcontainers en VS Code para desarrollo

✗ Errores comunes

✗Copiar datasets dentro de la imagen Docker (gigabytes desperdiciados)
✗Olvidar --gpus all en el docker run (entrena en CPU)
✗Usar :latest — la imagen cambia y rompe la reproducibilidad
✗No versionar el Dockerfile junto con el código del experimento

Conceptos clave

nvidia-docker2

Plugin que permite que los contenedores Docker accedan a GPU NVIDIA mediante --gpus all sin configuración manual de CUDA.

NVIDIA NGC

Registry de contenedores optimizados para GPU: PyTorch, TensorFlow, TensorRT — una base confiable para experimentos reproducibles.

devcontainers

Integración con VS Code que abre el editor dentro del contenedor Docker — el mismo entorno de desarrollo y producción.

✅ Resumen del módulo

✓

LeRobot = recopilación + entrenamiento + deploy — framework unificado de HuggingFace con 12k stars y más de 58k datasets públicos en el Hub.

✓

La teleoperación genera datos de calidad — 50-100 episodios consistentes superan a 500 deficientes; la calibración y la configuración de las cámaras son fundamentales.

✓

Políticas con distintas compensaciones — ACT para velocidad, Diffusion Policy para suavidad multimodal, TDMPC para horizontes largos.

✓

W&B + Docker = reproducibilidad — el seguimiento de experimentos y la contenerización garantizan que cualquier persona pueda replicar los resultados.

Siguiente módulo

2.3 — Simuladores: MuJoCo, Isaac Sim, PyBullet

← Volver a la Ruta Siguiente módulo →