# TOPReward

TOPReward — это **zero-shot reward model**, которая извлекает лог-вероятности токенов из готовой vision-language модели (VLM) в качестве сигнала вознаграждения для робототехники. По заданной видеотраектории и инструкции к задаче модель возвращает лог-правдоподобие того, что инструкция верна, — без необходимости дообучения.

**Статья**: [TOPReward: Token Probabilities as Hidden Zero-Shot Rewards for Robotics](https://arxiv.org/abs/2602.19313) **Проект**: [topreward.github.io](https://topreward.github.io/webpage/) **Исходный код**: [github.com/TOPReward/TOPReward](https://github.com/TOPReward/TOPReward) **Базовая модель по умолчанию**: [Qwen/Qwen3-VL-8B-Instruct](https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct)

## Обзор

TOPReward запрашивает у универсальной VLM вероятность того, что инструкция к задаче является правдоподобной, **с учётом видео** робота, пытающегося выполнить эту задачу. Конкретно, при наличии:

- Видео траектории (последовательность кадров).
- Инструкция к задаче (например, _"open the drawer"_).

он формирует чат-запрос вида

```text
<video>
"The above video shows a robot manipulation trajectory that completes the
 following task: <instruction> Decide whether the above statement is True
 or not. The answer is: True"
```

пропускает его через VLM, маскирует все токены, кроме последнего, и считывает лог-вероятность этого токена — по умолчанию это литерал `"True"`, закрывающий шаблон суффикса. Полученное значение `log P("True" | video + prompt + instruction)` является наградой.

Поскольку метод опирается только на замороженную VLM, TOPReward является **zero-shot**: размещать веса дообученной модели не нужно. «Модель» в LeRobot представляет собой небольшой обёрточный слой вокруг `transformers` и класса `Qwen3VLForConditionalGeneration`, дополненный логикой маскирования меток. Процессор управляет токенизатором и формирует полный чат-промпт (паттерн EO-1/Robometer).

## Что охватывает интеграция LeRobot

- Стандартная конфигурация `reward_model.type=topreward` через LeRobot.
- Загрузка VLM через API `transformers` `Qwen3VLForConditionalGeneration`.
- Сборка промпта и токенизация в процессоре (в соответствии с `QwenClient.compute_instruction_reward` из исходного кода).
- `compute_reward()` возвращает одно скалярное значение лог-вероятности на каждый образец.
- Сохранение и загрузка reward-модели LeRobot — `save_pretrained` записывает только `config.json` (VLM идентифицируется по `vlm_name`).
- Скрипт офлайн-разметки, создающий файл `topreward_progress.parquet` (со схемой, совместимой с SARM) для RA-BC и оверлея.

Текущая реализация LeRobot поддерживает только **клиент Qwen3-VL**. Другие клиенты из исходного репозитория (Gemini, OpenAI, Gemma, Molmo) могут быть добавлены в качестве дополнительных функций.

## Требования к установке

1. Установите LeRobot, следуя [Руководству по установке](./installation).
2. Установите дополнительный пакет TOPReward:

```bash
pip install -e ".[topreward]"
```

или, с `uv` из исходного кода:

```bash
uv sync --extra topreward
```

Это подключает `transformers`. При первом запуске TOPReward Hugging Face также скачает веса VLM с Hub (~16 ГБ для Qwen3-VL-8B-Instruct). Желательно использовать GPU.

## Входы и выходы модели

TOPReward ожидает:

- Видео траектории или последовательность кадров.
- Описание задачи на естественном языке.

В наборах данных LeRobot предобработчик читает:

| Поле конфигурации              | По умолчанию                     | Значение                                       |
| ------------------------- | --------------------------- | --------------------------------------------- |
| `reward_model.image_key`  | `observation.images.top`    | Наблюдение камеры, используемое в TOPReward          |
| `reward_model.task_key`   | `task`                      | Введите дополнительные данные для строки задачи |
| `reward_model.max_frames` | `16`                        | Ограничение количества кадров на образец                      |
| `reward_model.fps`        | `2.0`                       | Метаданные, передаваемые в видеопроцессор Qwen   |
| `reward_model.vlm_name`   | `Qwen/Qwen3-VL-8B-Instruct` | Идентификатор базовой VLM в Hugging Face Hub     |

Модель возвращает:

- `compute_reward(batch)`: одна логарифмическая вероятность на образец. Чем выше значение, тем лучше согласованность задачи и видео. Если `success_threshold` конечно, возвращается бинарное пороговое значение.

## Использование

### Загрузите модель вознаграждения напрямую

```python
from lerobot.rewards.topreward import TOPRewardConfig, TOPRewardModel

cfg = TOPRewardConfig(
    vlm_name="Qwen/Qwen3-VL-8B-Instruct",
    device="cuda",
)
reward_model = TOPRewardModel(cfg)
```

### Используйте фабрику вознаграждений

```python
from lerobot.rewards import make_reward_model, make_reward_model_config, make_reward_pre_post_processors

cfg = make_reward_model_config(
    "topreward",
    vlm_name="Qwen/Qwen3-VL-8B-Instruct",
    device="cuda",
    image_key="observation.images.top",
)
reward_model = make_reward_model(cfg)
preprocessor, postprocessor = make_reward_pre_post_processors(cfg)
```

Предобработчик токенизирует полный промпт (видео + префикс + суффикс инструкции), записывает тензоры Qwen-VL и `prompt_length` в `observation.topreward.*`. Модель считывает эти тензоры, применяет маску меток на основе `prompt_length` и извлекает награду в виде лог-вероятности.

### Разметка набора данных в автономном режиме

Создайте `topreward_progress.parquet` для обучения RA-BC и наложения видео:

```bash
# Sparse-dense (15 anchors per episode, matches upstream)
uv run python -m lerobot.rewards.topreward.compute_rabc_weights \
    --dataset-repo-id lerobot/libero_10_image \
    --num-samples 15 \
    --device cuda
```

Затем отобразите оверлей прогресса для любого эпизода:

```bash
uv run examples/dataset/create_progress_videos.py \
    --repo-id lerobot/libero_10_image \
    --episode 0 \
    --progress-file topreward_progress.parquet \
    --gif
```

## Заметки по конфигурации

### Параметры промпта

Промпт по умолчанию повторяет оригинальную статью:

```text
prompt_prefix = "The above video shows a robot manipulation trajectory that completes the following task: "
prompt_suffix_template = "{instruction} Decide whether the above statement is True or not. The answer is: True"
```

Оба параметра доступны в `TOPRewardConfig` для анализа влияния. Шаблон суффикса **должен** содержать `{instruction}`.

### Шаблон чата

`add_chat_template=True` оборачивает полный промпт (включая инструкцию) в шаблон чата токенизатора перед токенизацией. По умолчанию установлено значение `False`, что соответствует основным экспериментам в исходной статье.

## Ограничения

- Текущая реализация LeRobot поддерживает только **инференс и zero-shot**; метод `forward()` не переопределён, а `is_trainable` возвращает `False`.
- Поддерживается только **семейство Qwen3-VL**; другие клиенты из исходного проекта не входят в область применения.
- TOPReward наследует предвзятость базовой VLM.

## Ссылки

- [Страница проекта TOPReward](https://topreward.github.io/webpage/)
- [статья TOPReward](https://arxiv.org/abs/2602.19313)
- [Исходный код TOPReward](https://github.com/TOPReward/TOPReward)
- [Qwen3-VL-8B-Instruct](https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct)

## Цитирование

```bibtex
@article{chen2026topreward,
  title={TOPReward: Token Probabilities as Hidden Zero-Shot Rewards for Robotics},
  author={Chen, Shirui and Harrison, Cole and Lee, Ying-Chun and Yang, Angela Jin and
          Ren, Zhongzheng and Ratliff, Lillian J and Duan, Jiafei and Fox, Dieter and
          Krishna, Ranjay},
  journal={arXiv preprint arXiv:2602.19313},
  year={2026}
}
```

## Лицензия

Исходная кодовая база TOPReward распространяется по лицензии MIT. Порт для LeRobot следует лицензии LeRobot Apache 2.0; обёрнутые веса Qwen3-VL подчиняются исходной лицензии Qwen.