# خريطة الدمج (ميزة تجريبية)

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

يُبنى على:

- [التعديل المباشر (Monkey patching)](./monkey_patching) لاستبدال فئات الوحدات قبل إنشاء النموذج.
- [تحميل الأوزان الديناميكي](./weightconverter) لربط الأوزان بين تخطيطات وقت التشغيل الأصلية والمدمجة.

> [!WARNING]
> تُعدّ خرائط الدمج ميزة تحميل تجريبية. فهي تُغيّر بنية وحدة وقت التشغيل وقد تؤثر على سلوك النموذج. استخدمها فقط عندما ترغب صراحةً في تخطيط وقت تشغيل مدمج.

## البدء السريع

يتم تفعيل الدمج من خلال [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) باستخدام `fusion_config`:

```python
from transformers import AutoModelForImageTextToText

model = AutoModelForImageTextToText.from_pretrained(
    "Qwen/Qwen2-VL-2B-Instruct",
    fusion_config={"patch_embeddings": True},
)
```

بشكل افتراضي، لا يُطبَّق أي اندماج. إذا كان `fusion_config` مخزَّنًا في إعدادات النموذج، فستعيد `from_pretrained()` استخدامه تلقائيًا.

## كيف يعمل

تحدث تسجيل الدمج قبل إنشاء النموذج:

1. يستخدم [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) الحجة الصريحة `fusion_config` أو يعتمد على `config.fusion_config`.
2. يتحقق سجل الدمج من أسماء الدمج المطلوبة.
3. يُهيّئ كل اندماج مفعّل فئة النموذج المستهدف مبدئيًا، ويصفّي الوحدات المرشحة اختياريًا حسب الاسم، ويستخدم `is_fusable(...)` لاكتشاف فئات الوحدات المتوافقة.
4. تُسجَّل فئات الاستبدال المدمجة من خلال [register_patch_mapping()](/docs/transformers/main/ar/monkey_patching#transformers.monkey_patching.register_patch_mapping).
5. تُولَّد قواعد `~WeightTransform` المطابقة من ملف الإعدادات حتى يتمكن تحميل نقطة الحفظ من تعيين الأوزان إلى تخطيط وقت التشغيل المدمج.
6. بشكل افتراضي، يستخدم [save_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.save_pretrained) مسار التحويل العكسي لاستعادة تخطيط نقطة التفتيش الأصلية. مرّر `save_original_format=False` للإبقاء على تخطيط وقت التشغيل المحوّل بدلاً من ذلك.

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

ملاحظة: مع آلية التعديل الديناميكي (monkey-patching) الحالية، فإن تسجيل الدمج يتم على مستوى الفئة: تُطابق فئة وحدة واحدة متوافقة مع فئة بديلة مدمجة واحدة.

## عائلات الاندماج الحالية

حاليًا، يدعم `fusion_config` عائلة اندماج واحدة:

- `patch_embeddings` تفعيله عبر:

  ```python
  fusion_config = {"patch_embeddings": True}
  ```

  الأثر: يستبدل إسقاطات تضمين البقع المتوافقة `nn.Conv3d` بإسقاطات `nn.Linear` مسطحة مكافئة وقت التشغيل.

## توسيع خرائط الدمج

لإضافة عائلة اندماج جديدة:

1. أضف شرط `is_fusable`. يحدد هذا الشرط ما إذا كان الوحدة المكتشفة متوافقة مع الدمج.
2. أضِف اختياريًا `target_modules_patterns`. هذا يجعل خطوة الاكتشاف أكثر صراحةً من خلال تصفية أسماء الوحدات المرشحة مسبقًا قبل `is_fusable(...)`.
3. أضِف مصنع `make_fused_class`. يعيد هذا المصنع فئة الاستبدال وقت التشغيل لفئة وحدة متوافقة.
4. أضِف مصنع `make_transforms` إذا تطلّب التخطيط المدمج تحويل نقاط التفتيش. يعيد هذا المصنع قواعد `~WeightTransform` التي تُخضع الأوزان للتحويل بين التخطيط الأصلي والتخطيط المدمج لإعداد معيّن.
5. سجّل `ModuleFusionSpec` الجديد في [`fusion_mapping.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py).

بمجرد التسجيل، يصبح الاندماج الجديد متاحًا عبر `fusion_config`.

## واجهة برمجة التطبيقات الداخلية[[transformers.fusion_mapping.ModuleFusionSpec]]

#### transformers.fusion_mapping.ModuleFusionSpec[[transformers.fusion_mapping.ModuleFusionSpec]]

```python
transformers.fusion_mapping.ModuleFusionSpec()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L47)

وصفة أساسية لعائلة الاندماج.

تحدد مواصفة الدمج أي الوحدات المؤهلة للدمج، وكيفية بناء فئة الاستبدال وقت التشغيل، وأي تحويلات الأوزان المطلوبة لربط نقاط التفتيش بين التخطيط الأصلي والتخطيط المدمج.

#### get_empty_log[[transformers.fusion_mapping.ModuleFusionSpec.get_empty_log]]

```python
get_empty_log(model_name: str)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L57)

إرجاع رسالة التسجيل التي تُصدر عند عدم العثور على وحدات متوافقة.

#### is_fusable[[transformers.fusion_mapping.ModuleFusionSpec.is_fusable]]

```python
is_fusable(module: Module)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L61)

