# LIBERO-plus

  The commands below run the simulator locally. To keep its dependencies away from your policy's, serve it instead with `lerobot-env-server --config_path=docker/sim/configs/libero_plus.yaml --sim.task= --docker=true`, where `` is the command's `--env.task`, and add `--env.server.endpoint=tcp/127.0.0.1:7448` to the command. A server runs the task it was started with (see [Simulation: local or served](./simulation)).

LIBERO-plus es un **benchmark de robustez** para modelos Vision-Language-Action (VLA) construido sobre [LIBERO](./libero). Pone a prueba de forma sistemática las políticas aplicando **siete dimensiones de perturbación independientes** al conjunto de tareas original de LIBERO, exponiendo modos de fallo que los benchmarks estándar pasan por alto.

- Artículo: [Análisis en profundidad de la robustez de los modelos de visión-lenguaje-acción](https://arxiv.org/abs/2510.13626)
- GitHub: [sylvestf/LIBERO-plus](https://github.com/sylvestf/LIBERO-plus)
- Conjunto de datos: [lerobot/libero_plus](https://huggingface.co/datasets/lerobot/libero_plus)

![An overview of the LIBERO-plus benchmark perturbation dimensions](https://github.com/sylvestf/LIBERO-plus/raw/main/static/images/libero-plus.jpg)

## Dimensiones de perturbación

LIBERO-plus crea ~10 000 variantes de tareas perturbando cada tarea original de LIBERO a lo largo de estos ejes:

| Dimensión             | Qué cambia                                          |
| --------------------- | ----------------------------------------------------- |
| Distribución de objetos        | Posición objetivo, presencia de objetos confusos      |
| Puntos de vista de la cámara     | Posición, orientación y campo de visión de la cámara           |
| Estados iniciales del robot  | Postura inicial del manipulador                                |
| Instrucciones de idioma | Descripción de la tarea reescrita por un LLM (paráfrasis / sinónimo) |
| Condiciones de luz      | Intensidad, dirección, color, sombra                   |
| Texturas de fondo   | Superficie de la escena y apariencia de los objetos                   |
| Ruido del sensor          | Distorsiones fotométricas y degradación de imagen         |

## Suites de tareas disponibles

LIBERO-plus perturba las 40 tareas originales de las suites Spatial, Object, Goal y Long. Cada tarea registrada en estas cuatro suites es una variante perturbada, en lugar de una de las tareas originales. El fork también conserva las 90 tareas no perturbadas de LIBERO-90.

| Suite          | Nombre de la CLI         | Tareas originales | Tareas registradas | Pasos máximos | Descripción                                       |
| -------------- | ---------------- | -------------- | ---------------- | --------- | ------------------------------------------------- |
| LIBERO-Spatial | `libero_spatial` | 10             | 2,402            | 280       | Tareas que requieren razonamiento sobre relaciones espaciales |
| LIBERO-Object  | `libero_object`  | 10             | 2,518            | 280       | Tareas centradas en la manipulación de diferentes objetos  |
| LIBERO-Goal    | `libero_goal`    | 10             | 2,591            | 300       | Tareas condicionadas por objetivos con metas cambiantes      |
| LIBERO-90      | `libero_90`      | 90             | 90               | 400       | Tareas de LIBERO de horizonte corto no perturbadas            |
| LIBERO-Long    | `libero_10`      | 10             | 2,519            | 520       | Tareas de horizonte largo de la colección LIBERO-100 |

Estas cifras provienen del [registro de tareas](https://github.com/sylvestf/LIBERO-plus/blob/4976dc30028e805ff8094b55501d532c48fec182/libero/libero/benchmark/libero_suite_task_map.py) de la fuente. Los cuatro conjuntos perturbados contienen un total de **10.030 variantes de tareas**; LIBERO-90 no está incluido en ese total. Las cifras y los índices de tareas dependen de la revisión del fork instalado.

  La instalación de LIBERO-plus **sustituye** a LIBERO estándar: desinstala `hf-libero` para que `import libero` se resuelva hacia el fork de LIBERO-plus. No es posible tener ambos instalados al mismo tiempo. Para volver a LIBERO estándar, desinstala el fork y vuelve a instalarlo con `pip install -e ".[libero]"`.

## Instalación

### Dependencias del sistema (solo Linux)

```bash
sudo apt install libexpat1 libfontconfig1-dev libmagickwand-dev
```

### Paquete de Python

```bash
pip install -e ".[libero]" "robosuite==1.4.1" bddl easydict mujoco wand scikit-image gym
git clone https://github.com/sylvestf/LIBERO-plus.git
cd LIBERO-plus && pip install --no-deps -e .
pip uninstall -y hf-libero  # so `import libero` resolves to the fork
```

LIBERO-plus se instala desde su bifurcación de GitHub en lugar de desde un extra de pyproject: la bifurcación se distribuye como un paquete de espacio de nombres que pip no puede gestionar, por lo que debe clonarse y añadirse a `PYTHONPATH`. Consulte la etapa `libero_plus_native` de `docker/Dockerfile.sim` para la instalación canónica. MuJoCo es obligatorio, por lo que solo se admite Linux.

Establece el backend de renderizado de MuJoCo antes de ejecutar la evaluación:

```bash
export MUJOCO_GL=egl   # headless / HPC / cloud
```

### Descargar los recursos de LIBERO-plus

LIBERO-plus distribuye su paquete de recursos extendido por separado. Descargue `assets.zip` desde el [conjunto de datos de Hugging Face](https://huggingface.co/datasets/Sylvest/LIBERO-plus/tree/main) y extráigalo en el directorio del paquete LIBERO-plus:

```bash
# After installing the package, find where it was installed:
python -c "import libero; print(libero.__file__)"
# Then extract assets.zip into <package_root>/libero/assets/
```

## Evaluación

### Evaluación local predeterminada

Evalúe cada variante registrada en los cuatro conjuntos perturbados, utilizando un episodio por variante, tal como se recomienda en la [guía de evaluación de la fuente](https://github.com/sylvestf/LIBERO-plus#-evaluation):

```bash
lerobot-eval \
  --policy.path="your-policy-id" \
  --env.type=libero_plus \
  --env.task=libero_spatial,libero_object,libero_goal,libero_10 \
  --eval.batch_size=1 \
  --eval.n_episodes=1 \
  --env.max_parallel_tasks=1
```

Esto ejecuta **10.030 episodios** para el registro anterior. Con `--eval.n_episodes=10`, el mismo comando ejecuta **100.300 episodios**, no 400.

### Prueba de humo

Antes de lanzar una evaluación completa, compruebe su configuración con una variante registrada y un episodio:

```bash
lerobot-eval \
  --policy.path="your-policy-id" \
  --env.type=libero_plus \
  --env.task=libero_spatial \
  --env.task_ids='[0]' \
  --eval.batch_size=1 \
  --eval.n_episodes=1
```

Esta es una comprobación de configuración, no una evaluación representativa de robustez.

### Evaluación de un solo conjunto

Evaluar en un solo conjunto de LIBERO-plus:

```bash
lerobot-eval \
  --policy.path="your-policy-id" \
  --env.type=libero_plus \
  --env.task=libero_spatial \
  --eval.batch_size=1 \
  --eval.n_episodes=1
```

- `--env.task` selecciona la suite (`libero_spatial`, `libero_object`, etc.).
- `--env.task_ids` restringe la ejecución a los índices de tareas registrados (`[0]`, `[1,2,3]`, etc.), que identifican las variantes en las cuatro suites perturbadas. Omita este parámetro para ejecutar todas las tareas registradas. Al evaluar varias suites, la misma lista de índices se aplica de forma independiente a cada suite.
- `--eval.batch_size` controla cuántos entornos se ejecutan en paralelo.
- `--eval.n_episodes` define cuántos episodios se ejecutan por cada tarea registrada. Aumentar este valor repite la evaluación de las variantes seleccionadas; no selecciona variantes distintas adicionales.

### Evaluación multi-suite

Ejecute una política en varias suites a la vez pasando una lista separada por comas:

```bash
lerobot-eval \
  --policy.path="your-policy-id" \
  --env.type=libero_plus \
  --env.task=libero_spatial,libero_object \
  --eval.batch_size=1 \
  --eval.n_episodes=1
```

### Modo de control

LIBERO-plus admite dos modos de control: `relative` (predeterminado) y `absolute`. Los distintos puntos de control de VLA se entrenan con diferentes parametrizaciones de acción, por lo que asegúrese de que el modo coincida con su política:

```bash
--env.control_mode=relative   # or "absolute"
```

### Restablecer el rendimiento

Por defecto, LeRobot conserva el comportamiento de reinicio duro de LIBERO. Con los estados iniciales fijos habilitados, puedes optar por reinicios suaves para omitir la reconstrucción del modelo del simulador y del renderizador en cada episodio:

```bash
--env.init_states=true --env.hard_reset=false
```

Los reinicios suaves son más rápidos, pero no son idénticos a nivel de bit a los reinicios duros después de los pasos de estabilización del entorno, por lo que las observaciones de la cámara y los resultados de la política pueden diferir ligeramente. Utilice reinicios duros al reproducir resultados de benchmarks.

### Entradas y salidas de la política

**Observaciones:**

- `observation.state` — características propioceptivas de 8 dimensiones (posición del eef, orientación axis-angle, qpos del agarre)
- `observation.images.image` — vista de la cámara principal (`agentview_image`), HWC uint8
- `observation.images.image2` — vista de la cámara de la muñeca (`robot0_eye_in_hand_image`), HWC uint8

**Acciones:**

- Control continuo en `Box(-1, 1, shape=(7,))` — delta de efector final 6D + pinza 1D

### Carga de trabajo de evaluación y reproducibilidad

El número total de episodios de evaluación es **el número de tareas registradas seleccionadas en todos los conjuntos × `--eval.n_episodes`**. Por ejemplo, todas las variantes de Spatial con un episodio cada una dan 2.402 episodios; seleccionar `--env.task_ids='[0,1,2]'` en Spatial y Object con un episodio cada una da seis episodios.

El cálculo de 400 episodios (40 tareas originales × 10 episodios) se aplica a LIBERO vanilla, no a una evaluación completa de LIBERO-plus. Para LIBERO-plus, comience con un episodio por cada variante registrada. Los episodios repetidos de una variante no son equivalentes a muestrear variantes distintas de una tarea original.

Para un subconjunto personalizado, utiliza la [clasificación de tareas](https://github.com/sylvestf/LIBERO-plus/blob/4976dc30028e805ff8094b55501d532c48fec182/libero/libero/benchmark/task_classification.json) del fork para identificar las categorías de perturbación y los niveles de dificultad. No asumas que cada tarea original tiene diez variantes distintas en cada categoría de perturbación. Registra la revisión del fork, los nombres de las suites seleccionadas y los índices de las tareas, los episodios por variante, la semilla y la configuración de reinicio al informar los resultados. Para comparar con resultados publicados, sigue el protocolo de muestreo y agregación del benchmark en lugar de tratar un subconjunto arbitrario como equivalente.

## Entrenamiento

### Dataset

Se encuentra disponible un conjunto de datos de entrenamiento en formato LeRobot para LIBERO-plus en:

- [lerobot/libero_plus](https://huggingface.co/datasets/lerobot/libero_plus)

### Ejemplo de comando de entrenamiento

```bash
lerobot-train \
    --policy.type=smolvla \
    --policy.repo_id=${HF_USER}/smolvla_libero_plus \
    --policy.load_vlm_weights=true \
    --dataset.repo_id=lerobot/libero_plus \
    --env.type=libero_plus \
    --env.task=libero_spatial \
    --output_dir=./outputs/ \
    --steps=100000 \
    --batch_size=4 \
    --eval.batch_size=1 \
    --eval.n_episodes=1 \
    --env_eval_freq=1000
```

## Relación con LIBERO

LIBERO-plus es una extensión de LIBERO que se puede usar directamente:

- Misma interfaz de gimnasio de Python (`LiberoEnv`) y observaciones canónicas
- Mismos nombres de cámaras y formato de observación/acción
- Nombres de suites de tareas idénticos
- Se instala bajo el mismo nombre de paquete de Python `libero` (repositorio de GitHub diferente)

Para usar el benchmark original de LIBERO, consulte [LIBERO](./libero) y use `--env.type=libero`.