Hugging Face's logo

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.6.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

المعالجات

المعالجات هي طبقة تحويل البيانات بين الروبوت ومجموعة البيانات والسياسة. الخطّ الأنابيب هو سلسلة من خطوات ProcessorStep؛ حيث تُعلن كل خطوة عن كيفية تحويلها لكلٍّ من البيانات وعقد الميزات.

راجع مقدمة إلى معالجات الروبوت للمفاهيم، وتنفيذ معالجك الخاص لكتابة خطوة، وتصحيح أخطاء خط المعالجة الخاص بك عندما يتصرف خط المعالجة بشكل غير صحيح.

ProcessorStep

فئة lerobot.processor.ProcessorStep

< >

( )

فئة أساسية مجردة لخطوة واحدة في خط معالجة البيانات.

يجب على كل خطوة تنفيذ طريقة __call__ لإجراء تحويلها على انتقال البيانات، وطريقة transform_features لوصف كيفية تغييرها لشكل أو نوع ميزات البيانات.

يمكن أن تكون الفئات الفرعية اختيارية الحالة من خلال تنفيذ state_dict وload_state_dict.

get_config

< >

( )

يعيد إعدادات الخطوة للتسلسل.

load_state_dict

< >

( state: dict[str, torch.Tensor] )

المعاملات

  • state — قاموس من متجهات الحالة.

يحمّل حالة الخطوة من قاموس الحالة.

إعادة تعيين

< >

( )

يعيد تعيين الحالة الداخلية لخطوة المعالج، إن وُجدت.

save_artifacts

< >

( save_directory: Path )

احفظ الأصول غير المتجهات وخريطة معاملات المُنشئ إلى المسارات النسبية.

state_dict

< >

( )

يعيد حالة الخطوة (مثل المعلمات المتعلمة والمتوسطات التشغيلية).

transform_features

< >

( features: dict[PipelineFeatureType, dict[str, PolicyFeature]] )

المعاملات

  • features — قاموس يصف ميزات الإدخال للملاحظات والإجراءات وما إلى ذلك.

يحدد كيف تعدّل هذه الخطوة وصف ميزات خط المعالجة.

تُستخدم هذه الطريقة لتتبع التغييرات في أشكال البيانات أو أنواعها أو أنماطها أثناء مرور البيانات عبر خط المعالجة، دون الحاجة إلى معالجة البيانات الفعلية.

DataProcessorPipeline

فئة lerobot.processor.DataProcessorPipeline

< >

( steps: Sequence[ProcessorStep] = <factory>name: str = 'DataProcessorPipeline'to_transition: Callable[[TInput], EnvTransition] = <factory>to_output: Callable[[EnvTransition], TOutput] = <factory>before_step_hooks: list[Callable[[int, EnvTransition], None]] = <factory>after_step_hooks: list[Callable[[int, EnvTransition], None]] = <factory> )

المعاملات

  • steps — تسلسل من كائنات ProcessorStep التي تُشكّل خط الأنابيب.
  • name — اسم وصفي للخطّ الأنابيب.
  • to_transition — دالة لتحويل البيانات الخام إلى تنسيق EnvTransition الموحّد.
  • to_output — دالة لتحويل EnvTransition النهائي إلى صيغة المخرجات المطلوبة.
  • before_step_hooks — قائمة من الدوال التي تُستدعى قبل تنفيذ كل خطوة.
  • after_step_hooks — قائمة من الدوال التي تُستدعى بعد تنفيذ كل خطوة.

خط أنابيب تسلسلي لمعالجة البيانات، مُدمج مع Hugging Face Hub.

تربط هذه الفئة بين عدة كائنات ProcessorStep لتشكيل سير عمل كامل لمعالجة البيانات. وهي فئة عامة، مما يسمح بأنواع مخصصة للمدخلات والمخرجات، والتي يتولى معالجها محوّلا to_transition وto_output.

from_config

< >

( config: dict[str, Any]state_dict: dict[str, dict[str, torch.Tensor]] | None = Noneoverrides: dict[str, Any] | None = Noneto_transition: Callable[[TInput], EnvTransition] | None = Noneto_output: Callable[[EnvTransition], TOutput] | None = None )

