Train ACT Depth

ACT-D — Guia de Configuração de Treinamento

Referência completa de todos os parâmetros do YAML de treino do ACT-D (Action Chunking Transformer com Depth 3D).
Baseado em train_get_cup_depth.yaml — Projeto Prometheus, Unitree G1 + Dex3.

1. Dataset de treinamento (`dataset`)

dataset:
  repo_id: Mrwlker/pick_up_the_cup_2026-04-30
  root: meu_dataset/pick_up_the_cup_2026-04-30
  episodes: [1, 2, 3, 4, 5, 6, 8, 10, 11, 12, 13, 14, 15, 16, 17, 20, 21]

Parâmetro	Tipo	Descrição
`repo_id`	`str`	ID do dataset no Hugging Face Hub. O LeRobot baixa os metadados e vídeos desse repositório.
`root`	`str`	Caminho local onde o dataset é cacheado após o download. Se já existir localmente, evita re-download.
`episodes`	`list[int]`	Índices dos episódios usados no treino. Episódios não listados aqui são ignorados pelo dataloader — use isso para separar treino e validação manualmente.

Augmentação de imagem (`image_transforms`)

image_transforms:
  enable: true
  max_num_transforms: 1
  tfs:
    ColorJitter:
      type: ColorJitter
      weight: 1.0
      kwargs:
        brightness: [0.8, 1.2]
        contrast:   [0.8, 1.2]
        saturation: [0.5, 1.5]
        hue:        [-0.05, 0.05]

Parâmetro	Tipo	Descrição
`enable`	`bool`	Liga ou desliga toda a augmentação. Coloque `false` para validação ou debugging.
`max_num_transforms`	`int`	Quantas transformações são sorteadas e aplicadas por frame. `1` significa que apenas o ColorJitter é aplicado por vez. Aumentar aqui com múltiplos transforms aumenta a diversidade mas também o custo de CPU.
`tfs.ColorJitter.weight`	`float`	Probabilidade relativa de esta transform ser sorteada quando há mais de uma definida. Com apenas um transform, o peso não tem efeito.
`brightness`	`[min, max]`	Fator multiplicativo no brilho. `[0.8, 1.2]` significa ±20% de variação. Ajuda o modelo a generalizar para diferentes condições de iluminação.
`contrast`	`[min, max]`	Fator de contraste. Mesma lógica do brilho.
`saturation`	`[min, max]`	Fator de saturação de cor. Faixa mais ampla (`[0.5, 1.5]`) porque a cor do copo pode variar entre coletas.
`hue`	`[min, max]`	Variação de matiz em frações de 360°. Manter pequeno (`[-0.05, 0.05]`) para não distorcer cores de objetos de referência.

Nota: A augmentação é aplicada somente na imagem RGB. O mapa de profundidade não passa pelo ColorJitter — ele é processado diretamente pela PointNet como dados métricos.

2. Dataset de validação (`val_dataset`)

val_dataset:
  repo_id: Mrwlker/pick_up_the_cup_2026-04-30
  root: meu_dataset/pick_up_the_cup_2026-04-30
  episodes: [7, 9, 18, 19]

Mesma estrutura do dataset, mas sem image_transforms (augmentação desativada na validação por padrão).
Os episódios aqui não devem se sobrepor aos do dataset de treino — são os episódios reservados para medir generalização.

A validação roda a cada eval_freq steps e reporta val_loss, l1_loss e kld_loss separadamente no log e no WandB.

3. Política (`policy`)

Identificação

policy:
  type: actdepth
  repo_id: Mrwlker/pick_up_the_cup_depth
  push_to_hub: false

Parâmetro	Tipo	Descrição
`type`	`str`	Registra qual classe de política usar. `actdepth` aponta para `ACTConfig` registrado com `@PreTrainedConfig.register_subclass("actdepth")`. Não alterar.
`repo_id`	`str`	Repositório HF onde o modelo será publicado se `push_to_hub: true`.
`push_to_hub`	`bool`	Se `true`, faz upload automático do checkpoint ao final do treino. Manter `false` durante experimentos.

Features de entrada e saída

