# Nunchaku Lite

Nunchaku Lite هو واجهة خلفية للكمّية (quantization) لتحميل نقاط التفتيش المُكمّاة مسبقًا في Diffusers. أنشئ نقاط تفتيش متوافقة باستخدام [diffuse-compressor](https://github.com/rootonchair/diffuse-compressor). يقوم بتكميم مُحوِّل (transformer) وتصديره، ثم يجمعه كخط أنابيب (pipeline) في Diffusers.

يعتمد Nunchaku Lite على محرك الاستدلال الأصلي [Nunchaku](https://github.com/nunchaku-ai/nunchaku)، ومكتبة التكميم [DeepCompressor](https://github.com/nunchaku-ai/deepcompressor)، وورقة [SVDQuant](https://arxiv.org/abs/2411.05007).

## تثبيت نواة CUDA

يوفر حزمة kernels نواة CUDA المُحسّنة، والتي يتم تحميلها تلقائيًا. ثبّتها أولًا.

```bash
pip install -U kernels
```

تحمّل Nunchaku Lite نواتها من مستودع [`rootonchair/nunchaku-lite-kernels`](https://huggingface.co/rootonchair/nunchaku-lite-kernels)، حيث أن ناشره ليس ناشر نواة موثوقًا به على Hub. يؤدي تحميله إلى تنزيل وتنفيذ أكواد من Hub، لذا يتطلب Diffusers منك الموافقة صراحةً على ذلك عن طريق تعيين `DIFFUSERS_TRUST_REMOTE_KERNELS=true`. راجع [الثقة في النوى البعيدة](../optimization/attention_backends#trusting-remote-kernels) للتفاصيل.

## تحميل خط أنابيب مُكمَّم

حمّل خط الأنابيب المُكمَّم مسبقًا باستخدام [from_pretrained()](/docs/diffusers/main/ar/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained)، حيث يقرأ إعدادات الكمّ من `config.json`.

```python
import torch
from diffusers import DiffusionPipeline

model_id = "rootonchair/ERNIE-Image-Turbo-nunchaku-lite-nvfp4"

pipe = DiffusionPipeline.from_pretrained(
    model_id, dtype=torch.bfloat16,
).to("cuda")  # or "mps", "xpu", "cpu"

prompt = "A modern red armchair in a quiet studio, soft window light, realistic product photography"
image = pipe(
    prompt=prompt,
    height=1024,
    width=1024,
    num_inference_steps=8,
    guidance_scale=1.0,
).images[0]
image.save("ernie-image-turbo-nunchaku-lite.png")
```

> [!NOTE]
> يجب أن يطابق state dict المُصدَّر بنية نموذج Diffusers المستهدف تمامًا. على سبيل المثال، لن يتم تحميل نقطة تفتيش (checkpoint) تم كمّها باستخدام إسقاطات QKV مدمجة في إعداد نموذج يتوقع وحدات إسقاط منفصلة لكل من Q وK وV.

## أنواع التكميم المدعومة

يدعم Nunchaku Lite صيغ طبقات الخطي المُكمّمة التالية.

> [!TIP]
> استخدم `nvfp4` على وحدات معالجة الرسومات Blackwell. قد يكون تشغيل نقاط التفتيش `int4` على Blackwell أبطأ من `nvfp4`.

تدعم نواة CUDA حاليًا معماريات وحدات معالجة الرسوميات من NVIDIA التالية:

- `sm_75` (تورينغ، على سبيل المثال RTX 2080)
- `sm_80` (Ampere، على سبيل المثال A100)
- `sm_86` (Ampere، على سبيل المثال RTX 3090 و RTX A6000)
- `sm_89` (Ada، على سبيل المثال RTX 4090)
- `sm_120` (Blackwell، على سبيل المثال RTX 5090)

> [!NOTE]
> لا يتم دعم معالجات Hopper الرسومية، مثل `sm_90` H100 وH200، حاليًا.

يتطلب نقاط التفتيش `nvfp4` معالجًا رسوميًا من NVIDIA من طراز Blackwell أو أحدث. على معالجات Blackwell الرسومية، استخدم PyTorch >= 2.7 مع CUDA >= 12.8. تتطلب نقاط التفتيش `int4` معالجًا رسوميًا من NVIDIA من طراز Turing أو أحدث.

| الطريقة | الدقة | حجم المجموعة | ملاحظات |
|---|---:|---:|---|
| `svdq_w4a4` | `nvfp4` | 16 | يستخدم نواة NVFP4 وقت التشغيل مع تصحيح SVDQ منخفض الرتبة. |
| `svdq_w4a4` | `int4` | 64 | يستخدم نواة INT4 W4A4 مع تصحيح SVDQ منخفض الرتبة. |
| `awq_w4a16` | `int4` | 64 | يستخدم نواة INT4 للأوزان فقط بأسلوب AWQ. |

## NunchakuLiteQuantizationConfig

يجب أن يتضمن ملف `config.json` كائن [NunchakuLiteQuantizationConfig](/docs/diffusers/main/ar/api/quantization#diffusers.NunchakuLiteQuantizationConfig). وهو يحدد نوع البيانات `compute_dtype` وقت التشغيل، والوحدات المستهدفة لكل طريقة من طرق التكميم في Nunchaku Lite.

- `compute_dtype`: نوع البيانات وقت التشغيل للذاكرة المؤقتة ذات الفاصلة العائمة في الوحدات الكمية، وهو عادةً `torch.bfloat16`.
- `svdq_w4a4`: تكوين الهدف SVDQ W4A4 مع `precision` و`group_size` و`rank` و`targets`.
- `awq_w4a16`: إعدادات الهدف AWQ W4A16 مع `precision` و`group_size` و`targets`.

يجب أن يشير كل عنصر في `targets` إلى طبقة خطية. تستبدل Diffusers كل هدف `svdq_w4a4` بطبقة SVDQ W4A4 وكل هدف `awq_w4a16` بطبقة AWQ W4A16. يُظهر المثال أدناه الشكل المتوقع مع قوائم أهداف مُختصرة.

أدرج كل وحدة تريد تكميمها تحت `svdq_w4a4` أو `awq_w4a16`. لا يمكن أن تستخدم الوحدة طريقة واحدة فقط، لذا لا تدرج نفس الهدف تحت الطريقتين.

```json
{
  "_class_name": "ErnieImageTransformer2DModel",
  "quantization_config": {
    "quant_method": "nunchaku_lite",
    "compute_dtype": "bfloat16",
    "svdq_w4a4": {
      "precision": "nvfp4",
      "group_size": 16,
      "rank": 32,
      "targets": ["layers.0.self_attention.to_q"]
    },
    "awq_w4a16": {
      "precision": "int4",
      "group_size": 64,
      "targets": ["final_linear"]
    }
  }
}
```

## النواة المدمجة

يستمد محرك [Nunchaku](https://github.com/nunchaku-ai/nunchaku) الأصلي جزءًا كبيرًا من سرعته من مسارات التنفيذ المدمجة المحددة لكل نموذج. فهو يجمع بين إسقاطات Q وK وV مع RMSNorm وRoPE، ويستخدم نواة GELU مدمجة لطبقة MLP. أما Nunchaku Lite فيستخدم نموذج Diffusers القياسي مع طبقات خطية كمية عامة، لذا فهو لا يتضمن هذه الدمجات.

تُظهر القياسات التالية تأثير زمن الاستجابة لكل خطوة لهذه الدمج في محرك Nunchaku الأصلي، وقد قُيس باستخدام Flux Schnell على بطاقة RTX 5090.

| التحسين | زمن الاستجابة عند إيقافه | زمن الاستجابة عند تفعيله | التسريع |
| --- | --- | --- | --- |
| دمج QKV+norm+RoPE (مجمّع) | 1.057 s | 0.834 s | **1.27×** |
| — تجميع Q/K/V في عملية ضرب مصفوفات واحدة، بشكل منفصل | 1.059 s | 1.034 s | 1.025× |
| — دمج خاتمة RMSNorm+RoPE، فوق التجميع | 1.034 s | 0.836 s | 1.236× |
| دمج GELU-MLP | 0.766 s | 0.722 s | **1.06×** |

بدون هذه الدمجات، تُطلق وحدة المعالجة الرسومية (GPU) عمليات الإسقاط والتطبيع والتضمين الدوّاري وشبكة الطبقات متعددة الطبقات (MLP) ككُتل (kernels) منفصلة، مما يُضيف عبئًا على عملية الإطلاق. قد تقلل `torch.compile` من بعض هذا العبء، على الرغم من أنها لا تُعيد بالضرورة إنتاج الكُتل المدمجة الأصلية للمحرك. قم بإجراء اختبارات أداء (Benchmark) للخط الأنابيب المُجمّع (compiled pipeline) الخاص بنموذجك وحِمل العمل لديك.

## torch.compile

تتوافق نواة Nunchaku Lite والطبقات الخطية المُكمّمة مع [`torch.compile`](../optimization/fp16#torchcompile). قم بتجميع المُحوِّل المُكمَّم بعد تحميل خط الأنابيب للحصول على استدلال أسرع.

```python
pipe.transformer = torch.compile(pipe.transformer, mode="default", fullgraph=True)
```

يعمل خط أنابيب Nunchaku Lite NVFP4 المُجمَّع أسرع بنسبة 1.8 مرة من خط أنابيب BF16 الأصلي (من 2.271 ثانية إلى 1.675 ثانية على بطاقة RTX PRO 6000).

## الموارد

- [diffuse-compressor](https://github.com/rootonchair/diffuse-compressor)
- [متطلبات تثبيت Nunchaku](https://nunchaku.tech/docs/nunchaku/installation/installation.html)