MÓDULO 2.2

🤗 LeRobot: Pipeline End-to-End

O framework open-source da HuggingFace que democratiza robótica: coleta, treino e deploy em uma única ferramenta. Com 12k stars no GitHub e 58k+ datasets, LeRobot é o ponto de entrada mais acessível para VLA prático.

Tópicos

~50

Minutos

Técnico

Nível

Prático

Tipo

Diagrama ilustrativo — fluxo end-to-end do LeRobot: coleta → dataset → treino → avaliação → deploy.

🤗 LeRobot: 12k stars, 58k+ datasets

LeRobot é o framework open-source da HuggingFace para robótica end-to-end. Lançado em 2024, unifica coleta de dados, treinamento de políticas e deploy em robôs reais numa única ferramenta com documentação extensa e comunidade ativa.

🏗️ O que o LeRobot resolve

Antes do LeRobot, cada laboratório tinha seu pipeline ad-hoc: scripts de coleta proprietários, formatos de dataset incompatíveis, pipelines de treino isolados. O LeRobot padroniza tudo com uma API coesa — do hardware ao modelo treinado — e publica tudo no HuggingFace Hub para reutilização.

✓ O que o LeRobot inclui

✓Scripts de coleta com teleoperação (lerobot/record)
✓Políticas pré-implementadas: ACT, Diffusion Policy, TDMPC, VQ-BeT
✓Integração nativa com HuggingFace Hub (58k+ datasets)
✓Suporte a múltiplos robôs: SO-100, Koch v1.1, Aloha
✓Visualizador de episódios e métricas de avaliação

✗ O que o LeRobot não faz

✗Não é um simulador — precisa de MuJoCo/Isaac Sim para sim-to-real
✗Não substitui ROS2 para controle de baixo nível em produção
✗Não treina modelos de visão desde o zero (usa backbones pré-treinados)
✗Não garante segurança em ambientes não controlados

⚡ Instalação 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')"

Conceitos-chave

LeRobotDataset

Classe principal que encapsula um dataset no formato RLDS com vídeo, ações e metadados sincronizados.

lerobot/scripts/train.py

Script unificado de treinamento que carrega configuração YAML e salva checkpoints automaticamente.

Hub integration

Push e pull de datasets e modelos direto do HuggingFace Hub com huggingface-cli login.

Multi-robot support

Configurações prontas para SO-100, Koch v1.1 e Aloha; adicionar novo robô via YAML de calibração.

🎮 Coleta de Dados com Teleoperação

Teleoperação é a técnica de um humano controlar o robô remotamente para gerar demonstrações de qualidade. O LeRobot grava sincronizadamente vídeo das câmeras e posições dos atuadores, produzindo episódios com timestamps alinhados que alimentam o treinamento supervisionado.

💡 Regra dos 50-100 episódios

Para tarefas simples (pick-and-place, empilhar blocos), 50-100 episódios de alta qualidade superam 500 episódios ruins. Consistência e coverage de variações (ângulos, posições do objeto) importam mais que volume bruto.

🖥️ Gravando episódios com o 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âmeras: uma global, uma no pulso do robô
✓30 Hz de captura sincronizada de câmeras + atuadores
✓Calibração intrínseca/extrínseca antes de cada sessão
✓Verificar replay de cada episódio antes de prosseguir

✗ Erros comuns na coleta

✗Movimentos bruscos ou hesitações na demonstração
✗Câmeras com foco ruim ou iluminação inconsistente
✗Objetos sempre na mesma posição (pouca variação)
✗Não filtrar episódios falhos antes do treino

Conceitos-chave

Leader-follower

O robô "leader" (controlado pelo humano) comanda o "follower" (que executa). Ambos têm sensores para capturar o estado real.

Episode recording

Cada demonstração é um episódio: sequência de observações (imagens + posições) e ações com timestamps alinhados.

Data quality filtering

Remover episódios onde o robô falhou, teve movimentos anômalos ou a câmera ficou obstruída.

🧠 Políticas: ACT, Diffusion Policy, TDMPC

O LeRobot implementa múltiplas arquiteturas de política, cada uma com trade-offs diferentes entre velocidade de inferência, qualidade do movimento e complexidade de treino. Escolher a política certa para sua tarefa é tão importante quanto a qualidade dos dados.

Evolução das arquiteturas de política

ACT — Action Chunking with Transformers (2023)

Prediz k ações de uma vez (action chunk) em vez de uma por vez. Reduz erros de compounding. Inferência rápida (~10ms), ideal para controle em tempo real a 50Hz.

chunk_size=100 Transformer encoder-decoder

Diffusion Policy (2023)

Modela distribuições de ação com DDPM. Captura multimodalidade (várias formas de resolver a tarefa). Mais lento na inferência (10-100 denoising steps) mas produz movimentos mais suaves.

num_inference_steps=10 UNet condicional

TDMPC — TD-MPC2 (2024)

World model + planning: aprende um modelo de dinâmica do ambiente e usa MPC (Model Predictive Control) para planejar ações. Melhor generalização, mas requer mais dados e compute.

horizon=5 Latent world model

💡 Qual política escolher?

Comece com ACT para tarefas de manipulação simples — é o mais rápido para iterar. Use Diffusion Policy quando precisar de movimentos multimodais (ex.: tarefa que pode ser resolvida de múltiplas formas). Reserve TDMPC para tarefas de longo horizonte com sim-to-real.

Conceitos-chave

Action chunking

Predizer múltiplas ações futuras de uma vez para reduzir erros de compounding na execução sequencial.

