خط أنابيب الترميز

lerobot-annotate يراقب فيديو كل حلقة باستخدام نموذج رؤية ولغة (VLM) ويكتب تعليقات بلغة طبيعية مرة أخرى في مجموعة البيانات الخاصة بك. يملأ العمودين اللغويين من صفحة Language Columns and Recipes — language_persistent وlanguage_events — مباشرةً في data/chunk-*/file-*.parquet.

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

كيف تتكامل الأجزاء

  your dataset                  lerobot-annotate
  (LeRobotDataset v3.0)
        │
        ▼
  ┌─────────────────────────────────────────────────────┐
  │                    read episodes                     │
  └──────────────────────────┬──────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                     ▼
  ┌──────────┐      ┌───────────────┐        ┌──────────┐       one shared Qwen-VL
  │   plan   │      │ interjections │        │   vqa    │  ◀──   server (vLLM, OpenAI
  └────┬─────┘      └───────┬───────┘        └────┬─────┘        API) drives all three
       └────────────────────┼─────────────────────┘
                            │   each module stages raw JSONL
                            ▼   into .annotate_staging/
                  ┌─────────────────┐
                  │    validator    │  ◀──  checks everything
                  └────────┬────────┘
                           ▼
                  ┌─────────────────┐
                  │     writer      │
                  └────────┬────────┘
                           ▼
              data/chunk-*/file-*.parquet
              (+ meta/info.json tools)

تتواصل ثلاثة وحدات (plan، interjections، vqa) جميعها مع نموذج VLM مشترك واحد. تُحفظ مخرجات كل وحدة على القرص، ثم يتحقق مُتحقق من صحتها، ويعيد كاتب واحد كتابة شرائح مجموعة البيانات في مكانها.

ما ينتجه خط الأنابيب

تصدر كل وحدة أنواعًا قليلة من التعليقات التوضيحية (الأنماط)، وتُوجَّه إلى إحدى عمودَي اللغة:

كيف يتم توليد المهام الفرعية

لا يطلب وحدة plan من نموذج الرؤية واللغة المهام الفرعية دفعة واحدة. بدلاً من ذلك، تستخدم تدفقاً من خطوتين: وصف → تقسيم:

1. الوصف — يقوم نموذج VLM بسرد ما يراه فعليًا في الكاميرا المختارة (دون تخمين حول المهمة).
2. Segment — يُعاد إدخال ذلك الوصف، ويقوم نموذج الرؤية-اللغة بتقسيم الحلقة إلى مهام فرعية ذرّية متتالية.

تتعامل كلا المسارين مع الحلقة على أنها أوراق اتصال مُوقّتة — وهي إطارات مُستخرجة بمعدل frames_per_second (0.5 ثانية افتراضيًا) ومُجمّعة في شبكات JPEG مع حرق وقت كل إطار في زاويته، مما يتيح لنموذج اللغة البصري (VLM) الاستشهاد بأوقات الحدود الدقيقة مباشرةً. هذا النهج أرخص بكثير من حيث رموز الرؤية مقارنةً باستخدام صورة لكل إطار، مما يسمح بإبقاء الاستخراج كثيفًا؛ فالحلقات الأطول من max_frames_per_prompt تُقسَّم إلى نوافذ بنفس الكثافة ثم تُدمج. كما تحمل كلا التوجيهات تعريفًا سببيًا لـ حدود الأحداث (يبدأ حدث جديد عندما يصبح كائن ما ممسوكًا / يُحرَّر / يصل إلى موقع جديد / يتغير حالة غطاء / تتحرك المحتويات) لتوضيح أماكن التقطيع بدقة أكبر.

اختياريًا، تمريرة ثالثة seeded-relabel (--plan.subtask_seeded_relabel) تعيد زيارة كل مقطع مع أوراق الاتصال (contact sheets) للمقطع السابق/الحالي/التالي وتصحح التسمية تصحيحًا أدنى، مستخدمةً التسمية الأولى كسابق (prior) — فهي تحافظ على الحدود ثابتة وتحدّد الصياغة فقط، مقابل تكلفة استدعاء إضافي واحد لكل مهمة فرعية.

