# سياسة MolmoAct2

MolmoAct2 هو تنفيذ سياسة LeRobot لنموذج [MolmoAct2](https://allenai.org/blog/molmoact2)، وقد تم نقله إلى واجهات التدريب والتقييم وحفظ النقاط المرجعية والمجموعات البيانات في LeRobot لتسهيل استخدامه مع مجموعات بيانات LeRobot.

تدعم هذه النسخة الحالية التدريب والتقييم لنموذج MolmoAct2 العادي. أما MolmoAct2-Think، الذي يدعم الاستدلال العمق التكيفي، فلم يُدرج بعد في سياسة LeRobot هذه.

للوصول إلى كود التدريب الأصلي MolmoAct2 المستخدم في التجارب المبلّغ عنها في الورقة، راجع [allenai/molmoact2](https://github.com/allenai/molmoact2).

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

قم بتثبيت LeRobot مع تبعيات MolmoAct2 الاختيارية:

```bash
uv sync --locked --extra molmoact2
```

لتشغيل النماذج في هذا المستودع، تحتاج إلى معالج رسومي من NVIDIA. مسار الدقة المختلطة الحالي يخزّن خبير الإجراء الكامل في fp32 ومصفوفات VLM الكبيرة في bf16. `policy.compile_model=true` يجمّع كتل خبير الإجراء اختيارياً مع إبقاء VLM وبرج الرؤية والموصّل وغلاف السياسة في وضع eager. اجتاز هذا الحدّ فحوصات التكافؤ للمخرجات عند نفس نقطة البداية، والتدرّجات، وتحديثات المُحسِّن؛ بينما لم يجتز ذلك عند تجميع مسار VLM في bf16.

يزيد التدريب متعدد المعالجات الرسومية عبر `accelerate` من معدل الإنتاج والحجم الكلي للدفعات. وقد خضع هذا المسار للاختبار في عمليات تشغيل GB200 على عقدتين ومعالجات رسومية ثمانية، لكن هذا الإصدار من LeRobot لا يكشف عن مسار التدريب الأصلي لمولمو أكت 2 `fsdp_devices` القائم على تقسيم النموذج. أنتج تشغيل GB200 على معالج رسومي واحد بعرضَي موجهين حقيقيين اثنين رسمًا واحدًا للمخطط الإجراءي المُجمَّع دون أي انقطاعات في المخطط، مع ذروة ذاكرة متطابقة قدرها 55.15 GiB مقارنةً بالتنفيذ المباشر، وتسريع معتدل في الحالة المستقرة. تعامل مع هذه النتائج على أنها فحوصات تنفيذية وليس كمطالبات قابلة للنقل لمعدل الإنتاج أو تقدير الوقت.

تم اختبار المستودع مع Ubuntu 22.04.

## الاستخدام

للاستخدام MolmoAct2 في إعدادات تدريب LeRobot، اضبط:

```bash
--policy.type=molmoact2
```

## التدريب

يمكن ضبط MolmoAct2 بشكل دقيق انطلاقًا من نقطة التفتيش الصادرة بصيغة Hugging Face الخاصة بـ MolmoAct2، أو من نقطة تفتيش محفوظة مسبقًا بواسطة LeRobot. تستخدم كلا المسارَي نفس حلقة تدريب LeRobot، وتحويلات مجموعة البيانات، وحفظ نقاط التفتيش، والتسجيل. والفرق الوحيد هو كيفية تحميل أوزان السياسة الأولية وحالة المعالج.

يعطّل LeRobot زيادة صور البيانات (image augmentation) افتراضيًا. احتفظ بـ `--dataset.image_transforms.enable=true` في أوامر تدريب MolmoAct2. وصفة التحويل الأصلية الخاصة بـ MolmoAct2 ليست هي الإعداد الافتراضي العام للتحويلات في LeRobot، لذا فإن الأمر الأول يثبّت أيضًا قصّ 95%، ودوران 5 درجات، وتذبذب الألوان (color jitter) بشكل صريح. بالإضافة إلى ذلك، تطبّق الوصفة الأصلية ضبابية غاوسية (Gaussian blur) باحتمالية 0.2؛ ولا يمكن لإعداد مجموعة التحويلات الفرعية العامة في LeRobot التعبير عن هذا التحويل الرابع الاختياري دون أن يؤدي ذلك أحيانًا إلى إسقاط أحد التحويلات الثلاثة المطلوبة.

### التدريب باستخدام الأوزان الأصلية لـ MolmoAct2

استخدم `policy.checkpoint_path` عند البدء من نقطة تفتيش MolmoAct2 منشورة، مثل `allenai/MolmoAct2` أو `allenai/MolmoAct2-LIBERO`. سيقوم LeRobot بتحميل ملفات نموذج HF الأصلية، ثم بناء معالج سياسة خاص به من بيانات مجموعة البيانات وخيارات السياسة أدناه.

يُظهر الأمر أدناه الضبط الكامل على مجموعة بيانات LIBERO المدمجة من نقطة التفتيش الأساسية المُصدَّرة. يستخدم الأمر تحميل النموذج بصيغة bf16، و8 خطوات تدفق، وإحصاءات LIBERO الرسمية للنِّسَب المئوية، وتوسيع الصور، ومسار LeRobot لنقاط التفتيس والتسجيل. لا تُبدِل نِسَب البيانات الوصفية التقريبية الخاصة بـ`lerobot/libero` بالنِّسَب المئوية المُصدَّرة في`norm_stats.json`؛ فقيم q01/q99 فيها ليست متطابقة.

```bash
accelerate launch \
  --num_processes=8 \
  --mixed_precision=bf16 \
  -m lerobot.scripts.lerobot_train \
  --dataset.repo_id=lerobot/libero \
  --dataset.root=/path/to/lerobot/libero \
  --dataset.video_backend=pyav \
  --dataset.image_transforms.enable=true \
  --dataset.image_transforms.max_num_transforms=3 \
  --dataset.image_transforms.random_order=false \
  --dataset.image_transforms.tfs='{"crop":{"weight":1.0,"type":"RandomResizedCrop","kwargs":{"size":[256,256],"scale":[0.9025,0.9025],"ratio":[1.0,1.0]}},"rotation":{"weight":1.0,"type":"RandomRotation","kwargs":{"degrees":[-5.0,5.0],"interpolation":2}},"color":{"weight":1.0,"type":"ColorJitter","kwargs":{"brightness":0.2,"contrast":[0.8,1.2],"saturation":[0.8,1.2],"hue":0.05}}}' \
  --policy.type=molmoact2 \
  --policy.checkpoint_path=allenai/MolmoAct2 \
  --policy.device=cuda \
  --policy.action_mode=continuous \
  --policy.norm_tag=libero \
  --policy.norm_stats_path=/path/to/MolmoAct2-LIBERO/norm_stats.json \
  --policy.train_mode_vlm=fft \
  --policy.chunk_size=10 \
  --policy.n_action_steps=10 \
  --policy.setup_type="single franka robotic arm in libero" \
  --policy.control_mode="delta end-effector pose" \
  --policy.image_keys='["observation.images.image","observation.images.image2"]' \
  --policy.dtype=bfloat16 \
  --policy.num_flow_timesteps=8 \
  --policy.gradient_checkpointing=true \
  --policy.compile_model=true \
  --policy.freeze_embedding=true \
  --policy.normalize_gripper=false \
  --policy.enable_knowledge_insulation=false \
  --policy.push_to_hub=false \
  --trackio.enable=true \
  --trackio.project=<trackio_project> \
  --job_name=<job_name> \
  --output_dir=outputs/<job_name> \
  --steps=10000 \
  --batch_size=32 \
  --num_workers=4 \
  --log_freq=20 \
  --env_eval_freq=-1 \
  --save_checkpoint=true \
  --save_freq=2000
```

### التدريب باستخدام وزن LeRobot MolmoAct2

استخدم `policy.path` عند البدء من نقطة تفتيش MolmoAct2 تم حفظها بواسطة LeRobot، سواء من مجلد `pretrained_model` محلي أو من Hub. يؤدي هذا إلى استعادة إعدادات سياسة LeRobot المحفوظة، وأوزان النموذج، والمعالج، وإحصاءات التطبيع. يمكنك ما زال تجاوز خيارات وقت التدريب مثل `batch_size` أو `steps` أو `policy.action_mode`. تحميل نقاط التفتيش صارم ويحافظ على بنية FFT أو LoRA المحفوظة، لذا لا تتجاوز `policy.train_mode_vlm` عند استخدام `policy.path`. لبدء تشغيل LoRA جديد، قم بالمبادرة من أوزان HF باستخدام `policy.checkpoint_path` بدلاً من ذلك، على سبيل المثال باستخدام `--policy.type=molmoact2` و`--policy.checkpoint_path=allenai/MolmoAct2` و`--policy.train_mode_vlm=lora`.

```bash
accelerate launch \
  --num_processes=8 \
  --mixed_precision=bf16 \
  -m lerobot.scripts.lerobot_train \
  --dataset.repo_id=allenai/MolmoAct2-LIBERO-Dataset \
  --dataset.root=/path/to/lerobot/data/allenai/MolmoAct2-LIBERO-Dataset \
  --dataset.video_backend=pyav \
  --dataset.image_transforms.enable=true \
  --policy.path=/path/to/pretrained_model \
  --policy.device=cuda \
  --policy.action_mode=continuous \
  --policy.chunk_size=10 \
  --policy.n_action_steps=10 \
  --policy.dtype=bfloat16 \
  --policy.num_flow_timesteps=8 \
  --policy.gradient_checkpointing=true \
  --policy.compile_model=true \
  --trackio.enable=true \
  --trackio.project=<trackio_project> \
  --job_name=<job_name> \
  --output_dir=outputs/<job_name> \
  --steps=10000 \
  --batch_size=32 \
  --num_workers=4 \
  --log_freq=20 \
  --env_eval_freq=-1 \
  --save_checkpoint=true \
  --save_freq=2000
```

### الممارسات الشائعة

لإجراء الضبط الدقيق على مجموعة بيانات صغيرة نسبيًا، مثل مجموعة LIBERO الواحدة أو مجموعة بيانات من العالم الحقيقي تحتوي على أقل من 200 عرضًا توضيحيًا، يُعد حجم الدفعة العالمية بين 16 و32 نقطة انطلاق جيدة. في هذه الإعدادات، نوصي باستخدام `policy.train_mode_vlm=lora` (الافتراضي)، والذي يمنح عادةً أداءً مماثلًا أو حتى أفضل من `fft`. بالإضافة إلى ذلك، يُعد `policy.train_mode_vlm=freeze` خيارًا عمليًا أيضًا. في جميع الأوضاع، نحتفظ عمدًا بخبير الإجراء قابلًا للتدريب بالكامل، وهو ما وجدنا أنه أمر حاسم لأداء النموذج. لمجموعات بيانات الضبط الدقيق الأكبر حجمًا، يُفضَّل عادةً استخدام أحجام دفعات عالمية أكبر والضبط الدقيق الكامل لنموذج VLM (`policy.train_mode_vlm=fft`).

### خيارات السياسة الشائعة

- `policy.checkpoint_path`: نقطة التفتيش الأصلية من MolmoAct2 HF التي سيتم البدء من خلالها. استخدم هذا الخيار للأوزان المُطلَقة من MolmoAct2.
- `policy.path`: نقطة التفتيش الخاصة بـ LeRobot التي سيتم البدء منها. استخدم هذا للنقاط التي تم إنشاؤها بواسطة تدريب LeRobot.
- `policy.action_mode`: هدف التدريب، وهو أحد `continuous` أو `discrete` أو `both`. يستخدم ضبط MolmoAct2 الرسمي للروبوتات `continuous`. تحتفظ نقاط التفتيش المنشورة بأوزان الإجراءات المنفصلة؛ ويتوفر `both` كتجريد صريح يجمع بين مطابقة التدفق المشترك ورمز الإجراء.
- `policy.train_mode_vlm`: يتحكم في وضع الضبط الدقيق لنموذج VLM، وهو أحد `fft` أو `lora` أو `freeze`. يقوم `fft` بإجراء ضبط دقيق كامل لنموذج VLM، بينما يقوم `lora` بتدريب محولات LoRA على الطبقات الخطية لنموذج VLM، أما `freeze` فيجمّد نموذج VLM. يتم ضبط خبير الإجراء ضبطًا دقيقًا كاملًا في الأوضاع الثلاثة. القيمة الافتراضية هي `lora`. يتطلب وضع `freeze` تعيين `policy.action_mode=continuous`.
- `policy.enable_knowledge_insulation`: عند تعيين `true`، يتم فصل حالات K/V لسياق خبير الإجراء قبل خسارة الإجراء. القيمة الافتراضية هي `false`.
- `policy.chunk_size`: أفق الإجراء الذي تستخدمه السياسة. بالنسبة إلى LIBERO نستخدم `10`. يستبدل هذا الإصدار من LeRobot قيمة `max_action_horizon` في نقطة الحفظ المحمّلة بهذه القيمة.
- `policy.n_action_steps`: عدد الإجراءات المستهلكة من كل كتلة متوقعة قبل الاستعلام عن السياسة مرة أخرى. بالنسبة إلى LIBERO، اضبطه على `chunk_size`.
- `policy.setup_type`: نص يُدرج في الأمر الوصفي (prompt) لوصف الروبوت والمشهد، مثل `single franka robotic arm in libero`. توجد أمثلة إضافية في إدخالات `metadata_by_tag` ضمن [`norm_stats.json`](https://huggingface.co/allenai/MolmoAct2/blob/main/norm_stats.json).
- `policy.control_mode`: نص يُدرج في الاستعلام (prompt) لوصف مساحة الإجراءات، مثل `delta end-effector pose` أو `absolute joint pose`.
- `policy.image_keys`: مفاتيح ملاحظات الصور المرتبة من LeRobot التي تُمرَّر إلى المعالج.
- `policy.dtype`: مفتاح دقة على غرار Pi0.5. يستخدم `bfloat16` التحويل التلقائي والتخزين بصيغة bf16 لمصفوفات VLM الكبيرة مع الإبقاء على خبير الإجراءات الكامل والوحدات الحساسة رقمياً بصيغة fp32. يعطّل `float32` التحويل التلقائي ويُبقي النموذج كاملاً بصيغة fp32. يختلف ملف `bfloat16` منخفض الذاكرة عمداً عن تشغيل AMP الأصلي لمولمو أكت 2 بصيغة FP32-master: تتبع لحظات AdamW صيغة التخزين الخاصة بكل معامل، وبالتالي فإن معاملات VLM الكبيرة بصيغة bf16 تمتلك لحظات بصيغة bf16 أيضاً. يقوم الضبط الدقيق الكامل بتخصيص كسول لمصفوفة تعويض واحدة بصيغة bf16 لكل معامل bf16 يحمل تدرجات، بحيث تُنقل التحديثات الأصغر من وحدة أقل خانة (ULP) للمعامل إلى الخطوات اللاحقة. هذا ليس نسخة رئيسية بصيغة fp32. تحتفظ محولات LoRA، وخبير الإجراءات، والوحدات الحساسة صراحةً بمعاملات وحالة مُحسِّن بصيغة fp32؛ بينما لا تُخصَّص أي مصفوفة تعويض للمجمدات VLM في وضع LoRA.
- `policy.compile_model`: يُفعّل مسار `torch.compile` على مستوى الكتل في MolmoAct2. كلٌّ من الضبط الدقيق الكامل وLoRA يجمّعان كتل محوّل خبير الأفعال فقط. التنفيذ الفوري (Eager) لمكوّنات VLM/ViT/الوصلة يتجنّب انحراف التفعيلات والتدرّجات من نوع BF16 الناتج عن المُجمِّع، مع الحفاظ على التسريع لمسار الأفعال المُقيَّم في كل خطوة تدفّق. كما يُوجَّه Inductor إلى الحفاظ على حدود التحويل الفوري (downcast/upcast) من النوع BF16 عبر العمليات المُدمجة. هذه حدّ دقّة آمن واحد ثابت، ولا يضيف خيار تجميع آخر. التجميع معطَّل افتراضيًا؛ فعِّله لتدريبات GPU طويلة. تستخدم كتل الأفعال استراتيجية الشكل التلقائية في PyTorch. مع نقطة التفتيش للتدرّجات (gradient checkpointing)، يُعلَّم بُعد تسلسل سياق المُشفِّر المتغيّر فقط كديناميكي؛ بينما تبقى حجم الدفعة، أفق الأفعال، وعدد خطوات التدفّق ثابتة. في ذلك الوضع، يُعطَّل إعادة ترتيب ذاكرة التخزين المؤقت للرسوم في Dynamo ومُقسِّم الرسوم الإضافي الخاص بـ DDP، بحيث تختار إعادة الحساب للخلف (backward) نفس رسم الكتلة المستخدم في الأمام (forward). تُملأ تسلسلات النص/الأفعال المحلية للدفحة من اليسار إلى مضاعف داخلي من 8 قبل إدراج BOS. هذا يضيف بحدٍّ أقصى سبعة رموز مقنّعة، مع تقليل حادّ لوقت الإحماء الخاص بالتجميع لكل شكل؛ وهو ليس خيارًا واجهته للمستخدم.
- `policy.num_flow_timesteps`: عدد خطوات مطابقة التدفق المُستخرجة لكل مثال أثناء التدريب. نستخدم `8` للضبط الدقيق.
- `policy.num_inference_steps`: تجاوز اختياري لخطوات توليد الإجراءات المستمرة أثناء الاستدلال.
- `policy.gradient_checkpointing`: يُفعّل نقطة التفتيش في مسار النموذج اللغوي البصري/الإجراء لتقليل ذاكرة التنشيط.
- `policy.freeze_embedding`: يجمّد التضمينات المدخلة. القيمة الافتراضية هي `true`.
- `policy.normalize_gripper`: يتحكم في ما إذا كانت أبعاد الماسك (gripper) تُدرج في تطبيع الفواصل العشرية (quantile) للحالة/الإجراء. القيمة الافتراضية هي `false`.
- `policy.normalize_language`: يُطبّع نصوص المهام قبل بناء الموجه. القيمة الافتراضية هي `true`.
- `policy.mask_action_dim_padding`: يُخفي الأبعاد المُكمّلة في خسارة التدفق. تستخدم نقاط الفحص المُصدَّرة `policy.expected_max_action_dim=32`.
- `policy.max_sequence_length`: حد يدوي اختياري للترتيب. اتركه غير مضبوط ليتم استنتاجه من الصور، وأبعاد الحالة، وأبعاد الإجراء، وأفق الإجراء، ووضع الإجراءات المنفصلة.

### معدلات التعلم

يستخدم MolmoAct2 معدلات تعلم لمجموعات المعلمات لمطابقة تجارب الضبط الدقيق الأصلية الخاصة بـ MolmoAct2.

- يستخدم الضبط الكامل `policy.optimizer_lr=1e-5` لنموذج VLM، و`policy.optimizer_vit_lr=5e-6` لبرج الرؤية، و`policy.optimizer_connector_lr=5e-6` لطبقات الوسيط الخاصة بالصور، و`policy.optimizer_action_expert_lr=5e-5` لخبير الإجراءات.
- تُضبط مجموعات معاملات LoRA الخاصة بنموذج VLM والرؤية والموصّل على `5e-5` عندما يكون `policy.train_mode_vlm=lora`؛ بينما يُضبط خبير الإجراء بالكامل لا يزال باستخدام `policy.optimizer_action_expert_lr`.
- يستخدم التدريب الدقيق لنموذج Frozen-VLM الإعداد `policy.train_mode_vlm=freeze`، ويُدرب خبير الإجراءات فقط، ويستخدم `policy.optimizer_action_expert_lr=5e-5`.
- `policy.optimizer_grad_clip_norm` يُطبَّق بشكل مستقل على مجموعات معاملات LLM وبرج الرؤية وموصل الصور وخبير الإجراءات، بما يتوافق مع المُحسِّن الأصلي في MolmoAct2. إنه ليس معيار تدرّج واحدًا على مستوى النموذج ككل.

يمكنك تجاوز معدلات التعلم الخاصة بالتدريب الكامل وخبير الإجراءات باستخدام `policy.optimizer_lr` و`policy.optimizer_vit_lr` و`policy.optimizer_connector_lr` و`policy.optimizer_action_expert_lr`. يمكن تغيير إعدادات المجدول باستخدام `policy.scheduler_warmup_steps` و`policy.scheduler_decay_steps` و`policy.scheduler_decay_lr`. يتطابق أفق التلاشي الافتراضي البالغ 24,000 خطوة مع وصفة [`train_lerobot.py`](https://github.com/allenai/molmoact2/blob/5aac8f8a1180d79757ce500f819a02217079811c/experiments/launch_scripts/train_lerobot.py#L867-L868) الرسمية.

### إحصاءات الفواصل العشرية للمجموعة

يعتمد MolmoAct2 افتراضيًا على تطبيع الكمّات (quantile normalization) لميزات الحالة والإجراء. إذا لم يتم تحويل مجموعة بياناتك باستخدام إحصاءات الكمّات، يمكنك إضافتها باستخدام:

```bash
python src/lerobot/scripts/augment_dataset_quantile_stats.py \
  --repo-id=your_dataset
```

تسجيل واستئناف ودمج مقاييس التجميع (quantiles) من ملخصات كل حلقة، بحيث يحتوي `meta/stats.json` في النهاية على غلاف محافظ (`min` لـ `q <= 50`، و`max` لـ `q > 50`) بدلاً من مقاييس التجميع الخاصة بالبيانات الكاملة. لتقدير الأخيرة، امسح كل حلقة باستخدام هيستوغرام متحرك:

```bash
python src/lerobot/scripts/augment_dataset_quantile_stats.py \
  --repo-id=your_dataset \
  --overwrite \
  --skip-images
```

يحافظ `--skip-images` على إحصاءات الصور الموجودة مسبقًا ويتجنب تنزيل بيانات الفيديو أو فك ترميزها عندما يكون إعادة حساب `STATE`/`ACTION` فقط هو المطلوب، بينما يقرأ `--root` مجموعة بيانات محلية بدلاً من Hub. هذه القيم هي تقديرات مبنية على التوزيعات التكرارية، وتخضع لخطأ التقطيع وإعادة التجميع، لذا قد تختلف عن القيم الحذرة — مما يغيّر الأهداف المعيارية في MolmoAct2 وبالتالي مقياس دالة الخسارة. أما الإحصاءات المحفوظة مسبقًا داخل نقطة تحقق موجودة مسبقًا فلا تتأثر.

أو، درّب MolmoAct2 باستخدام تطبيع المتوسط/الانحراف المعياري:

```bash
--policy.normalization_mapping='{"ACTION": "MEAN_STD", "STATE": "MEAN_STD", "VISUAL": "IDENTITY"}'
```

## التقييم

يدعم التقييم أيضًا نقاط التفتيش المحفوظة بواسطة LeRobot ونقاط التفتيش الأصلية من MolmoAct2 على HF. لتكرار LIBERO، حافظ على بيئة العرض EGL ثابتة واستخدم `policy.per_episode_seed=true`.

**مهم:** وجدنا أن `num_steps_wait=10` لا يضمن بشكل موثوق استقرار مشهد LIBERO وقد يُضعف النجاح المقاس. جميع نتائج تقييم LIBERO المُبلَّغ عنها هنا تستخدم `num_steps_wait=50`.

### التقييم باستخدام LeRobot MolmoAct2 Weight

استخدم `policy.path` لنقطة تحقق محفوظة بواسطة LeRobot. يتم استعادة المعالج المحفوظ وإحصاءات التطبيع معًا مع النموذج.

```bash
export MUJOCO_GL=egl
export PYOPENGL_PLATFORM=egl
export OMP_NUM_THREADS=1
export MKL_NUM_THREADS=1

lerobot-eval \
  --policy.path=allenai/MolmoAct2-LIBERO-LeRobot \
  --policy.inference_action_mode=continuous \
  --policy.dtype=bfloat16 \
  --policy.enable_inference_cuda_graph=true \
  --policy.device=cuda \
  --policy.per_episode_seed=true \
  --policy.eval_seed=1000 \
  --env.type=libero \
  --env.task=libero_10,libero_goal,libero_object,libero_spatial \
  --env.camera_name_mapping='{"agentview_image":"image","robot0_eye_in_hand_image":"wrist_image"}' \
  --eval.batch_size=1 \
  --eval.n_episodes=50 \
  --seed=1000
```

### التقييم باستخدام الأوزان الأصلية لـ MolmoAct2

يمكنك تقييم نقطة تحقق (checkpoint) منشورة من Hugging Face مباشرة دون الحاجة إلى تحويلها أولاً إلى نقطة تحقق LeRobot. في هذه الحالة، اضبط `policy.checkpoint_path` على مستودع النموذج الخاص بـ HF، وفّر `policy.norm_tag`. بالنسبة إلى LIBERO، يقوم `policy.norm_tag=libero` بتحميل إحصاءات تطبيع الإجراءات/الحالة الخاصة بـ LIBERO، وأفق الإجراءات، وبيانات الوصف (metadata) للموجّهات، وترتيب مفاتيح الصور من `norm_stats.json` الخاص بنقطة التحقق.

لنسخ نتائج ورقة MolmoAct2 بالكامل باستخدام نقاط التفتيش المنشورة على Hugging Face، نوصي باستخدام الفرع [`allenai/lerobot` `molmoact2-hf-inference`](https://github.com/allenai/lerobot/tree/molmoact2-hf-inference) المثبت على الإصدار v0.5.1. يتطابق هذا الفرع مع إعدادات التقييم الأصلية المستخدمة للأرقام المُبلَّغ عنها.

```bash
export MUJOCO_GL=egl
export PYOPENGL_PLATFORM=egl
export OMP_NUM_THREADS=1
export MKL_NUM_THREADS=1

lerobot-eval \
  --policy.type=molmoact2 \
  --policy.checkpoint_path=allenai/MolmoAct2-LIBERO \
  --policy.norm_tag=libero \
  --policy.inference_action_mode=continuous \
  --policy.dtype=float32 \
  --policy.enable_inference_cuda_graph=true \
  --policy.device=cuda \
  --policy.per_episode_seed=true \
  --policy.eval_seed=1000 \
  --env.type=libero \
  --env.task=libero_goal \
  --env.camera_name_mapping='{"agentview_image":"image","robot0_eye_in_hand_image":"wrist_image"}' \
  --eval.batch_size=1 \
  --eval.n_episodes=50 \
  --seed=1000
```

استخدم `--env.task=libero_10,libero_goal,libero_object,libero_spatial` لتشغيل مجموعة LIBERO الكاملة. يعمل الأمر نفسه مع نقاط التفتيش الأخرى المنشورة من MolmoAct2 طالما أن `policy.norm_tag` المطلوب موجود في ملف `norm_stats.json` الخاص بذلك نقطة التفتيش.

### خيارات التقييم الشائعة

- `policy.inference_action_mode`: مطلوب لمرحلة rollout. استخدم `continuous` للاستدلال المطابق للتدفق أو `discrete` للاستدلال على رموز الإجراء. يجب أن يكون متوافقًا مع `policy.action_mode` وقت التدريب المحفوظ في نقطة التفتيش.
- `policy.path`: مسار نقطة التفتيش الخاصة بـ LeRobot أو مستودع Hub. استخدم هذا للنقاط المحفوظة بواسطة LeRobot.
- `policy.checkpoint_path`: مسار نقطة التفتيش الأصلية MolmoAct2 في HF أو مستودع Hub. استخدم هذا مع `policy.type=molmoact2` و`policy.norm_tag`.
- `policy.norm_tag`: يختار إحصاءات التطبيع، وبيانات الوصفية للموجّه، وترتيب مفاتيح الصور، وأفق الإجراء من ملف `norm_stats.json` الخاص بالنقطة الأصلية. وهو مطلوب للتقييم المباشر لنقاط الأصلية من HF.
- `policy.dtype`: ملف تخزين النموذج/التحويل التلقائي. استخدم `bfloat16` للتقييم العادي على وحدة معالجة الرسوميات. استخدم `float32` فقط عندما تريد صراحةً الاستدلال الكامل بدقة fp32.
- `policy.enable_inference_cuda_graph`: يُفعّل مسار رسم CUDA الخاص بالاستدلال في MolmoAct2 من أجل تسريع تكرار نشر الإجراءات المستمرة.
- `policy.per_episode_seed` و`policy.eval_seed`: تجعلان توليد الإجراءات المستمرة العشوائية حتمياً لكل حلقة من أجل التكرار.
- `env.task`: مجموعات LIBERO مفصولة بفواصل أو مجموعة واحدة. استخدم `libero_10,libero_goal,libero_object,libero_spatial` للمعيار الكامل.
- `env.camera_name_mapping`: يربط أسماء كاميرات LIBERO بمفاتيح الصور التي يتوقعها معالج السياسة.

## نتائج الأداء

### نتائج معيار LIBERO

أثبت MolmoAct2 أداءً قوياً في مجموعة اختبارات LIBERO. ولقارنة تنفيذ LeRobot واختباره، قمنا بإعادة ضبط [`allenai/MolmoAct2-LIBERO`](https://huggingface.co/allenai/MolmoAct2-LIBERO) لـ 10 آلاف خطوة إضافية على مجموعة بيانات LIBERO بحجم دفعة لكل وحدة معالجة رسومية (GPU) يبلغ 32، وذلك على 8 وحدات H100، ثم قارنّا النتائج بالنتائج المرجعية الأصلية الخاصة بـ MolmoAct2.

نقطة التفتيش المُعدّلة باستخدام LeRobot المذكورة هنا متاحة في [`allenai/MolmoAct2-LIBERO-LeRobot`](https://huggingface.co/allenai/MolmoAct2-LIBERO-LeRobot) وقد تم تدريبها على [`allenai/MolmoAct2-LIBERO-Dataset`](https://huggingface.co/datasets/allenai/MolmoAct2-LIBERO-Dataset).

| معايرة      | تنفيذ LeRobot | MolmoAct2 الأصلي |
| -------------- | ---------------------: | -----------------: |
| LIBERO المكانية |                  98.4% |              97.8% |
| LIBERO Object  |                 100.0% |             100.0% |
| هدف LIBERO    |                  98.0% |              97.8% |
| LIBERO 10      |                  96.6% |              93.2% |
| المتوسط        |                 98.25% |             97.20% |

تُظهر هذه النتائج الأداء القوي لنموذج MolmoAct2 عبر مجموعة متنوعة من مهام التلاعب الروبوتي. لإعادة إنتاجها، اتبع التعليمات الواردة في قسم تقييم LIBERO.

## النشر على الأجهزة (lerobot-rollout)

نقاط التفتيش بصيغة LeRobot متاحة على Hub للاستخدام المباشر مع `lerobot-rollout`. يستخدم كل نقطة تفتيش أسماء كاميرات محددة يجب أن تتطابق مع إعداد الكاميرات الخاص بروبوتك.

### تسمية الكاميرات

يتوقع كل نقطة تحقق مفاتيح محددة من `observation.images.*`. إذا كانت كاميرات روبوتك تحمل أسماء مختلفة، فاستخدم `--rename_map` لربطها:

| نقطة التفتيش                    | مفاتيح الكاميرا            | الوصف              |
| ----------------------------- | ---------------------- | ------------------------ |
| MolmoAct2-LIBERO-LeRobot      | `image`, `wrist_image` | كاميرات محاكاة LIBERO       |
| MolmoAct2-BimanualYAM-LeRobot | `top`, `left`, `right` | إعداد كاميرات YAM الثلاث       |
| MolmoAct2-DROID-LeRobot       | `cam0`, `cam1`         | خارجي + معصم         |
| MolmoAct2-SO100_101-LeRobot   | `cam0`, `cam1`         | العرض الأساسي + الثانوي |

مثال على روبوت SO-100 يستخدم كاميرات علوية وجانبية:

```bash
lerobot-rollout \
  --policy.path=lerobot/MolmoAct2-SO100_101-LeRobot \
  --rename_map='{"observation.images.top": "observation.images.cam0", "observation.images.side": "observation.images.cam1"}' \
  --robot.type=so100_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.cameras='{
      top: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30},
      side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30}
  }' \
  --task="pick up the red cube" --duration=30
```

للاستخدام بدلًا من ذلك كاميرا معصم، ما عليك سوى تغيير تعيين إعادة التسمية:

```bash
--rename_map='{"observation.images.top": "observation.images.cam0", "observation.images.wrist": "observation.images.cam1"}'
```

### تحويل الإطار المشترك (SO-100/101 بدون تدريب مسبق)

تم تدريب نقطة التفتيش MolmoAct2-SO100_101 على بيانات تستخدم اتفاقية معايرة للمفاصل مختلفة عن تلك المستخدمة في LeRobot >= 0.5.0. بدون تصحيح الإطار، قد يتحرك الذراع في الاتجاه الخاطئ.

يؤثر هذا على كل من **النشر بدون تدريب مسبق** و **الضبط الدقيق** من نقطة التفتيش الأصلية. تتوقع الأوزان المُدرَّبة مسبقًا الاتفاق القديم، لذا يجب تحويل جميع البيانات المشتركة (الملاحظات والإجراءات) لتتوافق معه.

يتضمن نقطة التفتيش المحوّلة من LeRobot (`lerobot/MolmoAct2-SO100_101-LeRobot`) بالفعل هذا التصحيح في خط معالجة البيانات الخاص بها. إذا قمت بتحويل نقطة التفتيش أو ضبطها الدقيق بنفسك، فقم بتعيين ما يلي في إعدادات السياسة (`configuration_molmoact2.py`):

- `joint_signs`: `[1, -1, 1, 1, 1, 1]` (يعكس اتجاه shoulder_lift)
- `joint_offsets`: `[0, 90, 90, 0, 0, 0]` (يُزيح shoulder_lift و elbow_flex بمقدار 90°)

راجع [دليل التوافق العكسي](./backwardcomp) لمعرفة التفاصيل المتعلقة بتغيير المعايرة.

## الاختلافات عن التنفيذ الأصلي

يُعدّ هذا الإصدار من LeRobot مخصصًا لمطابقة سلوك MolmoAct2 مع استخدام بنية LeRobot التحتية للبيانات والتدريب والتقييم والنقاط المحفوظة والسجلات. الفروقات الرئيسية عن مستودع التدريب الأصلي هي:

- يحتفظ إطار التدريب في الورقة الأصلية بمعاملات رئيسية بدقة fp32 ويُدرب باستخدام bf16 AMP. يستخدم هذا الإصدار من LeRobot `policy.dtype=bfloat16` لتقليل الذاكرة: تُخزَّن مصفوفات VLM الكبيرة بدقة bf16، بينما تبقى خبير الإجراءات (action expert) والوحدات الحساسة رقمياً بدقة fp32، وتُنفَّذ العمليات المؤهلة تحت bf16 autocast. يقلل متجه تعويض التحديث بدقة bf16 من خسارة تقريب المعاملات أثناء الضبط الدقيق الكامل، لكن لحظات Adam بدقة bf16 لا تزال لا تُعيد إنتاج حالة المُحسِّن الأصلية بدقة fp32 بشكل دقيق.
- يستخدم المستودع الأصلي مسار تدريب خاص به يعتمد على FSDP/توازي النموذج. أما نسخة LeRobot فتستخدم مسار التدريب القياسي الخاص بـ LeRobot/Accelerate ولم تُختبر بعد للتدريب متعدد العقد.
- يدعم المستودع الأصلي حزم التسلسلات. أما نسخة LeRobot فتدرّب على عينة LeRobot واحدة لكل عنصر، وتستخدم الحشو المحلي للدفع مع حارس يُستنتج منه الحد الأقصى لطول التسلسل.
- يتبع منفذ LeRobot معايير LeRobot الخاصة بمحسّن التدريب، ومجدول التعلم، وحفظ نقاط التفتيش، وتحويلات مجموعة البيانات، وتوسيع الصور، وتسجيل Trackio.
- يدعم مسار التدريب الأصلي أفقًا مختلطًا للإجراءات عن طريق ملء الفراغات حتى `max_action_horizon` وإخفاء فتحات الأفق المملوءة في انتباه الذات لخبير الإجراءات. وهذا مفيد عند التدريب عبر مجموعات بيانات ذات ترددات تحكم مختلفة. يستهدف نقل LeRobot حاليًا الضبط الدقيق لمجموعة بيانات واحدة، لذا فإن `policy.chunk_size` يتجاوز `max_action_horizon` في نقطة الحفظ، ولم يتم تنفيذ إخفاء الأفق بعد. يُخطط لدعم مسار الأفق المختلط هذا.

## الاستشهاد

```bibtex
@misc{fang2026molmoact2actionreasoningmodels,
      title={MolmoAct2: Action Reasoning Models for Real-world Deployment},
      author={Haoquan Fang and Jiafei Duan and Donovan Clay and Sam Wang and Shuo Liu and Weikai Huang and Xiang Fan and Wei-Chuan Tsai and Shirui Chen and Yi Ru Wang and Shanli Xing and Jaemin Cho and Jae Sung Park and Ainaz Eftekhar and Peter Sushko and Karen Farley and Angad Wadhwa and Cole Harrison and Winson Han and Ying-Chun Lee and Eli VanderBilt and Rose Hendrix and Suveen Ellawela and Lucas Ngoo and Joyce Chai and Zhongzheng Ren and Ali Farhadi and Dieter Fox and Ranjay Krishna},
      year={2026},
      eprint={2605.02881},
      archivePrefix={arXiv},
      primaryClass={cs.RO},
      url={https://arxiv.org/abs/2605.02881},
}
```

## رخصة

هذا النموذج مرخّص بموجب Apache 2.0. وهو مخصص للاستخدام البحثي والتعليمي وفقاً لـ[إرشادات الاستخدام المسؤول من Ai2](https://allenai.org/responsible-use)، بما يتوافق مع [allenai/molmoact2](https://github.com/allenai/molmoact2).

