LeRobot documentation

محاكاة

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.7.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

محاكاة

المحاكي في LeRobot هو بيئة Gymnasium تتبع اتفاقيات LeRobot (ملاحظات على شكل قاموس تتضمن صور الكاميرا وحالة الروبوت، وإجراءات مستمرة، والنجاح في info["is_success"]؛ راجع البيئة)، يُكتب مرة واحدة ويُستخدم في كل مكان يشغّل فيه LeRobot روبوتًا:

  • لتقييم سياسة، كـ بيئة مدمجة (--env.*): بيئات متعددة لنفس المهمة، تُخطو معًا. يستخدم lerobot-eval والتقييم أثناء التدريب ذلك.
  • بصفتها روبوت محاكاة (--robot.type=sim --robot.env.*): بيئة واحدة خلف واجهة Robot، قابلة للاستبدال بالأجهزة الفعلية. يستخدمها lerobot-rollout وlerobot-record وlerobot-teleoperate وlerobot-replay.

تعمل إما محليًا في بيئة بايثون الخاصة بك، أو مُقدَّمة بواسطة lerobot-env-server، وعادةً في صورة Docker مستقلة، بحيث لا تتقاطع تبعيات المحاكي مع تبعيات السياسة. اختيار endpoint يحدد التنفيذ المُقدَّم؛ وكلا المسارين يمنح السياسة الملاحظات نفسها (صور uint8 بصيغة HWC، وحالة مسطحة float32)، ونهايات الحلقات نفسها، واتفاقيات التحكم نفسها.

محليًاتم تقديم
بيئة مُجمَّعة: lerobot-eval--env.type=<sim>--env.type=<sim> --env.server.endpoint=tcp/...
روبوت المحاكاة: lerobot-rollout، -record، -teleoperate، -replay--robot.type=sim --robot.env.type=<sim>--robot.type=sim --robot.env.type=<sim> --robot.env.server.endpoint=tcp/...
التثبيتالمحاكي، إلى جانب LeRobot (إضافته)lerobot[remote]؛ حيث يوجد المحاكِى داخل صورة الخادم
إلىاقرأ
تقييم، تسجيل أو تشغيل عن بُعد في المحاكاةهذه الصفحة، وصفحة المحاكي الخاصة به (LIBERO، Meta-World، …)
استخدام محاكي أو نشره من Hugging Face HubEnvHub
أضِف معيار أداء يحافظ عليه LeRobot في بيئته المستمرةإضافة معيار مرجعي

تقييم نقطة تفتيش

محليًا، مع تثبيت المحاكي بجانب LeRobot (انظر إلى LIBERO):

lerobot-eval \
  --policy.path=lerobot/smolvla_libero \
  --policy.pretrained_revision=a24f1f380461b665158d52acd140152c79e8b36d \
  --policy.device=cuda \
  --env.type=libero --env.task=libero_spatial --env.task_ids='[0]' \
  --rename_map='{"observation.images.image": "observation.images.camera1", "observation.images.image2": "observation.images.camera2"}' \
  --eval.n_episodes=1 --eval.batch_size=1 \
  --output_dir=outputs/eval_libero

الخدمة: ابدأ الخادم بنفس البيئة (انظر إلى تقديم بيئة)، وأضف نقطة النهاية الخاصة به:

lerobot-env-server --config_path=docker/sim/configs/libero.yaml --docker=true
lerobot-eval ... --env.server.endpoint=tcp/127.0.0.1:7448

يعمل بيئة EnvHub بنفس الطريقة، باستخدام --env.type=envhub --env.hub_path=<user/repo>، وتُقدَّم عبر lerobot-env-server --envhub=<user/repo> --trust_remote_code=true --docker=true بعد الاطلاع على كودها.

