MÓDULO 2.1

🐍 Ecossistema Python: PyTorch, Transformers, Gymnasium

As ferramentas que todo engenheiro VLA precisa dominar: do tensor ao environment. PyTorch para autograd, HuggingFace para modelos pré-treinados, Gymnasium para ambientes padronizados.

Tópicos

~3h

Estimado

Técnico

Prático

Tipo

🔥 PyTorch para robótica: tensores e autograd

O framework de deep learning dominante em robótica. Entender tensores e o sistema de diferenciação automática é o pré-requisito técnico para qualquer trabalho sério com VLA.

💡 O que é

PyTorch é o framework de deep learning dominante em robótica e VLA. Tensores são arrays multidimensionais com suporte nativo a GPU via CUDA. O sistema autograd calcula gradientes automaticamente através do grafo computacional — essencial para backpropagation durante treinamento de políticas neurais. Praticamente todo VLA relevante (OpenVLA, pi-0, ACT) é implementado em PyTorch.

✓ Fazer

✓ Usar bfloat16 em GPUs Ampere+ para treinar VLAs grandes
✓ Mover tensores para device antes de operar: .to(device)
✓ Usar torch.compile() para acelerar loops de treinamento repetitivos
✓ Chamar optimizer.zero_grad() antes de cada backward

✗ Evitar

✗ Acumular tensores em listas Python — vaza memória GPU silenciosamente
✗ Misturar float32 e float16 sem torch.amp
✗ Chamar .item() dentro do loop de treino (sincroniza CPU/GPU)
✗ Esquecer model.eval() / torch.no_grad() na inferência

📦 Padrão mínimo: treinar uma política PyTorch

import torch
import torch.nn as nn

# device-agnostic
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

model = PolicyNet().to(device)
optimizer = torch.optim.AdamW(model.parameters(), lr=1e-4)

# mixed precision (Ampere+)
scaler = torch.cuda.amp.GradScaler()

for batch in dataloader:
    obs, action = batch["obs"].to(device), batch["action"].to(device)
    optimizer.zero_grad()
    with torch.autocast(device_type="cuda", dtype=torch.bfloat16):
        pred = model(obs)
        loss = nn.functional.mse_loss(pred, action)
    scaler.scale(loss).backward()
    scaler.step(optimizer)
    scaler.update()

torch.Tensor

Array ND com device, dtype e grad

nn.Module

Base de toda rede; forward() obrigatório

autograd

Grafo computacional + backward()

torch.compile

JIT para loops repetitivos (2× faster)

🤗 HuggingFace Transformers: modelos pré-treinados

A biblioteca que democratizou o acesso a modelos de linguagem e visão — e que hospeda praticamente todo VLA open-source relevante.

⚡ Por que aprender primeiro

O HuggingFace Hub é o centro do ecossistema open-source de VLA. OpenVLA, SmolVLA, Qwen-VL, PaliGemma — todos distribuídos via Hub com pipeline de inferência pronto. LeRobot hospeda 58k+ datasets lá. Sem dominar from_pretrained(), você não consegue nem fazer inferência.

300k+

modelos no Hub

58k+

datasets LeRobot

PEFT

LoRA fine-tune eficiente

🔧 Inferência com OpenVLA via HuggingFace

from transformers import AutoModelForVision2Seq, AutoProcessor
import torch

processor = AutoProcessor.from_pretrained("openvla/openvla-7b", trust_remote_code=True)
model = AutoModelForVision2Seq.from_pretrained(
    "openvla/openvla-7b",
    attn_implementation="flash_attention_2",
    torch_dtype=torch.bfloat16,
    low_cpu_mem_usage=True,
    trust_remote_code=True
).to("cuda")

# Processar frame + instrução em linguagem natural
inputs = processor(
    "In: What action should the robot take to pick up the cup?\nOut:",
    image,
    return_tensors="pt"
).to("cuda", dtype=torch.bfloat16)

