# TOPReward

TOPReward, bir robotik ödül sinyali olarak hazır bir görsel-dil modelinden (VLM) token log-olasılıklarını çıkaran **sıfır atışlı ödül modelidir**. Bir video yörüngesi ve bir görev talimatı verildiğinde, talimatın doğru olma olasılığının VLM log-olasılığını döndürür — ince ayar gerektirmez.

**Makale**: [TOPReward: Token Probabilities as Hidden Zero-Shot Rewards for Robotics](https://arxiv.org/abs/2602.19313) **Proje**: [topreward.github.io](https://topreward.github.io/webpage/) **Özgün kod**: [github.com/TOPReward/TOPReward](https://github.com/TOPReward/TOPReward) **Varsayılan omurga**: [Qwen/Qwen3-VL-8B-Instruct](https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct)

## Genel Bakış

TOPReward, bir robotun bu görevi tamamlamaya çalıştığı **videoya koşullu** olarak, bir görev talimatının ne kadar olası olduğunu genel bir VLM'den sorar. Somut olarak, verildiğinde:

- Bir yörünge videosu (kare dizisi).
- Görev talimatı (ör. _"dolabı aç"_).

şu biçimde bir sohbet istemi oluşturur

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

forwards it through the VLM, label-masks everything except the very last token, and reads back the log-probability of that token — by default the literal `"True"` that closes the suffix template. The resulting `log P("True" | video + prompt + instruction)` is the reward.

Yöntem yalnızca dondurulmuş bir VLM'ye bağlı olduğundan, TOPReward **zero-shot**tir: barındırılacak ince ayarlı ağırlıklar yoktur. LeRobot'taki "model", `transformers`'in `Qwen3VLForConditionalGeneration` sınıfının etrafındaki küçük bir sarmalayıcı ve etiket maskeleme mantığıdır. İşleyici (processor), belirteçleyiciyi (tokeniser) yönetir ve tam sohbet istemini (EO-1/Robometer deseni) oluşturur.

## LeRobot entegrasyonunun kapsadığı konular

- LeRobot üzerinden standart `reward_model.type=topreward` yapılandırması.
- `transformers` `Qwen3VLForConditionalGeneration` API'si üzerinden VLM yükleme.
- İşleyicide prompt derleme + tokenizasyon (yukarıdaki `QwenClient.compute_instruction_reward` ile eşleşir).
- `compute_reward()` örnek başına bir skaler log-olasılık döndürür.
- LeRobot ödül modeli kaydet/yükle — `save_pretrained` yalnızca `config.json` dosyasını yazar (VLM, `vlm_name` ile tanımlanır).
- RA-BC ve overlay için `topreward_progress.parquet` (SARM ile uyumlu şema) yazan çevrimdışı etiketleme betiği.

Mevcut LeRobot portu yalnızca **Qwen3-VL istemcisini** destekler. Diğer üst akış istemcileri (Gemini, OpenAI, Gemma, Molmo) takip eden ekler olarak eklenebilir.

## Kurulum Gereksinimleri

1. LeRobot'u [Yükleme Kılavuzu](./installation)'na göre yükleyin.
2. TOPReward isteğe bağlı ekini yükleyin:

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

veya kaynak kodundan `uv` ile:

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

Bu, `transformers` paketini çeker. TOPReward'ı ilk kez çalıştırdığınızda Hugging Face, VLM ağırlıklarını Hub'dan da indirir (Qwen3-VL-8B-Instruct için ~16 GB). GPU kullanılması şiddetle önerilir.

## Model Girdileri ve Çıktıları

TOPReward şunları bekler:

- Bir yörünge videosu veya kare dizisi.
- Doğal dilde bir görev açıklaması.

LeRobot veri setlerinde ön işleyici şunları okur:

| Yapılandırma alanı              | Varsayılan                     | Anlam                                       |
| ------------------------- | --------------------------- | --------------------------------------------- |
| `reward_model.image_key`  | `observation.images.top`    | TOPReward tarafından kullanılan kamera gözlemi          |
| `reward_model.task_key`   | `task`                      | Görev dizgesi için tamamlayıcı verileri girin |
| `reward_model.max_frames` | `16`                        | Örnekteki kare sayısını sınırla                      |
| `reward_model.fps`        | `2.0`                       | Qwen video işlemcisine geçirilen meta veriler   |
| `reward_model.vlm_name`   | `Qwen/Qwen3-VL-8B-Instruct` | Altta yatan VLM'nin Hugging Face Hub kimliği     |

Model şunu döndürür:

- `compute_reward(batch)`: örnek başına bir log-olasılık. Daha yüksek = görev-video hizalaması daha iyi. `success_threshold` sonluysa, bunun yerine ikili eşiklenmiş değeri döndürür.

## Kullanım

### Ödül modelini doğrudan yükleyin

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

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

### Ödül fabrikasını kullanın

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

Önişleyici, tam istemi (video + önek + talimat soneki) tokenize eder ve Qwen-VL tensörlerini + `prompt_length` değerini `observation.topreward.*` altında yazar. Model bu tensörleri okur, `prompt_length` değerine göre etiket maskesi uygular ve log-olasılık ödülünü çıkarır.

### Çevrimdışı veri seti etiketleme

RA-BC eğitimi ve üst üste bindirme videoları için bir `topreward_progress.parquet` yazın:

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

Ardından herhangi bir bölüm için ilerleme katmanını (progress overlay) görüntüleyin:

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

## Yapılandırma Notları

### Prompt ayarları

Varsayılan istem, üst akış makalesini yansıtır:

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

Her ikisi de ablatasyon için `TOPRewardConfig` üzerinde tanımlıdır. Sonek şablonu **mutlaka** `{instruction}` içermelidir.

### Sohbet şablonu

`add_chat_template=True`, tokenizasyon öncesinde tam istemi (talimat dahil) tokenizer'ın sohbet şablonuyla sarar. Varsayılan değer `False`'dır ve bu, üst akış makalesinin ana deneyleriyle uyumludur.

## Kısıtlamalar

- Mevcut LeRobot portu **sadece çıkarım ve sıfır atış** içindir; `forward()` yeniden tanımlanmamıştır ve `is_trainable` `False` döndürür.
- Yalnızca **Qwen3-VL ailesi** desteklenir; diğer üst akış istemcileri kapsam dışındadır.
- TOPReward, altındaki VLM'nin önyargılarını devralır.

## Referanslar

- [TOPReward proje sayfası](https://topreward.github.io/webpage/)
- [TOPReward makalesi](https://arxiv.org/abs/2602.19313)
- [Özgün TOPReward kodu](https://github.com/TOPReward/TOPReward)
- [Qwen3-VL-8B-Instruct](https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct)

## Atıf

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

## Lisans

Orijinal TOPReward kod tabanı MIT lisanslıdır. LeRobot portu, LeRobot Apache 2.0 lisansını takip eder; sarmalanan Qwen3-VL ağırlıkları ise orijinal Qwen lisansına tabidir.