LeRobot: framework end-to-end de Hugging Face

Contenido detallado

🔹 Qué es LeRobot: la filosofía open end-to-end

LeRobot es el esfuerzo de Hugging Face por hacer con la robótica lo que el transformers hizo con NLP: democratizar. En un solo repo PyTorch tienes datasets estandarizados, políticas SOTA reproducibles, entornos de simulación y drivers para hardware económico. El objetivo es eliminar la fragmentación que frenaba el área.

📊 Los cuatro pilares

Datasets — formato único (LeRobotDataset) versionado en el Hub.
Policies — ACT, Diffusion Policy, π0, VQ-BeT con checkpoints públicos.
Sim + envs — gym wrappers (ALOHA, PushT, Xarm) para evaluar.
Hardware — SO-100/SO-101, Koch, ALOHA con scripts de teleop y grabación.

⚡ Consejo práctico

Todo gira en torno al CLI/entrypoints (lerobot-record, lerobot-train, lerobot-eval). Aprende los tres comandos y ya puedes ejecutar el ciclo completo en un brazo de escritorio.

Open

Código + pesos públicos.

End-to-end

Datos → política → robot.

Hub

Versionar datos y ckpt.

Accesible

Hardware de bajo costo.

🔹 LeRobotDataset: formato parquet + video

O LeRobotDataset separa lo ligero de lo pesado: el estado, las acciones y las marcas de tiempo van en parquet (columnar, rápido), mientras las imágenes viven en mp4 codificado y se decodifican según la demanda. Cada episodio es una trayectoria; funciones describen el shape y el dtype de cada clave.

from lerobot.common.datasets.lerobot_dataset import LeRobotDataset

ds = LeRobotDataset("lerobot/svla_so101_pickplace")
print(ds.features.keys())
# observation.images.top, observation.state, action, timestamp, ...

sample = ds[0]
sample["observation.images.top"].shape   # (3, H, W) tensor já decodificado
sample["action"].shape                    # (action_dim,)

# delta_timestamps -> janelas temporais (chunking) automáticas
ds = LeRobotDataset(repo_id, delta_timestamps={"action": [t/30 for t in range(16)]})

📊 Anatomía de un episodio

observation.images.* — una clave por cámara (top, wrist), en mp4.
observation.state — posiciones de junta / pose del gripper.
action — comando objetivo del siguiente paso.
episode_index / frame_index — límites de trayectoria.

parquet

Estado/acción en columnas.

mp4

Imágenes con decodificación lazy.

funciones

Estructura del schema + dtype.

delta_timestamps

Ventanas temporales.

🔹 Políticas listas: ACT, Diffusion, π0, VQ-BeT

LeRobot empaqueta políticas de distintas clases con la misma interfaz. ACT (Action Chunking Transformer, de ALOHA) es el caballo de batalla para la manipulación con pocas demos; Diffusion Policy captura de multimodalidad; π0 aporta flow matching generalista; VQ-BeT usa tokens vectoriales cuantizados.

# treinar ACT no dataset do SO-101
lerobot-train \
  --policy.type=act \
  --dataset.repo_id=lerobot/svla_so101_pickplace \
  --batch_size=8 --steps=100000 \
  --output_dir=outputs/act_so101 \
  --policy.device=cuda --wandb.enable=true

# trocar para diffusion: --policy.type=diffusion
# fine-tune do π0: --policy.type=pi0 --policy.pretrained_path=lerobot/pi0

✓ Hacer

✓Empieza con ACT: pocos hparams, se entrena rápido y es un excelente baseline.
✓Usar π0 preentrenado cuando necesites generalización semántica.
✓Emparejar el tamaño del chunk de la policy con la frecuencia del robot.

✗ Evitar

✗Diffusion Policy con 10 demos y esperar la convergencia.
✗Cambiar de policy sin volver a comprobar la normalización de las acciones.
✗Entrenar π0 desde cero sin una GPU potente: parte del checkpoint.

ACT

Transformer + VAE con chunking.

Diffusion

Denoising de trayectoria.

π0

Flow matching generalista.

VQ-BeT

Tokens cuantizados.

🔹 Hardware compatible: SO-101, Koch, ALOHA

O SO-101 (sucesor del SO-100, proyecto The Robot Studio + Hugging Face) es el brazo de referencia: ~6 DOF, servos Feetech, costo de unos $100–150. La recopilación usa el esquema leader-follower — mueves un brazo «líder» y el «seguidor» lo replica, mientras graba estado+acción sincronizados con la cámara.

Montar y calibrar