action = model.predict_action(**inputs, unnorm_key="bridge_orig", do_sample=False)

✓ Boas práticas

✓ Usar safetensors em vez de pickle (.bin)
✓ Versionar modelos com revision="main" ou tag
✓ LoRA para fine-tune: treina 1-10% dos parâmetros
✓ Usar flash_attention_2 quando disponível

✗ Armadilhas comuns

✗ Esquecer trust_remote_code=True em VLAs custom
✗ Baixar modelos sem verificar licença de uso comercial
✗ Carregar full model sem low_cpu_mem_usage (OOM)
✗ Misturar processor de modelo A com model B

AutoModel

Carrega arquitetura correta automaticamente

LoRA/PEFT

Fine-tune eficiente com poucos parâmetros

safetensors

Formato seguro e rápido para pesos

Hub API

Push/pull modelos e datasets programaticamente

🏋️ Gymnasium: environments padronizados

A API universal entre política e ambiente. MuJoCo, Isaac Sim e PyBullet implementam essa interface — entender obs/act/reward/done é fundamental para qualquer loop de treinamento.

🔍 O que é

Gymnasium (sucessor do OpenAI Gym) define a interface padrão para ambientes de RL. Em robótica VLA, serve como wrapper para simuladores e permite treinar políticas com interface consistente. A API é simples mas poderosa:

Espaços

• observation_space — o que o robô vê
• action_space — o que ele pode fazer
• Box para contínuo, Discrete para discreto

Ciclo de vida

• env.reset() → estado inicial
• env.step(action) → (obs, reward, done, info)
• Loop até terminated ou truncated

Loop de episódio Gymnasium

`obs, info = env.reset(seed=42)`

Inicia episódio, retorna observação inicial. Seed garante reprodutibilidade do estado inicial.

`action = policy(obs)`

Política processa observação e retorna ação no espaço contínuo (ex.: velocidades de juntas, delta cartesiano).

`obs, reward, terminated, truncated, info = env.step(action)`

Ambiente executa ação, retorna nova observação, sinal de recompensa e flags de término.

`VectorEnv: N ambientes paralelos`

Para treinar mais rápido: gymnasium.vector.make("env-id", num_envs=8) roda 8 episódios simultâneos num único processo.

gym.Env

Classe base a subclassificar

Box(shape)

Espaço contínuo n-dimensional

Wrappers

Transformam obs/act sem tocar env

VectorEnv

N ambientes paralelos num processo

📦 Datasets e DataLoaders para trajetórias

Dados são o gargalo número um em robótica. Estruturar, carregar e aumentar trajetórias de forma eficiente é tão importante quanto a arquitetura do modelo.

📊 Formatos de Dataset em Robótica

RLDS (Google): TFRecord com metadados de episódio, padrão do Open X-Embodiment com 1M+ trajetórias.
LeRobot Dataset: Parquet + vídeo MP4 no HuggingFace Hub. 58k+ datasets, API Python nativa com from_hub().
HDF5 próprio: Usado por robótica acadêmica (RoboMimic, R2R2). Hierárquico, eficiente para sequências longas.

RLDS / Open X

• 1M+ trajetórias reais
• TFRecord (precisa TF)
• Metadata rico por step
• Padrão Google/DeepMind

LeRobot Dataset ★

• 58k+ datasets no Hub
• Parquet + vídeo MP4
• API Python limpa
• Integração nativa treino

HDF5 / Proprio

• Flexível e hierárquico
• Rápido acesso aleatório
• Sem dependência de nuvem
• Comum em academia

💡 Dica: DataLoader para trajetórias

Trajetórias têm comprimentos variáveis. Use collate_fn customizado para pad ou truncar sequências ao montar batches. Combine com num_workers=4 e pin_memory=True para maximizar throughput GPU.

loader = DataLoader(
    dataset, batch_size=32, num_workers=4,
    pin_memory=True, collate_fn=pad_trajectory_batch
)

RLDS

TFRecord com episódios Open X

LeRobot DS

