# Renommer les cartes et les caméras vides

Lors de l’entraînement, de l’évaluation ou de l’enregistrement avec une politique robotique, votre **jeu de données** ou votre **environnement** fournit des observations sous un ensemble de clés (par exemple `observation.images.front`, `observation.images.eagle`), tandis que votre **politique** en attend un autre (par exemple `observation.images.image`, `observation.images.image2`). La **carte de renommage** comble cet écart sans modifier la politique ni la source de données.

> **Portée :** la carte de renommage ne renomme que les clés **observation** (images et état). Les clés d'action ne sont pas affectées.

## Pourquoi les clés d'observation ne correspondent pas toujours

Les politiques disposent d'un ensemble fixe de **noms de caractéristiques d'entrée** intégré à leur configuration pré-entraînée. Par exemple :

- [pi0fast-libero](https://huggingface.co/lerobot/pi0fast-libero) s'attend à `observation.images.base_0_rgb` et `observation.images.left_wrist_0_rgb`.
- [xvla-base](https://huggingface.co/lerobot/xvla-base) s'attend à `observation.images.image`, `observation.images.image2` et `observation.images.image3`.

Votre jeu de données peut utiliser des noms entièrement différents (par exemple `observation.images.front`, `observation.images.eagle`, `observation.images.glove`), et votre environnement d’évaluation peut en utiliser un autre ensemble. Plutôt que de modifier la configuration de la politique ou de renommer les colonnes du jeu de données, vous passez une **carte de renommage** : un dictionnaire JSON qui associe les clés source aux clés attendues par la politique. Le renommage a lieu à l’intérieur du pipeline de préprocesseur, de sorte que la politique voit toujours les clés qu’elle attend.

## Utilisation de la carte de renommage

Passez le mapping en tant que chaîne JSON sur la ligne de commande. La convention est toujours la suivante :

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

où **source_key** est ce que le jeu de données ou l’environnement fournit, et **policy_key** est ce que la politique attend.

Seules les clés listées sont renommées ; tout le reste passe sans modification. L'ordre des entrées n'a pas d'importance.

Politiques prises en charge : **PI0**, **PI05**, **PI0Fast**, **SmolVLA** et **XVLA**.

### Entraînement

Supposons que vous effectuez un fine-tuning de [lerobot/xvla-base](https://huggingface.co/lerobot/xvla-base) sur un jeu de données contenant des images sous `observation.images.front`, `observation.images.eagle` et `observation.images.glove`. XVLA s'attend à `observation.images.image`, `observation.images.image2` et `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"}'
```

### Évaluation

Une politique qui s’attend à `observation.images.base_0_rgb` et `observation.images.left_wrist_0_rgb` (par exemple [pi0fast-libero](https://huggingface.co/lerobot/pi0fast-libero)), mais l’environnement LIBERO renvoie `observation.images.image` et `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"}'
```

## Alternative : modifier directement la configuration de la politique

Si vous utilisez toujours le même jeu de données ou environnement, vous pouvez **modifier le `config.json` de la politique** afin que ses clés d’observation correspondent à votre source de données. Dans ce cas, aucune carte de renommage n’est nécessaire.

Le compromis : modifier la configuration de la politique la lie à une source de données unique. Une carte de renommage permet de réutiliser une même politique sur de nombreux jeux de données et environnements.

## Caméras vides : moins de vues que prévu par la politique

Certaines politiques sont conçues pour un nombre fixe d'entrées d'images. Si votre jeu de données comporte moins de caméras, vous pouvez définir **`empty_cameras`** dans la configuration de la politique au lieu de modifier l'architecture du modèle.

### Fonctionnement

Définir `empty_cameras=N` ajoute N fonctionnalités d’image de substitution à la configuration de la politique, nommées :

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

À l'exécution, ces clés n'ont pas de données correspondantes dans le lot. La politique les remplit avec des tenseurs factices masqués (remplis avec `-1` pour les encodeurs visuels basés sur SigLIP, avec un masque d'attention nul), de sorte que les emplacements d'image supplémentaires sont effectivement ignorés pendant l'entraînement et l'inférence.

### Exemple

XVLA-base possède trois entrées visuelles et `empty_cameras=0` par défaut. Votre jeu de données ne contient que deux caméras :

1. Définissez `--policy.empty_cameras=1`.
2. La configuration ajoute une troisième clé : `observation.images.empty_camera_0`.
3. Utilisez la carte de renommage pour vos deux caméras réelles comme d’habitude.
4. Le troisième emplacement est masqué — aucune image factice n'est nécessaire dans votre jeu de données.

## Référence rapide

| Objectif                                    | Que faire                                                                  |
| --------------------------------------- | --------------------------------------------------------------------------- |
| Clés du jeu de données ≠ clés de la politique              | `--rename_map='{"dataset_key": "policy_key", ...}'`                         |
| Clés Env ≠ clés de la politique (évaluation)           | `--rename_map='{"env_key": "policy_key", ...}'`                             |
| Rollout avec des clés différentes (inférence) | `--rename_map='{"source_key": "policy_key", ...}'`.                         |
| Moins de caméras que prévu par la politique       | `--policy.empty_cameras=N` (pris en charge par PI0, PI05, PI0Fast, SmolVLA, XVLA) |
| Évitez de passer une carte de renommage              | Modifiez le `config.json` de la politique pour que ses clés correspondent à votre source de données          |