DDPM (Denoising Diffusion)

Processo de denoising progressivo que gera amostras de alta qualidade de distribuições de ação complexas.

VQ-BeT

Tokenização vetorial discreta de ações — trata ações como tokens, permitindo uso de arquiteturas de LLM.

Multimodalidade

Capacidade de aprender múltiplas formas de resolver uma tarefa, ao invés de "média" de todas as demonstrações.

⚙️ Treinamento em GPU: Config YAML e Checkpoints

O LeRobot usa arquivos YAML com Hydra para configuração hierárquica de treinamentos. Cada run salva checkpoints automaticamente e pode ser retomada, permitindo iteração rápida sem retrabalho.

🚀 Iniciando um treinamento

# 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 — fluxo de treinamento: YAML → GPU → checkpoint → métricas W&B.

Conceitos-chave

Gradient accumulation

Acumular gradientes por N batches antes do update — permite batch size efetivo maior do que a VRAM permite.

Mixed precision (BF16)

Usar BFloat16 para forward/backward e FP32 para atualização dos pesos — 2x mais rápido com memória similar.

DDP (DistributedDataParallel)

Estratégia PyTorch para multi-GPU: cada GPU processa um mini-batch e gradientes são sincronizados via AllReduce.

resume_from_checkpoint

Retomar treinamento de um checkpoint salvo, preservando estado do otimizador e scheduler de learning rate.

📊 Weights & Biases: Tracking de Experimentos

W&B é a plataforma padrão para rastrear experimentos de ML. O LeRobot tem integração nativa — basta adicionar wandb.enable=true no YAML de config para ter métricas, curvas de loss e vídeos de avaliação centralizados.

💡 Sem tracking = caixa preta

Treinar VLAs sem tracking estruturado é andar às cegas. Você precisa saber: qual run teve melhor success rate? Qual learning rate divergiu? Em que step o modelo parou de melhorar? W&B responde tudo isso com gráficos comparativos side-by-side.

📈 Configurando W&B no 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 essenciais a monitorar

✓train/loss — deve diminuir monotonicamente (com ruído)
✓eval/success_rate — porcentagem de episódios bem-sucedidos
✓eval/video — vídeos gravados do robô avaliando
✓Learning rate schedule — confirmar que decai conforme esperado

✗ Sinais de alerta no dashboard

✗Loss que sobe abruptamente — possível learning rate alto
✗Success rate estagnado após 20k steps — dataset insuficiente
✗Gradient norm explodindo — adicionar gradient clipping
✗GPU utilization abaixo de 70% — bottleneck no data loading

Conceitos-chave

wandb.Sweep

Hyperparameter search automático: define espaço de busca (lr, batch_size) e W&B agenda e rastreia todos os runs.

Model Registry

Versionar checkpoints de modelos com tags semânticas (best, staging, production) para rastreabilidade.

Tables para trajetórias

Logar sequências de ações e observações como tabelas W&B para análise qualitativa de comportamentos.

wandb.config

Registrar todos os hiperparâmetros do run automaticamente para reproducibilidade e comparação de experimentos.

🐳 Docker e Reprodutibilidade em Robótica

Reprodutibilidade é um dos maiores problemas em pesquisa de robótica. Versões de drivers CUDA, dependências Python e configurações de hardware criam ambientes frágeis. Docker containeriza tudo — um Dockerfile garante que qualquer pessoa (ou servidor de CI) consiga reproduzir seu treinamento exatamente.

💡 NVIDIA NGC: containers prontos

A NVIDIA mantém o NGC (NVIDIA GPU Cloud) com containers PyTorch+CUDA otimizados para diversas GPUs. LeRobot fornece Dockerfiles que estendem esses containers — você não precisa configurar CUDA manualmente.

🐳 Dockerfile multi-stage 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 ...

✓ Boas práticas Docker para robótica

✓Dockerfile multi-stage para separar build de runtime
✓Montar datasets como volumes (-v) — não copiar para a imagem
✓Fixar versão do container base (:24.01 não :latest)
✓Usar devcontainers no VS Code para desenvolvimento

✗ Armadilhas comuns

✗Copiar datasets para dentro da imagem Docker (gigabytes desperdiçados)
✗Esquecer --gpus all no docker run (treina em CPU)
✗Usar :latest — imagem muda e quebra reprodutibilidade
✗Não versionar Dockerfile junto com o código do experimento

Conceitos-chave

nvidia-docker2

Plugin que permite containers Docker acessarem GPUs NVIDIA via --gpus all sem configuração manual de CUDA.

NVIDIA NGC

Registry de containers otimizados para GPU: PyTorch, TensorFlow, TensorRT — base confiável para experimentos reproducíveis.

devcontainers

Integração VS Code que abre o editor dentro do container Docker — mesmo ambiente de desenvolvimento e produção.

✅ Resumo do Módulo

✓

LeRobot = coleta + treino + deploy — framework unificado da HuggingFace com 12k stars e 58k+ datasets públicos no Hub.

✓

Teleoperação gera dados de qualidade — 50-100 episódios consistentes superam 500 ruins; calibração e setup de câmeras são críticos.

✓

Políticas com trade-offs distintos — ACT para velocidade, Diffusion Policy para suavidade multimodal, TDMPC para longo horizonte.

✓

W&B + Docker = reprodutibilidade — tracking de experimentos e containerização garantem que resultados possam ser replicados por qualquer pessoa.

Próximo módulo

2.3 — Simuladores: MuJoCo, Isaac Sim, PyBullet

← Voltar para a Trilha Próximo módulo →