input_features:
  observation.images.head_camera:
    type: VISUAL
    shape: [3, 480, 640]
 
  observation.images.head_camera_depth:
    type: VISUAL
    shape: [3, 480, 640]
 
  observation.state:
    type: STATE
    shape: [28]
 
  observation.left_hand_pressure:
    type: STATE
    shape: [33]
 
  observation.right_hand_pressure:
    type: STATE
    shape: [33]
 
output_features:
  action:
    type: ACTION
    shape: [28]

Feature	Shape	Processamento
`observation.images.head_camera`	`[3, 480, 640]`	Imagem RGB — entra no ResNet18, gera tokens visuais `[B, h×w, 512]`. Recebe ColorJitter.
`observation.images.head_camera_depth`	`[3, 480, 640]`	Mapa de profundidade — não entra no ResNet. É convertido em nuvem de pontos 3D e processado pela PointNet, gerando um token próprio `[B, 1, 512]` no encoder.
`observation.state`	`[28]`	Posição das 28 juntas controladas do G1. Projetado para um state token `[B, 1, 512]`.
`observation.left_hand_pressure`	`[33]`	Leituras dos 33 sensores táteis da mão esquerda Dex3. Ativo somente se `use_pressure: true`.
`observation.right_hand_pressure`	`[33]`	Leituras dos 33 sensores táteis da mão direita Dex3. Ativo somente se `use_pressure: true`.
`action`	`[28]`	Ações de saída — posições alvo das 28 juntas para os próximos `chunk_size` passos.

Para desativar depth ou pressão, basta comentar as features correspondentes no YAML e setar use_depth_3d: false / use_pressure: false. As duas configurações precisam estar consistentes.

Parâmetros de chunk e observação

chunk_size: 100
n_action_steps: 100
n_obs_steps: 1
use_amp: true

Parâmetro	Tipo	Descrição
`chunk_size`	`int`	Quantos passos de ação o modelo prediz de uma vez. `100` significa que a cada chamada o modelo gera 100 ações futuras. Aumentar melhora o planejamento de longo prazo mas exige mais VRAM.
`n_action_steps`	`int`	Quantas das `chunk_size` ações são realmente executadas no robô antes de chamar o modelo novamente. Deve ser ≤ `chunk_size`. Com `n_action_steps = chunk_size`, todas as ações preditas são usadas.
`n_obs_steps`	`int`	Quantos frames de observação passados são passados à política. Atualmente fixo em `1` — múltiplos frames não estão implementados.
`use_amp`	`bool`	Habilita Automatic Mixed Precision (float16 nas operações de forward/backward). Reduz uso de VRAM em ~40% e acelera treino em GPUs com Tensor Cores (RTX, A100). Manter `true` salvo em debugging de NaN.

4. Módulos ACT-D exclusivos

Depth 3D — PointNet

use_depth_3d: true
camera_intrinsics:
  fx: 600.0
  fy: 600.0
  cx: 320.0
  cy: 240.0
pointnet_num_points: 1024

Parâmetro	Tipo	Descrição
`use_depth_3d`	`bool`	Liga o pipeline de profundidade. `true` → instancia PointNet, projeta depth em 3D, cria depth token no encoder. `false` → nenhum módulo de depth é criado, tensor de depth é ignorado mesmo que esteja nos `input_features`.
`camera_intrinsics.fx`	`float`	Distância focal horizontal em pixels. Usado na projeção pinhole para converter pixels em coordenadas 3D reais. Deve corresponder às intrínseças reais da câmera D435 ou equivalente.
`camera_intrinsics.fy`	`float`	Distância focal vertical em pixels.
`camera_intrinsics.cx`	`float`	Coordenada X do ponto principal (centro óptico) em pixels. Geralmente próximo a `width / 2`.
`camera_intrinsics.cy`	`float`	Coordenada Y do ponto principal em pixels. Geralmente próximo a `height / 2`.
`pointnet_num_points`	`int`	Número de pontos 3D amostrados da nuvem antes de entrar na PointNet. `1024` é o padrão — aumentar melhora a representação geométrica mas aumenta custo de memória e tempo por step. Pontos inválidos (z < 5cm) são filtrados antes da amostragem.

Como funciona o depth no ACT-D: O tensor de depth [B, 3, H, W] passa pela depth_to_pointcloud(), que reverte a normalização feita no pipeline ZMQ (multiplica por 2.0 para recuperar metros reais), aplica a projeção pinhole com as intrínsecas, e amostra aleatoriamente pointnet_num_points pontos válidos. A PointNet processa esses pontos e gera um vetor [B, 512] que é projetado e inserido como token próprio no ACTEncoder — separado do token de estado e dos tokens RGB.

