# واجهات الخلفية للخبراء

تنفّذ جميع تطبيقات مزيج الخبراء (MoE) نفس العملية الحسابية على المستوى العالي. فلكل رمز، يختار الموجّه *k* من الخبراء. ثم يُسقط حالة الرمز المخفية عبر معاملات الخبراء المختارين وتُجمَع باستخدام أوزان التوجيه. والفرق بين واجهات الخلفية الخاصة بالخبراء هو *كيف* تُنفَّذ عمليات ضرب المصفوفات الخاصة بتلك الخبراء.

يوفر `ExpertsInterface` واجهات خلفية مُحسّنة للخبراء. إنه يفصل تنفيذ الخبراء عن كود النموذج لتسهيل التجارب مع دوال مختلفة. أضف واجهات خلفية جديدة من خلال نفس الواجهة.

| خلفية الخبراء | الوصف | وحدة معالجة الرسوميات | وحدة المعالجة المركزية |
| --- | --- | --- | --- |
| `"eager"` | تنفيذ مرجعي يتكرر على الخبراء المحددين ويطبّق الإسقاطات على رموزهم. | أداء أساسي معقول دون الحاجة إلى التجميع. | أبطأ من `grouped_mm` لكن أسرع من `batched_mm`. |
| `"batched_mm"` | ينسخ معاملات الخبير المحدد لكل رمز ويحسب إسقاط جميع الرموز في دفعة واحدة باستخدام [torch.bmm](https://docs.pytorch.org/docs/stable/generated/torch.bmm.html). | Fastest للمدخلات الصغيرة، خاصةً عند استخدام التجميع. يستهلك ذاكرة أكبر بسبب تكرار المعلمات. | غير موصى به (أبطأ بكثير من الخوادم الخلفية الأخرى). |
| `"grouped_mm"` | ترتّب الرموز (Tokens) حسب الخبراء المختارين وتستخدم [torch.nn.functional.grouped_mm](https://docs.pytorch.org/docs/stable/generated/torch.nn.functional.grouped_mm.html) لإسقاط جميع الرموز في عملية GEMM مجمّعة واحدة (يتطلب PyTorch 2.9 أو أحدث). | يُعدّ الخيار الأفضل للمدخلات الأكبر حجمًا وأكثر كفاءةً في استخدام الذاكرة لأنه يتجنّب تكرار معاملات الخبراء. سريع عند استخدام التجميع. | أكثر الخوادم الخلفية كفاءةً لجميع أحجام المدخلات. |
| `"deepgemm"` | ترتّب الرموز حسب الخبير المحدد وتُرجِع جميع الرموز في عملية GEMM مجمّعة واحدة متوافقة مع TMA باستخدام نواة [DeepGEMM](https://github.com/deepseek-ai/DeepGEMM) من [kernels-community/deep-gemm](https://huggingface.co/kernels-community/deep-gemm). | واجهة خلفية أصلية لنماذج DeepSeek على Hopper (SM90+) وBlackwell (SM100+)؛ تدعم `bfloat16` والخبراء المُكمَّمين بصيغتي FP8/FP4. | غير مدعوم (CUDA فقط). |
| `"deepgemm_megamoe"` | يجمع بين توزيع الخبير المتوازي، وشبكة MLP البوابة (الإسقاط الصاعد، SwiGLU، الإسقاط الهابط)، ومزج EP في نواة DeepGEMM Mega MoE واحدة، مع تداخل عمليات نقل NVLink مع حسابات نواة المصفوفات. | Blackwell (SM100+) فقط، للخبراء المُكمّينين بـ FP4 الذين يعملون بالتوازي بين الخبراء. | غير مدعوم (CUDA فقط). |
| `"sonicmoe"` | يُدمج مسار `bfloat16` الخاص بـ MoE (توجيه الموزّع، الإسقاط الصاعد البوَّاب، التفعيل، الإسقاط الهابط) في نواة CuteDSL الخاصة بـ grouped-GEMM (من مكتبة [quack](https://github.com/Dao-AILab/quack)) من [kernels-community/sonic-moe](https://huggingface.co/kernels-community/sonic-moe). | أداء ذروة في الإنتاجية على Hopper (SM90+) لخبراء `bfloat16` مع تفعيل مُبوَّب (SwiGLU/GeGLU/ReGLU)، لا سيما في التدريب. | غير مدعوم (CUDA فقط). |

تعمل واجهتا `"batched_mm"` و`"grouped_mm"` أيضًا على الخبراء المُكمّمين بدقة FP8 وFP4 (المُجمّعة بصيغة `int8`) عبر نواة Triton finegrained-fp8، مع قراءة مقاييس بصيغة `float32` أو UE8M0. وتُشكّل هاتان الواجهتان الخيار الاحتياطي للنقاط الفحصية المُكمّمة عندما لا تكون واجهة `"deepgemm"` متاحة.

## التبديل في مرحلة فك الترميز

على وحدة معالجة الرسوميات (GPU)، يتحول النموذج المحمّل باستخدام `experts_implementation="grouped_mm"` تلقائيًا إلى `"batched_mm"` لمرحلة فك الترميز (decode) أثناء التوليد، وهو ما يكون أسرع بكثير عند عدد الرموز المنخفض. يتم استعادة الخلفية الأصلية بمجرد انتهاء التوليد. أما على وحدة المعالجة المركزية (CPU)، فتبقى `grouped_mm` نشطة طوال عملية التوليد لأنها أكثر كفاءة عند جميع أحجام المدخلات.

تصل عملية التبديل إلى طبقات MoE في النموذج على المستوى الأعلى وفي أي هيكل أساسي فرعي، مثل `text_config` لنموذج الرؤية واللغة. فقط إدخالات `grouped_mm` تتحول إلى `batched_mm`. أما الخبراء الذين يعملون بأي واجهة خلفية أخرى فيحتفظون بها.

## تعيين خلفية الخبراء

استخدم الحجة `experts_implementation` في [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لإنشاء نموذج مع واجهة خلفية محددة للخبراء.

```py
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen1.5-MoE-A2.7B",
    dtype="bfloat16",
    experts_implementation="batched_mm",
)
```

يمكنك التبديل بين واجهات الخلفيات للخبراء أثناء التشغيل دون إعادة تحميل النموذج باستخدام [set_experts_implementation()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.set_experts_implementation).

```py
model.set_experts_implementation("eager")
```

اقرأ الخلفية (backend) التي تعمل حاليًا باستخدام [get_experts_implementation()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.get_experts_implementation). تُرجع هذه الدالة `dict` تحتوي على مدخل واحد للنموذج، ومدخل واحد لكل إعداد فرعي (sub-config).

```py
model.get_experts_implementation()
# {"": "grouped_mm", "text_config": "grouped_mm", "vision_config": "eager"}
```

## خلفية الخبراء المحددة للعمود الفقري

يمكن أن تحتوي النماذج متعددة الوسائط على عدة إعدادات فرعية (على سبيل المثال، هياكل أساسية مختلفة). يمكنك تعيين خلفية خبراء مختلفة لكل إعداد فرعي عن طريق تمرير `dict` إلى `experts_implementation` عند التحميل.

يجب أن تتطابق المفاتيح في الترميز مع أسماء الإعدادات الفرعية.

```py
from transformers import AutoModelForImageTextToText

experts_implementation_per_backbone = {
    "text_config": "grouped_mm",
    "vision_config": "eager",
}

model = AutoModelForImageTextToText.from_pretrained(
    "Qwen/Qwen3-VL-Moe",
    experts_implementation=experts_implementation_per_backbone,
)
```

اضبط واجهة الخبراء الخلفية على مستوى النظام باستخدام مفتاح فارغ.

```py
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen1.5-MoE-A2.7B",
    experts_implementation={"": "batched_mm"},
)
```

## DeepGEMM

يوجّه الخلفية `"deepgemm"` عمليات ضرب المصفوفات للخبراء عبر نواة [DeepGEMM](https://github.com/deepseek-ai/DeepGEMM) التي توزعها [kernels-community/deep-gemm](https://huggingface.co/kernels-community/deep-gemm). تعمل مع خبراء `bfloat16` غير مُكمّين ومع خبراء مُكمّينين بصيغة FP8/FP4 يتم تحميلهم عبر [Fine-grained FP8](./quantization/finegrained_fp8).

يتطلب الخلفية `"deepgemm"`:

- وحدة معالجة رسومات CUDA بقدرات حسابية ≥ 9.0 (Hopper أو أحدث).
- أداة CUDA كاملة تتضمن `nvcc` لتجميع النواة عبر JIT، بإصدار 12.3 أو أحدث على Hopper و12.9 أو أحدث على Blackwell. التثبيت الذي يحتوي على وقت التشغيل فقط لا يتضمن `nvcc` ويُرفض. يحدد Transformers الأداة عبر `CUDA_HOME`، ثم `CUDA_PATH`، ثم `nvcc` في `PATH`، ثم `/usr/local/cuda`.
- حزمة [kernels](https://github.com/huggingface/kernels).

```py
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "deepseek-ai/DeepSeek-V3",
    dtype="bfloat16",
    experts_implementation="deepgemm",
)
```

يتم تحميل النواة بشكل كسول عند أول تمرير أمامي.

### الخبراء المُكمَّمون بصيغتي FP8 وFP4

عادةً ما تكون نقاط التفتيش بنمط DeepSeek مُكمّمة مسبقًا وتحمل إعدادات التكميم الخاصة بها، لذا لا حاجة إلى تمرير [FineGrainedFP8Config](/docs/transformers/main/ar/main_classes/quantization#transformers.FineGrainedFP8Config). يختار الخلفية `"deepgemm"` تلقائيًا نواة GEMM المجمّعة FP8 (أو FP4 على Blackwell). تتطلب DeepGEMM مقاييس تنشيط ديناميكية لكل صف (`activation_scheme="dynamic"`) وترفض تكميم التنشيط الثابت (لكل مُتجه).

```py
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "deepseek-ai/DeepSeek-V3",
    experts_implementation="deepgemm",
)
```

بالنسبة لأوزان الخبراء المُجمّعة بصيغة FP4 (على غرار DeepSeek V4)، يجب أن يكون المعالج الرسومي (GPU) من طراز SM100 أو أحدث (Blackwell). عادةً ما يحدد تكوين نقطة الحفظ (checkpoint) `expert_dtype="fp4"` و`scale_fmt="ue8m0"`.

> [!NOTE]
> على Blackwell (SM100+)، تتطلب نواة الخبراء `"deepgemm"` و`"deepgemm_megamoe"` مقاييس خبراء UE8M0 تكون قوى للعدد 2. يؤدي تحميل نقطة تحقق (checkpoint) مُكمّمة بمقاييس `float32` عادية (`scale_fmt="float"`) إلى رفع `ValueError` في أول تمريرة أمامية بدلاً من إتلاف المخرجات بصمت. حمّل نقطة تحقق مُكمّمة بـ`scale_fmt="ue8m0"`، أو انتقل إلى `grouped_mm` أو `batched_mm`، والتي تستهلك مقاييس الكتل `float32` مباشرةً. تستهلك Hopper (SM90+) مقاييس `float32` على مسار DeepGEMM دون أي تحويل.

السبب الرئيسي لتمرير [FineGrainedFP8Config](/docs/transformers/main/ar/main_classes/quantization#transformers.FineGrainedFP8Config) لنقطة تحقق مُكمّاة مسبقاً هو فكّ تكميمها مرة أخرى إلى `bfloat16`، وفي هذه الحالة تعمل الخبراء في `bfloat16` بدلاً من مسار DeepGEMM الخاص بـ FP8/FP4.

```py
from transformers import AutoModelForCausalLM, FineGrainedFP8Config

model = AutoModelForCausalLM.from_pretrained(
    "deepseek-ai/DeepSeek-V3",
    quantization_config=FineGrainedFP8Config(dequantize=True),
    experts_implementation="deepgemm",
)
```

### دمج ميجا مو إي على بلاكويل

على Blackwell (SM100+)، اضبط `experts_implementation="deepgemm_megamoe"` لتشغيل نواة مدمجة واحدة تجمع بين توزيع الخبراء بالتوازي، الإسقاط الصاعد، SwiGLU، الإسقاط الهابط، وتجميع EP، مع تداخل عمليات نقل NVLink مع حسابات نوى المصفوفات.

يتطلب هذا الخادم الخلفي:

- وحدة معالجة رسومات Blackwell (قدرة الحوسبة ≥ 10.0) مع مجموعة أدوات CUDA (`nvcc`) الإصدار 12.9 أو أحدث.
- أوزان الخبراء المُجمّعة بصيغة FP4 مع مقاييس أوزان بصيغة UE8M0 (يُعلن نقطة التفتيش المُسبقة التكميم عادةً عن `expert_dtype="fp4"` و`scale_fmt="ue8m0"` في ملف الإعداد الخاص بها).
- مجموعة عمليات `torch.distributed` لمجموعة التوازي بين الخبراء، والتي يوفرها التغليف الخاص بالتوازي بين الخبراء تلقائياً عندما يكون `ep_size > 1`.

```py
import os

from transformers import AutoModelForCausalLM, DistributedConfig

distributed_config = DistributedConfig(
    tp_size=int(os.environ["WORLD_SIZE"]),
    ep_size=int(os.environ["WORLD_SIZE"]),
)
model = AutoModelForCausalLM.from_pretrained(
    "deepseek-ai/DeepSeek-V4",
    experts_implementation="deepgemm_megamoe",
    distributed_config=distributed_config,
)
```

## SonicMoE

يجمع الخلفية `"sonicmoe"` بين تمرير MoE الموجَّه (الإرسال، الإسقاط الصاعد البوَّابي، التفعيل، الإسقاط الهابط) في مجموعة من نواة CuteDSL المجمَّعة GEMM المُحسَّنة للغاية، المبنية على مكتبة [quack](https://github.com/Dao-AILab/quack) والموزَّعة عبر [kernels-community/sonic-moe](https://huggingface.co/kernels-community/sonic-moe).

يتطلب الخلفية `"sonicmoe"`:

- وحدة معالجة رسومات CUDA بقدرات حسابية ≥ 9.0 (Hopper أو أحدث).
- حزمة [kernels](https://github.com/huggingface/kernels) وحزمة `nvidia-cutlass-dsl`.
- الخبراء الذين لديهم تفعيل مُتحكَّم به (`silu`، `gelu`، أو `relu`، مُرتبط بـ SwiGLU/GeGLU/ReGLU).

```py
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen1.5-MoE-A2.7B",
    dtype="bfloat16",
    experts_implementation="sonicmoe",
)
```

If the requirements aren't met, the forward raises `ImportError` and you should pick a different `experts_implementation`.

## torch.compile

تتوافق واجهات `"eager"` و`"batched_mm"` و`"grouped_mm"` مع `torch.compile` بدرجات متفاوتة. تلخّص الجدول التالي مدى توافقها. أما واجهات `"deepgemm"` و`"deepgemm_megamoe"` و`"sonicmoe"` فتعتمد على نوى CUDA خارجية، لذا لا يشملها هذا الجدول.

| التنفيذ          | أوضاع الترجمة                    | أنواع البيانات                           | `fullgraph=True` |
| ----------------------- | ------------------------------------ | -------------------------------- | ---------------- |
| `grouped_mm`            | `None`, `max-autotune-no-cudagraphs` | `bfloat16`                       | نعم              |
| `grouped_mm` (بديل احتياطي) | `None`, `max-autotune-no-cudagraphs` | `bfloat16`, `float16`, `float32` | نعم              |
| `batched_mm`            | الكل                                  | `bfloat16`, `float16`, `float32` | نعم              |
| `eager`                 | الكل                                  | `bfloat16`, `float16`, `float32` | لا               |

ملاحظات:

- يدعم مُنفّذ الخبراء `grouped_mm` حالياً `bfloat16` فقط عند تجميعه باستخدام `torch.compile`. بالإضافة إلى ذلك، فهو غير متوافق مع رسوم CUDA، لذا يجب عليك استخدام `mode=None` أو `mode="max-autotune-no-cudagraphs"` عند التجميع.
- يستخدم الخلفية `eager` للخبراء عملية تعتمد على البيانات للعثور على الخبراء الذين يُستخدمون في تمريرة أمامية. هذه العملية غير متوافقة مع تجميع الرسم البياني الكامل (`fullgraph=True`).

```py
import torch
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen1.5-MoE-A2.7B",
    dtype="bfloat16",
    experts_implementation="grouped_mm",
    device_map="auto",
).eval()

# Works for grouped_mm (no CUDA graphs)
model.forward = torch.compile(model.forward, mode="max-autotune-no-cudagraphs")
```

## المعايير

يقارن هذا [اختبار المعيار](https://github.com/user-attachments/files/24125816/bench.py) بين أحجام مدخلات مختلفة وتنفيذات الخبراء مع `torch.compile` وبدونه.