تقع جميع خيارات الخادم تحت --env.server.*، ولا ينطبق أي منها على التشغيل المحلي. يطلب العميل النشر المُسمّى باسم --env.type، كما تُسمّيه إعدادات الخادم؛ مرّر --env.server.deployment لاختيار نشر آخر. يفشل الاتصال بنقطة نهاية أو نشر خاطئ خلال --env.server.handshake_timeout_s (10 ثوانٍ) ويحدد ما تخدمه نقطة النهاية. عند التعامل مع خادم محمي بتشفير TLS، مرّر ملف Zenoh JSON5 الخاص به باستخدام --env.server.zenoh_config_path، كما هو الحال في الاستدلال عن بُعد. يجب أن يشغّل الخادم البيئة التي يصفها الأمر: نفس النوع والمهمة واتفاقيات التحكم والجسم المُحاكى (robot_type)، وإلا رفض التقييم البدء وقام بسرد الفروقات. تُسجَّل الخيارات الأخرى المختلفة (مثل الدقة وطول الحلقة) كتحذيرات.

تأتي أسماء الملاحظات من البيئة (observation.images.<camera>، observation.state). إذا تم تدريب نقطة التفتيش بأسماء كاميرات أخرى، فقم بتعيينها باستخدام --rename_map، كما هو الحال مع أي روبوت، مع الحفاظ على هوية كل كاميرا حتى عندما تتشارك عدة كاميرات نفس الشكل. الكاميرات الوهمية (empty_cameras) هي إعداد سياسة يُحفظ مع نقطة التفتيش؛ تجاوز هذا الإعداد باستخدام --policy.empty_cameras فقط عند الحاجة.

قبل الخطوة الأولى، يجب أن يكون كل مدخل نقطة تحقق موجودًا في البيئة بعد إعادة التسمية، مع أبعاد متطابقة للحالة والإجراء وعدد قنوات RGB. قد يختلف ارتفاع الصورة وعرضها: فمعالجة ما قبل السياسة هي المسؤولة عن تغيير الحجم. لا يتم فحص اتفاقيات المتحكم (الإجراءات التفاضلية مقابل المطلقة، صيغة الدوران)؛ استخدم نقطة تحقق تم تدريبها على اتفاقية البيئة.

الدفعات ومعدل الإنتاجية المُقدَّمة

تُقدّم كل استدعاء لـ step() كل بيئة غير منتهية في الدفعة خطوة واحدة. تبقى البيئة التي تنتهي عند ملاحظتها النهائية حتى إعادة الضبط التالية؛ ولا يؤدي تقدّم البيئات الأخرى إلى إعادة تشغيلها. عند استخدام --eval.use_async_envs=true (الافتراضي)، تعمل كل بيئة في عملية عامل مستقلة، محليًا أو على الخادم، وتُنفَّذ خطوات الدفعة بالتوازي. يستقبل الخادم حتى max_envs بيئة لكل دفعة (32 افتراضيًا).

--env.server.encoding=jpeg (أو --robot.env.server.encoding=jpeg، مع --env.server.jpeg_quality، حيث القيمة الافتراضية 90) يرسل إطارات الكاميرا المُقدَّمة بصيغة JPEG: ما يؤدي إلى ردود أصغر حجمًا لخادم بعيد ودفعات أكبر، مقابل تكلفة وقت الترميز وإطارات ذات فقدان. أما على localhost، فإن الإطارات الخام أسرع.

تحتوي الردود على إطارات كل بيئة في الدفعة، ويجب أن تتوافق مع max_payload_bytes (32 ميغابايت افتراضيًا) في كلا الطرفين، وإلا سيرفض الخادم الدفعة عند فتحها. للدفع الكبيرة أو الكاميرات عالية الدقة، قم بزيادة القيمة على الخادم (max_payload_bytes في قسم zenoh من ملف YAML، بجوار listen_endpoints) وعلى العميل (--env.server.max_payload_bytes، أو --robot.env.server.max_payload_bytes).

تشغيل روبوت محاكاة

نفس البيئة كبيئة مُجمَّعة وكروبوت محاكاة:

