تحميل النوى

يعمل النواة (Kernel) كبديل جاهز للاستخدام المباشر للعمليات القياسية في PyTorch. فهو يستبدل طريقة forward بتنفيذ النواة المحسّن دون كسر كود النموذج.

يُظهر هذا الدليل كيفية تحميل الأنوية (kernels) لتسريع الاستدلال.

قم بتثبيت Transformers مع الإصدار المدعوم من حزمة kernels.

pip install -U "transformers[kernels]"

اضبط use_kernels=True في from_pretrained() لتحميل أنجح النوى المتاحة على Hub لجهازك. يستبدل هذا العمليات المدعومة في PyTorch بتنفيذ النواة.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    use_kernels=True,
    device_map="auto"
)

يعتمد التخصيص الافتراضي على النموذج، والجهاز، ووضع التنفيذ. تدرج الجدول أدناه المستودعات الشائعة على Hub للأجهزة المعروضة. عند عدم تسجيل نواة (kernel) لمجموعة معينة، تعود العملية إلى استخدام PyTorch القياسي.

لا تُعدّ الجدول شاملاً. يمكن للنماذج تسجيل طبقات ودوال إضافية، وبعض التحويلات متاحة فقط لأوضاع تنفيذ محددة.

تُبلّغ وحدات معالجة الرسوميات من AMD عن نوع جهازها على أنه cuda في PyTorch. يكتشف Transformers بيئة ROCm وقت التشغيل ويوجّه العمليات المدعومة إلى نواة AMD المذكورة أعلاه، بما في ذلك إصدارات AITER مثل kernels-community/aiter-rope. لا تحتاج إلى تحديد نوع الجهاز بنفسك.

تصفّح الأنوية المتاحة في منظمة kernels-community.

أنوية الانتباه

حمّل نواة الانتباه من Hub باستخدام الحجة attn_implementation.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="kernels-community/flash-attn2",
    device_map="auto"
)

لاحظ أنه فيما يتعلق بنواة الانتباه (attention kernels)، فإن أي شيء لا يكون جزءًا من مستودع kernels-community (وهو مستودع موثوق - وقد نضيف مستودعات موثوقة أخرى في المستقبل) سيتطلب استخدام معامل allow_all_kernels=True الإضافي (على غرار معامل trust_remote_code=True الخاص بالنماذج غير التابعة لمنصة HF). والسبب في ذلك أن تحميل نواة قد يؤدي إلى تنفيذ أكواد عشوائية على الجهاز المضيف، ولا يمكننا التحقق من كل مستودع، لذا عليك السماح بذلك صراحةً.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="random-repo/random-attention",
    allow_all_kernels=True,
    device_map="auto"
)

تقبل نوى محددة، مثل الانتباه، عدة صيغ.

• @v2.1.0 يثبّت إلى وسم أو فرع محدد.
• @>=2.0,<3.0 يحدد قيود إصدارات الدلالات.

from transformers import AutoModelForCausalLM

# pin to a specific version
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="kernels-community/[email protected]",
    device_map="auto"
)
# use semantic versioning constraints
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="kernels-community/flash-attn2@>=2.0,<3.0",
    device_map="auto"
)

بديل FlashAttention

عند طلب attn_implementation="flash_attention_2" أو "flash_attention_3" أو "flash_attention_4"، يتم الرجوع إلى نواة Hub المطابقة إذا لم يكن حزمة flash-attn المُجمّعة مثبّتة أو إذا لم يكن جهازك CUDA.

دعم FlashAttention-4 في مرحلة تجريبية. قد تتغير واجهات برمجة التطبيقات والسلوك.

from transformers import AutoModelForCausalLM

# uses the compiled flash-attn package if present, otherwise the kernels-community/flash-attn2 Hub kernel
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="flash_attention_2",
    device_map="auto",
)

الوعي بالوضع

تتكيف الأنوية تلقائيًا مع وضعي التدريب والاستدلال بناءً على حالة model.training في PyTorch.

import torch
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    use_kernels=True,
    device_map="auto"
)

# Switch to inference mode - uses inference-optimized kernels
model.eval()
with torch.no_grad():
    output = model.generate(input_ids, max_new_tokens=50)

# Switch to training mode - uses training-optimized kernels with gradient support
model.train()
loss = model(input_ids, labels=labels).loss
loss.backward()

فعّل وضعي التدريب والاستدلال صراحةً باستخدام الحجة mode في الدالة kernelize(). كما يدعم وضع التدريب وضعًا إضافيًا لـ torch.compile.

from kernels import Mode
from transformers import kernelize

# inference optimized kernels
kernelize(model, mode=Mode.INFERENCE)

# training optimized kernels
kernelize(model, mode=Mode.TRAINING)

# training and torch-compile friendly kernels
kernelize(model, mode=Mode.TRAINING | Mode.TORCH_COMPILE)

KernelConfig

يخصص KernelConfig النوى المستخدمة في النموذج.

مفاتيح kernel_mapping هي أسماء مسجّلة من قِبل النموذج. يمكن أن تشير إلى طبقة، مثل "RMSNorm"، أو إلى دالة مسجّلة، مثل "rotary_pos_emb". يفصل : بين اسم مدخل نواة محدد داخل المستودع ويُسند ذلك المدخل إلى تلك الطبقة أو الدالة.

from transformers import AutoModelForCausalLM, KernelConfig

kernel_config = KernelConfig(
    kernel_mapping={
        "RMSNorm": "kernels-community/liger-kernels:LigerRMSNorm",
    }
)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="kernels-community/flash-attn2",
    use_kernels=True,
    kernel_config=kernel_config,
    device_map="auto"
)