Parquet+vídeo, 58k datasets

collate_fn

Montar batches de trajetórias variáveis

augmentation

Crop/jitter específico de robótica

📈 Weights & Biases: tracking de experimentos

Sem tracking estruturado, treinamentos de VLA viram caixa preta. W&B torna loss, success rate e hiperparâmetros visual e reproduzível.

💡 W&B + LeRobot: integração nativa

LeRobot tem suporte nativo a W&B via config YAML. Basta setar wandb.enable: true no arquivo de configuração — sem uma linha de código extra.

# config/train_act.yaml
wandb:
  enable: true
  project: "vla-pickup-cup"
  entity: "meu-time"
  notes: "ACT baseline lr=1e-4"

wandb.init()

Inicia um run de experimento

Sweeps

Busca automática de hiperparâmetros

Tables

Visualizar trajetórias e predições

Registry

Versionamento de checkpoints

🐳 Docker e reprodutibilidade em robótica

A combinação CUDA driver + PyTorch + MuJoCo pode quebrar de formas misteriosas. Containers eliminam o "funciona na minha máquina" da equação.

🔍 Por que Docker em robótica é crítico

Docker containeriza o ambiente de desenvolvimento: versões exatas de Python, PyTorch, CUDA e dependências ficam fixas. Em robótica, onde a combinação CUDA driver + PyTorch + MuJoCo pode quebrar facilmente, containers são essenciais. NVIDIA NGC e LeRobot fornecem containers prontos com tudo configurado.

✓ Setup recomendado

✓ Partir de imagem NVIDIA NGC: nvcr.io/nvidia/pytorch:24.01-py3
✓ Multi-stage build: builder → runtime (imagem menor)
✓ Montar datasets via volume, não copiar para imagem
✓ devcontainer para VS Code com GPU passthrough

✗ Erros comuns

✗ Copiar dataset inteiro para dentro da imagem Docker
✗ Usar docker run sem --gpus all
✗ Ignorar compatibilidade CUDA driver vs PyTorch CUDA
✗ Commitar segredos (tokens HF, W&B API key) no Dockerfile

🐳 Dockerfile mínimo para VLA com LeRobot

# Base: PyTorch + CUDA oficial NVIDIA
FROM nvcr.io/nvidia/pytorch:24.01-py3

WORKDIR /workspace

# Instalar LeRobot e dependências
RUN pip install lerobot[gymnasium,wandb] huggingface_hub

# Montar datasets externamente (não copiar)
VOLUME ["/data"]

# GPU passthrough: nvidia-docker2 ou --gpus all
CMD ["python", "train.py", "--config", "config/act.yaml"]

💡 devcontainers: GPU no VS Code

Adicione .devcontainer/devcontainer.json com "runArgs": ["--gpus", "all"] e toda a equipe abre o projeto com o mesmo ambiente, incluindo CUDA, sem configuração manual. LeRobot disponibiliza um devcontainer pronto no repositório oficial.

NVIDIA NGC

Containers otimizados PyTorch+CUDA

--gpus all

Passthrough GPU para container

devcontainer

Ambiente uniforme no VS Code

multi-stage

Builder + runtime = imagem enxuta

✅ Resumo do Módulo

✓

PyTorch é o coração do treino VLA — tensores, autograd, mixed precision e torch.compile formam a base técnica de todo engenheiro.

✓

HuggingFace Hub + LoRA — acesso a 300k+ modelos pré-treinados e fine-tune eficiente com 1-10% dos parâmetros originais.

✓

Gymnasium: contrato universal obs/act/reward — qualquer simulador (MuJoCo, Isaac Sim, PyBullet) fala essa linguagem; VectorEnv paraleliza episódios.

✓

Docker + W&B = reprodutibilidade — ambientes fixos com containers e rastreamento visual de experimentos são tão importantes quanto o modelo.

Próximo módulo

2.2 — LeRobot: Pipeline End-to-End (coleta, treino e deploy em robô real)

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