LeRobot: Framework End-to-End da Hugging Face

Conteúdo detalhado

🔹 O que é LeRobot: a filosofia open end-to-end

LeRobot é o esforço da Hugging Face para fazer com a robótica o que o transformers fez com NLP: democratizar. Num só repo PyTorch você tem datasets padronizados, políticas SOTA reprodutíveis, ambientes de sim e drivers de hardware barato. O objetivo é eliminar a fragmentação que travava a área.

📊 Os quatro pilares

Datasets — formato único (LeRobotDataset) versionado no Hub.
Policies — ACT, Diffusion Policy, π0, VQ-BeT com checkpoints públicos.
Sim + envs — gym wrappers (ALOHA, PushT, Xarm) para avaliar.
Hardware — SO-100/SO-101, Koch, ALOHA com scripts de teleop e gravação.

⚡ Dica prática

Tudo gira em torno do CLI/entrypoints (lerobot-record, lerobot-train, lerobot-eval). Aprenda os três comandos e você já roda o ciclo completo num braço de mesa.

Open

Código + pesos públicos.

End-to-end

Dado → policy → robô.

Hub

Versionar dados e ckpt.

Acessível

Hardware de baixo custo.

🔹 LeRobotDataset: formato parquet + vídeo

O LeRobotDataset separa o que é leve do que é pesado: estado, ações e timestamps vão em parquet (colunar, rápido), enquanto as imagens vivem em mp4 codificado e são decodificadas sob demanda. Cada episódio é uma trajetória; features descrevem shape e dtype de cada chave.

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)]})

📊 Anatomia de um episódio

observation.images.* — uma chave por câmera (top, wrist), em mp4.
observation.state — posições de junta / pose do gripper.
action — comando alvo do próximo passo.
episode_index / frame_index — fronteiras de trajetória.

parquet

Estado/ação colunar.

mp4

Imagens decode lazy.

features

Schema shape+dtype.

delta_timestamps

Janelas temporais.

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

LeRobot empacota políticas de classes distintas com a mesma interface. ACT (Action Chunking Transformer, do ALOHA) é o cavalo de batalha para manipulação com poucas demos; Diffusion Policy captura multimodalidade; π0 traz flow matching generalista; VQ-BeT usa tokens vetoriais quantizados.

# 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

✓ Fazer

✓Começar com ACT: poucos hparams, treina rápido, ótimo baseline.
✓Usar π0 pré-treinado quando precisar de generalização semântica.
✓Casar o chunk size da policy com a frequência do robô.

✗ Evitar

✗Diffusion Policy com 10 demos e esperar convergência.
✗Trocar de policy sem re-conferir normalização de ações.
✗Treinar π0 do zero sem GPU robusta — parta do checkpoint.

ACT

Chunking transformer + VAE.

Diffusion

Denoising de trajetória.

π0

Flow matching generalista.

VQ-BeT

Tokens quantizados.

🔹 Hardware suportado: SO-101, Koch, ALOHA

O SO-101 (sucessor do SO-100, projeto The Robot Studio + Hugging Face) é o braço-referência: ~6 DOF, servos Feetech, custo na casa dos $100–150. A coleta usa esquema leader-follower — você move um braço "líder" e o "seguidor" replica, gravando estado+ação sincronizados com a câmera.

Montar e calibrar

Identificar portas dos motores, rodar lerobot-calibrate para mapear faixa de cada junta.

Teleoperar

Leader move, follower copia. Câmeras (top + wrist) registram a cena em tempo real.

Gravar episódios

30–50 demos costumam bastar para ACT numa tarefa pick-and-place simples.

⚡ Dica prática

Consistência > quantidade. Demos limpas, mesma iluminação e variação proposital de posição do objeto ensinam generalização melhor do que 200 episódios bagunçados.

SO-101

Braço ~$100, 6 DOF.

Leader-follower

Teleop por cópia.

Calibração

Mapear faixa das juntas.

ALOHA

Bimanual de referência.

🔹 Fluxo: gravar → treinar → avaliar → deploy

O ciclo completo são três comandos e um loop de inferência. Você grava demos, treina uma policy, avalia no robô (ou em sim) e faz deploy rodando a policy em malha fechada 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

📊 Sinais de saúde do treino

loss caindo mas success rate parado → problema de normalização/câmera.
overfit a poucas demos → aumente diversidade, não só steps.
success em sim, falha real → gap sim-real (Trilha 3).

⚡ Dica prática

Avalie sempre com o robô na mesma configuração da gravação (iluminação, posição das câmeras, fundo). Mudar a cena entre treino e deploy é a causa nº 1 de uma policy que "funcionava ontem" falhar hoje — e não é bug, é distribution shift.

record

Coleta de demos.

train

Treina a policy.

eval rollout

Mede success rate.

deploy

Malha fechada 30 Hz.

✓ Fazer

✓Avaliar com rollouts no robô, não só a loss de treino.
✓Logar vídeo dos rollouts para diagnosticar falhas.
✓Versionar dataset + config + checkpoint juntos.

✗ Evitar

✗Aumentar steps quando o problema é falta de diversidade.
✗Confiar só em loss caindo como sinal de sucesso.
✗Mudar a cena entre gravação e deploy.

🔹 Comunidade e reprodutibilidade

O valor de LeRobot escala com a comunidade: milhares de datasets e checkpoints públicos no Hub, cada um versionado e com card descritivo. Você reproduz um paper baixando o dataset exato e o config, e contribui publicando suas demos do SO-101 para outros treinarem.

# 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

⚡ Dica prática

Antes de gravar do zero, busque no Hub: pode existir um dataset SO-101 da sua tarefa. Co-treinar com dados públicos + suas demos melhora generalização — a deixa perfeita para o módulo de datasets (2.6).

Hub

Datasets + checkpoints.

Reprodutível

Mesmo dado + config.

push_to_hub

Contribuir demos.

visualize

Inspeção no browser.

✅ Resumo do módulo

✓

LeRobot unifica — dados, políticas, sim e hardware num só repo open.

✓

LeRobotDataset — parquet para estado/ação, mp4 para imagem, features tipadas.

✓

ACT como baseline — depois Diffusion/π0/VQ-BeT conforme a tarefa.

✓

Ciclo de 3 comandos — record, train, eval/deploy no SO-101.

✓

Hub = reprodutibilidade — reuse e contribua datasets.

Próximo módulo

2.3 — Simuladores: MuJoCo/MJX, Isaac Sim/Lab e Habitat, onde geramos dados baratos e seguros em escala.

← Voltar à trilha Próximo módulo →