# تحميل النوى

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

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

قم بتثبيت Transformers مع الإصدار المدعوم من حزمة [kernels](https://github.com/huggingface/kernels).

```bash
pip install -U "transformers[kernels]"
```

اضبط `use_kernels=True` في [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أنجح النوى المتاحة على Hub لجهازك. يستبدل هذا العمليات المدعومة في PyTorch بتنفيذ النواة.

```py
from transformers import AutoModelForCausalLM

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

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

| العملية | إنفيديا (CUDA) | AMD (ROCm) | Intel (XPU) |
|---|---|---|---|
| RMSNorm | `kernels-community/liger-kernels` | `kernels-community/liger-kernels` | `kernels-community/rmsnorm` |
| MLP الخاص بـ MoE | `kernels-community/megablocks` | `kernels-community/megablocks` | `kernels-community/megablocks` |
| MLP (SwiGLU، GeGLU) | `kernels-community/liger-kernels` | — | — |
| خطي | `kernels-community/liger-kernels` | — | — |
| التفعيلات (متغيرات GELU، SiLU) | `kernels-community/activation` | — | — |
| تضمينات دوّارة | `kernels-community/rotary` | `kernels-community/aiter-rope` | `kernels-community/rotary` |
| خسارة نموذج اللغة السببي | `kernels-community/liger-kernels` | — | — |
| انتباه قابل للتشوه | `kernels-community/deformable-detr` | — | — |

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

> [!NOTE]
> تُبلّغ وحدات معالجة الرسوميات من AMD عن نوع جهازها على أنه `cuda` في PyTorch. يكتشف Transformers بيئة ROCm وقت التشغيل ويوجّه العمليات المدعومة إلى نواة AMD المذكورة أعلاه، بما في ذلك إصدارات [AITER](https://github.com/ROCm/aiter) مثل `kernels-community/aiter-rope`. لا حاجة إلى تحديد نوع الجهاز بنفسك.

تصفّح الأنوية المتاحة في منظمة [kernels-community](https://huggingface.co/kernels-community).

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

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

```py
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). والسبب في ذلك أن تحميل نواة قد يؤدي إلى تنفيذ أكواد عشوائية على الجهاز المضيف، ولا يمكننا التحقق من كل مستودع، لذا عليك السماح بذلك صراحةً.

```py
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` يحدد قيود إصدارات الدلالات.

```py
from transformers import AutoModelForCausalLM

# pin to a specific version
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    attn_implementation="kernels-community/flash-attn2@v2.1.0",
    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.

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

```py
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",
)
```

## الوعي بالوضع

تتكيف الأنوية تلقائيًا مع وضعي [التدريب](https://docs.pytorch.org/docs/stable/generated/torch.nn.Module.html#torch.nn.Module.train) و[الاستدلال](https://docs.pytorch.org/docs/stable/generated/torch.nn.Module.html#torch.nn.Module.eval) بناءً على حالة `model.training` في PyTorch.

```py
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()](/docs/transformers/main/ar/main_classes/kernels#transformers.kernelize). كما يدعم وضع التدريب وضعًا إضافيًا لـ torch.compile.

```py
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](/docs/transformers/main/ar/main_classes/kernels#transformers.KernelConfig) النوى المستخدمة في النموذج.

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

```py
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) لكل نوع من أنواع الأجهزة.

```py
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"
        }
    }
)
```

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

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

| خيار | الوصف | افتراضي |
|---|---|---|
| `version` | الإصدار الرئيسي لمستودع النواة. `2` يحمّل أحدث بناء على فرع `v2` في المستودع. | `1` |
| `revision` | الوسم أو الفرع أو الالتزام الدقيق الذي يجب تحميله بدلاً من إصدار. | --- |
| `trust_remote_code` | يتيح هذا الأمر استخدام مستودع خارج منظمة `kernels-community` الموثوقة. عند تحميل نواة، يتم تنفيذ الكود من ذلك المستودع على جهازك. | `False` |

```py
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. يجب أن تكون اسم الدالة مسجّلاً من قِبل النموذج.

```py
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](/docs/transformers/main/ar/main_classes/kernels#transformers.KernelConfig). يجب أن تتشارك جميع الأنماط نفس الوحدة الأم. يطابق `*` أي مقطع مسار واحد.

```python
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`. راجع دليل [كتابة النوى](./writing_kernels) لمعرفة كيفية تنفيذ ذلك.

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

حمّل الأنوية من مسارات ملفات محلية باستخدام `use_local_kernel=True` في [KernelConfig](/docs/transformers/main/ar/main_classes/kernels#transformers.KernelConfig). يؤدي هذا إلى التحميل من مسار نظام ملفات محلي بدلاً من مستودع Hub.

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

```py
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 في كل مكان دون تغيير كودك.

```bash
export USE_HUB_KERNELS=0  # or OFF or NO
```

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

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

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

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

```bash
pip install -U "transformers[kernels]"
```

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

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

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

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

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

## الموارد

- مستودع [Kernels](https://github.com/huggingface/kernels)
- مقال [حسّن نماذجك في 5 دقائق مع Hugging Face Kernel Hub](https://huggingface.co/blog/hello-hf-kernels)
- اكتشف الأنوية في منظمة [kernels-community](https://huggingface.co/kernels-community)