توسيع مُصدِّرات

torch.export يتتبع النموذج إلى رسم بياني، ثم تحوّل المراحل اللاحقة ذلك الرسم البياني، وتُصدر المرحلة النهائية أو تُخفضه لتشغيله على بيئة التشغيل المستهدفة. تمر معظم النماذج دون أي تعديل. عندما يكون هناك نمط في PyTorch لا تستطيع الخلفية التعامل معه، يطبّق المُصدِّر حلاً بديلاً بسيطاً في تلك المرحلة بدلاً من تعديل النموذج.

أضف حلًا بديلًا من خلال كتابة دالة واحدة وتسجيلها باستخدام مُزيِّن. يجب أن ينتمي كل حل بديل إلى أدنى مرحلة يمكن التعبير عنه فيها بوضوح.

التصحيحات والإصلاحات

الحل البديل هو إما رقع أو إصلاح. يختلف الاثنان في إمكانية التراجع عنهما.

توجد كلاهما في سجل داخل exporters/utils.py، ويقوم المُصدِّر بتثبيت كل ما تم تسجيله لخلفية تشغيله في المرحلة المناسبة.

لجأ إلى تطبيق تصحيح (Patch) عندما يكون الخلل متعلقًا بخلل في خفض (Lowering) واجهة خلفية واحدة: ترجمة ONNX مفقودة، أو غرابة في التحقق من صحة ORT، أو تفكيك FX يُصدر عملية ميتة. يبقى الحل البديل داخل المُصدِّر (Exporter)، وتبقى كود النمذجة نظيفًا.

عندما تُصدَّر كتل الأنماط عبر واجهات خلفية متعددة، مثل الحلقات المعتمدة على البيانات، أو ذاكرات التخزين المؤقت ذات الحالة خارج Cache، أو انتباه حلقة مقسومة مكتوبة يدويًا، فصحّح النموذج بدلاً من ذلك. إن إصلاحه مرة واحدة في النموذج يفيد كل مُصدِّر.

إضافة رقعة

افترض أن طريقة في النموذج تقوم بشيء لا يستطيع torch.export تتبّعه. يقوم NllbMoeTop2Router._cast_classifier في NLLB-MoE بتحويل أوزان المصنّف إلى نوع بيانات آخر، وهو أمر غير قابل للتتبّع. استبدله بعمليّة لا تفعل شيئًا (no-op) طوال فترة التصدير.

اكتب مصنعًا يستقبل الطريقة الأصلية ويعيد بديلها، ثم سجّل المصنع مقابل المسار المنقّط للطريقة:

from transformers.exporters.utils import register_patch

@register_patch("dynamo", "transformers.models.nllb_moe.modeling_nllb_moe.NllbMoeTop2Router._cast_classifier")
def _patch_classifier_cast(_original):
    # Replace the untraceable dtype cast with a no-op during export.
    return lambda self, *args, **kwargs: None

يستبدل المُصدِّر الطريقة قبل التتبع ثم يعيدها إلى وضعها الأصلي بعد ذلك، لذا فإن التصحيح يؤثر على التصدير فقط. بعض التغيرات:

• مرّر مسارات إضافية لمشاركة مصنع واحد عبر مواقع الاستدعاء، على سبيل المثال @register_patch("dynamo", path_a, path_b).
• قم بإصلاح عملية torch عن طريق توجيه المسار إليها، على سبيل المثال @register_patch("onnx", "torch.where"). تستقبل المصنع العملية الحقيقية كحجة لها، لذا يمكن للاستبدال أن يستدعيها.
• اكتب إصلاحًا (fix) بدلاً من رقع (patch) عندما تحتاج إلى إعادة كتابة الرسم البياني بعد التتبع. الآلية هي نفسها، وهي دالة مُزيَّنة (decorated) في سجل التطابق (matching registry).

مرجع المرحلة

تُوسِّم مصادر كل مُصدِّر مراحلها كتعليقات على شكل # ── Stage N: … ──، لذا يتطابق الملف مع هذا المرجع. راجع تلك المصادر لمعرفة العمليات والفئات الدقيقة التي تعالجها كل مرحلة.

DynamoExporter

تُنفّذ أداة التصدير الأساسية مرحلة تصحيح واحدة وأربعة مساعدين، بالترتيب، داخل DynamoExporter.export (انظر exporter_dynamo.py).

1. إصلاح التوقيع الأمامي: يمنح model.forward توقيعًا مسطّحًا للحجج حتى لا يجمع torch.export المدخلات في مجموعة **kwargs واحدة. هذا داخلي وليس نقطة توسيع.
2. إصلاحات النموذج: استبدال طرق النموذج غير القابلة للتتبع بما يعادلها الآمن للتصدير أثناء التتبع. وسّع باستخدام @register_patch("dynamo", ...).
3. تسجيل Pytree: سجّل كل من Cache وModelOutput بحيث يستطيع torch.export تسطيحها وإعادة بنائها (يحدث ذلك عادةً تلقائيًا). أضف فرعًا إلى _flatten_to_context / _unflatten_from_context لنوع لا يمكن لرحلة الاستعلام عن السمات الوصول إليه.
4. الأشكال الديناميكية: اسند Dim.AUTO إلى كل متجه ومخزن أوراق عند dynamic=True. يمكن تجاوز ذلك باستخدام DynamoConfig.dynamic_shapes.
5. تنظيف الحالة: إعادة تعيين خصائص الموترات التي يضبطها النموذج داخل forward والتي يتركها torch.export كموترات وهمية. قم بالتوسعة عن طريق إضافة اسم الخاصية إلى _STATEFUL_CACHE_ATTRS.