المعاملات

  • config — قاموس إعدادات لهيكلية مطابقة لملف JSON الخاص بالمعالج المحفوظ.
  • state_dict — حالة خط أنابيب اختياري في الذاكرة مجمّعة حسب مفتاح الحالة الذي لا يحمل لاحقة.
  • overrides — تجاوزات اختيارية للمُنشئ (constructor) مفهرسة باسم السجل أو اسم الفئة.
  • to_transition — محوّل اختياري من البيانات المدخلة إلى EnvTransition.
  • to_output — مُحوِّل اختياري من EnvTransition إلى بيانات الإخراج.

قم ببناء خط أنابيب من تكوين في الذاكرة وموترات حالة اختيارية.

from_pretrained

< >

( pretrained_model_name_or_path: str | Pathconfig_filename: strforce_download: bool = Falseresume_download: bool | None = Noneproxies: dict[str, str] | None = Nonetoken: str | bool | None = Nonecache_dir: str | Path | None = Nonelocal_files_only: bool = Falserevision: str | None = Noneoverrides: dict[str, Any] | None = Noneto_transition: Callable[[TInput], EnvTransition] | None = Noneto_output: Callable[[EnvTransition], TOutput] | None = None**kwargs )

المعاملات

  • pretrained_model_name_or_path — معرّف المستودع على Hugging Face Hub، أو مسار إلى مجلد محلي، أو مسار إلى ملف إعداد واحد.
  • config_filename — اسم ملف تكوين JSON الخاص بالخط الأنابيب. مطلوب دائمًا لمنع الغموض عند وجود تكوينات متعددة (مثل المعالج المسبق مقابل المعالج اللاحق).
  • force_download — ما إذا كان يجب إجبار (إعادة) تنزيل الملفات.
  • resume_download — يُحفظ من أجل التوافق مع الإصدارات السابقة ويُتجاهل. تُستأنف التنزيلات تلقائيًا.
  • proxies — يُحفظ للتوافق مع الإصدارات السابقة ويُتجاهل. استخدم HTTP_PROXY و HTTPS_PROXY بدلاً منه.
  • token — الرمز الذي يُستخدم كتوكن مصادقة HTTP bearer للمستودعات الخاصة في Hub.
  • cache_dir — المسار إلى مجلد تخزين مؤقت محدد لتخزين الملفات التي تم تنزيلها.
  • local_files_only — إذا كانت القيمة True، فتجنّب تنزيل الملفات من Hub.
  • revision — إصدار النموذج المحدد الذي سيتم استخدامه (مثل اسم فرع، أو اسم وسم، أو معرف التزامن).
  • overrides — قاموس لتجاوز إعدادات خطوات محددة. يجب أن تتطابق المفاتيح مع اسم فئة الخطوة أو اسمها في السجل.
  • to_transition — دالة مخصصة لتحويل البيانات المدخلة إلى EnvTransition.
  • to_output — دالة مخصصة لتحويل EnvTransition النهائي إلى صيغة الإخراج.
  • **kwargs — حُجج إضافية (غير مستخدمة).

يرفع

FileNotFoundError أو ValueError أو ImportError أو KeyError أو ProcessorMigrationError

  • FileNotFoundError — إذا تعذّر العثور على ملف الإعدادات.
  • ValueError — إذا كانت الإعدادات غير واضحة أو فشلت عملية الإنشاء.
  • ImportError — إذا تعذّر استيراد فئة خطوة معينة.
  • KeyError — إذا لم يطابق مفتاح التغطية أي خطوة في خط المعالجة.
  • ProcessorMigrationError — إذا كان النموذج يتطلب الترحيل إلى صيغة المعالج.

يحمّل خط أنابيب من مجلد محلي، أو ملف واحد، أو مستودع في Hugging Face Hub.

تنفّذ هذه الطريقة خط أنابيب مبسّط للتحميل مع كشف ذكي للهجرة:

