LeRobot documentation
دليل ترميز الفيديو البث
دليل ترميز الفيديو البث
1. نظرة عامة
تُزيل ترميز الفيديو البثّي دورة PNG التقليدية أثناء تسجيل مجموعات بيانات الفيديو. بدلاً من:
- التقاط الإطار -> كتابة ملف PNG على القرص -> (في نهاية الحلقة) قراءة ملفات PNG -> الترميز إلى MP4 -> حذف ملفات PNG
يمكن ترميز الإطارات في الوقت الفعلي أثناء الالتقاط:
- التقاط الإطار -> وضعه في طابور خيط المُشفِّر -> التشفير مباشرة إلى MP4
يجعل هذا save_episode() شبه فوري (حيث يكون الفيديو مشفراً بالفعل عند انتهاء الحلقة) ويزيل الانتظار المحجوز الذي كان يحدث سابقاً بين الحلقات، خاصةً عند استخدام عدة كاميرات في حلقات طويلة.
2. ضبط المعلمات
| معامل | علامة سطر الأوامر | النوع | افتراضي | الوصف |
|---|---|---|---|---|
streaming_encoding | --dataset.streaming_encoding | bool | False | تفعيل الترميز في الوقت الفعلي أثناء الالتقاط |
vcodec | --dataset.rgb_encoder.vcodec | str | "libsvtav1" | ترميز الفيديو. "auto" يكتشف أفضل مشفر للأجهزة |
encoder_threads | --dataset.encoder_threads | int \| None | None (تلقائي) | عدد الخيوط لكل مثيل من المُشفِّر. None سيترك لـ vcoded أن يقرر |
encoder_queue_maxsize | --dataset.encoder_queue_maxsize | int | 30 | أقصى عدد للإطارات المخزنة مؤقتًا لكل كاميرا (حوالي ثانية واحدة عند 30 إطارًا في الثانية). يستهلك ذاكرة الوصول العشوائي |
3. اعتبارات الأداء
تعني الترميز البثي أن المعالج المركزي يرمّز الفيديو أثناء حلقة الالتقاط، وليس بعدها. وهذا يُنشئ ميزانية للمعالج المركزي يجب مشاركتها بين:
- حلقة التحكم (قراءة الكاميرات، التحكم في الروبوت، كتابة البيانات غير المرئية)
- خيوط المُشفِّر (مجموعة واحدة لكل كاميرا)
- إعادة تشغيل التصور (إذا كان مفعلاً)
- نظام التشغيل والعمليات الأخرى
تأثير الدقة وعدد الكاميرات
| الإعداد | معدل الإنتاجية (بكسل/ثانية) | تحميل الترميز على المعالج | ملاحظات |
|---|---|---|---|
| 2camsx 640x480x3 @30fps | 55M | منخفض | يعمل على معظم الأنظمة |
| 2camsx 1280x720x3 @30fps | 165M | متوسط | مريح على الأنظمة الحديثة |
| 2camsx 1920x1080x3 @30fps | 373M | عالية | يتطلب معالجًا مركزيًا قويًا من الطراز العالي |
encoder_threads الضبط
يتحكم هذا المعامل في عدد الخيوط التي يستخدمها كل مثيل من وحدات الترميز داخلياً:
- قيم أعلى (مثل 4-5): ترميز أسرع، لكنه يستخدم نوى معالج أكثر لكل كاميرا. مناسب لأنظمة عالية الأداء ذات عدد كبير من النوى.
- قيم أدنى (مثل 1-2): تقليل استخدام المعالج لكل كاميرا، مما يحرر الأنوية لالتقاط الصور وعرضها. مناسب للصور منخفضة الدقة والمعالجات القوية.
None(الافتراضي): يُتيح للمُرمِّز أن يقرر. المعلومات المتاحة في سجلات المُرمِّز.
الضغط المرتد وإسقاط الإطارات
تحتوي كل كاميرا على طابور محدود (encoder_queue_maxsize، الافتراضي 30 إطارًا). عندما لا يستطيع المُشفِّر مواكبة الإيقاع:
- تتملأ قائمة الانتظار (مما يستهلك ذاكرة الوصول العشوائي)
- تُستبعد الإطارات الجديدة (بدلاً من حظرها) — يستمر حلقة الالتقاط دون انقطاع
- يُسجَّل تحذير:
"Encoder queue full for {camera}, dropped N frame(s)" - في نهاية الحلقة، يتم الإبلاغ عن إجمالي الإطارات المفقودة لكل كاميرا
أعراض تأخر المُشفِّر
- يبدو النظام بطيئًا ويتجمد: جميع المعالجات تعمل بنسبة 100%
- تحذيرات الإطارات المفقودة في السجل أو عدد إطارات/إطارات في الثانية أقل من المتوقع في مجموعة البيانات المسجلة
- حركة روبوتية متقطعة: إذا كان المعالج المركزي (CPU) مُحمَّلاً بشكل شديد، فقد يتأثر حلقة الالتقاط (capture loop) أيضاً
- تأخر إعادة التشغيل المتراكم: تتأخر عملية التصور عن الوقت الفعلي
4. الترميز المُسرَّع عبر العتاد
متى تستخدم
استخدم الترميز عبر وحدة المعالجة الرسومية (HW) عندما:
- المعالج المركزي هو عنق الزجاجة (إطارات مفقودة، حركة روبوت متقطعة، تأخر في إعادة التشغيل)
- لديك عتاد متوافق (وحدة معالجة رسومية GPU أو مشفّر مخصص)
- أنت تسجّل بمعدل إنتاجية عالٍ (دقة عالية أو باستخدام العديد من الكاميرات)
اختيار مُرمِّز
| ترميز | استخدام المعالج | حجم الملف | الجودة | ملاحظات |
|---|---|---|---|---|
libsvtav1 (افتراضي) | عالية | الأصغر | أفضل | الافتراضي. أفضل ضغط لكنه الأكثر استهلاكًا للمعالج |
h264 | متوسط | أكبر بنسبة 30-50% تقريبًا | جيد | برمجيات H.264. استخدام أقل للمعالج |
| مشفرات العتاد | منخفض جداً | أكبر | جيد | يُحمّل المهام إلى أجهزة مخصصة. الأفضل للأنظمة التي تعاني من قيود المعالج |
المشفرات المتاحة على مستوى العتاد
| المُشفِّر | المنصة | الأجهزة | قيمة سطر الأوامر |
|---|---|---|---|
h264_videotoolbox | macOS | Apple Silicon / Intel | --dataset.rgb_encoder.vcodec=h264_videotoolbox |
hevc_videotoolbox | macOS | Apple Silicon / Intel | --dataset.rgb_encoder.vcodec=hevc_videotoolbox |
h264_nvenc | Linux/Windows | وحدة معالجة رسومات من NVIDIA | --dataset.rgb_encoder.vcodec=h264_nvenc |
hevc_nvenc | Linux/Windows | وحدة معالجة رسومات من NVIDIA | --dataset.rgb_encoder.vcodec=hevc_nvenc |
h264_vaapi | Linux | GPU من Intel/AMD | --dataset.rgb_encoder.vcodec=h264_vaapi |
h264_qsv | Linux/Windows | Intel Quick Sync | --dataset.rgb_encoder.vcodec=h264_qsv |
auto | أي | يستكشف النظام بحثًا عن وحدات ترميز الأجهزة المتاحة. إذا لم يتم العثور على وحدة ترميز للأجهزة، يتم الرجوع إلى libsvtav1 | --dataset.rgb_encoder.vcodec=auto |
للاستفادة من مشفّرات تسريع العتاد، قد تحتاج إلى تحديث برامج تشغيل وحدة معالجة الرسوميات (GPU).
libsvtav1هو الافتراضي لأنه يوفر أفضل أداء للتدريب؛ يمكن لباقي مشفرات الفيديو تقليل استخدام المعالج المركزي والسرعة، لكنها تنتج عادةً ملفات أكبر وقد تؤثر على وقت التدريب.
5. استكشاف الأخطاء وإصلاحها
| العرض | السبب المحتمل | إصلاح |
|---|---|---|
| تجمّد النظام أو حركة روبوتية متقطعة أو تأخر في عرض Rerun | نقص المعالج المركزي (استهلاك حمل 100%) | أغلق التطبيقات الأخرى، وقلّل معدل الترميز، وخفّض encoder_threads، واستخدم h264، واستخدم display_data=False. إذا استمر المعالج المركزي في العمل بنسبة 100% فقد يكون غير كافٍ لإعدادك، فكّر في استخدام --dataset.streaming_encoding=false أو الترميز عبر العتاد (--dataset.rgb_encoder.vcodec=auto) |
| تحذيرات “Encoder queue full” أو إطارات مرفوضة في مجموعة البيانات | لا يستطيع المُشفِّر مواكبة الطلب (امتلاء الطابور) | إذا لم يكن المعالج المركزي عند 100%: قم بزيادة encoder_threads، أو بزيادة encoder_queue_maxsize، أو استخدم الترميز العتادي (--dataset.rgb_encoder.vcodec=auto). |
| استهلاك عالٍ للذاكرة العشوائية | تعبئة الطابور أسرع من الترميز | encoder_threads منخفض جدًا أو المعالج المركزي غير كافٍ. قلّل encoder_queue_maxsize أو استخدم الترميز عبر العتاد |
| ملفات الفيديو الكبيرة | استخدام مُرمِّح العتاد أو H.264 | مقايضة متوقعة. انتقل إلى libsvtav1 إذا سمح المعالج المركزي بذلك |
save_episode() ما زال بطيئًا | streaming_encoding هو False | اضبط --dataset.streaming_encoding=true |
| انهيار خيط المُشفِّر | المشفر غير متوفر أو الإعدادات غير صالحة | تحقق من تثبيت vcodec، وحاول استخدام --dataset.rgb_encoder.vcodec=auto |
| المجموعة المسجلة مفقود منها إطارات | نقص موارد المعالج المركزي/وحدة معالجة الرسوميات أو ذروات الحمل العرضية | إذا كانت نسبة الإطارات المفقودة حوالي 5%، فمن المرجح أن نظامك مُثقل — اتبع التوصيات المذكورة أعلاه. إذا كانت نسبة الإطارات المفقودة أقل (~2%)، فمن المحتمل أن تكون ناتجة عن ذروات حمل مؤقتة متقطعة (غالبًا عند الإقلاع) ويمكن اعتبارها متوقعة. |
6. التكوينات الموصى بها
هذه التقديرات متحفظة؛ ننصح باختبارها على إعدادك—ابدأ بحِمل منخفض ثم زد تدريجيًا.
الأنظمة عالية الأداء: 12 نواة حديثة أو أكثر (24 خيطاً أو أكثر)
يجب أن يكون معدل الإنتاجية بين ~250-500M px/sec مريحًا عند المعالجة على وحدة المعالجة المركزية (CPU). للحصول على نتائج أفضل، جرّب الترميز العتادي (HW encoding) إذا كان متاحًا.
# 3camsx 1280x720x3 @30fps: Defaults work well. Optionally increase encoder parallelism.
# 2camsx 1920x1080x3 @30fps: Defaults work well. Optionally increase encoder parallelism.
lerobot-record --dataset.encoder_threads=5 ...
# 3camsx 1920x1080x3 @30fps: Might require some tuning.أنظمة متوسطة المدى: 8+ أنوية حديثة (16+ خيوط) أو Apple Silicon
يجب أن يكون من الممكن تحقيق معدل معالجة يتراوح بين ~80-300 مليون بكسل/ثانية على المعالج المركزي (CPU).
# 3camsx 640x480x3 @30fps: Defaults work well. Optionally decrease encoder parallelism.
# 2camsx 1280x720x3 @30fps: Defaults work well. Optionally decrease encoder parallelism.
lerobot-record --dataset.encoder_threads=2 ...
# 2camsx 1920x1080x3 @30fps: Might require some tuning.أنظمة الموارد المنخفضة: معالجات حديثة بـ 4+ أنوية (8+ خيوط) أو Raspberry Pi 5
على الأنظمة ذات الموارد المحدودة للغاية، قد يتنافس الترميز البثي بشكل مفرط مع حلقة الالتقاط. تعطيل هذا الخيار يعيد إلى النهج القائم على PNG حيث يحدث الترميز بين الحلقات (مُحجِب، لكنه لا يتداخل مع الالتقاط). كبديل، سجّل بمعدل نقل أقل لتقليل كل من حمولة الالتقاط والرميز. فكّر أيضًا في تغيير مُرمّز الفيديو إلى h264 واستخدام الترميز الدُفعي.
# 2camsx 640x480x3 @30fps: Requires some tuning.
# Use H.264, disable streaming, consider batching encoding
lerobot-record --dataset.rgb_encoder.vcodec=h264 --dataset.streaming_encoding=false ...7. ملاحظة ختامية
يعتمد الأداء في النهاية على إعدادك الدقيق — عدد الإطارات في الثانية، والدقة، وعدد أنوية المعالج المركزي وحمله، والذاكرة المتاحة، وطول الحلقة، ومُشفِّر الفيديو الذي تختاره. اختبر دائمًا باستخدام حمل العمل المستهدف لديك، وكن حريصًا بشأن قدرات المعالج المركزي والنظام لديك، وضبط encoder_threads وencoder_queue_maxsize وvcodec بشكل معقول. ومع ذلك، فإن إعدادًا عمليًا شائعًا (لكثير من التطبيقات) هو ثلاث كاميرات بدقة 640×480x3 @30fps؛ وعادةً ما يعمل هذا بسلاسة مع إعدادات ترميز الفيديو البث الافتراضية في الأنظمة الحديثة. تحقق دائمًا من صحة مجموعة البيانات المسجلة من خلال مقارنة مدة الفيديو مع مدة الحلقة في سطر الأوامر والتأكد من أن عدد الصفوف يساوي عدد الإطارات في الثانية × مدة سطر الأوامر.