🎓 Aprender por demonstração

No módulo 5.3 você fez o seguidor copiar o líder em tempo real. Agora a ideia é dar um passo além: gravar essas demonstrações e treinar uma rede neural que aprende a ligação "o que eu vejo e onde minhas juntas estão → qual o próximo movimento". Depois de treinada, ela comanda o seguidor sem ninguém no líder. Isso se chama aprendizado por imitação.

Como ler: as setas verdes são uma volta do ciclo; o bloco brilhante (treinar) é o único que precisa de GPU. A seta ciano é o que separa quem consegue de quem desiste: a avaliação diz em que situação a política erra, e a correção é gravar mais exemplos exatamente dessa situação.

Por que aprender

Programar a mão um "pegar e soltar" funciona até o cubo sair 3 cm do lugar. A política aprendida olha a câmera a cada instante e corrige o caminho. É assim que os laboratórios ensinam braços hoje, e o SO-101 com o LeRobot põe esse método na sua mesa.

Conceitos-chave

Cada demonstração gravada é um episódio. O comando lerobot-record liga o líder, o seguidor e as câmeras, e a cada quadro guarda três coisas: as imagens, a posição atual das juntas do seguidor (o estado) e a posição que o líder mandou (a ação). Entre um episódio e outro há um tempo de reset para você arrumar a mesa.

Como ler: cada coluna é um quadro. A linha de cima é o que a câmera viu (o cubo se aproxima, é pego e aparece na caixa). As linhas de baixo são os números que a rede vai aprender a relacionar: dado o estado e a imagem, prever a ação. A instrução de texto vale para o episódio inteiro.

Passo a passo da primeira gravação

Objetivo: gravar episódios da tarefa "pôr o cubo na caixa" com uma câmera de frente. Troque as portas, os id e o seu usuário do Hugging Face (sem os sinais < >).

# Gravar demonstrações com o par SO-101 (Linux; no Windows a porta é COM3, COM4...)
HF_USER=<seu_usuario_hf>          # troque pelo seu usuário do Hugging Face
DATASET=cubo-na-caixa-teste        # nome do dataset

lerobot-record \
  --robot.type=so101_follower --robot.port=/dev/ttyACM0 --robot.id=seguidor \
  --robot.cameras="{ frente: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
  --teleop.type=so101_leader --teleop.port=/dev/ttyACM1 --teleop.id=lider \
  --dataset.repo_id=${HF_USER}/${DATASET} \
  --dataset.single_task="Pôr o cubo vermelho na caixa cinza." \
  --dataset.num_episodes=2 \
  --dataset.episode_time_s=20 \
  --dataset.reset_time_s=10 \
  --dataset.push_to_hub=false \
  --display_data=true

Por que aprender

A política nunca será melhor que as demonstrações. Quem grava com calma e consistência treina uma vez; quem grava com pressa treina cinco vezes e não entende por que não funciona.

Conceitos-chave

O LeRobot salva cada dataset numa pasta com formato padrão: tabelas com estado e ação, vídeos das câmeras e um arquivo de metadados. Esse mesmo formato pode ser enviado ao Hugging Face Hub, onde você treina numa máquina com GPU (ou no Colab) sem copiar arquivos à mão, e onde outras pessoas podem usar seus dados, se você quiser.

Como ler: o nome no topo é o repo_id. As tabelas (meio) são leves; os vídeos (direita, em ciano) ocupam quase todo o espaço. Se o dataset ficou pesado demais, reduza a resolução ou o número de câmeras, não o número de episódios.

Objetivo: fazer login, conferir um episódio gravado e enviar o dataset ao Hub como privado. Rode no mesmo ambiente Python em que instalou o LeRobot.

hf auth login                       # cola o token de escrita (uma vez por máquina)
lerobot-dataset-viz --repo-id <seu_usuario_hf>/<dataset> --episode-index 0

# Abre o dataset local, mostra o tamanho e envia ao Hub como privado.
import sys
from lerobot.datasets.lerobot_dataset import LeRobotDataset

repo_id = sys.argv[1]                    # ex.: <seu_usuario_hf>/<dataset>
ds = LeRobotDataset(repo_id)             # lê de ~/.cache/huggingface/lerobot/
print("episódios:", ds.num_episodes, "| quadros:", ds.num_frames, "| fps:", ds.fps)
print("colunas:", list(ds.features))
ds.push_to_hub(private=True)             # privado: só você vê
print("enviado: https://huggingface.co/datasets/" + repo_id)

Por que aprender

Separar "onde grava" de "onde treina" resolve o problema de quem não tem GPU em casa: grava no notebook ao lado do braço e treina no Colab ou no laboratório. E um dataset bem documentado vira material de aula para a turma inteira.

Conceitos-chave