Percepção tátil — Pressão

use_pressure: true
pressure_feature_dim: 66
pressure_hidden_dim: 256

Parâmetro	Tipo	Descrição
`use_pressure`	`bool`	Liga o pipeline tátil. `true` → instancia o MLP de pressão, concatena left + right e projeta para `[B, 512]`. `false` → sensores de pressão são ignorados mesmo que estejam nos `input_features`.
`pressure_feature_dim`	`int`	Dimensão total da entrada de pressão. `66 = 33 (esquerda) + 33 (direita)`. Ajustar se o número de sensores mudar.
`pressure_hidden_dim`	`int`	Dimensão da camada oculta do MLP que processa a pressão. `256` é suficiente para 66 entradas; aumentar para `512` se a tarefa for muito dependente de tato fino.

Scene Uncertainty Gate

scene_uncertainty_threshold: 0.5

Parâmetro	Tipo	Descrição
`scene_uncertainty_threshold`	`float`	Limiar de incerteza VAE para ativar o gate de segurança durante inferência. Quando o desvio padrão médio do espaço latente supera esse valor, a ação predita é interpolada suavemente em direção à posição neutra do robô. `0.0` desativa o gate completamente.

Valores guia:

Valor	Comportamento
`0.0`	Gate desligado — comportamento original do ACT. Use durante treino e primeiros testes.
`0.3`	Agressivo — robô retorna ao neutro com frequência em situações novas.
`0.5`	Recomendado para deploy inicial — ativa em incerteza moderada.
`0.8`	Conservador — gate só em cenários muito fora da distribuição de treino.

Durante o treino este parâmetro não tem efeito — o gate só é aplicado no select_action() (inferência). Manter 0.0 no YAML de treino e ajustar na hora do deploy.

5. Anti-overfitting

dropout: 0.2
optimizer_weight_decay: 1e-3
kl_weight: 1.0

Parâmetro	Tipo	Descrição
`dropout`	`float`	Dropout aplicado nas camadas do Transformer (encoder, decoder, feed-forward). `0.2` é mais alto que o padrão ACT (`0.1`) porque o dataset é pequeno (~21 episódios). Reduzir para `0.1` se o dataset crescer para 100+ episódios.
`optimizer_weight_decay`	`float`	L2 regularization no AdamW. `1e-3` é 10× maior que o padrão (`1e-4`) — penaliza pesos grandes, reduz memorização. Junto com dropout, é a principal defesa contra overfitting em datasets pequenos.
`kl_weight`	`float`	Peso da divergência KL no loss total: `loss = l1_loss + kl_weight × kld_loss`. `1.0` equilibra reconstrução e regularização do espaço latente. Aumentar força o VAE a aprender um prior mais compacto; diminuir prioriza a reconstrução fiel das ações.

6. Arquitetura Transformer

dim_model: 512
n_heads: 8
dim_feedforward: 3200
n_encoder_layers: 4
n_decoder_layers: 1
use_vae: true
latent_dim: 32
n_vae_encoder_layers: 4