استراتيجية التحميل المبسطة:

  1. تحميل الإعدادات (_load_config):

    • المجلد: تحميل config_filename المحدد من المجلد
    • ملف واحد: تحميل الملف مباشرةً (يتم تجاهل config_filename)
    • مستودع Hub: تنزيل config_filename المحدد من Hub

  2. التحقق من صحة التكوين (_validate_loaded_config):

    • التحقق من التنسيق: التأكد من أن الإعدادات بصيغة معالج صالحة
    • كشف عملية الترحيل: توجيه المستخدمين لترحيل نماذج LeRobot القديمة
    • توضيح الأخطاء: تقديم رسائل خطأ قابلة للتنفيذ

  3. بناء الخطوات (_build_steps_with_overrides):

    • حلّ الفئة: البحث في السجل أو الاستيرادات الديناميكية
    • الاستبدال عند الدمج: تُستبدل الإعدادات المحفوظة بمعايير المستخدم
    • تحميل الحالة: تحميل ملفات .safetensors للخطوات ذات الحالة

  4. تجاوز التحقق (_validate_overrides_used):

    • تأكد من تطبيق جميع تجاوزات المستخدم (لاكتشاف الأخطاء الإملائية)
    • تقديم رسائل خطأ مفيدة مع المفاتيح المتاحة

كشف الترحيل:

  • الاكتشاف الذكي: يحلل ملفات JSON للكشف عن نماذج LeRobot القديمة
  • استهداف دقيق: يتجنب الإيجابيات الكاذبة على نماذج HuggingFace الأخرى
  • إرشادات واضحة: يوفر أمر الترحيل الدقيق الذي يجب تشغيله
  • وضع الخطأ: يرمي دائمًا ProcessorMigrationError لاتخاذ إجراء واضح من قبل المستخدم

تحميل الأمثلة:

# Directory loading
pipeline = DataProcessorPipeline.from_pretrained("/models/my_model", config_filename="processor.json")

# Single file loading
pipeline = DataProcessorPipeline.from_pretrained(
    "/models/my_model/processor.json", config_filename="processor.json"
)

# Hub loading
pipeline = DataProcessorPipeline.from_pretrained("user/repo", config_filename="processor.json")

# Multiple configs (preprocessor/postprocessor)
preprocessor = DataProcessorPipeline.from_pretrained(
    "model", config_filename="policy_preprocessor.json"
)
postprocessor = DataProcessorPipeline.from_pretrained(
    "model", config_filename="policy_postprocessor.json"
)

نظام التخطي:

  • مطابقة المفاتيح: استخدم أسماء السجل أو أسماء الفئات كمفاتيح للتجاوز
  • دمج الإعدادات: تتفوق قيم المستخدم المُعدّلة على الإعدادات المحفوظة
  • التحقق: تأكد من تطابق جميع مفاتيح التغطية مع الخطوات الفعلية (لاكتشاف الأخطاء الإملائية)
  • مثال: overrides={“NormalizeStep”: {“device”: “cuda”}}

get_config

< >

( )

إرجاع إعدادات خط الأنابيب القابلة للتسلسل بصيغة JSON.

load_state_dict

< >

( state_dict: dict[str, dict[str, torch.Tensor]] )

المعاملات

  • state_dict — قاموس يربط مفاتيح الحالة التي لا تحمل لاحقة بقواميس حالة الخطوة.

يرفع

KeyError

  • KeyError — إذا اكتشف التحميل حالة متوقعة مفقودة أو حالة إضافية غير متوقعة.

حمّل متجهات حالة خط الأنابيب إلى الخطوات الموجودة.

process_action

< >

( action: PolicyAction | RobotAction | EnvAction )

المعاملات

  • action — بيانات الإجراء.

يعالج الجزء الخاص بالإجراء فقط من الانتقال عبر خط المعالجة.

process_complementary_data

< >

( complementary_data: dict[str, Any] )

المعاملات

  • complementary_data — قاموس البيانات التكميلية.

يعالج فقط الجزء التكميلي من البيانات للانتقال عبر خط المعالجة.

process_done

< >

( done: bool | torch.Tensor )

المعاملات

  • done — علم الانتهاء.

يعالج فقط علم "done" للانتقال عبر خط الأنابيب.

process_info

< >

( info: dict[str, Any] )

المعاملات

  • info — قاموس المعلومات.

يعالج فقط قاموس المعلومات الخاص بانتقال واحد عبر خط المعالجة.

process_observation

< >

( observation: RobotObservation )

المعاملات

  • observation — قاموس الملاحظة.

يعالج الجزء المتعلق بالملاحظة فقط من الانتقال عبر خط المعالجة.

