# GGUF

يُستخدم تنسيق ملفات GGUF عادةً لتخزين النماذج للاستدلال باستخدام [GGML](https://github.com/ggerganov/ggml)، ويدعم مجموعة متنوعة من خيارات التكميم على مستوى الكتل. يدعم Diffusers تحميل نقاط التفتيش المُكمَّمة مسبقًا والمُحفوظة بتنسيق GGUF عبر تحميل `from_single_file` باستخدام فئات النموذج. حاليًا، لا يُدعم تحميل نقاط التفتيش بتنسيق GGUF عبر خطوط الأنابيب (Pipelines).

سيُحمّل المثال التالي نموذج التحويلة [FLUX.1 DEV](https://huggingface.co/black-forest-labs/FLUX.1-dev) باستخدام متغير التكميم GGUF Q2_K.

قبل البدء، يرجى تثبيت gguf في بيئتك

```shell
pip install -U gguf
```

بما أن GGUF هو تنسيق ملف واحد، استخدم `~FromSingleFileMixin.from_single_file` لتحميل النموذج وقم بتمرير [GGUFQuantizationConfig](/docs/diffusers/main/ar/api/quantization#diffusers.GGUFQuantizationConfig).

عند استخدام نقاط التفتيش بصيغة GGUF، تبقى الأوزان المُكمّمة في نوع بيانات ذاكرة منخفض `dtype` (عادةً `torch.uint8`) وتُفكّ كمّتها وتُحوَّل ديناميكيًا إلى `compute_dtype` المُهيّأ أثناء مرور كل وحدة في المسار الأمامي عبر النموذج. ويتيح لك `GGUFQuantizationConfig` ضبط `compute_dtype`.

تستند الدوال المستخدمة لفك الترميز الديناميكي إلى العمل الرائع الذي أنجزه [city96](https://github.com/city96/ComfyUI-GGUF)، والذي أنشأ إصدارات Pytorch من التنفيذ الأصلي بـ [`numpy`](https://github.com/ggerganov/llama.cpp/blob/master/gguf-py/gguf/quants.py) الذي أنشأه [compilade](https://github.com/compilade).

```python
import torch

from diffusers import FluxPipeline, FluxTransformer2DModel, GGUFQuantizationConfig

ckpt_path = (
    "https://huggingface.co/city96/FLUX.1-dev-gguf/blob/main/flux1-dev-Q2_K.gguf"
)
transformer = FluxTransformer2DModel.from_single_file(
    ckpt_path,
    quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
    dtype=torch.bfloat16,
)
pipe = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    transformer=transformer,
    dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()
prompt = "A cat holding a sign that says hello world"
image = pipe(prompt, generator=torch.manual_seed(0)).images[0]
image.save("flux-gguf.png")
```

## استخدام نواة CUDA المُحسَّنة مع GGUF

يمكن أن تُسرّع نواة CUDA المُحسَّنة استنتاج نماذج GGUF المُكمّمة بنسبة تقارب 10%. تتطلب هذه الميزة وحدة معالجة رسومات متوافقة تكون قيمة `torch.cuda.get_device_capability` فيها أكبر من 7، بالإضافة إلى مكتبة النواة:

```shell
pip install -U kernels
```

بعد التثبيت، اضبط `DIFFUSERS_GGUF_CUDA_KERNELS=true` لاستخدام الأنوية المحسّنة عند توفرها. لاحظ أن أنوية CUDA قد تُدخل فروقات رقمية طفيفة مقارنةً بتنفيذ GGUF الأصلي، مما قد يسبب اختلافات بصرية دقيقة في الصور المولّدة. لتعطيل استخدام أنوية CUDA، اضبط متغير البيئة `DIFFUSERS_GGUF_CUDA_KERNELS=false`.

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

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

- BF16
- Q4_0
- Q4_1
- Q5_0
- Q5_1
- Q8_0
- Q2_K
- Q3_K
- Q4_K
- Q5_K
- Q6_K

## التحويل إلى GGUF

استخدم المساحة أدناه لتحويل نقطة تحقق من Diffusers إلى صيغة GGUF للاستدلال. نفّذ التحويل:

<iframe src="https://diffusers-internal-dev-diffusers-to-gguf.hf.space" frameborder="0" width="850" height="450"
>

```py
import torch

from diffusers import FluxPipeline, FluxTransformer2DModel, GGUFQuantizationConfig

ckpt_path = (
    "https://huggingface.co/sayakpaul/different-lora-from-civitai/blob/main/flux_dev_diffusers-q4_0.gguf"
)
transformer = FluxTransformer2DModel.from_single_file(
    ckpt_path,
    quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
    config="black-forest-labs/FLUX.1-dev",
    subfolder="transformer",
    dtype=torch.bfloat16,
)
pipe = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    transformer=transformer,
    dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()
prompt = "A cat holding a sign that says hello world"
image = pipe(prompt, generator=torch.manual_seed(0)).images[0]
image.save("flux-gguf.png")
```

عند استخدام نقاط التفتيش GGUF بصيغة Diffusers، يجب تقديم مسار `config` للنموذج. إذا كان تكوين النموذج موجودًا في `subfolder`، فيجب تحديد ذلك أيضًا.