# 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 là một **benchmark đánh giá độ bền vững** cho các mô hình Vision-Language-Action (VLA) được xây dựng dựa trên [LIBERO](./libero). Nó kiểm tra áp lực có hệ thống các chính sách bằng cách áp dụng **bảy chiều nhiễu độc lập** lên bộ tác vụ LIBERO gốc, phơi bày các chế độ thất bại mà các benchmark tiêu chuẩn bỏ sót.

- Bài báo: [Phân tích độ bền chi tiết của các mô hình Thị giác-Ngôn ngữ-Hành động](https://arxiv.org/abs/2510.13626)
- GitHub: [sylvestf/LIBERO-plus](https://github.com/sylvestf/LIBERO-plus)
- Bộ dữ liệu: [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)

## Các chiều nhiễu

LIBERO-plus tạo ra ~10 000 biến thể tác vụ bằng cách nhiễu loạn mỗi tác vụ LIBERO gốc dọc theo các trục sau:

| Kích thước             | Những thay đổi                                          |
| --------------------- | ----------------------------------------------------- |
| Bố cục các đối tượng        | Vị trí mục tiêu, sự hiện diện của các vật thể gây nhiễu      |
| Góc nhìn của camera     | Vị trí, hướng, trường nhìn của camera           |
| Trạng thái ban đầu của robot  | Tư thế bắt đầu của cơ cấu chấp hành                                |
| Hướng dẫn ngôn ngữ | Mô tả nhiệm vụ được viết lại bởi LLM (diễn đạt lại / từ đồng nghĩa) |
| Điều kiện ánh sáng      | Cường độ, hướng, màu sắc, bóng đổ                   |
| Kết cấu nền   | Bề mặt cảnh và ngoại quan của đối tượng                   |
| Nhiễu cảm biến          | Biến dạng quang trắc và suy giảm hình ảnh         |

## Các bộ nhiệm vụ có sẵn

LIBERO-plus gây nhiễu cho 40 tác vụ gốc trong các bộ Spatial, Object, Goal và Long. Mỗi tác vụ được đăng ký trong bốn bộ này là một biến thể gây nhiễu, thay vì một trong các tác vụ gốc. Bản fork cũng giữ lại 90 tác vụ không gây nhiễu trong LIBERO-90.

| Bộ          | Tên CLI         | Các tác vụ ban đầu | Các tác vụ đã đăng ký | Số bước tối đa | Mô tả                                       |
| -------------- | ---------------- | -------------- | ---------------- | --------- | ------------------------------------------------- |
| LIBERO-Spatial | `libero_spatial` | 10             | 2,402            | 280       | Các tác vụ đòi hỏi suy luận về các quan hệ không gian |
| LIBERO-Object  | `libero_object`  | 10             | 2,518            | 280       | Các tác vụ tập trung vào việc thao tác với các đối tượng khác nhau  |
| LIBERO-Goal    | `libero_goal`    | 10             | 2,591            | 300       | Các tác vụ có điều kiện theo mục tiêu với các mục tiêu thay đổi      |
| LIBERO-90      | `libero_90`      | 90             | 90               | 400       | Các tác vụ LIBERO tầm ngắn không bị nhiễu            |
| LIBERO-Long    | `libero_10`      | 10             | 2,519            | 520       | Các tác vụ dài hạn từ bộ sưu tập LIBERO-100 |

Các số lượng này đến từ [đăng ký tác vụ](https://github.com/sylvestf/LIBERO-plus/blob/4976dc30028e805ff8094b55501d532c48fec182/libero/libero/benchmark/libero_suite_task_map.py) nguồn gốc. Bốn bộ bài toán bị nhiễu chứa tổng cộng **10.030 biến thể tác vụ**; LIBERO-90 không được tính vào tổng số đó. Số lượng và chỉ số tác vụ phụ thuộc vào phiên bản fork đã cài đặt.

  Việc cài đặt LIBERO-plus **thay thế** LIBERO gốc — nó sẽ gỡ cài đặt `hf-libero` để `import libero` trỏ đến nhánh fork của LIBERO-plus. Bạn không thể cài đặt cả hai cùng lúc. Để chuyển lại về LIBERO gốc, hãy gỡ cài đặt nhánh fork và cài đặt lại bằng `pip install -e ".[libero]"`.

## Cài đặt

### Phụ thuộc hệ thống (chỉ dành cho Linux)

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

### Gói 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 được cài đặt từ bản fork trên GitHub thay vì từ một extra của pyproject — bản fork được phát hành dưới dạng namespace package mà pip không thể xử lý, do đó phải được clone và thêm vào `PYTHONPATH`. Xem giai đoạn `libero_plus_native` của `docker/Dockerfile.sim` để biết cách cài đặt chuẩn. MuJoCo là bắt buộc, vì vậy chỉ hỗ trợ Linux.

Đặt backend render của MuJoCo trước khi chạy đánh giá:

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

### Tải tài sản LIBERO-plus

LIBERO-plus phát hành gói tài nguyên mở rộng riêng biệt. Tải xuống `assets.zip` từ [dataset Hugging Face](https://huggingface.co/datasets/Sylvest/LIBERO-plus/tree/main) và giải nén vào thư mục gói 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/
```

## Đánh giá

### Đánh giá cục bộ mặc định

Đánh giá mọi biến thể đã đăng ký trên bốn bộ dữ liệu nhiễu, sử dụng một tập (episode) cho mỗi biến thể như được khuyến nghị trong [hướng dẫn đánh giá upstream](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
```

Điều này chạy **10.030 episode** cho registry ở trên. Với `--eval.n_episodes=10`, cùng lệnh đó chạy **100.300 episode**, không phải 400.

### Kiểm thử nhanh

Trước khi chạy đánh giá đầy đủ, hãy kiểm tra cấu hình của bạn với một biến thể đã đăng ký và một tập:

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

Đây là kiểm tra cài đặt, không phải đánh giá độ bền đại diện.

### Đánh giá bộ duy nhất

Đánh giá trên một bộ 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` chọn bộ bài tập (`libero_spatial`, `libero_object`, v.v.).
- `--env.task_ids` giới hạn theo các chỉ số tác vụ đã đăng ký (`[0]`, `[1,2,3]`, v.v.), dùng để xác định các biến thể trong bốn bộ bài kiểm tra đã nhiễu. Bỏ qua tham số này để chạy tất cả các tác vụ đã đăng ký. Khi đánh giá nhiều bộ bài kiểm tra, cùng một danh sách chỉ số sẽ được áp dụng độc lập cho từng bộ.
- `--eval.batch_size` kiểm soát số lượng môi trường chạy song song.
- `--eval.n_episodes` xác định số lượng episode cần chạy cho mỗi task đã đăng ký. Việc tăng giá trị này sẽ lặp lại quá trình đánh giá các biến thể đã chọn; nó không chọn thêm các biến thể khác biệt.

### Đánh giá đa bộ

Đánh giá hiệu năng của một chính sách trên nhiều bộ bài kiểm tra cùng lúc bằng cách truyền vào một danh sách phân tách bằng dấu phẩy:

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

### Chế độ điều khiển

LIBERO-plus hỗ trợ hai chế độ điều khiển — `relative` (mặc định) và `absolute`. Các checkpoint VLA khác nhau được huấn luyện với các tham số hóa hành động khác nhau, vì vậy hãy đảm bảo chế độ khớp với chính sách của bạn:

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

### Đặt lại hiệu suất

Mặc định, LeRobot giữ nguyên hành vi hard-reset của LIBERO. Khi đã bật trạng thái ban đầu cố định, bạn có thể chọn dùng soft reset để bỏ qua việc xây dựng lại mô hình mô phỏng và trình hiển thị ở mỗi episode:

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

Soft resets nhanh hơn nhưng không giống hệt bit với hard resets sau các bước ổn định của môi trường, do đó quan sát từ camera và kết quả chính sách có thể khác nhau đôi chút. Hãy sử dụng hard resets khi tái tạo kết quả benchmark.

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

**Quan sát:**

- `observation.state` — 8 chiều đặc trưng cảm nhận bản thân (vị trí eef, hướng axis-angle, qpos của kẹp)
- `observation.images.image` — góc nhìn từ camera chính (`agentview_image`), HWC uint8
- `observation.images.image2` — góc nhìn camera cổ tay (`robot0_eye_in_hand_image`), HWC uint8

**Thao tác:**

- Điều khiển liên tục trong `Box(-1, 1, shape=(7,))` — delta của đầu cuối 6D + kẹp 1D

### Tải công việc đánh giá và khả năng tái lập

Tổng số tập đánh giá là **số lượng tác vụ đã đăng ký được chọn trên tất cả các bộ bài × `--eval.n_episodes`**. Ví dụ, tất cả các biến thể Spatial với mỗi tập một episode cho ra 2.402 tập; việc chọn `--env.task_ids='[0,1,2]'` trong Spatial và Object với mỗi tập một episode cho ra sáu tập.

Việc tính toán 400 tập (40 tác vụ gốc × 10 tập) áp dụng cho LIBERO thông thường, không phải cho một đánh giá LIBERO-plus đầy đủ. Đối với LIBERO-plus, hãy bắt đầu với một tập cho mỗi biến thể đã đăng ký. Các tập lặp lại của một biến thể không tương đương với việc lấy mẫu các biến thể khác nhau của một tác vụ gốc.

Đối với một tập con tùy chỉnh, hãy sử dụng [phân loại tác vụ](https://github.com/sylvestf/LIBERO-plus/blob/4976dc30028e805ff8094b55501d532c48fec182/libero/libero/benchmark/task_classification.json) của bản fork để xác định các danh mục nhiễu và mức độ khó. Không được giả định rằng mọi tác vụ gốc đều có mười biến thể riêng biệt trong mọi danh mục nhiễu. Khi báo cáo kết quả, hãy ghi lại phiên bản fork, tên các bộ bài kiểm tra đã chọn và chỉ số tác vụ, số tập (episodes) cho mỗi biến thể, hạt ngẫu nhiên (seed) và các cài đặt đặt lại (reset). Để so sánh với các kết quả đã công bố, hãy tuân theo giao thức lấy mẫu và tổng hợp của bộ chuẩn (benchmark) thay vì coi một tập con tùy ý là tương đương.

## Huấn luyện

### Bộ dữ liệu

Bộ dữ liệu huấn luyện định dạng LeRobot cho LIBERO-plus có sẵn tại:

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

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

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

## Mối quan hệ với LIBERO

LIBERO-plus là một phần mở rộng thay thế trực tiếp của LIBERO:

- Giao diện gym Python tương tự (`LiberoEnv`) và các quan sát chuẩn
- Cùng tên camera và định dạng quan sát/hành động
- Cùng tên bộ nhiệm vụ
- Được cài đặt dưới cùng tên gói Python `libero` (kho GitHub khác)

Để sử dụng bộ chuẩn LIBERO gốc, hãy xem [LIBERO](./libero) và sử dụng `--env.type=libero`.