lerobot-eval    --env.type=libero --env.task=libero_spatial --env.task_ids='[0]' ...
lerobot-rollout --robot.type=sim --robot.env.type=libero --robot.env.task=libero_spatial --robot.task_id=0 ...

على سبيل المثال:

lerobot-rollout \
  --robot.type=sim --robot.env.type=libero --robot.env.task=libero_spatial --robot.task_id=0 \
  --task="pick up the black bowl between the plate and the ramekin and place it on the plate" \
  --policy.path=lerobot/smolvla_libero \
  --policy.pretrained_revision=a24f1f380461b665158d52acd140152c79e8b36d \
  --rename_map='{"observation.images.image": "observation.images.camera1", "observation.images.image2": "observation.images.camera2"}' \
  --device=cuda --fps=20 --inference.type=sync \
  --display_data=true --display_mode=rerun \
  --return_to_initial_position=false --play_sounds=false
  • --robot.env.* يتقبل نفس الخيارات التي يتقبلها --env.* في التقييم. يختار --robot.task_id المهمة الواحدة التي ينفذها الروبوت، بينما ينفذ التقييم كل مهام المجموعة أو تلك الموجودة في --env.task_ids. بيئات EnvHub هي --robot.env.type=envhub --robot.env.hub_path=<user/repo>، مع --robot.env.trust_remote_code=true لتشغيلها محليًا.
  • --robot.env.server.endpoint=tcp/... يشغّل البيئة على خادم بيئات بدلاً من ذلك، كما يفعل --env.server.endpoint لبيئة مُجمَّعة. يتحقق الروبوت من أن الخادم يشغّل تلك البيئة.
  • تُقدّم كل استدعاء لـ send_action() البيئة خطوة واحدة بالضبط. أما قراءة الملاحظات، والاستدلال على السياسة، والانتظار، فلا تُقدّم المحاكاة؛ إذ يملك حلقة التحكم الحالية إيقاع الساعة الحقيقية.
  • يجب أن يساوي --fps معدل التحكم في البيئة، مقسومًا على --interpolation_multiplier عند الاستيفاء، لأن كل أمر يُقدّم البيئة خطوة واحدة. عند التسجيل، يجب أن يساوي --dataset.fps قيمة --fps. وإلا فإن Rollout يرفض البدء.

الروبوت المحاكي هو روبوت: استبدل --robot.type=sim --robot.env.* بـ --robot.* الخاص بالمتابع الحقيقي، ويبقى كل شيء آخر كما هو. يقود المشغّل عن بُعد هذا الروبوت كما يقود المتابع الحقيقي (--teleop.type=so101_leader لتوأم SO-101 مثل lerobot/so101-tabletop-mujoco)، عندما يعلن البيئة عن أسماء وحدات الإجراء ووحداتها الخاصة بالمتابع؛ ويُبلَّغ عن أي عدم تطابق عند أول إجراء.

تستخدم ميزات كاميرا الروبوت نفس أسماء observation.images.<camera> المستخدمة في التسجيل على الأجهزة الحقيقية. الكاميرا الواحدة غير المسماة هي observation.images.image. يحافظ التقييم المجمّع على مفاتيح البيئة الخاصة بها، مثل observation.image لكاميرا واحدة؛ عند نشر نقطة تحقق تحمل ذلك الاسم عبر روبوت محاكاة، استخدم --rename_map='{"observation.images.image": "observation.image"}'.

عند تأخر السياسة، فإن الاحتفاظ بروبوت محاكاة لا يُقدّم الفيزياء إلى الأمام. تنتقل أعطال المحاكي إلى إيقاف التمرير.

التسجيل في المحاكاة

lerobot-record يخزّن الجسم الذي يحدده البيئة كنوع الروبوت robot_type في مجموعة البيانات (panda لـ LIBERO، وso_follower لنسخة SO-101)، أو sim_robot إذا لم تحدد أي نوع.

