# X-VLA: El primer modelo de base para robots con soft prompts para cualquier robot y cualquier tarea

## Resumen

Durante años, la robótica ha aspirado a construir agentes que puedan seguir instrucciones humanas naturales y operar con destreza en múltiples entornos y cuerpos robóticos. Los avances recientes en LLMs y VLMs sugieren un camino a seguir: extender estas arquitecturas de modelos de base al control encarnado, anclándolas en acciones. Esto ha dado lugar al auge de los modelos Vision-Language-Action (VLA), con la esperanza de que un único modelo generalista pueda combinar una amplia comprensión semántica con habilidades de manipulación robustas.

Pero entrenar estos modelos es difícil. Los datos de robots están fragmentados entre plataformas, sensores, configuraciones corporales y protocolos de recopilación. La heterogeneidad aparece en todas partes: diferentes configuraciones de brazos, diferentes espacios de acción, diferentes configuraciones de cámaras, diferentes dominios visuales y diferentes distribuciones de tareas. Estas inconsistencias generan grandes cambios de distribución que hacen que el preentrenamiento sea inestable y la adaptación, poco fiable.

Inspirados en el meta-aprendizaje y el aprendizaje de prompts, nos preguntamos: **"¿Y si un modelo VLA pudiera aprender la estructura de cada robot y conjunto de datos de la misma manera en que los LLMs aprenden tareas, a través de prompts?"**

**X-VLA** es un marco VLA con soft prompts y flow matching que trata cada configuración de hardware como una "tarea" y la codifica mediante un pequeño conjunto de embeddings aprendibles. Estos **Soft Prompts** capturan las variaciones de encarnación y específicas del dominio, guiando al Transformer desde las primeras etapas de la fusión multimodal. Con este mecanismo, X-VLA puede armonizar diversas morfologías de robots, tipos de datos y configuraciones de sensores dentro de una única arquitectura unificada.

  <img
    src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/xvla-architecture.png"
    alt="XVLA Architecture"
    style="max-width: 100%; height: auto; width: 800px;"
  />

Construido a partir de codificadores Transformer puros, X-VLA escala de forma natural con el tamaño del modelo y la diversidad del conjunto de datos. En 6 benchmarks de simulación y 3 robots reales, Soft Prompts supera consistentemente a los métodos existentes en el manejo de las diferencias de hardware y de dominio. X-VLA-0.9B, entrenado con 290K episodios que abarcan siete plataformas robóticas, aprende una política generalista agnóstica al encarnamiento en la Fase I, y se adapta eficientemente a nuevos robots en la Fase II simplemente aprendiendo un nuevo conjunto de prompts, mientras mantiene el backbone congelado.

  <img
    src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/xvla-architecture2.png"
    alt="XVLA Architecture 2"
    style="width: 60%; height: auto;"
  />

Con solo el 1% de los parámetros ajustados (9M), X-VLA-0.9B logra un rendimiento cercano al de π₀ en LIBERO y Simpler-WidowX, a pesar de utilizar **300 veces menos parámetros entrenables**. También demuestra una gran destreza en el mundo real con demostraciones mínimas, incluyendo doblar telas en menos de dos minutos.

  <img
    src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/xvla-fold.png"
    alt="XVLA fold visualization"
    style="width: 95%; max-width: 1100px; height: auto;"
  />

X-VLA demuestra que la inteligencia robótica generalista no requiere arquitecturas cada vez más complejas, sino la forma adecuada de absorber la heterogeneidad. Soft Prompts ofrecen un mecanismo simple y escalable para unificar datos robóticos diversos, allanando el camino hacia modelos de base robóticos adaptables y de encarnación cruzada.

## Instalación

Después de instalar LeRobot, instala las dependencias de X-VLA:

```bash
pip install -e ".[xvla]"
```

Si instalaste LeRobot desde PyPI en su lugar:

```bash
pip install 'lerobot[xvla]'
```