Parâmetro	Tipo	Descrição
`dim_model`	`int`	Dimensão principal do Transformer — todos os tokens têm este tamanho. `512` é o padrão ACT. Aumentar para `768` ou `1024` melhora capacidade mas dobra/triplica uso de VRAM.
`n_heads`	`int`	Número de cabeças de atenção no multi-head attention. Deve dividir `dim_model` exatamente (`512 / 8 = 64` dims por cabeça).
`dim_feedforward`	`int`	Dimensão da camada feed-forward dentro de cada bloco do Transformer. `3200 ≈ 6.25 × dim_model`. Segue a proporção padrão do ACT original.
`n_encoder_layers`	`int`	Número de camadas do ACTEncoder. `4` é o padrão. Aumentar melhora a integração entre tokens (RGB ↔ depth ↔ state) mas aumenta custo.
`n_decoder_layers`	`int`	Número de camadas do ACTDecoder. Fixo em `1` por compatibilidade com a implementação original do ACT (ver issue #25 do repositório tonyzhaozh/act).
`use_vae`	`bool`	Habilita o objetivo variacional. `true` → o encoder VAE estima `mu` e `log_sigma`, o loss inclui KL divergence. `false` → o modelo vira um transformer puro sem regularização latente. Manter `true`.
`latent_dim`	`int`	Dimensão do espaço latente do VAE. `32` é suficiente para capturar variabilidade de estilo de execução entre episódios.
`n_vae_encoder_layers`	`int`	Número de camadas do encoder VAE (separado do encoder principal). `4` é o padrão.

7. Backbone visual

vision_backbone: resnet18
pretrained_backbone_weights: ResNet18_Weights.IMAGENET1K_V1

Parâmetro	Tipo	Descrição
`vision_backbone`	`str`	Arquitetura ResNet usada para extrair features das imagens RGB. `resnet18` gera features de 512 canais. `resnet34` também gera 512. `resnet50`/`resnet101` geram 2048 (requer ajuste interno).
`pretrained_backbone_weights`	`str \| null`	Pesos pré-treinados do torchvision para inicializar o backbone. `ResNet18_Weights.IMAGENET1K_V1` parte de ImageNet — acelera convergência das features visuais. `null` inicializa aleatoriamente (não recomendado).

O backbone treina com lr = optimizer_lr_backbone (igual ao optimizer_lr por padrão). As camadas BatchNorm ficam congeladas via FrozenBatchNorm2d para evitar que batchs pequenos corrompam as estatísticas de normalização.

8. Configurações de treinamento

output_dir: "train_output/pick_up_the_cup_depth-260512"
steps: 100000
batch_size: 128
num_workers: 10
log_freq: 25
save_freq: 10000
save_checkpoint: false
save_best_checkpoint: true

Parâmetro	Tipo	Descrição
`output_dir`	`str`	Diretório raiz onde checkpoints, logs e metadados são salvos. Recomendado incluir a data no nome para não sobrescrever runs anteriores.
`steps`	`int`	Total de steps de gradiente do treino. `100000` steps com `batch_size=128` e ~4800 frames de treino equivale a aproximadamente 2600 épocas.
`batch_size`	`int`	Número de amostras por step de gradiente. `128` é o máximo viável em ~16GB VRAM com `use_amp: true`. Reduzir se der OOM.
`num_workers`	`int`	Processos paralelos do DataLoader para carregar e decodificar frames. `10` é adequado para SSDs rápidos. Reduzir se o sistema travar por falta de RAM.
`log_freq`	`int`	A cada quantos steps loga métricas no terminal e no WandB. `25` significa log a cada 25 steps.
`save_freq`	`int`	A cada quantos steps salva um checkpoint periódico em `output_dir/checkpoints/step_XXXXX/`. Só ativo se `save_checkpoint: true`.
`save_checkpoint`	`bool`	Habilita checkpoints periódicos em `save_freq`. `false` economiza espaço em disco durante experimentos — o best checkpoint ainda é salvo independentemente.
`save_best_checkpoint`	`bool`	Salva automaticamente em `output_dir/best_val_checkpoint/` sempre que o `val_loss` bater o recorde histórico. Um arquivo `best_val_meta.txt` registra o step e o valor. Recomendado manter `true` — é o checkpoint mais útil para deploy.

9. Curriculum de posição neutra

neutral_position_loss_weight: 0.3

Parâmetro	Tipo	Descrição
`neutral_position_loss_weight`	`float`	A cada 50 steps, injeta um batch sintético onde o estado de entrada é a posição neutra do robô e a ação correta é permanecer nela. O loss desse batch é multiplicado por esse peso e somado ao loss principal. `0.3` = 30% do loss normal. `0.0` desativa o curriculum.

Efeito prático: Ensina o modelo que "quando não sei o que fazer, fico parado" — reduz movimentos explosivos no início do deploy ou em situações fora da distribuição de treino.

Usar 0.0 durante os primeiros treinos para isolar o efeito do depth. Ativar (0.3) depois que o treino base estiver convergindo.

10. Avaliação e logs

eval_freq: 50
 
wandb:
  enable: true
  project: prometheus_g1

Parâmetro	Tipo	Descrição
`eval_freq`	`int`	A cada quantos steps roda a validação no `val_dataset`. `50` significa validação frequente — útil para detectar overfitting cedo. Aumentar para `200`-`500` se a validação estiver lenta.
`wandb.enable`	`bool`	Liga o logging no Weights & Biases. `false` para rodar offline ou sem conta WandB.
`wandb.project`	`str`	Nome do projeto no WandB onde a run aparece. Todas as runs do Prometheus ficam agrupadas em `prometheus_g1`.

Métricas logadas:

Métrica	Descrição
`loss`	Loss total do step: `l1_loss + kl_weight × kld_loss` + curriculum se ativo.
`l1_loss`	Erro L1 entre ações preditas e reais — métrica principal de qualidade.
`kld_loss`	Divergência KL do VAE — mede quão bem o espaço latente está sendo regularizado.
`val_loss`	Loss de validação — principal indicador de generalização.
`grdn`	Norma do gradiente — valores consistentemente altos (>100) indicam instabilidade.
`lr`	Learning rate atual.

11. Comportamento do Ctrl+C

O run_train.py intercepta o sinal de interrupção:

Ação	Resultado
Ctrl+C uma vez	Finaliza o step atual, salva estado em `output_dir/emergency_checkpoint/`, encerra limpo.
Ctrl+C duas vezes	Encerra imediatamente sem salvar.

12. Estrutura de checkpoints gerados

output_dir/
├── best_val_checkpoint/        ← melhor val_loss (salvo automaticamente)
│   ├── policy/                 ← pesos da política
│   └── best_val_meta.txt       ← step e valor do recorde
├── emergency_checkpoint/       ← salvo no Ctrl+C
│   └── policy/
└── checkpoints/
    └── step_XXXXX/             ← checkpoints periódicos (se save_checkpoint: true)
        └── policy/

13. Referência rápida — flags para experimentos

Objetivo	O que mudar
Treinar sem depth	`use_depth_3d: false` + comentar `head_camera_depth` nos `input_features`
Treinar sem pressão	`use_pressure: false` + comentar as features de pressão nos `input_features`
Treinar sem VAE	`use_vae: false` (remove KL loss, modelo vira transformer puro)
Reduzir VRAM	Reduzir `batch_size` ou `pointnet_num_points`
Deploy com gate de segurança	`scene_uncertainty_threshold: 0.5` no YAML de inferência
Ativar curriculum de neutro	`neutral_position_loss_weight: 0.3`
Desativar augmentação	`image_transforms.enable: false`

SUMARIO

Introdução

Ambiente

SSH Cliente e start-server

Navigation Menu

Uh oh!

Train ACT Depth

ACT-D — Guia de Configuração de Treinamento

1. Dataset de treinamento (`dataset`)

Augmentação de imagem (`image_transforms`)

2. Dataset de validação (`val_dataset`)

3. Política (`policy`)

Identificação

Features de entrada e saída

Parâmetros de chunk e observação

4. Módulos ACT-D exclusivos

Depth 3D — PointNet

Percepção tátil — Pressão

Scene Uncertainty Gate

5. Anti-overfitting

6. Arquitetura Transformer

7. Backbone visual

8. Configurações de treinamento

9. Curriculum de posição neutra

10. Avaliação e logs

11. Comportamento do Ctrl+C

12. Estrutura de checkpoints gerados

13. Referência rápida — flags para experimentos

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SUMARIO

Clone this wiki locally

Uh oh!

Train ACT Depth

ACT-D — Guia de Configuração de Treinamento

1. Dataset de treinamento (dataset)

Augmentação de imagem (image_transforms)

2. Dataset de validação (val_dataset)

3. Política (policy)

Identificação

Features de entrada e saída

Parâmetros de chunk e observação

4. Módulos ACT-D exclusivos

Depth 3D — PointNet

Percepção tátil — Pressão

Scene Uncertainty Gate

5. Anti-overfitting

6. Arquitetura Transformer

7. Backbone visual

8. Configurações de treinamento

9. Curriculum de posição neutra

10. Avaliação e logs

11. Comportamento do Ctrl+C

12. Estrutura de checkpoints gerados

13. Referência rápida — flags para experimentos

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SUMARIO

Clone this wiki locally

1. Dataset de treinamento (`dataset`)

Augmentação de imagem (`image_transforms`)

2. Dataset de validação (`val_dataset`)

3. Política (`policy`)