تتبع الحلقات المسجّلة بيئة المحاكاة. يعيد lerobot-record واستراتيجية النشر الحلقية تشغيل بيئة المحاكاة في بداية كل حلقة، وينهيانها عند انتهاء حلقة البيئة (سواءً بالنجاح أو بالإنهاء أو بلوغ حدّ الخطوات) أو عند انتهاء مدّتها، أيهما يأتي أولاً. وبالتالي، كل حلقة مسجّلة هي حلقة محاكاة واحدة، بدءاً من حالتها الأولية. لا حاجة لإعادة الضبط يدوياً، لذا تخطَّ مرحلة إعادة الضبط بين الحلقات باستخدام --dataset.reset_time_s=0، ومع استراتيجية النشر الحلقية مرّر أيضاً --strategy.reset_to_initial_position=false.

عند انتهاء حلقة، يتوقف الروبوت: فهو يتجاهل الإجراءات ويحافظ على حالته النهائية، بينما يحتفظ latest بالمكافأة النهائية والانتهاء والنجاح. ثم تبدأ عملية التشغيل عن بُعد واستراتيجية النشر الأساسية حلقة جديدة (كما تعيد الاستراتيجية ضبط السياسة)، ويتوقف الإعادة. لتسجيل باستخدام سياسة، استخدم استراتيجية النشر الدورية. لا تتأثر الروبوتات الحقيقية: فحلقاتها موقوتة، ويُعاد ضبط مشهدتها يدويًا. لمعدلات النجاح، قَيِّم باستخدام lerobot-eval وبيئة مُجمَّعة.

الاستدلال عن بُعد

حافظ على نفس خيارات --robot.* واستبدل خيارات السياسة والاستدلال المحلية بما يلي:

--inference.type=remote \
--inference.endpoint=tcp/127.0.0.1:7447 \
--inference.deployment=libero \
--inference.semantics=libero-delta-v1

ابدأ خادم السياسة بشكل منفصل باستخدام إعداد الاستدلال عن بُعد. يجب أن يتطابق مخططه مع ملاحظات الروبوت بعد --rename_map. احذف --policy.path من أمر التمرير لأن خادم السياسة يقوم بتحميل نقطة التفتيش. للاستخدام المحلي لـ RTC، استخدم --inference.type=rtc مع إعدادات RTC الخاصة بالسياسة.

تقديم بيئة

من نسخة المصدر الخاصة بـ LeRobot (يتم بناء الصورة منها)، نفّذ الأمر التالي من جذر المستودع:

# An in-tree simulator
lerobot-env-server --config_path=docker/sim/configs/libero.yaml --docker=true
# An EnvHub repository, once you have read its code
lerobot-env-server --envhub=<user/repo>@<commit> --trust_remote_code=true --docker=true

يستخدم --docker=true الملف docker/sim/compose.server.yaml، ويختار الصورة من sim.type (أو يبني واحدة من مستودع EnvHub)، ويربط ملف YAML الفعّال، ويشغّل الحاوية على شبكة المضيف، بحيث يستمع الخادم إلى localhost:7448 ما لم يُخالف ذلك --zenoh.listen_endpoints. استبدل ملف YAML لاختيار محاكي آخر. تأتي نسبة التحكم، واتفاقية الإجراء، وأسماء المكونات، ونوع الروبوت لكل محاكي من conventions() الخاص بتكامله (أي LEROBOT_SIM في مستودع EnvHub)، لذا فإن ملف YAML يسمّي المهمة فقط وخيارات المحاكاة.

أما lerobot-policy-server، فتقبل كل حقل في ملف YAML تجاوزًا مدمجًا عبر سطر الأوامر، ويبقى الملف دون تغيير. يتم دمج قيمة القاموس مثل sim.kwargs في ملف YAML:

lerobot-env-server --config_path=docker/sim/configs/libero.yaml --docker=true \
  --sim.task=libero_goal \
  --sim.kwargs='{gym_kwargs: {observation_height: 256, observation_width: 256}}'

