# 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) 是一个针对**基于语言条件的长程推理机器人操作**的大规模基准测试。其上游测试套件涵盖 100 个任务类别，涉及 2,000 多个物体，并从六个维度评估机器人智能：网格与纹理理解、空间推理、世界知识迁移、语义指令理解、物理定律理解以及长程规划。该基准基于 MuJoCo / dm_control 构建，使用 Franka Panda 7 自由度机械臂。LeRobot 通过 `--env.task` 暴露了其中的 **43 个任务**（21 个基础任务 + 22 个组合任务，详见下文 [可用任务](#available-tasks)）。

- 论文：[VLABench：一个用于具有长时程推理的语言条件机器人操作的大规模基准](https://arxiv.org/abs/2412.18194)
- GitHub: [OpenMOSS/VLABench](https://github.com/OpenMOSS/VLABench)
- 项目网站：[vlabench.github.io](https://vlabench.github.io)
- 预训练策略：[`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%"
/>

## 可用任务

VLABench 提供了两个任务套件，涵盖了 LeRobot 的 `--env.task` 接口中的 **43 个任务类别**：

| 套件     | CLI 名称    | 任务 | 描述                                                      |
| --------- | ----------- | ----- | ---------------------------------------------------------------- |
| 原始 | `primitive` | 21    | 单一/少量技能组合（选择、插入、物理问答）     |
| 复合 | `composite` | 22    | 多步推理和长时程规划（烹饪、重新布置） |

**基础任务：** `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`，以及物理推理任务（`density_qa`、`friction_qa`、`magnetism_qa`、`reflection_qa`、`simple_cuestick_usage`、`simple_seesaw_usage`、`sound_speed_qa`、`thermal_expansion_qa`、`weight_qa`）。

**复合任务：** `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` 接受三种形式：

- 单个任务名称（`select_fruit`）
- 逗号分隔的列表（`select_fruit,heat_food`）
- 套件快捷方式（`primitive`、`composite` 或 `primitive,composite`）

## 安装

VLABench **未发布到 PyPI**——其唯一的分发方式是 [OpenMOSS/VLABench](https://github.com/OpenMOSS/VLABench) GitHub 仓库——因此 LeRobot 没有提供 `vlabench` 额外依赖。请手动将其作为可编辑的克隆进行安装，同时安装 VLABench 所需的 MuJoCo / dm_control 版本固定，然后获取网格资产：

```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 需要 Linux（`sys_platform == 'linux'`）和 Python 3.10+。在运行之前，请设置 MuJoCo 渲染后端：

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

## 评估

以下所有评估代码片段均与 CI 运行的命令保持一致（参见 `.github/workflows/benchmark_tests.yml`）。`--rename_map` 参数将 VLABench 的 `image` / `second_image` / `wrist_image` 相机键映射到已发布的 `smolvla_vlabench` 策略所训练的三相机（`camera1` / `camera2` / `camera3`）输入布局上。

### 单任务评估（推荐用于快速迭代）

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

### 多任务评估

传入以逗号分隔的任务列表：

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

### 全套件评估

运行整个测试套件（全部 21 个原语或全部 22 个复合项）：

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

或同时使用这两个套件：

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

### 推荐的评估回合

**每个任务 10 个回合**，以实现可复现的基准测试（完整原语套件共 210 个，组合任务共 220 个）。与 VLABench 论文中的协议一致。

## 策略输入和输出

**观察：**

- `observation.state` — 7 维末端执行器状态（位置 xyz + 欧拉角 xyz + 夹爪）
- `observation.images.image` — 前置摄像头，480×480 HWC uint8
- `observation.images.second_image` — 第二个摄像头，480×480 HWC uint8
- `observation.images.wrist_image` — 手腕相机，480×480 HWC uint8

**操作：**

- `Box(-1, 1, shape=(7,))` 中的连续控制 — 3D 位置 + 3D 欧拉角姿态 + 1D 夹爪。

## 训练

### 数据集

Hub 上以 LeRobot 格式预收集的 VLABench 数据集：

- [`VLABench/vlabench_primitive_ft_lerobot_video`](https://huggingface.co/datasets/VLABench/vlabench_primitive_ft_lerobot_video) — 5,000 个回合，128 个任务，480×480 图像。
- [`VLABench/vlabench_composite_ft_lerobot_video`](https://huggingface.co/datasets/VLABench/vlabench_composite_ft_lerobot_video) — 5,977 个 episode，167 个任务，224×224 图像。

### 示例训练命令

在基础原语套件上微调 SmolVLA 基础模型：

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

## 复现已发表的结果

发布的检查点 [`lerobot/smolvla_vlabench`](https://huggingface.co/lerobot/smolvla_vlabench) 是在上述 primitive-suite 数据集上训练的，并使用 [Single-task](#single-task-evaluation-recommended-for-quick-iteration) / [Suite-wide](#suite-wide-evaluation) 命令进行评估。CI 会在每个触及该基准的 PR 上运行一个包含 10 个 primitive 任务的冒烟评估（每个任务一个 episode）。