Identificar los puertos de los motores, ejecutar lerobot-calibrate para mapear el rango de cada articulación.

Teleoperar

El leader se mueve y el follower copia. Las cámaras (top + wrist) registran la escena en tiempo real.

Grabar episodios

30–50 demos suelen bastar para ACT en una tarea sencilla de pick-and-place.

⚡ Consejo práctico

Consistencia > cantidad. Las demos limpias, con la misma iluminación y variaciones intencionales en la posición del objeto, enseñan mejor la generalización que 200 episodios desordenados.

SO-101

Brazo de ~$100, 6 DOF.

Leader-follower

Teleoperación por copia.

Calibración

Mapear el rango de las articulaciones.

ALOHA

Bimanual de referencia.

🔹 Flujo: grabar → entrenar → evaluar → deploy

El ciclo completo consta de tres comandos y un loop de inferencia. Grabas demos, entrenas una policy, evalúas en el robot (o en sim) y haces deploy ejecutando la policy en lazo cerrado a ~30 Hz.

# 1) gravar 50 demos no SO-101
lerobot-record \
  --robot.type=so101_follower --robot.port=/dev/ttyACM0 \
  --teleop.type=so101_leader --teleop.port=/dev/ttyACM1 \
  --dataset.repo_id=eu/so101_pegar_cubo --dataset.num_episodes=50

# 2) treinar
lerobot-train --policy.type=act --dataset.repo_id=eu/so101_pegar_cubo --steps=80000

# 3) avaliar/deploy: rodar a policy no follower
lerobot-record --policy.path=outputs/act/checkpoints/last \
  --robot.type=so101_follower --dataset.num_episodes=10  # eval rollouts

📊 Señales de salud del entrenamiento

loss en descenso pero la tasa de éxito se mantiene → problema de normalización/cámara.
overfit con pocas demos → aumenta la diversidad, no solo los steps.
éxito en simulación, fallo real → brecha de simulación-realidad (Ruta 3).

⚡ Consejo práctico

Evalúa siempre con el robot con la misma configuración de la grabación (iluminación, posición de las cámaras, fondo). Cambiar la escena entre el entrenamiento y el deploy es la causa n.º 1 de que una policy que "funcionaba ayer" falle hoy, y no es un bug, es distribution shift.

record

Recopilación de demos.

train

Entrena la policy.

eval rollout

Mide la tasa de éxito.

deploy

Bucle cerrado de 30 Hz.

✓ Hacer

✓Evalúa con rollouts en el robot, no solo la loss de entrenamiento.
✓Registrar video de los rollouts para diagnosticar fallas.
✓Versionar dataset + config + checkpoint juntos.

✗ Evitar

✗Aumentar los steps cuando el problema es la falta de diversidad.
✗Confiar solo en que la loss disminuya como señal de éxito.
✗Cambiar la escena entre la grabación y el deploy.

🔹 Comunidad y reproducibilidad

El valor de LeRobot crece con la comunidad: miles de datasets y checkpoints públicos en Hub, cada uno versionado y con una tarjeta descriptiva. Puedes reproducir un paper descargando el dataset exacto y la configuración, y contribuir publicando tus demos del SO-101 para que otros entrenen.

# publicar seu dataset no Hub
huggingface-cli login
lerobot-record ... --dataset.push_to_hub=true --dataset.repo_id=eu/minha_tarefa

# visualizar qualquer dataset no navegador
# https://huggingface.co/spaces/lerobot/visualize_dataset

⚡ Consejo práctico

Antes de grabar desde cero, busca en el Hub: puede haber un dataset SO-101 de tu tarea. El coentrenamiento con datos públicos + tus demos mejora la generalización: la introducción perfecta para el módulo de datasets (2.6).

Hub

Datasets + checkpoints.

Reproducible

Mismos datos + configuración.

push_to_hub

Contribuir con demos.

visualiza

Inspección en el navegador.

✅ Resumen del módulo

✓

LeRobot unifica — datos, políticas, simulación y hardware en un solo repo open.

✓

LeRobotDataset — parquet para estado/acción, mp4 para imagen, features tipadas.

✓

ACT como baseline — después, Diffusion/π0/VQ-BeT según la tarea.

✓

Ciclo de 3 comandos — grabar, entrenar y evaluar/desplegar en el SO-101.

✓

Hub = reproducibilidad — reutiliza y contribuye datasets.

Próximo módulo

2.3 — Simuladores: MuJoCo/MJX, Isaac Sim/Lab y Habitat, donde generamos datos económicos y seguros a escala.

← Volver a la ruta Próximo módulo →