# TOPReward

TOPReward هو **نموذج مكافأة بلا تدريب مسبق** يستخرج احتمالات السجلات (log-probabilities) للرموز من نموذج لغة-رؤية جاهز (VLM) كإشارة مكافأة روبوتية. عند تقديم مسار فيديو وتعليمات مهمة، يعيد النموذج احتمال السجل (log-likelihood) الذي يعبّر عن صحة التعليمات — دون الحاجة إلى أي ضبط دقيق.

**الورقة**: [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 عامًا عن مدى احتمال تعليمات المهمة، **بشرط وجود فيديو** لروبوت يحاول إتمام تلك المهمة. وبشكل محدد، بالنظر إلى:

- فيديو مسار (سلسلة من الإطارات).
- تعليمات مهمة (مثل _"افتح الدرج"_).

يبني موجه دردشة من الشكل

```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، ثم يُخفي كل الرموز باستثناء الرمز الأخير فقط، ويقرأ قيمة الاحتمال اللوغاريتمي (log-probability) لذلك الرمز — وهو افتراضيًا النص الحرفي `"True"` الذي يُغلق قالب البادئة. القيمة الناتجة `log P("True" | video + prompt + instruction)` هي المكافأة.

بما أن الطريقة تعتمد فقط على نموذج VLM مجمّد، فإن TOPReward **صفرية الإطلاقات**: لا توجد أوزان مُحسَّنة يجب استضافتها. النموذج في LeRobot هو غلاف صغير حول `Qwen3VLForConditionalGeneration` الخاص بـ`transformers` بالإضافة إلى منطق إخفاء التسميات. يتولى المعالج إدارة المُرمِّز وبناء موجه الدردشة الكامل (نمط EO-1/Robometer).

## ما تغطيه تكامل LeRobot

- إعداد `reward_model.type=topreward` القياسي من خلال LeRobot.
- تحميل نماذج الرؤية-اللغة عبر واجهة `Qwen3VLForConditionalGeneration` في مكتبة `transformers`.
- تجميع المُوجِّه + الترميز في المعالج (مطابقًا لـ `QwenClient.compute_instruction_reward` في المنبع).
- `compute_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` | معرّف Hugging Face Hub الخاص بنموذج VLM الأساسي     |

يعيد النموذج:

- `compute_reward(batch)`: احتمال سجل واحد لكل عينة. كلما ارتفعت القيمة، زادت ملاءمة المهمة للفيديو. عندما تكون قيمة `success_threshold` محدودة، تُعاد القيمة الثنائية المُعتَمة بدلاً من ذلك.

## الاستخدام

### This is a heading, so I will use the imperative form to match the instructional tone of the English source.
"Reward model" is a specific technical term in RLHF (Reinforcement Learning from Human Feedback). I will translate it as "نموذج المكافأة" (al-namūdhaj al-mukāfāʾa), which is the standard and most natural translation in Arabic ML literature.
"Directly" translates to "بشكل مباشر" (bishakl mubāshir) or simply "مباشرة" (mubāshira). In the context of loading a model, "مباشرة" is concise and natural.

```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 هو **للاستدلال فقط وبدون تدريب مسبق**؛ حيث لم يتم تجاوز `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 الأصلي.