إضافة معيار

المعيار (Benchmark) هو محاكي يقود LeRobot في مكان واحد، وهو lerobot.sim، بحيث تتصرف جميع طرق استخدامه بنفس الطريقة: lerobot-eval (بيئة مجمّعة، --env.type=<benchmark>)، والتشغيل والتسجيل (روبوت محاكاة، --robot.type=sim --robot.env.type=<benchmark>)، محليًا أو عبر lerobot-env-server من صورة Docker الخاصة به. راجع المحاكاة: محلية أو عبر خادم لمعرفة كيفية استخدامه.

ما يجب إضافته

تُظهر المساران نفس سلوك البيئة:

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 يقيّم كل معيار أداء بنفس الطريقة:

1. make_env() يبني قاموسًا متداخلًا على النحو {suite: {task_id: vector env}}.
2. eval_policy_all() ينفّذ n_episodes من جولات كل مهمة، مهمةً تلو الأخرى (أو --env.max_parallel_tasks في آنٍ واحد).
3. تُجمَّع النتائج لكل حلقة، ومهمة، وحزمة، وإجمالي: 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

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)

step() يُبلّغ عن النجاح في info["is_success"]، وعن أي قياسات أخرى في info["metrics"]. الإجراءات عبارة عن Box مستمر أحادي البُعد.

الملاحظات هي قاموس (dict) يفهمه مُكيّف canonical_observation() الخاص بالتكامل. يُجري المُكيّف الافتراضي القابل لإعادة الاستخدام الخرائط التالية:

تُمرَّر أي مصفوفة أخرى على أنها 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

1. تحقق من مُكيّف الملاحظات الخاص بالتكامل مقابل المخرجات الخام لمحاكيك، لا سيما اتجاه الكاميرا وترتيب الحالة، وتحقق من الإجراءات المطبقة بواسطة غلاف البيئة.
2. قارن تسلسلات إعادة الضبط/الخطوة المُزروعة محليًا والمُقدَّمة (scripts/ci/check_sim_parity.py)؛ اضبط parity: true في عنصر قائمة التشغيل لمحاكي حتمي حتى تُنفّذ CI ذلك. تحقق من تجميد الطرفية، والنجاح، وطول الحلقة، والعرض، وتنظيف الموارد.
3. شغّل حراس الاستيراد المعطّلين لـ torch لأكواد الخادم ووحدة الأصل الخاصة بك. وثّق المحاكيّات التي تحتاج إلى وقت تشغيل خاص بها لـ torch، مثل RoboTwin وRoboMME.
4. شغّل lerobot-eval --env.type=<name> --env.task=<task> --eval.n_episodes=1 --policy.path=<checkpoint> محليًا، ومع --env.server.endpoint ضد الخادم. افحص أوصاف المهام وعروض الكاميرا المُصيَّرة.
5. شغّل مهمة المعيار المولّدة على منفّذ 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 للحصول على أمثلة كاملة.