تُدمج المقاطع الناتجة بعد ذلك لتكوين تغطية كاملة للحلقة دون فجوات، بحيث يوجد لكل إطار فرعية واحدة نشطة بالضبط. راجع التشغيل على Hugging Face Jobs لمعرفة إعدادات الإنتاج (كاميرا واحدة، أوراق اتصال مختومة بالوقت، توليد فرعية تلقائي النوافذ).

الأدوات

لا يضيف الكاتب عمود tools إلى parquet. بل يوجد كتالوج الأدوات في meta/info.json["tools"] بدلاً من ذلك (انظر الأدوات). بعد كل تشغيل، يتأكد خط المعالجة من وجود مخطط say القياسي في تلك القائمة، مع الحفاظ على أي أدوات أعلنتها مسبقاً.

هل تريد إضافة أداة خاصة بك؟ عدّل meta/info.json["tools"] مباشرةً — فخط المعالجة يحافظ على ما هو موجود بالفعل. وهذا يجعل الأداة مرئية لقالب المحادثة، بحيث يمكن للنموذج أن يتعلم توليد الاستدعاء. أما طبقة وقت التشغيل التي تنفّذ فعليًا استدعاءً مولّدًا (بروتوكول Tool / TOOL_REGISTRY تحت src/lerobot/tools/) فلم تُنفَّذ بعد — ويوثّق مستند Tools تلك الأجزاء على أنها غير منفّذة بعد.

التشغيل على Hugging Face Jobs

يتطلب توثيق مجموعة بيانات حقيقية بطاقة GPU كبيرة بما يكفي لتشغيل نموذج VLM، لذا يمكن لـ lerobot-annotate أن يُوجّه نفسه إلى Hugging Face Jobs — تمامًا كما يفعل lerobot-train. أضف --job.target=<flavor> إلى الأمر الدقيق الذي كنت ستشغّله محليًا، وسيُنفَّذ على ذلك العتاد بدلًا من ذلك:

hf auth login   # once

uv run lerobot-annotate \
    --repo_id=user/my_dataset \
    --new_repo_id=user/my_dataset_annotated \
    --push_to_hub=true \
    --vlm.model_id=Qwen/Qwen3.6-27B \
    --vlm.num_gpus=1 \
    --vlm.serve_command="vllm serve Qwen/Qwen3.6-27B --tensor-parallel-size 1 \
        --max-model-len 32768 --gpu-memory-utilization 0.8 \
        --uvicorn-log-level warning --port {port}" \
    --vlm.serve_ready_timeout_s=1800 \
    --vlm.chat_template_kwargs='{"enable_thinking": false}' \
    --job.target=h200

يقوم ذلك بإرسال مهمة h200 على وحدة معالجة رسومات واحدة:

1. يبدأ من صورة vllm/vllm-openai ويقوم بتثبيت lerobot فوقها،
2. يُشغّل خادم vLLM واحدًا لكل وحدة معالجة رسومية ويتحكم فيه عبر واجهة برمجة التطبيقات المتوافقة مع OpenAI،
3. تشغّل وحدات plan / interjections / vqa عبر مجموعة البيانات،
4. مع --push_to_hub=true، يُحمّل النتيجة إلى --new_repo_id (أو يعيدها إلى --repo_id في مكانها إذا تركت ذلك غير مضبوط).

يُبث الأمر سجلات المهمة؛ Ctrl-C يفصل دون إلغائها. اطلع على الأنواع المتاحة وأسعارها باستخدام hf jobs hardware.

يأتي Qwen3.6 مفعّلًا خاصية التفكير، مما يستهلك ميزانية الرموز التي يحتاجها المُعلِّم لإجابته بصيغة JSON — يُعطَّل ذلك عبر --vlm.chat_template_kwargs='{"enable_thinking": false}'. وبدون --push_to_hub=true يتم التخلّي عن مجموعة البيانات المُعلَّمة عند خروج العُقدة.

