# FineART-VLA

تستند FineART-VLA إلى **π0.5 من Physical Intelligence** وتنفيذه [openpi](https://github.com/Physical-Intelligence/openpi)، من خلال سياسة [Pi05](./pi05) في LeRobot. وتوسّع هذه الأساس بإضافة رأس لغة PaliGemma قابل للتدريب، ونظام تشغيل بديل بين توليد اللغة وتوليد الإجراء. يمكن لنقطة تحقق واحدة التنبؤ بمهمة فرعية منخفضة المستوى، وتحديث الذاكرة اختيارياً أو الإجابة عن أسئلة بصرية، وشروط خبير الإجراء المطابق للتدفق الخاص بها على ذلك النص.

استخدم Pi05 عندما تكون بحاجة إلى إجراءات مشروطة بالمهمة فقط. استخدم FineART-VLA عندما يجب على السياسة توليد أو استهلاك لغة وسيطة أثناء التنفيذ.

## كيف يختلف FineART-VLA عن Pi05

| القدرة          | Pi05                                                   | FineART-VLA                                                                       |
| ------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------- |
| نموذج الإجراء        | بادئة الرؤية واللغة PaliGemma + خبير الإجراءات Gemma | نفس البنية الأساسية                                                            |
| رأس اللغة       | غير مُدرَّب لتوليد وقت التشغيل                     | أُعيد تفعيلها وتدريبها باستخدام إنتروبيا التبادلية للنص                                    |
| شرطية الإجراء | مهمة الحلقة                                           | المهمة الفرعية منخفضة المستوى النشطة بالإضافة إلى حالة الروبوت المعيارية                              |
| أهداف التدريب    | إجراءات مطابقة التدفق                                  | إجراءات التدفق، النص المحدد بواسطة الوصفة، ورموز إجراءات FAST الاختيارية               |
| متطلب مجموعة البيانات | الصور القياسية، الحالة، الإجراءات والمهمة              | نفس الحقول بالإضافة إلى تعليقات اللغة لكل قدرة لغوية تقوم بتدريبها |
| التنفيذ             | سياسة مباشرة من المهمة إلى الإجراء                           | حلقة هرمية للمهمة ← المهمة الفرعية ← الإجراء، مع ذاكرة اختيارية وVQA           |

يمكن لـ FineART-VLA أن يُهيّئ نفسه من نقطة تحقق Pi05. تبقى بنية السياسة متوافقة، بينما يبني FineART-VLA معالجاته الخاصة حتى لا تُستبدل تسميات الوصفات وتسميات FAST بصمت بواسطة مجموعة معالجات Pi05.

## التثبيت

قم بتثبيت LeRobot مع تبعيات FineART-VLA:

```bash
git clone https://github.com/huggingface/lerobot.git
cd lerobot
python -m venv .venv
source .venv/bin/activate
pip install -e ".[fineart_vla]"
```

يتضمن الإصدار الإضافي `fineart_vla` تبعيات PaliGemma/FAST. لتثبيت نوى التدريب المدمجة الاختيارية على Linux مع بطاقة CUDA GPU، ثبّت `".[fineart_vla_kernels]"` بدلاً من ذلك. يضيف هذا الحزمة `liger-kernel` وحزمة `kernels` من Hugging Face المستخدمة في واجهات FlashRT. تُنشر نوى FlashRT لبعض إصدارات PyTorch فقط؛ في حال عدم وجود بناء مطابق، تسجّل واجهات FlashRT تحذيراً وتعود إلى استخدام PyTorch. يُفعَّل Liger اختيارياً عبر `--policy.use_liger_kernels=true`: فهو يعدّل PaliGemma RoPE/GeGLU في transformers للعملية بأكملها، لذا فإن أي سياسات أخرى مبنية على PaliGemma وتُحمَّل في نفس العملية ستعمل أيضاً مع النوى المدمجة.

## تجهيز البيانات المُعلَّمة باللغة

لا يستنتج FineART-VLA المهام الفرعية المُشرَّفة من مجموعة بيانات LeRobot عادية أثناء التدريب. يجب أن تحتوي مجموعة البيانات على الأهداف اللغوية المستخدمة في الوصفة المختارة في العمودين الاختياريين `language_persistent` و`language_events`.

بحد أدنى، قم بتعليق خط زمني متواصل لـ`subtask` بحيث تحتوي كل إطار تدريب على تعليمات منخفضة المستوى نشطة. أضف `memory`، وVQA، والتعليقات الجانبية، وتعليقات الكلام فقط إذا كانت الوصفة تدرب تلك القدرات.

تضمّن FineART-VLA وصفة افتراضية لها في `FineARTVLAConfig`، تمامًا مثل EO-1. فهي تعيّن 30% للتنبؤ بالمهام عالية المستوى → المهام الفرعية، و70% لتدريب الإجراءات المشروطة بالمهام الفرعية منخفضة المستوى. تمتلك كل إعداد قوامتها الخاصة بالوصفة، وتحمل نقاط التفتيش المحفوظة ذلك القاموس إلى الاستدلال.

استخدم `--policy.recipe_path=/path/to/custom.yaml` لتجاوز الإعداد الافتراضي. تحتفظ الوصفات المشتركة في `src/lerobot/configs/recipes/` بدلالات الفرع الرئيسي؛ ولا يستبدل FineART-VLA بها. للتدريب على الأهداف فقط، استخدم وصفة مضمّنة تحتوي على رسالة مستخدم واحدة منخفضة المستوى تتضمن `${task}`، أو اضبط `recipe=None` وعطّل خسائر النص/FAST لخط أنابيب PI05 العادي.

يعتمد الإعداد الافتراضي على تفكيك الاستدلال إلى π(a|o, subtask)·π(subtask|o, task). تتطلب وصفة تسلسل مشترك مخصصة معالج وقت تشغيل مطابقًا يعرض المهمة والنطاق الذي أنشأه المساعد بنفس العلامات السببية المستخدمة أثناء التدريب. لم يعد مُنشئ الموجه المشترك على جانب السياسة القديم مستخدمًا في التمرير (rollout).

يتولى Rollout تحديد إيقاع التخطيط (`--autosteer_interval_s=3`) والأوامر التفاعلية والجدولة المتزامنة/RTC. أما FineART-VLA فيولّد النص فقط عند الاستعلام عنه؛ فنداءات الإجراءات العادية لا تولّد أي مهمة فرعية أخرى دون علم وقت التشغيل.

لا تُعدّ وسائد الذاكرة/المهام الفرعية المدمجة هي الافتراضية، وتتطلب وصفة مخصصة بالإضافة إلى متحكم وقت تشغيل واعٍ بالذاكرة. حافظ على `memory_scratchpad=false` لتوليد المهام الفرعية العادية؛ وتحتفظ نقاط التفتيش القديمة لوسائد العمل بحارسها الصريح ضد تمرير الاستجابات المدمجة مباشرةً إلى التحكم في الإجراءات.

استخدم `lerobot-annotate` لتوليد هذه الأعمدة. يتضمن المستودع مُشغِّل Hugging Face Jobs يمكنك تعديله لمجموعات البيانات المصدرية والوجهة. لتشغيل التسمية محليًا، ثبّت أولًا `pip install -e ".[annotations]"`:

```bash
HF_TOKEN=hf_... uv run python examples/annotations/run_hf_job.py
```

قبل بدء دورة تدريب طويلة، افحص عدة حلقات وتحقق من أن المهام الفرعية صحيحة زمنيًا وتغطي العرض الكامل. راجع [خط أنابيب التسمية](./annotation_pipeline) للتوليد والتحقق، و[الأعمدة اللغوية والوصفات](./language_and_recipes) للمخطط ومحلل الوصفات.

  إذا لم يحتوي مجموعة البيانات على أعمدة للغة، فإن عرض الوصفة يصبح عملية لا تؤثر على شيء، ويعود FineART-VLA إلى مسار موجه Pi05 العادي. هذا مفيد من أجل التوافق لكنه لا يدرب مخطط اللغة.

## تدريب FineART-VLA

يُهيّئ هذا المثال FineART-VLA من `lerobot/fineart_vla_base`، وهو نقطة التفتيش التي تم تدريبها جزئيًا على FineART للتنبؤ بمهمتها الفرعية التالية، ثم يدرب وصف المهمة الفرعية المدمج بنسبة 70/30. يحمّل `--policy.path` إعداد نقطة التفتيش الأساسية نفسها، لذا يحافظ الضبط الدقيق على تخطيط رموز FAST (`fast_skip_tokens`) والوصف الذي تم تدريب الأساس عليه؛ بينما تتجاوز الأعلام الأخرى `--policy.*` هذا الإعداد.

```bash
lerobot-train \
    --dataset.repo_id=${HF_USER}/my_language_annotated_dataset \
    --policy.path=lerobot/fineart_vla_base \
    --policy.tokenizer_max_length=256 \
    --policy.dtype=bfloat16 \
    --policy.device=cuda \
    --policy.freeze_vision_encoder=false \
    --policy.gradient_checkpointing=true \
    --batch_size=8 \
    --steps=30000 \
    --output_dir=outputs/fineart_vla \
    --job_name=fineart_vla \
    --trackio.enable=true
```

ابدأ بتشغيل صغير وتأكد من لوحة تحكم Trackio من أن الخسائر تتصرف كما هو متوقع قبل التوسع.

لبدء من نقطة التفتيش الأساسية لـ PI0.5 بدلاً من ذلك، احتفظ بإعداد FineART-VLA الافتراضي وجعل `--policy.pretrained_path` يشير إليها: `--policy.type=fineart_vla --policy.pretrained_path=lerobot/pi05_base`. يتم تحويل الأوزان بصيغة OpenPI عند التحميل، وتبدأ خسائر النص وFAST من رأس اللغة الخاص بـ PaliGemma بدلاً من تدريب FineART المتوسط.

### أدوات التحكم الرئيسية في التدريب

| خيار                           | افتراضي | الغرض                                                             |
| -------------------------------- | ------: | ------------------------------------------------------------------- |
| `policy.recipe_path`             |  `None` | تجاوز اختياري لوصفة المهام الفرعية المضمنة 70/30              |
| `policy.text_loss_weight`        |   `1.0` | وزن إنتروبيا المتقاطعة لرأس اللغة؛ `0` يعطّل تدريب النص      |
| `policy.flow_loss_weight`        |  `10.0` | وزن خسارة تدفق الإجراء المستمر                                  |
| `policy.enable_fast_action_loss` |  `true` | يضيف إشراف رموز إجراء منفصلة FAST                         |
| `policy.fast_action_loss_weight` |   `1.0` | وزن دالة الخسارة المتقاطعة (Cross-Entropy) في FAST                                           |
| `policy.knowledge_insulation`    |  `true` | يمنع تدفق تدرجات خسارة الإجراء عبر مسار K/V الخاص بنموذج اللغة المرئي               |
| `policy.flow_num_repeats`        |     `5` | يعيد استخدام بادئة واحدة لنموذج اللغة البصري (VLM) لأهداف إزالة الضوضاء المستقلة             |
| `policy.lm_head_lr_scale`        |   `1.0` | يُقيّم معدل تعلّم رأس اللغة؛ `1.0` يستخدم المعدل الأساسي        |
| `policy.fast_skip_tokens`        |  `1152` | FAST id offset; يتخطى `<seg>`+`<loc>` حتى لا تتعارض VQA و FAST |

يضع `fast_skip_tokens=1152` رموز FAST خارج نطاق `<loc>` الخاص بـ PaliGemma. الاتفاق المتبع في pi0-FAST ضمن openpi هو `128` (حيث تشغل رموز FAST معرّفات `<loc>`)؛ استخدم هذه القيمة فقط للبقاء متوافقاً مع الأوزان مع نقاط التفتيش المدرّبة على هذا النحو، وتجنّب دمجها مع وصفة VQA، حيث ستشارك أهداف `<loc>` الخاصة بها صفوف التضمين مع رموز FAST.

أوزان الدالة الخاسرة هي نقاط انطلاق وليست ثوابت مستقلة عن مجموعة البيانات. تتبّع خسارة التدفق وخسائر النص/FAST بشكل منفصل، وافحص المهام الفرعية المولّدة بدلاً من اختيار نقطة تفتيش بناءً على الخسارة الإجمالية وحدها.

### مُرمِّز FAST الخاص بمجموعة البيانات

بشكل افتراضي (`--policy.auto_fit_fast_tokenizer=true`)، يقوم التدريب بملاءمة مُرمِّز FAST على مجموعة بيانات التدريب، بدءًا من `--policy.action_tokenizer_name`، ويُخزّنه مؤقتًا في `--policy.fast_tokenizer_cache_dir`. ينطبق هذا أيضًا عند الضبط الدقيق من نقطة تفتيش مثل `lerobot/fineart_vla_base`، بحيث تتطابق أهداف FAST مع توزيع الإجراءات الخاص بالروبوت الجديد. يُحفظ المُرمِّز المُلائم داخل مُخرجات المعالج الخاصة بنقطة التفتيش، لذا يعيد الاستدلال استخدامه. اضبط `--policy.auto_fit_fast_tokenizer=false` لاستخدام `action_tokenizer_name` دون تغيير.

## أداء التدريب

يستخدم FineART-VLA مسارات تدريب مُحسّنة افتراضيًا:

- تكرار الدفعات لأهداف التدفق والتوقعات البادئة بدلاً من إعادة تشغيل العمليات الصغيرة في بايثون؛
- تخزّن أقنعة الإجراءات الثابتة وتُحسب مواضع RoPE مرة واحدة لكل تمريرة أمامية؛
- يختار تنفيذ إنتروبيا المتقاطعة النصية/السريعة من الشكل المستهدف والتخلخل؛
- يتخطّى التدرّج العكسي الميت رياضياً في نماذج اللغة البصرية/الرؤية على الدفعات المعزولة معرفياً والتي تعتمد على التدفق فقط؛
- يستخدم نقاط التفتيش الأصلية لطبقة SigLIP غير المعاد دخولها عند تمكين نقاط التفتيش للتدرج؛ و
- يحافظ على نواة Liger RoPE/GeGLU مع تجنب رقعة LayerNorm الأبطأ عند أشكال SigLIP.

تكون واجهات التدريب الاختيارية معطّلة افتراضيًا:

| خيار                                 | متى تجرّبه                                                                                    |
| -------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `policy.use_flashrt_adarms=true`       | دمج تطبيع RMSNorm التكيفي والبقايا البوابة على وحدات معالجة الرسوميات CUDA المدعومة                                 |
| `policy.use_compiled_text_ce=true`     | حاويات CE المادية المُجمّعة                                                            |
| `policy.use_compiled_vision=true`      | يتم تجميع الرؤية فقط عندما لا تحتوي عملية الرؤية على تدرجات                                        |
| `policy.use_flex_attention=true`       | إعدادات CUDA المُحلَّلة مع عزل المعرفة و`flow_num_repeats > 1`؛ وإلا يُستخدم SDPA |
| `policy.use_manual_attention=true`     | الأشكال المُحدَّدة صراحةً حيث يكون الانتباه المادي أسرع                                 |
| `policy.manual_attention_scope=action` | يقيّد الانتباه اليدوي باستعلامات الإجراءات                                                      |

لا تفعّل كل واجهة خلفية بشكل أعمى. انتباه Flex وانتباه اليدوي متنافيان، وبدائل انتباه/AdaRMS تتطلب عزلًا للمعرفة. الإعداد الأفضل في الاختبارات القياسية استخدم نص CE المُجمَّع وFlashRT AdaRMS، مع تفعيل انتباه Flex/اليدوي وإيقاف الرؤية المُجمَّعة.

## أداء الاستدلال

يحتوي FineART-VLA على حلقتي استنتاج، وكلاهما يتجنبان الترميز المتكرر للمقدمة متعددة الوسائط المكلفة:

1. يقوم **إزالة الضوضاء من الإجراء** بتشفير بادئة الصورة/اللغة مرة واحدة، وإعادة استخدام ذاكرة التخزين المؤقت KV الخاصة بها عبر خطوات التدفق، وبناء أقنعة لاحقة الإجراء على الجهاز، وقص اللاحقة المؤقتة K/V بدلاً من استنساخ ذاكرة التخزين المؤقت للبادئة. كما ينشئ جدول خطوات الزمن على الجهاز مرة واحدة لكل شريحة، مع الحفاظ على حسابات خطوات الزمن التاريخية. لا تُثبت هذه التفاصيل التنفيذية تسريعًا شاملًا من البداية إلى النهاية دون إجراء اختبارات أداء.
2. يستخدم **فك ترميز اللغة** التخزين المؤقت التلقائي المتسلسل لـ KV، بحيث يعالج كل رمز جديد الرمز المُستخرج فقط مقابل مفاتيح الصورة/اللغة المخزنة مؤقتًا بدلاً من إعادة تشغيل البادئة الكاملة.

يعمل وقت التشغيل المشترك على اللغة والإجراءات بمعدلات مختلفة. قم بزيادة `--autosteer_interval_s` عندما يبقى المهام الفرعية صالحة لفترة أطول، أو استخدم `/subtask` لتزويد تعليمات مباشرة دون توليد اللغة. يقلل الفاصل الزمني الأطول من تكلفة التوليد لكنه يبطئ أيضاً إعادة التخطيط.

## تشغيل نقطة تفتيش

استخدم `lerobot-rollout` مع تكوين الروبوت/الكاميرا المطابق لنقطة التفتيش، و`--interactive=true`، و`--autosteer_interval_s=3`. اختر `--inference.type=sync` أو `--inference.type=rtc`. في الطرفية التفاعلية، يفعّل `/autosteer <goal>` المهام الفرعية المولّدة، ويوفّر `/subtask <instruction>` مهمة فرعية واحدة يدوياً، ويبدأ `/start` التحكم بالروبوت. راجع [التحكم اللغوي التفاعلي](./inference#interactive-language-control) للحصول على إعدادات العتاد الكاملة، وسلوك السلامة، وتحكمات التسجيل. خيارات سطر الأوامر السابقة `--sim`، و`--mode`، و`--high_level_hz` ليست جزءاً من هذه الواجهة.

## استكشاف الأخطاء وإصلاحها

- **تدرّجات خسارة التدفق الكبيرة:** يعمل FineART-VLA على تشغيل انتباه البادئة/الإجراء المشترك مع تعطيل KI على الخلفية الرياضية لـ PyTorch SDPA باستخدام حسابات انتباه بدقة FP32، مع إعادة تحويل مخرجه إلى نوع البيانات الخاص بالنموذج (بينما يحافظ PI0.5 القياسي على انتباهه الجائر). يتجنّب هذا النهج انتباه الدقة المنخفضة، الذي قد يُزعزع استقرار التدرّجات عند خطوات تدفق منخفضة مع تنشيطات استعلام/مفتاح كبيرة. تبقى نقاط التفتيش الحالية وطبقات التطبيع دون تغيير؛ كما يستمر التدريب مع تعطيل KI عبر مفاتيح وقيم نموذج اللغة البصرية. راقب `flow_loss` و`text_loss` ومنظومة التدرّج قبل القص بشكل منفصل، بدلاً من الاعتماد على الخسارة الإجمالية المنتهية وحدها.
- **لا فقدان للنص أو مهام فرعية مولّدة:** تأكد من أن الوصفة المختارة قادرة على ربط التعليقات على الإطارات المُستخرجة وأن `policy.text_loss_weight > 0`.
- **تبدو المهام الفرعية معقولة لكن الإجراءات تفشل:** تحقق من حدود المهام الفرعية، وإحصاءات الحالة/الإجراء المعيارية، ووجود عينات الوصفة منخفضة المستوى.
- **ينهار النص إلى رموز متكررة أو رموز موقع:** افحص تغطية النص المستهدف، ومعدل تعلم رأس اللغة، والتوازن بين خسائر التدفق وFAST والنص.
- **نفاد الذاكرة:** قلّل حجم الدفعة (batch size) أولاً، ثم فعّل نقطة التفتيش للتدرجات (gradient checkpointing). لا تفعّل واجهات الانتباه (attention backends) المُجمّعة أو البديلة دون قياس استهلاكها من الذاكرة بناءً على عدد الكاميرات لديك.
- **تدريج النشر:** افصل زمن استجابة الإجراء عن زمن استجابة اللغة، ثم اضبط `--autosteer_interval_s` (تكرار توليد مهمة فرعية جديدة) و`--policy.num_inference_steps` (خطوات إزالة الضوضاء في التدفق).

## الاستشهاد

إذا كنت تستخدم FineART-VLA أو مجموعة بيانات FineART، فيرجى الاستشهاد بما يلي:

```bibtex
@misc{choghari2026fineart,
  title  = {FineART: Fine-Grained Annotated Robotic Trajectory Dataset and Vision-Language-Action Model for Bimanual Manipulation},
  author = {Choghari, Jade and Kooijmans, Pepijn and Agarwal, Mansi and Ciftci, Yusuf Umut and Doriwala, Aseem and Weaver, Catherine and Sivapurapu, Mouli and Yang, Kai and Lee, Jackson and Wolf, Thomas and Mannam, Pragna},
  year   = {2026},
}
```

تستند FineART-VLA إلى [π₀.₅](https://arxiv.org/abs/2504.16054) و[عزل المعرفة](https://arxiv.org/abs/2505.23705) من Physical Intelligence.

## رخصة

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