# 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) là một benchmark quy mô lớn cho **thao tác robot có điều kiện ngôn ngữ với suy luận dài hạn**. Bộ bài kiểm tra gốc bao phủ 100 danh mục tác vụ trên hơn 2.000 đối tượng và đánh giá sáu khía cạnh của trí tuệ robot: hiểu mesh & texture, suy luận không gian, chuyển giao kiến thức thế giới, hiểu chỉ dẫn ngữ nghĩa, hiểu luật vật lý và lập kế hoạch dài hạn. Được xây dựng trên MuJoCo / dm_control với cánh tay Franka Panda 7-DOF. LeRobot cung cấp **43 trong số các tác vụ này** thông qua `--env.task` (21 nguyên thủy + 22 tổ hợp, xem [Các tác vụ khả dụng](#available-tasks) bên dưới).

- Bài báo: [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)
- Trang web dự án: [vlabench.github.io](https://vlabench.github.io)
- Chính sách được huấn luyện trước: [`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%"
/>

## Các tác vụ khả dụng

VLABench cung cấp hai bộ nhiệm vụ bao gồm **43 danh mục nhiệm vụ** trong bề mặt `--env.task` của LeRobot:

| Bộ     | Tên CLI    | Nhiệm vụ | Mô tả                                                      |
| --------- | ----------- | ----- | ---------------------------------------------------------------- |
| Nguyên thủy | `primitive` | 21    | Các tổ hợp kỹ năng đơn lẻ / ít kỹ năng (chọn, chèn, kiểm tra vật lý)     |
| Composite | `composite` | 22    | Lập luận nhiều bước và lập kế hoạch tầm xa (nấu ăn, sắp xếp lại) |

**Các tác vụ cơ bản:** `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`, và các tác vụ suy luận vật lý (`density_qa`, `friction_qa`, `magnetism_qa`, `reflection_qa`, `simple_cuestick_usage`, `simple_seesaw_usage`, `sound_speed_qa`, `thermal_expansion_qa`, `weight_qa`).

**Các tác vụ tổng hợp:** `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` chấp nhận ba dạng:

- một tên tác vụ duy nhất (`select_fruit`)
- một danh sách phân tách bằng dấu phẩy (`select_fruit,heat_food`)
- phím tắt bộ công cụ (`primitive`, `composite`, hoặc `primitive,composite`)

## Cài đặt

VLABench **không có trên PyPI** — kênh phân phối duy nhất là kho GitHub [OpenMOSS/VLABench](https://github.com/OpenMOSS/VLABench) — do đó LeRobot không cung cấp extra `vlabench`. Hãy cài đặt thủ công dưới dạng clone có thể chỉnh sửa, cùng với các phiên bản MuJoCo / dm_control mà VLABench yêu cầu, sau đó tải các tài sản mesh:

```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 yêu cầu Linux (`sys_platform == 'linux'`) và Python 3.10+. Đặt backend render của MuJoCo trước khi chạy:

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

## Đánh giá

Tất cả các đoạn mã eval bên dưới mô phỏng lệnh mà CI chạy (xem `.github/workflows/benchmark_tests.yml`). Tham số `--rename_map` ánh xạ các khóa camera `image` / `second_image` / `wrist_image` của VLABench sang bố cục đầu vào ba camera (`camera1` / `camera2` / `camera3`) mà chính sách `smolvla_vlabench` đã phát hành được huấn luyện trên đó.

### Đánh giá đơn nhiệm vụ (khuyến nghị cho việc lặp lại nhanh)

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

### Đánh giá đa nhiệm

Truyền vào một danh sách các tác vụ được phân tách bằng dấu phẩy:

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

### Đánh giá toàn bộ bộ

Chạy toàn bộ bộ (tất cả 21 nguyên thủy hoặc tất cả 22 tổ hợp):

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

Hoặc cả hai bộ:

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

### Các tập đánh giá được khuyến nghị

**10 episodes cho mỗi tác vụ** để benchmarking có thể tái lập (tổng cộng 210 cho bộ nguyên thủy đầy đủ, 220 cho bộ tổ hợp). Phù hợp với giao thức trong bài báo VLABench.

## Đầu vào và đầu ra của Policy

**Quan sát:**

- `observation.state` — trạng thái đầu cuối 7 chiều (vị trí xyz + Euler xyz + kẹp)
- `observation.images.image` — camera trước, 480×480 HWC uint8
- `observation.images.second_image` — camera thứ hai, 480×480 HWC uint8
- `observation.images.wrist_image` — camera cổ tay, 480×480 HWC uint8

**Thao tác:**

- Điều khiển liên tục trong `Box(-1, 1, shape=(7,))` — vị trí 3D + hướng Euler 3D + kẹp 1D.

## Huấn luyện

### Bộ dữ liệu

Các bộ dữ liệu VLABench đã được thu thập trước ở định dạng LeRobot trên Hub:

- [`VLABench/vlabench_primitive_ft_lerobot_video`](https://huggingface.co/datasets/VLABench/vlabench_primitive_ft_lerobot_video) — 5.000 tập, 128 tác vụ, ảnh 480×480.
- [`VLABench/vlabench_composite_ft_lerobot_video`](https://huggingface.co/datasets/VLABench/vlabench_composite_ft_lerobot_video) — 5.977 tập, 167 tác vụ, ảnh 224×224.

### Lệnh huấn luyện mẫu

Tinh chỉnh một SmolVLA cơ bản trên bộ nguyên thủy:

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

## Tái tạo các kết quả đã công bố

Checkpoint đã phát hành [`lerobot/smolvla_vlabench`](https://huggingface.co/lerobot/smolvla_vlabench) được huấn luyện trên bộ dữ liệu primitive-suite ở trên và được đánh giá bằng các lệnh [Single-task](#single-task-evaluation-recommended-for-quick-iteration) / [Suite-wide](#suite-wide-evaluation). CI chạy một đánh giá smoke gồm 10 tác vụ nguyên thủy (mỗi tác vụ một episode) trên mọi PR đụng chạm đến benchmark.