# VLABench

  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/vlabench.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)).

[VLABench](https://github.com/OpenMOSS/VLABench) é um benchmark em larga escala para **manipulação robótica condicionada por linguagem com raciocínio de longo horizonte**. A suíte upstream cobre 100 categorias de tarefas entre mais de 2.000 objetos e avalia seis dimensões da inteligência robótica: compreensão de malha & textura, raciocínio espacial, transferência de conhecimento do mundo, compreensão de instruções semânticas, compreensão de leis físicas e planejamento de longo horizonte. Construído sobre MuJoCo / dm_control com um braço Franka Panda de 7-DOF. O LeRobot expõe **43 dessas tarefas** através de `--env.task` (21 primitivas + 22 compostas, veja [Tarefas disponíveis](#available-tasks) abaixo).

- Artigo: [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)
- Site do projeto: [vlabench.github.io](https://vlabench.github.io)
- Política pré-treinada: [`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%"
/>

## Tarefas disponíveis

VLABench inclui dois conjuntos de tarefas que abrangem **43 categorias de tarefas** na superfície `--env.task` do LeRobot:

| Suite     | Nome da CLI    | Tarefas | Descrição                                                      |
| --------- | ----------- | ----- | ---------------------------------------------------------------- |
| Primitiva | `primitive` | 21    | Combinações de uma / poucas habilidades (seleção, inserção, QA de física)     |
| Composto | `composite` | 22    | Raciocínio em múltiplas etapas e planejamento de longo prazo (cozinhar, reorganizar) |

**Tarefas 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`, e tarefas de raciocínio físico (`density_qa`, `friction_qa`, `magnetism_qa`, `reflection_qa`, `simple_cuestick_usage`, `simple_seesaw_usage`, `sound_speed_qa`, `thermal_expansion_qa`, `weight_qa`).

**Tarefas compostas:** `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` aceita três formas:

- um único nome de tarefa (`select_fruit`)
- uma lista separada por vírgulas (`select_fruit,heat_food`)
- um atalho de suíte (`primitive`, `composite` ou `primitive,composite`)

## Instalação

VLABench é **não está no PyPI** — sua única distribuição é o repositório GitHub [OpenMOSS/VLABench](https://github.com/OpenMOSS/VLABench) — portanto, o LeRobot não expõe um extra `vlabench`. Instale-o manualmente como um clone editável, junto com as versões fixas de MuJoCo / dm_control que o VLABench precisa, e em seguida obtenha os assets de malha:

```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 requer Linux (`sys_platform == 'linux'`) e Python 3.10+. Defina o backend de renderização do MuJoCo antes de executar:

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

## Avaliação

Todos os trechos de avaliação abaixo espelham o comando executado pelo CI (veja `.github/workflows/benchmark_tests.yml`). O argumento `--rename_map` mapeia as chaves de câmera `image` / `second_image` / `wrist_image` do VLABench para o layout de entrada de três câmeras (`camera1` / `camera2` / `camera3`) no qual a política `smolvla_vlabench` liberada foi treinada.

### Avaliação de tarefa única (recomendada para iteração 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"}'
```

### Avaliação multi-tarefa

Passe uma lista de tarefas separadas por vírgulas:

```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"}'
```

### Avaliação em toda a suíte

Execute uma suíte inteira (todos os 21 primitivos ou todos os 22 compostos):

```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"}'
```

Ou ambos os conjuntos:

```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"}'
```

### Episódios de avaliação recomendados

**10 episódios por tarefa** para benchmarking reproduzível (210 no total para a suíte completa de primitivas, 220 para as compostas). Corresponde ao protocolo do paper VLABench.

## Entradas e saídas da política

**Observações:**

- `observation.state` — estado de 7 dimensões do efetuador final (posição xyz + Euler xyz + garra)
- `observation.images.image` — câmera frontal, 480×480 HWC uint8
- `observation.images.second_image` — segunda câmera, 480×480 HWC uint8
- `observation.images.wrist_image` — câmera do pulso, 480×480 HWC uint8

**Ações:**

- Controle contínuo em `Box(-1, 1, shape=(7,))` — posição 3D + orientação Euler 3D + garra 1D.

## Treinamento

### Conjuntos de dados

Conjuntos de dados VLABench pré-coletados no formato LeRobot no Hub:

- [`VLABench/vlabench_primitive_ft_lerobot_video`](https://huggingface.co/datasets/VLABench/vlabench_primitive_ft_lerobot_video) — 5.000 episódios, 128 tarefas, imagens de 480×480.
- [`VLABench/vlabench_composite_ft_lerobot_video`](https://huggingface.co/datasets/VLABench/vlabench_composite_ft_lerobot_video) — 5.977 episódios, 167 tarefas, imagens de 224×224.

### Exemplo de comando de treinamento

Ajuste fino de um SmolVLA base no 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
```

## Reproduzindo resultados publicados

O checkpoint liberado [`lerobot/smolvla_vlabench`](https://huggingface.co/lerobot/smolvla_vlabench) foi treinado no conjunto de dados primitive-suite acima e é avaliado com os comandos [Single-task](#single-task-evaluation-recommended-for-quick-iteration) / [Suite-wide](#suite-wide-evaluation). O CI executa uma avaliação de fumaça com 10 tarefas de primitivas (um episódio cada) em cada PR que altera o benchmark.