# π₀-FAST (باي-صفر-فاست)

π₀-FAST هو **نموذج رؤية ولغة وإجراء للتحكم العام في الروبوتات** يستخدم التنبؤ التلقائي بالرمز التالي لنمذجة الإجراءات المستمرة للروبوت.

## نظرة عامة على النموذج

يجمع π₀-FAST بين قوة نماذج الرؤية واللغة مع نهج جديد لتجزئة الإجراءات يُسمى **FAST (تجزئة تسلسل الإجراءات في مجال التردد)**. وهذا يتيح تدريب نماذج VLA ذاتية التراجع على مهام تتطلب مهارة عالية يصعب تنفيذها باستخدام التقسيم القياسي القائم على التجميع، مع تدريب **أسرع حتى 5 أضعاف** مقارنةً بالأساليب القائمة على الانتشار مثل π₀.

<img
  src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/lerobot-pifast.png"
  alt="An overview of Pi0-FAST"
  width="85%"
/>

### لماذا FAST؟

تعتمد الأساليب القياسية لتجزئة أفعال الروبوت على مخططات تقسيم بسيطة لكل بُعد ولكل خطوة زمنية. وعلى الرغم من أن هذا مقبول للأفعال البسيطة، إلا أنه ينهار بسرعة عند التعامل مع المهارات المعقدة والدقيقة التي تتطلب دقة عالية وتحكماً بتردد عالٍ.

تحل FAST هذه المشكلة عن طريق ضغط تسلسلات الإجراءات باستخدام تقنيات معالجة الإشارات، مما يؤدي إلى تسلسل كثيف من رموز الإجراءات يمكن التنبؤ بها بشكل ذاتي التراجع—تمامًا مثل رموز اللغة.

### كيف تعمل عملية الترميز السريع FAST

يضغط مُجزّئ FAST تسلسلات الإجراءات من خلال الخطوات التالية:

1. **التطبيع**: خذ قطعة فعل مستمرة من الشكل `(H, D)` حيث `H` هو الأفق و`D` هو بُعد الفعل. قسّم باستخدام إحدى طرق التطبيع المدعومة (يُوصى باستخدام الفواصل العشرية Quantiles للتعامل مع القيم الشاذة).

2. **تحويل جيب التمام المنفصل (DCT)**: تطبيق DCT (عبر scipy) على كل بُعد من أبعاد الحركة بشكل منفصل. يُعد DCT خوارزمية ضغط تُستخدم بشكل شائع في مشفرات الصور والصوت (JPEG، MP3).

3. **التكميم**: تقريب وإزالة المعاملات غير المهمة لكل بُعد من أبعاد الإجراء، مما ينتج عنه مصفوفة ترددات متناثرة.

4. **Flatten**: تسطيح المصفوفة إلى متجه أحادي البُعد، مع وضع المكونات منخفضة التردد أولاً.

5. **ترميز زوج البايت (BPE)**: تدريب مُجزِّئ BPE لضغط معاملات DCT إلى رموز إجراء كثيفة، مما يحقق عادةً **ضغطًا بنسبة 10x** مقارنةً بأساليب التجزئة السابقة.

يمكن لهذا النهج تحويل **أي نموذج VLM موجود** إلى نموذج VLA من خلال تدريبه على التنبؤ برموز FAST هذه.

## متطلبات التثبيت

1. قم بتثبيت LeRobot باتباع [دليل التثبيت](./installation) الخاص بنا.
2. قم بتثبيت تبعيات π₀-FAST من خلال تشغيل:

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

## تدريب مُرمِّز FAST مخصص

لديك خياران لمُقسِّم FAST:

1. **استخدام مُجزِّئ الرموز المُدرَّب مسبقًا**: تم تدريب مُجزِّئ الرموز `lerobot/fast-action-tokenizer` على أكثر من مليون تسلسل حقيقي لإجراءات الروبوت، ويعمل كمُجزِّئ رموز عام.

2. **تدريب مُجزِّئ خاص بك**: للحصول على أفضل أداء على مجموعة البيانات الخاصة بك، يمكنك ضبط المُجزِّئ على بياناتك الخاصة.

### تدريب مُجزِّئ خاص بك

```bash
lerobot-train-tokenizer \
    --repo_id "user/my-lerobot-dataset" \
    --action_horizon 10 \
    --encoded_dims "0:6" \
    --vocab_size 1024 \
    --scale 10.0 \
    --normalization_mode QUANTILES \
    --output_dir "./my_fast_tokenizer" \
    --push_to_hub true \
    --hub_repo_id "username/my-action-tokenizer"
```

### معلمات المُجزِّئ الرئيسية

