# Renomear Map e Empty Cameras

Ao treinar, avaliar ou gravar com uma política de robô, seu **conjunto de dados** ou **ambiente** fornece observações sob um conjunto de chaves (por exemplo, `observation.images.front`, `observation.images.eagle`), enquanto sua **política** espera outro (por exemplo, `observation.images.image`, `observation.images.image2`). O **mapa de renomeação** preenche essa lacuna sem alterar a política ou a fonte de dados.

> **Escopo:** O mapa de renomeação renomeia apenas as chaves de **observation** (imagens e estado). As chaves de ação não são afetadas.

## Por que as chaves de observação nem sempre correspondem

As políticas possuem um conjunto fixo de **nomes de recursos de entrada** incorporados à sua configuração pré-treinada. Por exemplo:

- [pi0fast-libero](https://huggingface.co/lerobot/pi0fast-libero) espera `observation.images.base_0_rgb` e `observation.images.left_wrist_0_rgb`.
- [xvla-base](https://huggingface.co/lerobot/xvla-base) espera `observation.images.image`, `observation.images.image2` e `observation.images.image3`.

Seu conjunto de dados pode usar nomes completamente diferentes (por exemplo, `observation.images.front`, `observation.images.eagle`, `observation.images.glove`), e seu ambiente de avaliação pode usar outro conjunto. Em vez de editar a configuração da política ou renomear colunas no conjunto de dados, você passa um **mapa de renomeação**: um dicionário JSON que mapeia as chaves de origem para as chaves que a política espera. O renomeamento ocorre dentro do pipeline do pré-processador, para que a política sempre veja as chaves esperadas.

## Usando o mapa de renomeação

Passe o mapeamento como uma string JSON na linha de comando. A convenção é sempre:

```
--rename_map='{"source_key": "policy_key", ...}'
```

onde **source_key** é o que o conjunto de dados ou o ambiente fornece, e **policy_key** é o que a política espera.

Apenas as chaves listadas são renomeadas; tudo o mais passa inalterado. A ordem das entradas não importa.

Políticas suportadas: **PI0**, **PI05**, **PI0Fast**, **SmolVLA** e **XVLA**.

### Treinamento

Suponha que você faça o ajuste fino de [lerobot/xvla-base](https://huggingface.co/lerobot/xvla-base) em um conjunto de dados com imagens sob `observation.images.front`, `observation.images.eagle` e `observation.images.glove`. O XVLA espera `observation.images.image`, `observation.images.image2` e `observation.images.image3`:

```bash
lerobot-train \
  --dataset.repo_id=YOUR_DATASET \
  --output_dir=./outputs/xvla_training \
  --job_name=xvla_training \
  --policy.path="lerobot/xvla-base" \
  --policy.repo_id="HF_USER/xvla-your-robot" \
  --policy.dtype=bfloat16 \
  --policy.action_mode=auto \
  --steps=20000 \
  --policy.device=cuda \
  --policy.freeze_vision_encoder=false \
  --policy.freeze_language_encoder=false \
  --policy.train_policy_transformer=true \
  --policy.train_soft_prompts=true \
  --rename_map='{"observation.images.front": "observation.images.image", "observation.images.eagle": "observation.images.image2", "observation.images.glove": "observation.images.image3"}'
```

### Avaliação

Uma política que espera `observation.images.base_0_rgb` e `observation.images.left_wrist_0_rgb` (por exemplo, [pi0fast-libero](https://huggingface.co/lerobot/pi0fast-libero)), mas o ambiente LIBERO retorna `observation.images.image` e `observation.images.image2`:

```bash
lerobot-eval \
  --policy.path=lerobot/pi0fast-libero \
  --env.type=libero \
  ... \
  --rename_map='{"observation.images.image": "observation.images.base_0_rgb", "observation.images.image2": "observation.images.left_wrist_0_rgb"}'
```

## Alternativa: edite a configuração da política diretamente

Se você sempre usa o mesmo conjunto de dados ou ambiente, pode **editar o `config.json` da política** para que as chaves de observação correspondam à sua fonte de dados. Assim, nenhum mapa de renomeação é necessário.

A compensação: modificar a configuração da política a vincula a uma única fonte de dados. Um mapa de renomeação mantém uma única política utilizável em muitos conjuntos de dados e ambientes.

## Câmeras vazias: menos visualizações do que a política espera

Algumas políticas são construídas para um número fixo de entradas de imagem. Se o seu conjunto de dados tiver menos câmeras, você pode definir **`empty_cameras`** na configuração da política em vez de modificar a arquitetura do modelo.

### Como funciona

Definir `empty_cameras=N` adiciona N recursos de imagem de preenchimento à configuração da política, nomeados:

```
observation.images.empty_camera_0
observation.images.empty_camera_1
...
```

Em tempo de execução, essas chaves não possuem dados correspondentes no lote. A política as preenche com tensores fictícios mascarados (preenchidos com `-1` para codificadores de visão baseados em SigLIP, com uma máscara de atenção nula), de modo que os slots de imagem extras são efetivamente ignorados durante o treinamento e a inferência.

### Exemplo

O XVLA-base possui três entradas visuais e `empty_cameras=0` por padrão. Seu conjunto de dados tem apenas duas câmeras:

1. Defina `--policy.empty_cameras=1`.
2. A configuração adiciona uma terceira chave: `observation.images.empty_camera_0`.
3. Use o mapa de renomeação para suas duas câmeras reais como de costume.
4. O terceiro slot é mascarado — nenhuma imagem falsa é necessária no seu conjunto de dados.

## Referência rápida

| Objetivo                                    | O que fazer                                                                  |
| --------------------------------------- | --------------------------------------------------------------------------- |
| Chaves do dataset ≠ chaves da política              | `--rename_map='{"dataset_key": "policy_key", ...}'`                         |
| Chaves de Env ≠ chaves de policy (avaliação)           | `--rename_map='{"env_key": "policy_key", ...}'`                             |
| Rollout com chaves diferentes (inferência) | `--rename_map='{"source_key": "policy_key", ...}'`.                         |
| Menos câmeras do que a política espera       | `--policy.empty_cameras=N` (suportado por PI0, PI05, PI0Fast, SmolVLA, XVLA) |
| Evite passar um mapa de renomeação              | Edite o `config.json` da policy para que suas chaves correspondam à sua fonte de dados          |