خيارات الوظائف

لمجموعة بيانات أكبر، قم بالتوسع إلى h200x4 وارفع --vlm.parallel_servers / --vlm.num_gpus بما يتناسب مع ذلك، ومنح المهمة مساحة أكبر على سبيل المثال باستخدام --job.timeout=8h.

تتطلب التشغيلات عن بُعد --repo_id (حيث يقوم العُقدة بسحب مجموعة البيانات من Hub؛ بينما يحدد --root مجلدًا موجودًا على جهازك فقط). تُدفع مجموعة البيانات الموجودة في ذاكرة التخزين المؤقت المحلية فقط إلى مستودع خاص أولاً.

خيارات رئيسية

هذه هي الأعلام التي ستلجأ إليها في أغلب الأحيان. نفّذ lerobot-annotate --help لمعرفة كل ما عدا ذلك؛ فالقيم الافتراضية مُعدّة خصيصًا لحلقات التلاعب القصيرة.

مجموعة البيانات في / خارج

الوحدات التي تعمل

كل وحدة مفعّلة افتراضيًا ويمكن تبديلها بشكل مستقل (اضبطها على false لتخطيها، مثلًا للتكرار على وحدة واحدة في كل مرة):

نموذج اللغة المرئي (VLM) ( --vlm.* )

المهام الفرعية / الخطة / الذاكرة ( --plan.* )

التدخلات + VQA

المساهمة في وحدات جديدة

صُمِّم خط الأنابيب ليتم توسيعه، ونرحب بالمساهمات بشدة — سواء كان ذلك عبر وحدة جديدة تمامًا (مثل تتبع المسارات أو الإمكانات)، أو قالب موجّه جديد، أو تدفق تثبيت أكثر ذكاءً، أو إصلاحات جودة للوحدات الموجودة plan / interjections / vqa.

توجد كل وحدة تحت src/lerobot/annotations/steerable_pipeline/modules/، وتشارك عميل VLM وذاكرة التخزين المؤقت للإطارات الرئيسية، وتكتب مخرجاتها الخام إلى شجرة التجميع، وتُدمج في المنفّذ كمرحلة مستقلة. لديك فكرة؟ افتح مشكلة أو طلب سحب في المستودع.

كيف تستهلك الوصفات المخرجات

تُصمَّم التعليقات ليتم قراءتها بواسطة الوصفات (انظر أعمدة اللغات والوصفات). عادةً:

• تقرأ فروع المستوى المنخفض / المستوى العالي / تحديث الذاكرة subtask / plan / memory من language_persistent.
• تقرأ فرع المقاطعة-الاستجابة أحداث interjection بالإضافة إلى ذرّة الكلام المزدوجة (المدمجة في دور مساعد واحد عبر tool_calls_from) وتحديث plan المطابق عند نفس الطابع الزمني.
• تقرأ فرع VQA أزواج (vqa, user) و(vqa, assistant) من language_events.

لماذا يتم فصل الحالة والأحداث

تتخذ التصميم شكله فكرتان:

1. الحالة الدائمة مقابل الأحداث الدقيقة. الصفوف الدائمة (subtask، plan، memory) تنطبق على الحلقة بأكملها وتُجيب عن سؤال «ما الذي صحيح الآن؟». أما الصفوف الحدثية (interjection، vqa، الكلام) فتظهر فقط في الإطار الوحيد الذي يطابق طابعه الزمني. تُنسخ الطوابع الزمنية مباشرةً من ملف parquet المصدر — ولا تُعاد حسابها أبدًا باستخدام الفاصلة العائمة.
2. مرور واحد لنموذج الرؤية-اللغة. تتشارك جميع الوحدات الثلاث عميلًا واحدًا لنموذج الرؤية-اللغة (العميل المتوافق مع OpenAI الذي يتواصل مع خادم vLLM الخاص بالمهمة)، لذا تدفع مقابل تحميل نموذج واحد لكل مجموعة بيانات، وليس ثلاثة.