حدد تنفيذاً مختلفاً للنواة (kernel) لكل نوع من أنواع الأجهزة.

from transformers import KernelConfig

kernel_config = KernelConfig(
    kernel_mapping={
        "RMSNorm": {
            "cuda": "kernels-community/liger-kernels:LigerRMSNorm",
            "rocm": "kernels-community/liger-kernels:LigerRMSNorm",
            "xpu": "kernels-community/rmsnorm:RMSNorm"
        }
    }
)

بيانات الوصف الأساسية للنواة

أضف قاموس بيانات وصفية للتحكم في أي بناء من نواة يُحمَّل.

from transformers import KernelConfig

kernel_config = KernelConfig(
    kernel_mapping={
        "RMSNorm": ("kernels-community/liger-kernels:LigerRMSNorm", {"version": 3}),
    }
)

قد لا تتوفر فحوصات (builds) لإصدارات PyTorch و CUDA الخاصة بك في الفروع الأقدم من مستودع النواة (kernel). إذا فشل تحميل النواة، جرّب إصدارًا أحدث من version قبل الاستنتاج بأن جهازك غير مدعوم.

الخرائط الموروثة

يرث KernelConfig تعيين النواة الافتراضي لـ Transformers الخاص بنوى Hub، وتُغني الإدخالات في kernel_mapping عن الافتراضي للطبقات والدوال المقابلة. اضبط inherit_mapping=False لاستخدام الإدخالات الموجودة في kernel_mapping فقط. أي شيء تتركه دون تحديد سيعود إلى PyTorch القياسي. وهذا مفيد عند إجراء اختبارات أداء لنواة محددة أو اختبار تنفيذ مخصص دون تطبيق الإعدادات الافتراضية الأخرى.

يُقرّن الإعداد أدناه دالة rotary_pos_emb بنواة RoPE ويُبقي كل عملية أخرى على PyTorch. يجب أن تكون اسم الدالة مسجلاً من قِبل النموذج.

from transformers import AutoModelForCausalLM, KernelConfig

kernel_config = KernelConfig(
    kernel_mapping={
        "rotary_pos_emb": (
            "kernels-community/rotary:apply_rotary_transformers",
            {"version": 2},
        ),
    },
    inherit_mapping=False,
)

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    use_kernels=True,
    kernel_config=kernel_config,
    device_map="auto",
)

دمج الوحدات

ادمج الوحدات المتجاورة في نواة واحدة عن طريق تمرير مجموعة من أزواج (class_name, path_pattern) كمفتاح في KernelConfig. يجب أن تتشارك جميع الأنماط نفس الوحدة الأم. يطابق * أي مقطع مسار واحد.

from transformers import AutoModelForCausalLM, KernelConfig

kernel_config = KernelConfig(
    {
        (
            ("RMSNorm", "model.layers.*.post_attention_layernorm"),
            ("MLP",     "model.layers.*.mlp"),
        ): "owner/fused-rmsnorm-mlp:RMSNormMLP",
    }
)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    use_kernels=True,
    kernel_config=kernel_config,
    device_map="auto",
)

يتطلب الدمج أن يوفر مستودع النواة (kernel) فئة مرافقة باسم KernelNameLayout إلى جانب فئة KernelName. راجع دليل كتابة النوى لمعرفة كيفية تنفيذ ذلك.

النواة المحلية

حمّل الأنوية من مسارات ملفات محلية باستخدام use_local_kernel=True في KernelConfig. يؤدي هذا إلى التحميل من مسار نظام ملفات محلي بدلاً من مستودع Hub.

تستخدم الأنوية المحلية /abs/path:layer_name بدلاً من صيغة Hub org/repo:layer_name.

from transformers import KernelConfig, AutoModelForCausalLM

kernel_mapping = {
    "RMSNorm": "/path/to/liger-kernels:LigerRMSNorm",
}
kernel_config = KernelConfig(kernel_mapping, use_local_kernel=True)

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    dtype="auto",
    device_map="auto",
    use_kernels=True,
    kernel_config=kernel_config
)

تعطيل الأنوية على مستوى النظام

اضبط متغير البيئة USE_HUB_KERNELS لتعطيل نواة Hub في كل مكان دون تغيير كودك.

export USE_HUB_KERNELS=0  # or OFF or NO

استكشاف الأخطاء وإصلاحها

يعتمد تكامل النواة على عمل العتاد، وسائقات النظام، وإصدارات الحزم معًا بشكل متناغم. تغطي الأقسام التالية حالات الفشل الشائعة.

مشكلات التثبيت

تعني أخطاء الاستيراد أن حزمة kernels مفقودة أو أن إصدارها يقع خارج النطاق الذي يدعمه Transformers. أعد التثبيت عبر الإضافة الإضافية للحصول على إصدار متوافق.

pip install -U "transformers[kernels]"

أخطاء في تحميل النواة

إذا فشلت نوى محددة في التحميل، جرّب ما يلي.

• تحقق من توافق العتاد مع متطلبات النواة.
• تحقق من أن برامج تشغيل CUDA/ROCm/Metal لديك محدّثة.
• استشر توثيق مستودع النواة (kernel) لمعرفة المشكلات المعروفة.

توافق الأجهزة

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

الموارد

• مستودع Kernels
• مقال حسّن نماذجك في 5 دقائق مع Hugging Face Kernel Hub
• اكتشف الأنوية في منظمة kernels-community