# 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 — это **бенчмарк устойчивости** для моделей Vision-Language-Action (VLA), построенный на базе [LIBERO](./libero). Он систематически проверяет политики на прочность, применяя **семь независимых измерений возмущений** к исходному набору задач LIBERO, что выявляет режимы отказа, которые стандартные бенчмарки упускают из виду.

- Статья: [Детальный анализ устойчивости моделей «зрение-язык-действие»](https://arxiv.org/abs/2510.13626)
- GitHub: [sylvestf/LIBERO-plus](https://github.com/sylvestf/LIBERO-plus)
- Набор данных: [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)

## Размеры возмущений

LIBERO-plus создаёт ~10 000 вариантов задач, изменяя каждую исходную задачу LIBERO по следующим осям:

| Размерность             | Что изменилось                                          |
| --------------------- | ----------------------------------------------------- |
| Расположение объектов        | Целевое положение, наличие мешающих объектов      |
| Точки обзора камеры     | Положение, ориентация и угол обзора камеры           |
| Начальные состояния робота  | Начальное положение манипулятора                                |
| Инструкции по языкам | Описание задачи, переписанное LLM (парафраз / синоним) |
| Световые условия      | Интенсивность, направление, цвет, тень                   |
| Фоновые текстуры   | Поверхность сцены и внешний вид объектов                   |
| Шум датчика          | Фотометрические искажения и деградация изображений         |

## Доступные наборы задач

LIBERO-plus вносит изменения в 40 исходных задач из наборов Spatial, Object, Goal и Long. Каждая зарегистрированная задача в этих четырёх наборах является изменённым вариантом, а не одной из исходных задач. Вилка также сохраняет 90 неизменённых задач из LIBERO-90.

| Suite          | Имя CLI         | Исходные задачи | Зарегистрированные задачи | Максимальное количество шагов | Описание                                       |
| -------------- | ---------------- | -------------- | ---------------- | --------- | ------------------------------------------------- |
| LIBERO-Spatial | `libero_spatial` | 10             | 2,402            | 280       | Задачи, требующие рассуждений о пространственных отношениях |
| LIBERO-Object  | `libero_object`  | 10             | 2,518            | 280       | Задачи, связанные с манипулированием различными объектами  |
| LIBERO-Goal    | `libero_goal`    | 10             | 2,591            | 300       | Задачи с целевым условием и изменяющимися целями      |
| LIBERO-90      | `libero_90`      | 90             | 90               | 400       | Неизменённые задачи LIBERO с коротким горизонтом            |
| LIBERO-Long    | `libero_10`      | 10             | 2,519            | 520       | Долгосрочные задачи из коллекции LIBERO-100 |

Эти данные о количестве задач получены из [реестра задач](https://github.com/sylvestf/LIBERO-plus/blob/4976dc30028e805ff8094b55501d532c48fec182/libero/libero/benchmark/libero_suite_task_map.py) в исходном репозитории. Четыре модифицированных набора в общей сложности содержат **10 030 вариантов задач**; LIBERO-90 в эту сумму не входит. Количество задач и их индексы зависят от установленной ревизии форка.

  Установка LIBERO-plus **заменяет** стандартный LIBERO — она удаляет `hf-libero`, чтобы `import libero` указывал на форк LIBERO-plus. Одновременно установить оба варианта невозможно. Чтобы вернуться к стандартному LIBERO, удалите форк и установите пакет заново с помощью `pip install -e ".[libero]"`.

## Установка

### Системные зависимости (только Linux)

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

### Пакет 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 устанавливается из его GitHub-форка, а не через pyproject extra — форк поставляется как namespace-пакет, с которым pip не может работать, поэтому его необходимо клонировать и добавить в `PYTHONPATH`. См. этап `libero_plus_native` в `docker/Dockerfile.sim` для канонической установки. Требуется MuJoCo, поэтому поддерживается только Linux.

Установите backend рендеринга MuJoCo перед запуском оценки:

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

### Скачать ресурсы LIBERO-plus

LIBERO-plus распространяет расширенный набор ассетов отдельно. Скачайте `assets.zip` из [датасета на Hugging Face](https://huggingface.co/datasets/Sylvest/LIBERO-plus/tree/main) и распакуйте его в каталог пакета 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/
```

## Оценка

### Локальная оценка по умолчанию

Оцените каждый зарегистрированный вариант на четырёх модифицированных наборах, используя один эпизод на вариант, как рекомендуется в [руководстве по оценке 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
```

Это запускает **10 030 эпизодов** для реестра выше. С `--eval.n_episodes=10` та же команда запускает **100 300 эпизодов**, а не 400.

### Тест дымового контроля

Перед запуском полной оценки проверьте конфигурацию с одним зарегистрированным вариантом и одним эпизодом:

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

Это проверка конфигурации, а не репрезентативная оценка устойчивости.

### Оценка на одном наборе

Оценка на одном наборе 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` выбирает набор (`libero_spatial`, `libero_object` и т. д.).
- `--env.task_ids` ограничивает выбор зарегистрированными индексами задач (`[0]`, `[1,2,3]` и т. д.), которые идентифицируют варианты в четырёх модифицированных наборах. Если параметр не указан, выполняются все зарегистрированные задачи. При оценке нескольких наборов один и тот же список индексов применяется независимо к каждому из них.
- `--eval.batch_size` управляет количеством сред, работающих параллельно.
- `--eval.n_episodes` задаёт количество эпизодов, выполняемых для каждой зарегистрированной задачи. Увеличение этого значения приводит к повторной оценке выбранных вариантов, но не к выбору дополнительных различных вариантов.

### Оценка на нескольких наборах

Чтобы протестировать политику сразу в нескольких наборах, передайте список через запятую:

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

### Режим управления

LIBERO-plus поддерживает два режима управления — `relative` (по умолчанию) и `absolute`. Разные контрольные точки VLA обучаются с различными параметризациями действий, поэтому убедитесь, что режим соответствует вашей политике:

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

### Сброс производительности

По умолчанию LeRobot сохраняет поведение жёсткого сброса (hard-reset) в LIBERO. При включённых фиксированных начальных состояниях можно перейти на мягкий сброс (soft reset), чтобы пропускать пересборку модели симулятора и рендерера в каждом эпизоде:

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

Мягкие сбросы выполняются быстрее, но после шагов стабилизации среды они не совпадают с жёсткими сбросами на уровне битов, поэтому наблюдения камеры и результаты политики могут незначительно отличаться. Используйте жёсткие сбросы при воспроизведении результатов бенчмарков.

### Входы и выходы политики

**Наблюдения:**

- `observation.state` — 8-мерные проприоцептивные признаки (позиция eef, ориентация в формате ось-угол, qpos захвата)
- `observation.images.image` — вид с основной камеры (`agentview_image`), HWC uint8
- `observation.images.image2` — вид с камеры на запястье (`robot0_eye_in_hand_image`), HWC uint8

**Действия:**

- Непрерывное управление в `Box(-1, 1, shape=(7,))` — дельта 6D для конечного эффектора + захват 1D

### Нагрузочное тестирование и воспроизводимость

Общее количество эпизодов оценки равно **числу выбранных зарегистрированных задач во всех наборах × `--eval.n_episodes`**. Например, все варианты Spatial с одним эпизодом каждый дают 2402 эпизода; выбор `--env.task_ids='[0,1,2]'` в Spatial и Object с одним эпизодом каждый даёт шесть эпизодов.

Расчёт на 400 эпизодов (40 исходных задач × 10 эпизодов) относится к базовой версии LIBERO, а не к полной оценке LIBERO-plus. Для LIBERO-plus начните с одного эпизода на каждый зарегистрированный вариант. Повторные эпизоды одного варианта не эквивалентны выборке различных вариантов исходной задачи.

Для пользовательского подмножества используйте [классификацию задач](https://github.com/sylvestf/LIBERO-plus/blob/4976dc30028e805ff8094b55501d532c48fec182/libero/libero/benchmark/task_classification.json) в форке, чтобы определить категории возмущений и уровни сложности. Не предполагайте, что для каждой исходной задачи существует десять различных вариантов в каждой категории возмущений. При публикации результатов фиксируйте ревизию форка, имена выбранных наборов и индексы задач, количество эпизодов на вариант, сид и настройки сброса. Для сравнения с опубликованными результатами следуйте протоколу выборки и агрегации бенчмарка, а не считайте произвольное подмножество эквивалентным.

## Обучение

### Набор данных

Набор данных для обучения в формате LeRobot для LIBERO-plus доступен по адресу:

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

### Пример команды обучения

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

## Связь с LIBERO

LIBERO-plus — это модульное расширение LIBERO:

- Тот же интерфейс Python gym (`LiberoEnv`) и канонические наблюдения
- Одинаковые имена камер и формат наблюдений/действий
- Одинаковые имена наборов задач
- Устанавливается под тем же именем Python-пакета `libero` (другой репозиторий на GitHub)

Чтобы использовать исходный бенчмарк LIBERO, см. [LIBERO](./libero) и используйте `--env.type=libero`.