# VLABench

  Los comandos siguientes ejecutan el simulador localmente. Para mantener sus dependencias separadas de las de su política, sirva en su lugar con `lerobot-env-server --config_path=docker/sim/configs/vlabench.yaml --sim.task= --docker=true`, donde `` 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)).

[VLABench](https://github.com/OpenMOSS/VLABench) es un benchmark a gran escala para **manipulación robótica condicionada por lenguaje con razonamiento de largo horizonte**. El conjunto de tareas de origen abarca 100 categorías de tareas en más de 2.000 objetos y evalúa seis dimensiones de la inteligencia robótica: comprensión de mallas y texturas, razonamiento espacial, transferencia de conocimiento del mundo, comprensión de instrucciones semánticas, comprensión de leyes físicas y planificación de largo horizonte. Está construido sobre MuJoCo / dm_control con un brazo Franka Panda de 7 GDL. LeRobot expone **43 de estas tareas** a través de `--env.task` (21 primitivas + 22 compuestas, ver [Tareas disponibles](#available-tasks) a continuación).

- Artículo: [VLABench: A Large-Scale Benchmark for Language-Conditioned Robotics Manipulation with Long-Horizon Reasoning](https://arxiv.org/abs/2412.18194)
- GitHub: [OpenMOSS/VLABench](https://github.com/OpenMOSS/VLABench)
- Sitio web del proyecto: [vlabench.github.io](https://vlabench.github.io)
- Política preentrenada: [`lerobot/smolvla_vlabench`](https://huggingface.co/lerobot/smolvla_vlabench)

<img
  src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/vlabench.png"
  alt="VLABench benchmark overview"
  width="85%"
/>

## Tareas disponibles

VLABench incluye dos suites de tareas que abarcan **43 categorías de tareas** en la superficie `--env.task` de LeRobot:

| Suite     | Nombre de la CLI    | Tareas | Descripción                                                      |
| --------- | ----------- | ----- | ---------------------------------------------------------------- |
| Primitiva | `primitive` | 21    | Combinaciones de una o pocas habilidades (selección, inserción, QA de física)     |
| Compuesto | `composite` | 22    | Razonamiento de varios pasos y planificación a largo plazo (cocinar, reorganizar) |

**Tareas primitivas:** `select_fruit`, `select_toy`, `select_chemistry_tube`, `add_condiment`, `select_book`, `select_painting`, `select_drink`, `insert_flower`, `select_billiards`, `select_ingredient`, `select_mahjong`, `select_poker`, y tareas de razonamiento físico (`density_qa`, `friction_qa`, `magnetism_qa`, `reflection_qa`, `simple_cuestick_usage`, `simple_seesaw_usage`, `sound_speed_qa`, `thermal_expansion_qa`, `weight_qa`).

**Tareas compuestas:** `cluster_billiards`, `cluster_book`, `cluster_drink`, `cluster_toy`, `cook_dishes`, `cool_drink`, `find_unseen_object`, `get_coffee`, `hammer_nail`, `heat_food`, `make_juice`, `play_mahjong`, `play_math_game`, `play_poker`, `play_snooker`, `rearrange_book`, `rearrange_chemistry_tube`, `set_dining_table`, `set_study_table`, `store_food`, `take_chemistry_experiment`, `use_seesaw_complex`.

`--env.task` acepta tres formas:

- un único nombre de tarea (`select_fruit`)
- una lista separada por comas (`select_fruit,heat_food`)
- un atajo de suite (`primitive`, `composite` o `primitive,composite`)

## Instalación

VLABench **no está en PyPI**: su única vía de distribución es el repositorio de GitHub [OpenMOSS/VLABench](https://github.com/OpenMOSS/VLABench), por lo que LeRobot no expone un extra `vlabench`. Instálalo manualmente como un clon editable, junto con las versiones fijas de MuJoCo / dm_control que VLABench necesita, y luego descarga los activos de malla:

```bash
# After following the standard LeRobot installation instructions.

git clone https://github.com/OpenMOSS/VLABench.git ~/VLABench
git clone https://github.com/motion-planning/rrt-algorithms.git ~/rrt-algorithms
pip install -e ~/VLABench -e ~/rrt-algorithms
pip install "mujoco==3.2.2" "dm-control==1.0.22" \
            open3d colorlog scikit-learn openai gdown

python ~/VLABench/scripts/download_assets.py
```

VLABench requiere Linux (`sys_platform == 'linux'`) y Python 3.10+. Establece el backend de renderizado de MuJoCo antes de ejecutar:

```bash
export MUJOCO_GL=egl  # for headless servers (HPC, cloud)
```

## Evaluación

Todos los fragmentos de evaluación a continuación replican el comando que ejecuta CI (ver `.github/workflows/benchmark_tests.yml`). El argumento `--rename_map` asigna las claves de cámara `image` / `second_image` / `wrist_image` de VLABench al esquema de entrada de tres cámaras (`camera1` / `camera2` / `camera3`) en el que se entrenó la política `smolvla_vlabench` publicada.

### Evaluación de una sola tarea (recomendada para iteración rápida)

```bash
lerobot-eval \
  --policy.path=lerobot/smolvla_vlabench \
  --env.type=vlabench \
  --env.task=select_fruit \
  --eval.batch_size=1 \
  --eval.n_episodes=10 \
  --eval.use_async_envs=false \
  --policy.device=cuda \
  '--rename_map={"observation.images.image": "observation.images.camera1", "observation.images.second_image": "observation.images.camera2", "observation.images.wrist_image": "observation.images.camera3"}'
```

### Evaluación multitarea

Pase una lista de tareas separadas por comas:

```bash
lerobot-eval \
  --policy.path=lerobot/smolvla_vlabench \
  --env.type=vlabench \
  --env.task=select_fruit,select_toy,add_condiment,heat_food \
  --eval.batch_size=1 \
  --eval.n_episodes=10 \
  --eval.use_async_envs=false \
  --policy.device=cuda \
  '--rename_map={"observation.images.image": "observation.images.camera1", "observation.images.second_image": "observation.images.camera2", "observation.images.wrist_image": "observation.images.camera3"}'
```

### Evaluación de toda la suite

Ejecutar una suite completa (los 21 primitivos o los 22 compuestos):

```bash
lerobot-eval \
  --policy.path=lerobot/smolvla_vlabench \
  --env.type=vlabench \
  --env.task=primitive \
  --eval.batch_size=1 \
  --eval.n_episodes=10 \
  --eval.use_async_envs=false \
  --policy.device=cuda \
  --env.max_parallel_tasks=1 \
  '--rename_map={"observation.images.image": "observation.images.camera1", "observation.images.second_image": "observation.images.camera2", "observation.images.wrist_image": "observation.images.camera3"}'
```

O ambas suites:

```bash
lerobot-eval \
  --policy.path=lerobot/smolvla_vlabench \
  --env.type=vlabench \
  --env.task=primitive,composite \
  --eval.batch_size=1 \
  --eval.n_episodes=10 \
  --eval.use_async_envs=false \
  --policy.device=cuda \
  --env.max_parallel_tasks=1 \
  '--rename_map={"observation.images.image": "observation.images.camera1", "observation.images.second_image": "observation.images.camera2", "observation.images.wrist_image": "observation.images.camera3"}'
```

### Episodios de evaluación recomendados

**10 episodios por tarea** para un benchmarking reproducible (210 en total para el conjunto completo de primitivas, 220 para el compuesto). Coincide con el protocolo del artículo de VLABench.

## Entradas y salidas de la política

**Observaciones:**

- `observation.state` — estado de 7 dimensiones del efector final (posición xyz + Euler xyz + pinza)
- `observation.images.image` — cámara frontal, 480×480 HWC uint8
- `observation.images.second_image` — segunda cámara, 480×480 HWC uint8
- `observation.images.wrist_image` — cámara de muñeca, 480×480 HWC uint8

**Acciones:**

- Control continuo en `Box(-1, 1, shape=(7,))` — posición 3D + orientación Euler 3D + pinza 1D.

## Entrenamiento

### Conjuntos de datos

Conjuntos de datos de VLABench pre-recopilados en formato LeRobot en el Hub:

- [`VLABench/vlabench_primitive_ft_lerobot_video`](https://huggingface.co/datasets/VLABench/vlabench_primitive_ft_lerobot_video) — 5.000 episodios, 128 tareas, imágenes de 480×480.
- [`VLABench/vlabench_composite_ft_lerobot_video`](https://huggingface.co/datasets/VLABench/vlabench_composite_ft_lerobot_video) — 5.977 episodios, 167 tareas, imágenes de 224×224.

### Ejemplo de comando de entrenamiento

Ajusta un modelo base de SmolVLA en el conjunto de primitivas:

```bash
lerobot-train \
  --policy.type=smolvla \
  --policy.repo_id=${HF_USER}/smolvla_vlabench_primitive \
  --policy.load_vlm_weights=true \
  --policy.push_to_hub=true \
  --dataset.repo_id=VLABench/vlabench_primitive_ft_lerobot_video \
  --env.type=vlabench \
  --env.task=select_fruit \
  --output_dir=./outputs/smolvla_vlabench_primitive \
  --steps=100000 \
  --batch_size=4 \
  --env_eval_freq=5000 \
  --eval.batch_size=1 \
  --eval.n_episodes=1 \
  --save_freq=10000
```

## Reproducción de resultados publicados

El checkpoint publicado [`lerobot/smolvla_vlabench`](https://huggingface.co/lerobot/smolvla_vlabench) se entrenó con el conjunto de datos primitive-suite anterior y se evalúa con los comandos [Single-task](#single-task-evaluation-recommended-for-quick-iteration) / [Suite-wide](#suite-wide-evaluation). CI ejecuta una evaluación de humo de 10 tareas de primitivas (un episodio cada una) en cada PR que modifica el benchmark.

