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 s'attend à observation.images.base_0_rgb et observation.images.left_wrist_0_rgb.
• 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 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 :

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), mais l’environnement LIBERO renvoie observation.images.image et observation.images.image2 :

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