LeRobot documentation
إضافة معيار
إضافة معيار
يتناول هذا الصفحة كيفية إضافة معيار أداء إلى LeRobot نفسه، حيث يُدار ويُختبر ضمن بيئة CI الخاصة بـ LeRobot، على غرار LIBERO أو Meta-World. لمشاركة بيئة خاصة بك، انشرها على Hub بدلاً من ذلك: راجع EnvHub.
كود المعيار المرجعي هو وحدة واحدة، src/lerobot/sim/integrations/<benchmark>.py: تتضمن gym.Env، والمكيّف الذي يحوّل ملاحظاته إلى ملاحظات LeRobot، وقواعد التحكم الخاصة به. كل طريقة لاستخدام المعيار المرجعي تبنيه من تلك الوحدة: lerobot-eval (بيئة مجمّعة، --env.type=<benchmark>)، والتشغيل والتسجيل (روبوت محاكاة، --robot.type=sim --robot.env.type=<benchmark>)، في عملية المستخدم أو عبر lerobot-env-server من صورة Docker الخاصة به. لا تملك أي أوامر غلافًا خاصًا بها، لذا ترى جميعها الملاحظات نفسها وتطبّق الإجراءات بالطريقة ذاتها. راجع Simulation لمعرفة كيفية استخدامه.
يتصل الاختبار المرجعي بثلاث طبقات:
- يحتوي
lerobot.envsعلىEnvConfig: وهي الخيارات التي يمررها المستخدمون عبر--env.*(و--robot.env.*)، وكيفية ارتباطها بإعدادات المحاكي (sim_settings()). - يحتوي
lerobot.simعلى المحاكي نفسه، ووحدة تكامله، التي تُدار خطوة بخطوة بواسطةLocalVectorEnv. ولا يستورد torch أبدًا، حتى يعمل داخل صورة الخادم. - يقدّم
lerobot.env_serverخدمةlerobot.simللعمليات الأخرى. ويتحكمRemoteVectorEnvفي المحاكي المُقدَّم باستخدام نفس واجهة برمجة التطبيقات الخاصة بـLocalVectorEnv، لذا تعمل الأوامر بالطريقة نفسها سواء كان يعمل في عملية المستخدم أو على خادم.
ما يجب إضافته
| مكوّن | الموقع | ما يجب إضافته |
|---|---|---|
| التكامل | src/lerobot/sim/integrations/<benchmark>.py | The gym.Env, env_fns() factories, canonical_observation() adapter and conventions() for that simulator |
| إعداد | src/lerobot/envs/configs.py | فئة فرعية من EnvConfig حيث تُخضع sim_settings() خياراتها إلى معاملات مصنع المصنع |
| إعداد الخادم | docker/sim/configs/<benchmark>.yaml | المهام ومعاملات المصنع (kwargs) التي يستخدمها الخادم وCI |
| صورة المحاكاة | docker/Dockerfile.sim | مرحلة <benchmark>_native: اعتمادات أصلية مثبتة (بما في ذلك مجموعة أدوات CUDA، حيث أن الأساس هو Ubuntu عادي) ومراجعات الأصول؛ تضيف المرحلة النهائية الخادم |
| ملف تعريف CI | benchmarks/benchmarks.yaml | الاسم، المهام، مراجعة نقطة التفتيش، الكاميرا rename_map وparity الاختياري؛ والباقي يُستكمل افتراضياً من الاسم |
| التبعيات | pyproject.toml | مجموعة اعتمادات اختيارية للاستخدام المحلي |
| التوثيق | docs/source/<benchmark>.mdx, _toctree.yml | صفحة موجهة للمستخدم |
| المصدر | docs/source/<benchmark>.mdx | مستودعات المصدر، ومراجعات الأكواد والأصول المثبتة مع تراخيصها، ومعدل نجاح منشور لنقطة تحقق يمكنك تشغيلها |
تُظهر المساران نفس سلوك البيئة:
native simulator → LocalVectorEnv, locally or on an env server → canonical NumPy observations → batched env or sim robot → one-time image/tensor preparation → saved policy preprocessing → policy → saved action postprocessing → native simulator
ضع اتجاه الصورة، وتحويل الرباعي، وترتيب الحالة في مُكيّف canonical_observation() لذلك المحاكي، وضع اتفاقيات التحكم الخاصة به في conventions()، بحيث تتوافق التقييمات مع عمليات النشر. أعد استخدام sim/integrations/utils.py فقط للخرائط المشتركة بين التكاملات؛ فلا يجوز لبيئة الشيفرة المشتركة أن تتفرع بناءً على أسماء المحاكيات. لا يحتاج معيار جديد إلى معالج بيئة: فالرصدات تصل إلى معالجات السياسة الخاصة بها وهي بالفعل قياسية.
كيفية تنفيذ التقييم
lerobot-eval يقيّم كل معيار أداء بنفس الطريقة:
make_env()يبني قاموسًا متداخلًا على النحو{suite: {task_id: vector env}}.eval_policy_all()ينفّذn_episodesمن جولات كل مهمة، مهمةً تلو الأخرى (أو--env.max_parallel_tasksفي آنٍ واحد).- تُجمَّع النتائج لكل حلقة، ومهمة، وحزمة، وإجمالي:
pc_success(معدل النجاح)، وavg_sum_rewardوavg_max_reward. يأتي كل معدل نجاح مع عدّاداته (n_successمن أصلn_episodes) وفترة ثقة ويلسون بنسبة 95% بالمئوية (pc_success_ci95). تغطي هذه الفترة ضجيج العينة عبر الحلقات فقط؛ ولا تُفيد بأي شيء عن التباين بين تشغيلات التدريب المختلفة لنفس الوصفة.
تأتي النتيجة من info["is_success"]، والتي يبلغ بها بيئتك في كل step(). كما يمكن لبيئتك أن تبلغ بأرقام خاصة بها. تضعها في info["metrics"]، وهي خريطة من كل اسم إلى قيمة عشرية واحدة لكل بيئة. تصل هذه القيم إلى إدخال كل حلقة تحت per_episode[i]["metrics"]، مأخوذة في الخطوة التي انتهت فيها الحلقة.
ما يجب أن توفره بيئة التشغيل
هيكل البيئة
env_fns() يعيد مصانع بيئات كل مهمة، دون بنائها:
def env_fns(
task: str,
n_envs: int,
gym_kwargs: dict | None = None,
) -> dict[str, dict[int, list[Callable[[], gym.Env]]]]:
"""{suite: {task_id: [make_single_env] * n_envs}} for MyBenchmark."""يعيد معيار المهام الواحدة {"<task>": {0: [...]}}؛ بينما يعيد معيار المهام المتعددة (مثل LIBERO) {"libero_spatial": {0: [...], 1: [...], ...}, ...}. يستدعي LocalVectorEnv كل مصنع make_single_env عند الاستخدام الأول، محلياً أو على الخادم، ومع --eval.use_async_envs=true، في عملية منفصلة لكل بيئة.
بيئة gym.Env
يتبع البيئة نفس العقد كما في بيئة EnvHub (انظر البيئة): الملاحظات على شكل قاموس من مصفوفات NumPy، وإجراء مستمر أحادي البُعد Box، وinfo["is_success"] في كل خطوة، وإختياريًا info["metrics"].
class MyBenchmarkEnv(gym.Env):
metadata = {"render_modes": ["rgb_array"], "render_fps": <fps>}
def __init__(self, task_suite, task_id, ...):
super().__init__()
self.task = <task_name_string>
self.task_description = <natural_language_instruction>
self._max_episode_steps = <max_steps>
self.observation_space = spaces.Dict({...})
self.action_space = spaces.Box(low=..., high=..., shape=(...,), dtype=np.float32)| الخاصية | النوع | لماذا |
|---|---|---|
_max_episode_steps | int | ينهي (يقصّ) حلقة |
task_description | str | يُمرَّر إلى سياسات VLA كتعليم لغوي |
task | str | المعرّف الاحتياطي إذا لم يتم تعيين task_description |
step() يُبلّغ عن النجاح في info["is_success"]، وعن أي قياسات أخرى في info["metrics"]. الإجراءات عبارة عن Box مستمر أحادي البُعد.
الملاحظات هي قاموس (dict) يفهمه مُكيّف canonical_observation() الخاص بالتكامل. يُجري المُكيّف الافتراضي القابل لإعادة الاستخدام الخرائط التالية:
| مخرجات بيئة التشغيل الخاصة بك | المفتاح القياسي | ما هو |
|---|---|---|
"pixels" (مصفوفة واحدة) | observation.image | صورة كاميرا واحدة، HWC uint8 |
"pixels" (قاموس) | observation.images.<cam> | كاميرات متعددة، كل منها HWC uint8 |
"agent_pos" | observation.state | متجه الحالة الحسية الذاتية |
"environment_state" | observation.environment_state | حالة البيئة الكاملة (مثل PushT) |
تُمرَّر أي مصفوفة أخرى على أنها observation.<key>. أعد تسمية مخرجات محاكيك إلى هذه المفاتيح داخل gym.Env، أو تعامل مع تمثيله الأصلي في مُكيّف ذلك التكامل.
محاكيات تعتمد على وحدة معالجة الرسوميات (مثل MuJoCo مع عرض EGL): إذا كان محاكيك يخصص سياقات GPU/EGL أثناء __init__، فاجّل هذا التخصيص إلى دالة مساعدة _ensure_env() تُستدعى عند أول reset()/step()، بحيث لا ترث البيئة المُنشأة في عملية عامل مقابض GPU قديمة. راجع LiberoEnv._ensure_env() لمعرفة النمط.
الاتفاقيات ( conventions() في التكامل)
يعيد معدل التحكم في المحاكي والمُتحكِّم وأسماء المكونات المرتبة من conventions(kwargs)، وهي دالة لخيارات المحاكي (يمكن أن تعتمد على وضع إجراء، كما في RoboTwin). تملأ الإعدادات التي تُهملها التهيئة، وتسمّي مكونات الحالة والإجراء للروبوتات ومجموعات البيانات ونقاط الحفظ. القيمة الافتراضية لـsemantics هي <type>-<control>-v1. يسمّي robot_type الجسم المُحاكى، المسجَّل بواسطة روبوت محاكاة: النوع الذي يسجّله الروبوت الحقيقي عندما يكون لدى lerobot فئة له (so_follower)، وإلا فاسم قصير (panda، sawyer)؛ وإذا حُذف، تسجّل مجموعات البيانات sim_robot.
التكوين ( src/lerobot/envs/configs.py )
سجّل إعدادات (config) بحيث يتمكن المستخدمون من اختيار معيارك المرجعي (benchmark) باستخدام --env.type=<name> (و --robot.env.type=<name>). يصف sim_settings() المحاكي (simulator) على أنه قسم sim في ملف YAML الخاص بالخادم؛ بينما يتولى LocalVectorEnv الباقي:
@EnvConfig.register_subclass("<benchmark_name>")
@dataclass
class MyBenchmarkEnvConfig(EnvConfig):
task: str = "<default_task>"
fps: int = <fps>
obs_type: str = "pixels_agent_pos"
@property
def gym_kwargs(self) -> dict:
return {"obs_type": self.obs_type}
def sim_settings(self) -> dict:
return {"type": "<benchmark_name>", "task": self.task, "kwargs": {"gym_kwargs": self.gym_kwargs}}حافظ على توافق قيمها الافتراضية مع قيم ملف YAML الخاص بالخادم: يرفض التقييم المُقدَّم خادمًا يعمل في بيئة أخرى غير تلك التي يصفها الأمر. تأتي الميزات من وصف البيئة عند إنشائها، لذلك لا يُعلن الإعداد عن أي منها.
قبول نقطة التفتيش
--rename_map يُعرّف أسماءً بديلة لمفاتيح البيئة والكاميرا لتطابق المفاتيح المُدرَّبة في نقطة الحفظ، كما هو الحال مع أي روبوت؛ وفي بيئة الاختبار التلقائي (CI) يأتي من حقل rename_map الخاص بالدخول في benchmarks/benchmarks.yaml. يجب أن تكون مدخلات نقطة الحفظ موجودة بعد إعادة التسمية، وأن تتطابق أبعاد الحالة/الإجراء؛ ولا يمكن لإعادة التسمية إصلاح بيانات نقطة الحفظ الوصفية. يتم التحقق من عدد قنوات RGB وترتيبها عند القبول. قد يختلف ارتفاع/عرض الاستحواذ عن البيانات الوصفية للتدريب؛ وينتمي تغيير الحجم إلى ما قبل المعالجة في السياسة.
التحقق و CI
- تحقق من مُكيّف الملاحظات الخاص بالتكامل مقابل المخرجات الخام لمحاكيك، لا سيما اتجاه الكاميرا وترتيب الحالة، وتحقق من الإجراءات المطبقة بواسطة غلاف البيئة.
- قارن تسلسلات إعادة الضبط/الخطوة المُزروعة محليًا والمُقدَّمة (
scripts/ci/check_sim_parity.py)؛ اضبطparity: trueفي عنصر قائمة التشغيل لمحاكي حتمي حتى تُنفّذ CI ذلك. تحقق من تجميد الطرفية، والنجاح، وطول الحلقة، والعرض، وتنظيف الموارد. - تحقق من أن كود الخادم وتكاملاتك تستورد دون torch.
- شغّل
lerobot-eval --env.type=<name> --env.task=<task> --eval.n_episodes=1 --policy.path=<checkpoint>محليًا، ومع--env.server.endpointضد الخادم. افحص أوصاف المهام وعروض الكاميرا المُصيَّرة. - شغّل مهمة المعيار المولّدة على منفّذ GPU. حافظ على اختبار تدريب LIBERO عند إجراء تغييرات على تكامل التقييم/التدريب المشترك.
benchmarks/benchmarks.yaml يولّد المصفوفة عبر scripts/ci/benchmark_matrix.py؛ بينما .github/workflows/benchmark_run.yml يشغّل كل عنصر. أضِف العناصر إلى قائمة البيانات بدلاً من نسخ مهام CI. تُقيّد CI عدد الحلقات للتحقق من خط الأنابيب من البداية إلى النهاية؛ وتسجّل metrics.json نسخة نقطة التفتيش، ووسم صورة المحاكِية، والتزام، والحد الأقصى، وتُعلّم هذه التشغيلات بـsmoke: فمعدلات نجاحها ليست درجات سياسة. تمتلك صور المحاكِية أرقام تثبيت ووسوم محتوى منفصلة؛ ولا تُحفظ ذاكرة BuildKit المؤقتة إلا على المنفذين الدائمين.
تغيير معيار الأداء
تحدد دالة canonical_observation() ودالة conventions() وغلاف البيئة الخاصة بالتكامل ما يراه النموذج الاستراتيجي وكيفية تطبيق أفعاله. لا يؤدي اتجاه صورة خاطئ أو ترتيب حالة أو معدل تحكم غير صحيح إلى انهيار النظام: بل يرى النموذج الاستراتيجي مدخلات خاطئة بشكل طفيف، مما يؤدي إلى انخفاض معدل نجاحه. أي تغيير في أي من هذه العناصر يترافق مع:
- اختبار انحدار يقارن المخرجات القديمة والجديدة على ملاحظة مسجّلة أو اصطناعية. يُعدّ
test_libero_numpy_adapter_parityفيtests/sim/integrations/test_libero.pyالنموذج المرجعي: فهو يُظهر أن مُكيّف LIBERO الخالي من torch ينتج بالضبط ما كان مُعالج LIBERO السابق ينتجه. - التأثير المتوقع على الدرجات في طلب الإرسال: لا يوجد، أو أي الدرجات ينبغي أن تتغير ولماذا.
التبعيات ( pyproject.toml )
أضف مجموعة اعتمادات اختيارية جديدة للاستخدام المحلي:
mybenchmark = ["my-benchmark-pkg==1.2.3", "lerobot[scipy-dep]"]قواعد التثبيت:
- ثبّت دائمًا حزم المعايير على إصدارات محددة لضمان قابلية التكرار (مثل
metaworld==3.0.0). - أضف علامات المنصة عند الحاجة (مثل
; sys_platform == 'linux'). - تثبيت التبعيات غير المباشرة الهشة إذا كانت معروفة (على سبيل المثال، يثبّت صورة Meta-World
mujoco==3.15.0، لأن MuJoCo 3.17 يكسر لحامات التقاط الحركة الخاصة بها). - قيود المستند في صفحة مستند المعيار المرجعي الخاص بك. عندما تتعارض التبعيات مع تبعيات LeRobot، فإن المسار المُقدَّم هو المدعوم.
كتابة صفحة مستند للمعايير
أضف الصفحة إلى قسم “Benchmarks” في docs/source/_toctree.yml. يجب أن تتضمن كل صفحة معيار:
- العنوان والوصف — فقرة أو فقرتان حول ما يختبره المعيار ولماذا يهم.
- روابط — الورقة البحثية، مستودع GitHub، موقع المشروع (إن كان متاحًا).
- المصدر والتراخيص — مستودعات المصدر، ومراجعات الأكواد والأصول المثبتة، وترخيص كل منها. لا تضف معيار تقييم إذا كان ترخيصه يمنع الاستخدام.
- صورة أو ملف GIF تعريفي.
- المهام المتاحة — جدول لمجموعات المهام مع عدد المهام ووصف موجز.
- التثبيت —
pip install -e ".[<benchmark>]"، أو أمر الخادم. - التقييم — الأمر
lerobot-evalالموصى به معn_episodesللحصول على نتائج قابلة للتكرار. - مدخلات ومخرجات السياسة — مفاتيح الملاحظة مع أشكالها، وصف مساحة الإجراءات.
- التدريب — مثال على أمر
lerobot-train. - نتائج مرجعية — معدل النجاح المنشور لنقطة تحقق مسبقة التدريب واحدة على الأقل يمكنك تشغيلها، مع إصدارها وأمر
lerobot-evalالذي يعيد إنتاجه. التكامل الذي لا يصل إلى مستوى قريب من ذلك يُعتبر غير مكتمل.
راجع docs/source/libero.mdx وdocs/source/metaworld.mdx للحصول على أمثلة كاملة.