إعادة تشغيل وحدة واحدة

يُخزّن كل وحدة مخرجاتها الخام في <root>/.annotate_staging/episode_{N:06d}/<module>.jsonl. وهذا يجعل تكرار المحفزات رخيص التكلفة: فإعادة تشغيل وحدة واحدة تُعيد كتابة ملف JSONL الخاص بها فقط، ثم يعيد الكاتب تركيب ملف parquet النهائي. عطّل الوحدات التي لا ترغب في تشغيلها باستخدام --plan.enabled=false (وبالمثل --interjections.enabled / --vqa.enabled) لاختبار وحدة واحدة في كل مرة.

ما يفحصه المُتحقّق

قبل تشغيل الكاتب، يتحقق StagingValidator مما يلي:

• تقع كل صفّ حدثٍ تمامًا على طابع زمنيّ لإطارٍ حقيقيّ؛
• لا تبقى أي أزواج من الكلام/التصريحات معزولة؛
• يُحدَّث plan عند كل طابع زمني للتدخل؛
• تقع صفوف memory على حدود المهام الفرعية (إنها تحذير وليس خطأً)؛
• كل محتوى مساعد VQA content هو JSON صالح بأحد الأشكال التالية: bbox / keypoint / count / attribute / spatial؛
• تذهب كل صف إلى العمود الذي تحدده column_for_style(style).

تؤدي أي أخطاء إلى إيقاف الكاتب. مرّر --skip_validation=true لتجاوز ذلك أثناء التصحيح.

من أين تأتي أفكار كل وحدة

• plan — المهام الفرعية. روبوت Hi (Shi 2025) لحجم الذرّة (مثل “التقاط قطعة خس واحدة”، “وضع الوعاء في الصندوق”); وPi0.7 (Physical Intelligence 2025) لتفاصيل “كيف وليس ماذا”.
• plan — الذاكرة. MEM (Torne 2026): احتفظ بالمعلومات ذات الصلة الحد الأدنى فقط — حافظ على النتائج، وأزل الخصائص المحددة.
• interjections. تصنيف سيناريوهات Hi Robot: مهمة سلبية، تصحيح مرتبط بالسياق، قيد محدد، تفضيل. الكلام هو ذرّة مخصّصة لاستدعاء الأدوات فقط (tool_calls=[{type:function, function:{name:"say", arguments:{text:...}}}]).
• vqa. ECoT (Zawalski 2024) للميزات المرسّخة (صناديق الحدود [x_min, y_min, x_max, y_max] ونقاط المفاتيح، المخزّنة ككسور من الصورة ضمن المجال [0, 1]) وسياسات VLA القابلة للتوجيه (Zhao 2025) للترسيخ متعدد المستويات التجريدية. كما يرسّخ Pi0.7 الإجابات عبر مستويات التجريد المختلفة.

عند تحسين وحدة، عدّل قالب موجهاتها في src/lerobot/annotations/steerable_pipeline/prompts/ بدلاً من إعادة كتابتها من الصفر.

كم تبلغ تكلفته تقريباً

في كل حلقة، يُجري خط الأنابيب حوالي plan_max_steps من استدعاءات التخطيط، وmax_interjections_per_episode من استدعاءات المقاطعة، وvqa_emission_hz × episode_seconds من استدعاءات VQA. مع القيم الافتراضية (8 مهام فرعية، 3 مقاطعات، 1 هرتز × 3 أزواج) في حلقة مدتها 30 ثانية، يكون ذلك حوالي 50 استدعاءً لنموذج VLM.

تبقى مساحة التخزين صغيرة: language_persistent لا يتجاوز بضع عشرات من الكيلوبايت لكل حلقة (حيث يقوم parquet بتشفير القاموس للدخول الواحد الذي يتكرر عبر الإطارات)، وlanguage_events فارغ في معظم الإطارات — حيث تتناسب حجمه مع عدد الإطلاقات، وليس مع num_frames × num_emissions.