Renombrar Map y Empty Cameras

Cuando entrenas, evalúas o registras con una política de robot, tu conjunto de datos o entorno proporciona observaciones bajo un conjunto de claves (p. ej. observation.images.front, observation.images.eagle), mientras que tu política espera otro (p. ej. observation.images.image, observation.images.image2). El mapa de renombrado cubre esa brecha sin modificar la política ni la fuente de datos.

Alcance: El mapa de renombrado solo renombra las claves de observation (imágenes y estado). Las claves de acción no se ven afectadas.

Por qué las claves de observación no siempre coinciden

Las políticas tienen un conjunto fijo de nombres de características de entrada incorporado en su configuración preentrenada. Por ejemplo:

• pi0fast-libero espera observation.images.base_0_rgb y observation.images.left_wrist_0_rgb.
• xvla-base espera observation.images.image, observation.images.image2 y observation.images.image3.

Es posible que su conjunto de datos use nombres completamente distintos (p. ej. observation.images.front, observation.images.eagle, observation.images.glove) y que su entorno de evaluación use otro conjunto. En lugar de editar la configuración de la política o renombrar columnas en el conjunto de datos, pasa un mapa de renombrado: un diccionario JSON que mapea las claves de origen a las claves que la política espera. El renombrado ocurre dentro del pipeline del preprocesador, por lo que la política siempre ve sus claves esperadas.

Usando el mapa de renombrado

Pase el mapeo como una cadena JSON en la línea de comandos. La convención es siempre:

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

donde source_key es lo que proporciona el conjunto de datos o el entorno, y policy_key es lo que espera la política.

Solo se renombran las claves enumeradas; todo lo demás se mantiene sin cambios. El orden de las entradas no importa.

Políticas admitidas: PI0, PI05, PI0Fast, SmolVLA y XVLA.

Entrenamiento

Supongamos que ajustas lerobot/xvla-base en un conjunto de datos con imágenes bajo observation.images.front, observation.images.eagle y observation.images.glove. XVLA espera observation.images.image, observation.images.image2 y 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"}'

Evaluación

Una política que espera observation.images.base_0_rgb y observation.images.left_wrist_0_rgb (p. ej. pi0fast-libero), pero el entorno LIBERO devuelve observation.images.image y 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"}'

Alternativa: editar la configuración de la política directamente

Si siempre usas el mismo conjunto de datos o entorno, puedes editar el config.json de la política para que sus claves de observación coincidan con tu fuente de datos. Entonces no se necesita un mapa de renombrado.

La desventaja: modificar la configuración de la política la vincula a una única fuente de datos. Un mapa de renombrado mantiene una sola política utilizable en muchos conjuntos de datos y entornos.

Cámaras vacías: menos vistas de las que espera la política

Algunas políticas están diseñadas para un número fijo de entradas de imagen. Si tu conjunto de datos tiene menos cámaras, puedes establecer empty_cameras en la configuración de la política en lugar de modificar la arquitectura del modelo.

Cómo funciona

Establecer empty_cameras=N añade N características de imagen de marcador de posición a la configuración de la política, denominadas:

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

En tiempo de ejecución, estas claves no tienen datos correspondientes en el lote. La política las rellena con tensores ficticios enmascarados (rellenados con -1 para codificadores visuales basados en SigLIP, con una máscara de atención cero), de modo que los espacios de imagen adicionales se ignoran efectivamente durante el entrenamiento y la inferencia.

Ejemplo

XVLA-base tiene tres entradas visuales y empty_cameras=0 de forma predeterminada. Su conjunto de datos solo tiene dos cámaras:

1. Establezca --policy.empty_cameras=1.
2. La configuración añade una tercera clave: observation.images.empty_camera_0.
3. Usa el mapa de renombrado para tus dos cámaras reales como de costumbre.
4. El tercer hueco está enmascarado: no se necesitan imágenes falsas en su conjunto de datos.

Referencia rápida