A ACT (Action Chunking with Transformers) é a política recomendada para começar: pequena, treina rápido e funciona bem com 50 episódios de uma tarefa. O truque dela está no nome: em vez de prever um movimento por vez, ela prevê um pedaço (chunk) de vários movimentos seguidos, o que deixa o braço mais suave e menos hesitante.

Como ler: à esquerda está tudo o que a rede vê num instante. À direita, as barras são movimentos futuros: as cheias são executadas, as vazadas são jogadas fora porque, até lá, a câmera já terá informação nova. A seta ciano fecha a malha, como no ciclo sentir-pensar-agir do 1.1.

Objetivo: treinar uma ACT no seu dataset numa máquina com GPU NVIDIA. Em Mac com chip Apple, troque cuda por mps; sem GPU, use o Colab (há um caderno pronto na documentação do LeRobot).

# Treinar a política ACT (confira as flags com: lerobot-train --help)
HF_USER=<seu_usuario_hf>
DATASET=<dataset>

lerobot-train \
  --dataset.repo_id=${HF_USER}/${DATASET} \
  --policy.type=act \
  --policy.device=cuda \
  --output_dir=outputs/train/act-${DATASET} \
  --job_name=act-${DATASET} \
  --batch_size=8 \
  --steps=20000 \
  --wandb.enable=false \
  --policy.push_to_hub=false

Por que aprender

Saber ler o treino evita desperdício de GPU: você aprende a parar quando a loss estabilizou, a testar checkpoints intermediários e a distinguir "falta dado" de "falta treino".

Conceitos-chave

Avaliar é deixar a política comandar o seguidor, sem o líder, e contar quantas vezes ela acerta. Na versão atual do LeRobot isso se faz com lerobot-rollout; versões anteriores usavam o próprio lerobot-record com a política indicada. Confira qual vale para a sua instalação com --help.

Objetivo: rodar a política treinada por 30 segundos no seguidor, com a mesma câmera e a mesma instrução da gravação.

# Rodar a política no braço real (confira as flags com: lerobot-rollout --help)
POLITICA=outputs/train/act-<dataset>/checkpoints/last/pretrained_model

lerobot-rollout \
  --strategy.type=base \
  --policy.path=${POLITICA} \
  --robot.type=so101_follower --robot.port=/dev/ttyACM0 --robot.id=seguidor \
  --robot.cameras="{ frente: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
  --task="Pôr o cubo vermelho na caixa cinza." \
  --duration=30

Planilha de avaliação (20 tentativas)

Quando o padrão de falha aparecer (por exemplo, "erra sempre que o cubo está à esquerda"), grave 10 a 20 episódios novos naquela região e treine de novo. O LeRobot também tem um modo em que você assume o controle com o líder quando a política erra e essa correção vira episódio novo (--strategy.type=dagger); é o jeito mais eficiente de melhorar depois da primeira versão.

Por que aprender

Sem avaliação com número, todo projeto de IA "quase funciona". Com a planilha você sabe exatamente onde está, compara versões e tem algo concreto para mostrar na apresentação do projeto final.

Conceitos-chave

A ACT aprende uma tarefa e ignora o texto. Um VLA (modelo Visão-Linguagem-Ação, apresentado no 5.1) recebe também a instrução escrita e pode fazer tarefas diferentes conforme o pedido: "ponha o cubo na caixa" ou "ponha a bola na caixa". Esses modelos já vêm pré-treinados em muitos robôs; você só faz o ajuste fino com os seus episódios.

Como ler: a diferença entre um VLA e a ACT é a caixa ciano. Com o texto, o mesmo modelo escolhe qual objeto pegar. O texto não vira código nem lista de passos: ele condiciona diretamente os movimentos das juntas.

Objetivo: fazer o ajuste fino do SmolVLA a partir do modelo base lerobot/smolvla_base usando o seu dataset. Grave antes episódios com instruções diferentes (por exemplo, metade "cubo", metade "bola").

# Instalar o extra do SmolVLA no mesmo ambiente do LeRobot
pip install "lerobot[smolvla]"

# Ajuste fino a partir do modelo base (confira as flags na doc atual)
lerobot-train \
  --policy.path=lerobot/smolvla_base \
  --dataset.repo_id=<seu_usuario_hf>/<dataset> \
  --policy.device=cuda \
  --output_dir=outputs/train/smolvla-<dataset> \
  --batch_size=16 \
  --steps=20000 \
  --wandb.enable=false \
  --policy.push_to_hub=false

Por que aprender

O projeto final (5.6) precisa de um braço que obedeça a pedidos diferentes. Com a ACT você treina uma política por tarefa e o modelo de linguagem escolhe qual chamar; com um VLA, uma política só recebe o pedido em texto. Conhecer os dois caminhos deixa você escolher pelo hardware que tem.

Conceitos-chave