يُحفظ التكوين الفعّال تحت $HF_LEROBOT_HOME/sim، بحيث يجده الحاوية عند إعادة تشغيلها. يؤدي تبديل التكوين إلى إعادة إنشاء الخادم وإنهاء الجلسات النشطة. يتم بناء الصورة عند غيابها؛ أضف --build=true لإعادة بنائها بعد تغيير المحاكي أو مصدر LeRobot، أو --stop=true لإيقاف الخادم. تتطلب الحاوية وصول Docker إلى GPU لعرض EGL.

إذا فشل محاكي يعرض باستخدام Vulkan (مثل Isaac Sim، أو ManiSkill/SAPIEN كما في RoboMME، حيث يتضمن ملف الصورة الخاص به ملف Vulkan خاصًا به) داخل الحاوية مع vkCreateInstance failed أو ERROR_INCOMPATIBLE_DRIVER بينما يعمل خارج Docker، فإن الحاوية تحتوي على مكتبات برنامج تشغيل NVIDIA ولكن ليس ملفات المحمّل التي تشير إليها (/usr/share/vulkan/icd.d/nvidia_icd.json، /usr/share/glvnd/egl_vendor.d/10_nvidia.json). قد لا يقوم الوضع الافتراضي لأداة NVIDIA Container Toolkit، المستخدم بواسطة gpus: all، بتركيب هذه الملفات؛ بينما يقوم وضع CDI بذلك. اطلب وحدة المعالجة الرسومية عبر CDI (--device nvidia.com/gpu=all لـ docker run، devices: [nvidia.com/gpu=all] بدلًا من gpus: all في docker/sim/compose.server.yaml)، أو أضف الملفين إلى الصورة.

بدون --docker=true، يعمل الأمر نفسه الخادم في البيئة الحالية: تثبيت التبعيات الأصلية لمحاكي الحركة في بيئة معزولة باستخدام Python 3.12 أو أحدث، وتثبيت LeRobot مع --no-deps، وتثبيت docker/sim/requirements.txt. الخادم جزء من LeRobot، لذا يحتاج إلى نفس إصدار Python الخاص بـ LeRobot؛ ولا يمكن تقديم محاكي يدعم إصدارًا أقدم من Python فقط.

المكان الذي يعمل فيه الخادم

يقبل الخادم اتصالات من جهازه فقط بشكل افتراضي، لأن الاتصال غير مشفّر وغير مُوثّق: أي شخص يصل إليه يمكنه تشغيل البيئة. لتشغيله على جهاز آخر، مثل محطة عمل أو مثيل سحابي مزوّد بوحدة معالجة رسومية، بينما تعمل السياسة على جهازك، مرّر عنوان واجهة الشبكة التي يصل إليها جهازك باستخدام --zenoh.listen_endpoints='[tcp/<address>:7448]'، واتصل باستخدام --env.server.endpoint=tcp/<address>:7448 (أو --robot.env.server.endpoint لروبوت محاكاة). ابقَ على شبكة موثوقة، أو أضف TLS وتحكم في الوصول باستخدام zenoh.config_file في ملف YAML الخاص بالخادم و--env.server.zenoh_config_path على العميل، كما هو الحال مع الاستدلال عن بُعد. على رابط أبطأ، تحتاج إطارات JPEG إلى عرض نطاق أقل.

لا يتم إعادة إرسال طلبات الخادم أبدًا. بعد انتهاء المهلة الزمنيّة الغامض، يفشل العميل؛ أغلقه وافتح جلسة جديدة.

إضافة محاكي

لمشاركة بيئة خاصة بك، انشرها على Hub كبيئة EnvHub: ملف env.py في مستودع Hub هو التكامل بأكمله، وهو يمنحك كل ما هو مذكور في هذه الصفحة. أما المعايير التي يحافظ عليها LeRobot ويختبرها في بيئته المستمرة (CI)، مع نقطة تفتيش مثبتة ومرحلة Docker، فتُضاف إلى LeRobot نفسه؛ راجع إضافة معيار.

Update on GitHub