process_reward

< >

( reward: float | torch.Tensor )

المعاملات

  • reward — قيمة المكافأة.

يعالج فقط الجزء المتعلق بالمكافأة من الانتقال عبر خط المعالجة.

process_truncated

< >

( truncated: bool | torch.Tensor )

المعاملات

  • truncated — علم المقطوع.

يعالج فقط علم الاقتطاع (truncated flag) للانتقال عبر خط الأنابيب.

register_after_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

المعاملات

  • fn — دالة قابلة للاستدعاء تقبل فهرس الخطوة والانتقال الحالي.

يسجّل دالةً تُستدعى بعد كل خطوة.

register_before_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

المعاملات

  • fn — دالة قابلة للاستدعاء تقبل فهرس الخطوة والانتقال الحالي.

يسجّل دالةً تُستدعى قبل كل خطوة.

إعادة تعيين

< >

( )

يعيد تعيين حالة جميع الخطوات ذات الحالة في خط المعالجة.

save_pretrained

< >

( save_directory: str | Path | None = Nonerepo_id: str | None = Nonepush_to_hub: bool = Falsecard_kwargs: dict[str, Any] | None = Noneconfig_filename: str | None = None**push_to_hub_kwargs )

المعاملات

  • save_directory — المجلد الذي سيتم حفظ خط المعالجة فيه. إذا كانت القيمة None، يتم الحفظ في HF_LEROBOT_HOME/processors/{sanitized_pipeline_name}.
  • repo_id — معرف مستودعك على Hub. يُستخدم فقط إذا كان push_to_hub=true.
  • push_to_hub — ما إذا كان سيتم دفع كائنك إلى Hugging Face Hub بعد حفظه.
  • card_kwargs — حُجج إضافية تُمرَّر إلى قالب البطاقة لتخصيصها.
  • config_filename — اسم ملف الإعدادات بصيغة JSON. إذا كانت القيمة None، يتم توليد اسم من خاصية name الخاصة بالخط.
  • **push_to_hub_kwargs — Additional key word arguments passed along to the push_to_hub method.

يحفظ تكوين خط المعالجة وحالته في مجلد.

ينشئ هذا الأسلوب ملف تكوين بصيغة JSON يحدد بنية خط الأنابيب (الاسم والخطوات). ولكل خطوة ذات حالة، يحفظ أيضًا ملف .safetensors يحتوي على قاموس حالتها.

state_dict

< >

( )

إرجاع تينسورات حالة خط الأنابيب مجمّعةً حسب مفتاح الحالة.

step_through

< >

( data: TInput )

المعاملات

  • data — البيانات المدخلة.

يعالج البيانات خطوة بخطوة، مع تقديم الانتقال عند كل مرحلة.

هذه طريقة مولِّدة مفيدة لتصحيح الأخطاء وفحص الحالة الوسيطة للبيانات أثناء مرورها عبر خط المعالجة.

transform_features

< >

( initial_features: dict[PipelineFeatureType, dict[str, PolicyFeature]] )

المعاملات

  • initial_features — قاموس يصف الميزات الأولية.

يطبّق تحويلات الميزات من جميع الخطوات بشكل متسلسل.

تقوم هذه الطريقة بنشر قاموس وصف الميزات عبر طريقة transform_features لكل خطوة، مما يتيح للخط أن يحدد بشكل ثابت مواصفات ميزات الإخراج دون معالجة أي بيانات حقيقية.

unregister_after_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

المعاملات

  • fn — كائن الدالة الدقيق الذي تم تسجيله سابقًا.

يرفع

ValueError

  • ValueError — إذا لم يتم العثور على الخطاف في القائمة.

يلغي تسجيل خطاف 'after_step'.

unregister_before_step_hook

< >

( fn: Callable[[int, EnvTransition], None] )

المعاملات

  • fn — كائن الدالة الدقيق الذي تم تسجيله سابقًا.

يرفع

ValueError

  • ValueError — إذا لم يتم العثور على الخطاف في القائمة.

يلغي تسجيل خطاف 'before_step'.

PolicyProcessorPipeline

lerobot.processor.DataProcessorPipeline

( *args**kwargs )

Update on GitHub

←سياسات البيئات→