تُرجع ما إذا كان `module` متوافقًا مع عائلة الدمج هذه.

#### make_fused_class[[transformers.fusion_mapping.ModuleFusionSpec.make_fused_class]]

```python
make_fused_class(original_cls: type)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L65)

أنشئ فئة الاستبدال وقت التشغيل لفئة وحدة متوافقة.

#### make_transforms[[transformers.fusion_mapping.ModuleFusionSpec.make_transforms]]

```python
make_transforms(config: PretrainedConfig)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L69)

أنشئ تحويلات الأوزان اللازمة لتحميل وحفظ تخطيط وقت التشغيل المدمج.

#### transformers.fusion_mapping.PatchEmbeddingsFusionSpec[[transformers.fusion_mapping.PatchEmbeddingsFusionSpec]]

```python
transformers.fusion_mapping.PatchEmbeddingsFusionSpec()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L97)

دمج تضمينات البقع المتوافقة مع Conv3d في إسقاطات خطية مسطحة.

#### transformers.fusion_mapping._register_module_fusion[[transformers.fusion_mapping._register_module_fusion]]

```python
transformers.fusion_mapping._register_module_fusion(config: PretrainedConfig, fusion_name: str, spec: ModuleFusionSpec)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L193)

سجّل عائلة اندماج واحدة لـ`cls`.

تحديث هذه الدالة السجلَّين العالميين المستخدمين في التحميل المدمج:
- سجل التعديل الديناميكي (monkey-patching)، بحيث تُستبدل فئات الوحدات المتوافقة قبل التهيئة
- خريطة تحويل نقطة الحفظ، بحيث لا تزال وحدات وقت التشغيل المدمجة تُحمَّل من تخطيط نقطة الحفظ الأصلية

ملاحظات:
- تفشل تحويلات نقاط التفتيش المتعارضة بسرعة

#### transformers.fusion_mapping.register_fusion_patches[[transformers.fusion_mapping.register_fusion_patches]]

```python
transformers.fusion_mapping.register_fusion_patches(config, fusion_config: collections.abc.Mapping[str, bool | collections.abc.Mapping[str, typing.Any]] | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L269)

سجّل اندماجات وقت التشغيل المطلوبة لـ`cls`.

تقوم هذه الدالة بما يلي:
- يتحقق من `fusion_config` مقابل `_FUSION_REGISTRY`
- يحدد عائلات الدمج المفعّلة بترتيب المستخدم
- يسجّل ترقيعات القرد (monkey patches) وتحويلات نقاط التفتيش (checkpoint transforms) قبل إنشاء النموذج