## Inicio rápido

### Uso básico

Para usar X-VLA en tu configuración de LeRobot, especifica el tipo de política como:

```bash
policy.type=xvla
```

### Evaluación de puntos de control preentrenados

Ejemplo de evaluación con LIBERO:

```bash
lerobot-eval \
  --policy.path="lerobot/xvla-libero" \
  --env.type=libero \
  --env.task=libero_spatial,libero_goal,libero_10 \
  --env.control_mode=absolute \
  --eval.batch_size=1 \
  --eval.n_episodes=1 \
  --env.episode_length=800 \
  --seed=142
```

## Puntos de control disponibles

### 🎯 Modelo base

**[lerobot/xvla-base](https://huggingface.co/lerobot/xvla-base)**

Una instancia de X-VLA con 0.9B de parámetros, entrenada con una receta de procesamiento de datos y aprendizaje cuidadosamente diseñada. El pipeline de entrenamiento consta de dos fases:

- **Fase I: Preentrenamiento** - Preentrenado con 290K episodios de Droid, Robomind y Agibot, que abarcan siete plataformas en cinco tipos de brazos robóticos (desde configuraciones de un solo brazo hasta bimanuales). Al aprovechar prompts suaves para absorber las variaciones específicas de cada encarnación, el modelo aprende una política generalista agnóstica a la encarnación.

- **Fase II: Adaptación de dominio** - Adaptado a políticas desplegables para dominios objetivo. Se introduce y optimiza un nuevo conjunto de soft prompts para codificar la configuración de hardware del dominio novel, mientras que el backbone preentrenado permanece congelado.

### Puntos de control de simulación

**[lerobot/xvla-libero](https://huggingface.co/lerobot/xvla-libero)**

Alcanza una tasa de éxito del 93% en los benchmarks de LIBERO. Ajustado a partir del modelo base para tareas de simulación.

**[lerobot/xvla-widowx](https://huggingface.co/lerobot/xvla-widowx)**

Ajustado con BridgeData para experimentos de recogida y colocación en plataformas compactas WidowX. Demuestra capacidades de manipulación robustas.

### 🤖 Puntos de control en el mundo real

**[lerobot/xvla-folding](https://huggingface.co/lerobot/xvla-folding)**

Un modelo de manipulación diestra afinado, entrenado en el conjunto de datos de alto calidad Soft-FOLD para doblar telas. Alcanza una tasa de éxito del 100% durante 2 horas de plegado continuo de telas.

**[lerobot/xvla-agibot-world](https://huggingface.co/lerobot/xvla-agibot-world)**

Optimizado para tareas de manipulación hábil de robots AgileX.

**[lerobot/xvla-google-robot](https://huggingface.co/lerobot/xvla-google-robot)**

Adaptado para plataformas de robots de Google.

## Entrenamiento de X-VLA

### Configuración de entrenamiento recomendada

Al realizar el ajuste fino de X-VLA para una nueva encarnación o tarea, recomendamos no congelar el VLM y también establecer `policy.dtype=bfloat16` para evitar errores de OOM.

```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
```

### Parámetros de entrenamiento explicados

| Parámetro                  | Predeterminado | Descripción                                    |
| -------------------------- | ------- | ---------------------------------------------- |
| `freeze_vision_encoder`    | `false` | No congeles los pesos del codificador de visión del VLM   |
| `freeze_language_encoder`  | `false` | No congeles los pesos del codificador de lenguaje del VLM |
| `train_policy_transformer` | `true`  | Permitir que las capas del transformador de política se entrenen       |
| `train_soft_prompts`       | `true`  | Permitir que los soft prompts se entrenen                    |

**💡 Buena práctica**: Para la adaptación de la Fase II a nuevas encarnaciones, no congeles los codificadores del VLM y entrena también el transformador de la política y los soft prompts.

### Ejemplo: Entrenamiento en un robot bimanual

```bash
lerobot-train \
  --dataset.repo_id=<USER>/bimanual-so100-handover-cube \
  --output_dir=./outputs/xvla_bimanual \
  --job_name=xvla_so101_training \
  --policy.path="lerobot/xvla-base" \
  --policy.dtype=bfloat16 \
  --policy.repo_id="YOUR_USERNAME/xvla-biso101" \
  --steps=3000 \
  --policy.device=cuda \
  --policy.action_mode=so101_bimanual \
  --policy.freeze_vision_encoder=false \
  --policy.freeze_language_encoder=false \
  --policy.train_policy_transformer=true \
  --policy.train_soft_prompts=true
```

💡 **Mejor rendimiento:** Si dispone de recursos computacionales suficientes y desea lograr el mejor rendimiento en el ajuste fino de X-VLA, debe seguir la estrategia oficial de ajuste fino:

**🔥 Ajuste fino completo de todos los componentes con un esquema de tasa de aprendizaje personalizado**

Para garantizar una optimización estable, el modelo de visión-lenguaje (VLM) debe entrenarse con solo 1/10 de la tasa de aprendizaje base, mientras que todos los demás componentes utilizan la tasa de aprendizaje completa. Esta proporción de tasa de aprendizaje es crucial para lograr un rendimiento de ajuste fino sólido y estable. Esto ya se hace de forma predeterminada. ❕Nota

Coincidir por completo con el rendimiento oficial reportado puede requerir un programa de calentamiento adicional para la tasa de aprendizaje de los soft-prompts, lo cual puede aportar mejoras menores. Animamos a implementar esto en su pipeline de entrenamiento personalizado para obtener resultados óptimos.

## Conceptos principales

### 1. Modos de acción

X-VLA utiliza un sistema de **Action Registry** para manejar diferentes espacios de acciones y encarnaciones. El parámetro `action_mode` define cómo se procesan las acciones, qué funciones de pérdida se utilizan y cómo se procesan las predicciones de forma posterior.

#### Modos de acción disponibles

| Modo de acción      | Dimensión de acción              | Descripción                                 | Caso de uso                             |
| ---------------- | ----------------------- | ------------------------------------------- | ------------------------------------ |
| `ee6d`           | 20                      | Efector final con xyz, rotación 6D, pinza | Configuraciones de doble brazo con control espacial |
| `joint`          | 14                      | Espacio conjunto con pinza                    | Robots con control conjunto directo          |
| `agibot_ee6d`    | 20                      | Variante de AGI-bot con pérdida MSE               | Plataformas de bots AGI                    |
| `so101_bimanual` | 20 (modelo), 12 (real)   | Robot bimanual SO101                        | Tareas de manipulación bimanual          |
| `auto`           | 20 (modelo), auto (real) | Detecta automáticamente la dimensión de la acción desde el conjunto de datos        | **Recomendado** para nuevos robots       |

#### Por qué son importantes los modos de acción

Cuando tienes un punto de control preentrenado como `lerobot/xvla-base` entrenado con `action_dim=20` y quieres entrenar en un conjunto de datos con una dimensión de acción diferente (p. ej., 14 para brazos bimanuales), no puedes simplemente recortar la dimensión de acción. El modo de acción orquesta:

1. **Cálculo de la pérdida**: Diferentes funciones de pérdida para diferentes componentes de la acción (MSE para articulaciones, BCE para pinzas, etc.)
2. **Preprocesamiento**: Poner a cero los canales de la pinza, rellenar las dimensiones
3. **Postprocesamiento**: Aplicar sigmoid a los logits de la pinza, recortar el padding

#### Ejemplo: Espacio de acciones de BimanualSO101

El modo de acción `so101_bimanual` gestiona la discrepancia entre la salida del modelo (20D) y el control del robot real (12D):

```python
# Model outputs 20 dimensions for compatibility
dim_action = 20

# Real robot only needs 12 dimensions
# [left_arm (6), right_arm (6)] = [joints (5) + gripper (1)] × 2
REAL_DIM = 12

# Preprocessing: Pad 12D actions to 20D for training
# Postprocessing: Trim 20D predictions to 12D for deployment
```

Consulte la implementación de [action_hub.py](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/xvla/action_hub.py) para obtener más detalles.

#### Modo de acción automática (recomendado)

El modo de acción `auto` es la forma más sencilla de usar X-VLA con cualquier robot. Detecta automáticamente la dimensión de acción de tu conjunto de datos y gestiona el relleno/recorte:

```bash
lerobot-train \
  --policy.path="lerobot/xvla-base" \
  --policy.action_mode=auto \
  --policy.max_action_dim=20 \
  ...
```

**Cómo funciona:**

- Lee `action_feature.shape[-1]` de tu conjunto de datos (p. ej., 7 para Franka)
- Las salidas del modelo `max_action_dim` (predeterminado 20) para compatibilidad con modelos preentrenados
- La pérdida se calcula **solo en las dimensiones reales**: `MSE(pred[:,:,:real_dim], target[:,:,:real_dim])`
- Postprocess recorta la salida a `real_dim` para el control del robot

Esto elimina la necesidad de crear modos de acción personalizados para la mayoría de los robots.

### 2. IDs de dominio

Los IDs de dominio son identificadores aprendibles para diferentes configuraciones de robots y configuraciones de cámaras. Permiten a X-VLA distinguir entre:

- Diferentes robots (Robot 1 vs Robot 2)
- Diferentes configuraciones de cámara (cam1 vs cam2)
- Diferentes combinaciones (Robot1-cam1-cam2 vs Robot1-cam1 vs Robot2-cam1)

#### Configuración de los ID de dominio

**Durante el entrenamiento**: Por defecto, domain_id se establece en 0 para el entrenamiento general.

**Durante la evaluación**: especifique el domain_id que coincida con la configuración de entrenamiento de su checkpoint.

```python
# Example: LIBERO checkpoint uses domain_id=3
domain_id = 3
```

El `domain_id` se añade automáticamente a las observaciones mediante el `XVLAAddDomainIdProcessorStep` en el pipeline de preprocesamiento.

El modelo `lerobot/xvla-base` se ha entrenado con los siguientes identificadores de dominio. Se recomienda elegir el que más se asemeje a su robot/configuración:

#### Conjuntos de datos para el ajuste fino

| Nombre del conjunto de datos     | ID de dominio |
| ---------------- | --------- |
| Puente           | 0         |
| RT1              | 1         |
| Calvin           | 2         |
| libero           | 3         |
| widowx-air       | 4         |
| AIR-AGILEX-HQ    | 5         |
| robotwin2_abs_ee | 6         |
| robotwin2_clean  | 6         |
| robocasa-human   | 7         |
| VLABench         | 8         |
| AGIBOT-challenge | 9         |
| AIR-AGILEX       | 10        |
| AIRBOT           | 18        |

### 3. Pasos del procesador

X-VLA requiere pasos específicos de preprocesamiento y posprocesamiento para un funcionamiento adecuado.

#### Pasos de preprocesamiento requeridos

1. **XVLAImageToFloatProcessorStep**: Convierte las imágenes del rango [0, 255] al rango [0, 1]
2. **XVLAImageNetNormalizeProcessorStep**: Aplica la normalización de ImageNet (necesaria para el backbone de VLM)
3. **XVLAAddDomainIdProcessorStep**: Añade domain_id a las observaciones

#### Ejemplo de procesador personalizado

Para los entornos LIBERO, un procesador personalizado convierte la observación canónica en la entrada con la que se entrenó X-VLA:

```python
from lerobot.policies.xvla.processor_xvla import LiberoProcessorStep

processor = LiberoProcessorStep()
# Builds the 9D state from the canonical 8D state, with the end-effector rotation in 6D
# Rotates the wrist camera back, since the LIBERO integration rotates every camera by 180°
```

### 4. Parámetros de configuración

Parámetros de configuración clave para X-VLA:

```python
# Observation and action
n_obs_steps: int = 1          # Number of observation timesteps
chunk_size: int = 32           # Action sequence length
n_action_steps: int = 32       # Number of action steps to execute

# Model architecture
hidden_size: int = 1024        # Transformer hidden dimension
depth: int = 24                # Number of transformer layers
num_heads: int = 16            # Number of attention heads
num_domains: int = 30          # Maximum number of domain IDs
len_soft_prompts: int = 32     # Length of soft prompt embeddings

# Action space
action_mode: str = "ee6d"      # Action space type (use "auto" for auto-detection)
use_proprio: bool = True       # Use proprioceptive state
max_state_dim: int = 32        # Maximum state dimension
max_action_dim: int = 20       # Max action dim for padding (used by "auto" mode)

# Vision
num_image_views: int | None    # Number of camera views
resize_imgs_with_padding: tuple[int, int] | None  # Target image size with padding

# Training
num_denoising_steps: int = 10  # Flow matching denoising steps
```

## Creación de modos de acción personalizados

Si tu robot tiene un espacio de acciones único, puedes crear un modo de acción personalizado:

### Paso 1: Defina su espacio de acciones

```python
from lerobot.policies.xvla.action_hub import BaseActionSpace, register_action
import torch
import torch.nn as nn

@register_action("my_custom_robot")
class MyCustomActionSpace(BaseActionSpace):
    """Custom action space for my robot."""

    dim_action = 15  # Your robot's action dimension
    gripper_idx = (7, 14)  # Gripper channel indices

    def __init__(self):
        super().__init__()
        self.mse = nn.MSELoss()
        self.bce = nn.BCEWithLogitsLoss()

    def compute_loss(self, pred, target):
        """Define your loss computation."""
        # Example: MSE for joints, BCE for grippers
        joints_loss = self.mse(pred[:, :, :7], target[:, :, :7])
        gripper_loss = self.bce(pred[:, :, self.gripper_idx],
                                target[:, :, self.gripper_idx])

        return {
            "joints_loss": joints_loss,
            "gripper_loss": gripper_loss,
        }

    def preprocess(self, proprio, action, mode="train"):
        """Preprocess actions before training."""
        # Example: Zero out grippers in proprioception
        proprio_m = proprio.clone()
        action_m = action.clone() if action is not None else None
        proprio_m[..., self.gripper_idx] = 0.0
        if action_m is not None:
            action_m[..., self.gripper_idx] = 0.0
        return proprio_m, action_m

    def postprocess(self, action):
        """Post-process predictions for deployment."""
        # Example: Apply sigmoid to gripper logits
        action[..., self.gripper_idx] = torch.sigmoid(action[..., self.gripper_idx])
        return action
```

### Paso 2: Use su modo de acción personalizado

```bash
lerobot-train \
  --policy.action_mode=my_custom_robot \
  --dataset.repo_id=YOUR_DATASET \
  --policy.path="lerobot/xvla-base" \
  ...
```

## Temas avanzados

### Soporte para múltiples cámaras

X-VLA admite múltiples vistas de cámara a través del parámetro `num_image_views`:

```python
# Configure for 3 camera views
policy.num_image_views=3

# Add empty cameras if you have fewer physical cameras
policy.empty_cameras=1  # Adds 1 zero-padded camera view
```

### Pipeline de preprocesamiento personalizado

Crea un pipeline de preprocesamiento personalizado para tu entorno:

```python
from lerobot.processor import PolicyProcessorPipeline
from lerobot.policies.xvla import (
    XVLAImageToFloatProcessorStep,
    XVLAImageNetNormalizeProcessorStep,
    XVLAAddDomainIdProcessorStep,
)

# Build custom pipeline
preprocessor = PolicyProcessorPipeline(
    steps=[
        YourCustomProcessorStep(),  # Your custom processing
        XVLAImageToFloatProcessorStep(),  # Required: convert to float
        XVLAImageNetNormalizeProcessorStep(),  # Required: ImageNet norm
        XVLAAddDomainIdProcessorStep(domain_id=5),  # Your domain ID
    ]
)
```

### Gestión de diferentes dimensiones de acción

Cuando su conjunto de datos tiene menos dimensiones de acción que el modelo preentrenado:

**Opción 1 (recomendada)**: usar el modo de acción `auto`

```bash
# Automatically detects your dataset's action dimension
# Works with any robot without custom code
policy.action_mode=auto
policy.max_action_dim=20  # Match pretrained model
```

**Opción 2**: usar un modo de acción predefinido con relleno integrado

```python
# Model expects 20D, dataset has 12D
# Action mode handles padding internally
action_mode = "so101_bimanual"  # Pads 12 → 20
```

**Opción 2**: Crear un modo de acción personalizado que mapee las dimensiones explícitamente

```python
@register_action("my_mapped_action")
class MappedActionSpace(BaseActionSpace):
    dim_action = 20
    REAL_DIM = 12

    def _pad_to_model_dim(self, x):
        # Custom padding logic
        ...
```

## Solución de problemas

### Problemas comunes

**Problema**: "Desajuste en la dimensión de la acción"

- **Solución**: Compruebe que su `action_mode` coincide con el espacio de acciones de su robot. Cree un modo de acción personalizado si es necesario.

**Problema**: "Valores de imagen fuera del rango [0, 1]"

- **Solución**: Asegúrese de que las imágenes se preprocesen con `XVLAImageToFloatProcessorStep` antes de la normalización.

**Problema**: "Domain ID not found"

- **Solución**: Asegúrate de que `XVLAAddDomainIdProcessorStep` esté en tu pipeline de preprocesamiento con el domain_id correcto.

**Problema**: "Baja tasa de éxito en la nueva encarnación"

- **Solución**:
  1. Verifica que tu action_mode sea correcto
  2. Comprueba que los soft prompts se están entrenando (`train_soft_prompts=True`)
  3. Asegura el preprocesamiento adecuado (normalización de ImageNet, domain_id)
  4. Considere aumentar los pasos de entrenamiento

**Problema**: "Memoria insuficiente durante el entrenamiento"

- **Solución**:
  1. Reduce `chunk_size` (p. ej., de 32 a 16)
  2. Activar el control de puntos de control de gradientes
  3. Reducir el tamaño del lote
  4. Congelar más componentes

## Cita

Si usas X-VLA en tu investigación, por favor cita:

```bibtex
@article{zheng2025x,
  title   = {X-VLA: Soft-Prompted Transformer as Scalable Cross-Embodiment Vision-Language-Action Model},
  author  = {Zheng, Jinliang and Li, Jianxiong and Wang, Zhihao and Liu, Dongxiu and Kang, Xirui
             and Feng, Yuchun and Zheng, Yinan and Zou, Jiayin and Chen, Yilun and Zeng, Jia and others},
  journal = {arXiv preprint arXiv:2510.10274},
  year    = {2025}
}
```

## Recursos adicionales

- [Artículo de X-VLA](https://arxiv.org/pdf/2510.10274)
- [Documentación de LeRobot](https://github.com/huggingface/lerobot)
- [Implementación del registro de acciones](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/xvla/action_hub.py)
- [Implementación del procesador](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/xvla/processor_xvla.py)
- [Configuración del modelo](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/xvla/configuration_xvla.py)

## Contribuir

¡Aceptamos contribuciones! Si has implementado un nuevo modo de acción o procesador para tu robot, considera enviar un PR para ayudar a la comunidad.