| معامل              | الوصف                                                                       | افتراضي      |
| ---------------------- | --------------------------------------------------------------------------------- | ------------ |
| `--repo_id`            | معرّف مستودع مجموعة بيانات LeRobot                                                     | مطلوب     |
| `--action_horizon`     | عدد الإجراءات المستقبلية في كل شريحة                                            | `10`         |
| `--encoded_dims`       | نطاقات الأبعاد مفصولة بفواصل لتشفيرها (على سبيل المثال، `"0:6,7:23"`)                   | `"0:6,7:23"` |
| `--vocab_size`         | حجم مفردات BPE                                                               | `1024`       |
| `--scale`              | معامل توسيع DCT للكم                                               | `10.0`       |
| `--normalization_mode` | وضع التطبيع (`MEAN_STD`، `MIN_MAX`، `QUANTILES`، `QUANTILE10`، `IDENTITY`) | `QUANTILES`  |
| `--sample_fraction`    | نسبة الأجزاء التي يتم أخذ عينة منها في كل حلقة                                          | `0.1`        |

## الاستخدام

للاستخدام π₀-FAST في LeRobot، حدد نوع السياسة على النحو التالي:

```python
policy.type=pi0_fast
```

## التدريب

لتدريب π₀-FAST، يمكنك استخدام سكربت تدريب LeRobot:

```bash
lerobot-train \
    --dataset.repo_id=your_dataset \
    --policy.type=pi0_fast \
    --output_dir=./outputs/pi0fast_training \
    --job_name=pi0fast_training \
    --policy.pretrained_path=lerobot/pi0fast-base \
    --policy.dtype=bfloat16 \
    --policy.gradient_checkpointing=true \
    --policy.chunk_size=10 \
    --policy.n_action_steps=10 \
    --policy.max_action_tokens=256 \
    --steps=100000 \
    --batch_size=4 \
    --policy.device=cuda
```

### معلمات التدريب الرئيسية

| معامل                              | الوصف                                        | افتراضي                         |
| -------------------------------------- | -------------------------------------------------- | ------------------------------- |
| `--policy.gradient_checkpointing=true` | يقلل من استهلاك الذاكرة بشكل كبير أثناء التدريب | `false`                         |
| `--policy.dtype=bfloat16`              | استخدم التدريب بدقة مختلطة من أجل الكفاءة        | `float32`                       |
| `--policy.chunk_size`                  | عدد خطوات الإجراء للتنبؤ (أفق الإجراء) | `50`                            |
| `--policy.n_action_steps`              | عدد خطوات الإجراء التي يجب تنفيذها                  | `50`                            |
| `--policy.max_action_tokens`           | الحد الأقصى لعدد رموز FAST لكل شريحة إجراء     | `256`                           |
| `--policy.action_tokenizer_name`       | مُقسِّم FAST للاستخدام                              | `lerobot/fast-action-tokenizer` |
| `--policy.compile_model=true`          | تفعيل torch.compile لتسريع التدريب           | `false`                         |
| `--policy.optimizer_fused=true`        | استخدم AdamW المدمج؛ يتم تجاهله عند الاستئناف                 | `None`                          |

## الاستدلال

### التخزين المؤقت لـ KV للاستدلال السريع

يدعم π₀-FAST تقنية **تخزين مفاتيح القيم (KV-caching)**، وهي تحسين شائع الاستخدام في استدلال نماذج اللغة الكبيرة. تقوم هذه التقنية بتخزين أزواج المفاتيح والقيم من آلية الانتباه، مما يتجنب الحسابات المكررة أثناء فك الترميز التلقائي التوليد.

```python
# KV-caching is enabled by default
policy.use_kv_cache=true
```

### مثال على الاستدلال

```python
from lerobot.policies.pi0_fast import PI0FastPolicy, PI0FastConfig

# Load the policy
policy = PI0FastPolicy.from_pretrained("your-model-path")

# During inference
actions = policy.predict_action_chunk(batch)
```

## بنية النموذج

يستخدم π₀-FAST معمارية مبنية على PaliGemma:

- **مشفّر الرؤية**: برج SigLIP البصري لفهم الصور
- **نموذج اللغة**: Gemma 2B لمعالجة تعليمات اللغة والتنبؤ برموز الإجراءات

يستقبل النموذج الصور والتعليمات النصية وحالة الروبوت كمدخلات، ويخرج رموز FAST منفصلة يتم فك ترميزها مرة أخرى إلى إجراءات مستمرة.

## خيارات التهيئة

