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

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

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

تعمل واجهتا "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() لإنشاء نموذج مع واجهة خلفية محددة للخبراء.

from transformers import AutoModelForCausalLM

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

يمكنك التبديل بين واجهات الخلفيات للخبراء أثناء التشغيل دون إعادة تحميل النموذج باستخدام set_experts_implementation().

model.set_experts_implementation("eager")

اقرأ الخلفية (backend) قيد التشغيل حاليًا باستخدام get_experts_implementation(). تُعيد هذه الدالة dict يحتوي على إدخال واحد للنموذج، وإدخال واحد لكل إعداد فرعي (sub-config).

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

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

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

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

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,
)

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

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

DeepGEMM

يوجّه الخلفية "deepgemm" عمليات ضرب المصفوفات للخبراء عبر نواة DeepGEMM التي توزعها kernels-community/deep-gemm. تعمل مع خبراء bfloat16 غير مُكمّين ومع خبراء مُكمّينين بصيغة FP8/FP4 يتم تحميلهم عبر Fine-grained 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.

from transformers import AutoModelForCausalLM

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

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

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

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

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".

على 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 لنقطة تحقق مُكمّاة مسبقاً هو فكّ تكميمها مرة أخرى إلى bfloat16، وفي هذه الحالة تعمل الخبراء في bfloat16 بدلاً من مسار DeepGEMM الخاص بـ FP8/FP4.

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.

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 والموزَّعة عبر kernels-community/sonic-moe.

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

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

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 خارجية، لذا لا يشملها هذا الجدول.

ملاحظات:

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

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")

المعايير

يقارن هذا اختبار المعيار بين أحجام مدخلات مختلفة وتنفيذات الخبراء مع torch.compile وبدونه.