OnnxExporter

OnnxExporter يضيف خمس مراحل حول torch.onnx.export (انظر exporter_onnx.py). ابحث في الملف عن القائمة الكاملة للإصلاحات:

grep -nE "^def (_patch_|_fix_|_aten_)" src/transformers/exporters/exporter_onnx.py

1. رقعات Torch: استبدال عمليات torch التي لا يستطيع مُصدِّر ONNX ترجمتها كما هي. قم بالتوسعة باستخدام @register_patch("onnx", ...).
2. إصلاحات ONNX: إعادة تشغيل إصلاحات العقد بعد run_decompositions حتى تُصلح عقد حراسة الشكل الجديدة قبل التحويل. يستخدم نفس سجل @register_patch("onnx", ...).
3. إصلاحات عقد FX: إعادة كتابة عقد الرسم البياني التي لا يستطيع مُصدِّر ONNX تحويلها، مثل عمليات الاستعارة (alias ops)، وعروض الموقع (in-place views)، والتحققات غير الفعّالة (dead asserts). قم بالتوسعة باستخدام @register_fx_node_fix("onnx").
4. ترجمات ONNX: قدّم خفضًا مخصصًا لعملية aten حيث تكون الافتقادية مفقودة أو بها خطأ (على سبيل المثال aten.index_put أو aten._grouped_mm). أضف دالة _aten_* إلى _ONNX_TRANSLATION_TABLE.
5. إصلاحات ONNX IR: إعادة كتابة برنامج ONNX المُنجَز لتجاوز أخطاء ONNX Runtime (على سبيل المثال، فرض TopK(sorted=True)). أضف دالة _fix_ir_* إلى _IR_FIXES.

ExecutorchExporter

ExecutorchExporter يضيف خمس مراحل حول to_edge_transform_and_lower وto_executorch، مبتدئًا بتجهيز الخلفية (انظر exporter_executorch.py).

1. التحضير للواجهة الخلفية: انقل النموذج إلى الجهاز ونوع البيانات المستهدفين واختر مُقسِّمه (prepare_for_xnnpack، prepare_for_cuda). أضف واجهة خلفية عن طريق تسجيل prepare_for_<name> في _BACKEND_PREPARE.
2. رقعات Torch: استبدال عمليات torch التي لا تقبلها واجهات ExecuTorch الخلفية، مثل split_copy وchunk وtopk(k>dim). قم بالتوسعة باستخدام @register_patch("executorch", ...).
3. رقعات ExecuTorch: استبدال مكونات ExecuTorch الداخلية التي تتسبب في انهيار الرسوم البيانية ذات الأشكال الديناميكية الصالحة. تستخدم نفس سجل @register_patch("executorch", ...).
4. إصلاحات برنامج FX: إصلاح البرنامج المُصدَّر حيث يتطلب الإصلاح سياق البرنامج الكامل، مثل توسيع قيود المدى أو ملء بيانات الوصف المفقودة للمواقع الوهمية. قم بالتوسعة باستخدام @register_fx_program_fix("executorch").
5. إصلاحات عقد FX: إعادة كتابة العقد الفردية، مثل تعيين عمليات Python الرمزية إلى executorch_prim.* أو إعادة كتابة pow كسلسلة من mul. قم بالتوسعة باستخدام @register_fx_node_fix("executorch").

حلول مؤقتة معروفة في المنبع

تتعرض بعض فئات النماذج لأخطاء مؤكدة في مُحسِّن الرسوم البيانية في onnxscript (مثل انهيار طي الثوابت عند SplitToSequence، أو فقدان مُهيِّئات FPN). يُعطِّل ONNX_DISABLE_OPTIMIZE تحسين onnxscript لتلك النماذج. يسجِّل كل بند المشكلة الأصلية (upstream issue) بجوار اسم النموذج. ومن المتوقع أن يتقلَّص هذا القائمة مع معالجة الأخطاء الأصلية، لذا يجب أن يُحيل أي بند جديد إلى خطأ محدد في المصدر الأصلي بدلاً من تعطيل التحسين بشكل تعسفي.

EXPORT_SKIPS، يُستثنى عدد قليل من فئات النماذج تمامًا من عملية التصدير عندما يكون النموذج غير قابل للتصدير بشكل أساسي كما هو (تدفق تحكم يعتمد على البيانات ولا يمكن تحويله إلى متجهات، أو وحدات تُعامل كحجوزات للأمام). تحمل كل مدخل سببًا يحدد التغيير المطلوب على جانب النموذج. ومن المتوقع أيضًا أن تتقلص هذه القائمة، لا أن تتوسع.