| معامل            | الوصف                                     | افتراضي    |
| -------------------- | ----------------------------------------------- | ---------- |
| `paligemma_variant`  | نوع العمود الفقري لنموذج VLM (`gemma_300m`، `gemma_2b`) | `gemma_2b` |
| `max_state_dim`      | أبعاد متجه الحالة الأقصى (مع التعبئة)         | `32`       |
| `max_action_dim`     | أبعاد متجه الإجراء الأقصى (مع التعبئة)        | `32`       |
| `temperature`        | درجة الحرارة للعينة (0.0 للاستخدام الجشع)           | `0.0`      |
| `max_decoding_steps` | الحد الأقصى لخطوات فك الترميز                          | `256`      |
| `use_kv_cache`       | تفعيل تخزين KV للاستدلال الأسرع          | `true`     |

## المقارنة مع π₀

| ميزة               | π₀                        | π₀-FAST                      |
| --------------------- | ------------------------- | ---------------------------- |
| تمثيل الإجراء | مطابقة التدفق (الانتشار) | رموز التوليد التتابعي (FAST) |
| سرعة التدريب        | 1x                        | **أسرع 5 مرات**                |
| المهارة             | عالية                      | عالية                         |
| طريقة الاستدلال      | إزالة الضوضاء التكرارية       | الترميز التوليفي      |
| التخزين المؤقت لـ KV            | N/A                       | مدعوم                    |

## إعادة إنتاج نتائج π₀Fast

نعيد إنتاج نتائج π₀Fast على معيار LIBERO باستخدام تطبيق LeRobot. نأخذ النموذج الأساسي LeRobot PiFast [lerobot/pi0fast-base](https://huggingface.co/lerobot/pi0fast-base) ونقوم بتدريبه الدقيق لـ 40 ألف خطوة إضافية في bfloat16، مع حجم دفعة يبلغ 256 على 8 وحدات معالجة رسومية H100 باستخدام [مجموعة بيانات HuggingFace LIBERO](https://huggingface.co/datasets/HuggingFaceVLA/libero).

يمكن العثور على النموذج المُحسَّن هنا:

- **π₀Fast LIBERO**: [lerobot/pi0fast-libero](https://huggingface.co/lerobot/pi0fast-libero)

باستخدام أمر التدريب التالي:

```bash
lerobot-train \
  --dataset.repo_id=lerobot/libero \
  --output_dir=outputs/libero_pi0fast \
  --job_name=libero_pi0fast \
  --policy.path=lerobot/pi0fast-base \
  --policy.dtype=bfloat16 \
  --steps=100000 \
  --save_freq=20000 \
  --batch_size=4 \
  --policy.device=cuda \
  --policy.scheduler_warmup_steps=4000 \
  --policy.scheduler_decay_steps=100000 \
  --policy.scheduler_decay_lr=1e-5 \
  --policy.gradient_checkpointing=true \
  --policy.chunk_size=10 \
  --policy.n_action_steps=10 \
  --policy.max_action_tokens=256 \
  --policy.empty_cameras=1
```

ثم نقيّم النموذج المُحسَّن باستخدام تطبيق LeRobot LIBERO، من خلال تنفيذ الأمر التالي:

```bash
tasks="libero_object,libero_spatial,libero_goal,libero_10"
lerobot-eval \
  --policy.path=lerobot/pi0fast-libero \
  --policy.max_action_tokens=256 \
  --env.type=libero \
  --policy.gradient_checkpointing=false \
  --env.task=${tasks} \
  --eval.batch_size=1 \
  --eval.n_episodes=1 \
  --rename_map='{"observation.images.image":"observation.images.base_0_rgb","observation.images.image2":"observation.images.left_wrist_0_rgb"}'
```

**ملاحظة:** قمنا بإعداد `n_action_steps=10`، على غرار التنفيذ الأصلي لـ OpenPI.

### النتائج

نحصل على النتائج التالية على معيار LIBERO:

| النموذج       | LIBERO المكانية | LIBERO Object | هدف LIBERO | LIBERO 10 | المتوسط  |
| ----------- | -------------- | ------------- | ----------- | --------- | -------- |
| **π₀-fast** | 70.0           | 100.0         | 100.0       | 60.0      | **82.5** |

متوفر مجلد مخرجات التقييم الكامل، بما في ذلك مقاطع الفيديو، [هنا](https://drive.google.com/drive/folders/1HXpwPTRm4hx6g1sF2P7OOqGG0TwPU7LQ?usp=sharing)

## رخصة

يتبع هذا النموذج **رخصة Apache 2.0**، بما يتوافق مع مستودع [OpenPI](https://github.com/Physical-Intelligence/openpi) الأصلي.

## المراجع

- [FAST: ترقيم رموز إجراء الروبوت بكفاءة](https://www.physicalintelligence.company/research/fast) - مدونة Physical Intelligence
- [مستودع OpenPI](https://github.com/Physical-Intelligence/openpi) - التنفيذ الأصلي
- [مُقسِّم FAST على Hugging Face](https://huggingface.co/physical-intelligence/fast) - مُقسِّم مُدرَّب مسبقًا