# Metal

تنفّذ عملية التكميم على Metal تكميمًا خطيًا (affine) على أجهزة Apple Silicon (MPS) باستخدام نواة Metal مستضافة على Hugging Face Hub ([kernels-community/mlx-quantization-metal-kernels](https://huggingface.co/kernels-community/mlx-quantization-metal-kernels)). تنحدر هذه النوى من إطار [MLX](https://github.com/ml-explore/mlx) وتُترجم عبر مكتبة [`kernels`](https://github.com/huggingface/kernels).

تُحزم الأوزان في متجهات من نوع `uint32` مع مقاييس وانحيازات لكل مجموعة، ويستخدم مسار الأمامي نواة Metal مدمجة لفك التكميم وضرب المصفوفات (`affine_qmm_t`). وهذا يحافظ على انخفاض استهلاك الذاكرة أثناء تشغيل الاستدلال بالكامل على وحدة معالجة الرسوميات دون أي ذهاب وإياب مع وحدة المعالجة المركزية.

العرضات البتية المدعومة هي **2 و4 و8**. يمكن ضبط حجم المجموعة (الافتراضي 64).

## المتطلبات

- ماك بـ Apple Silicon (M1 / M2 / M3 / M4) مع دعم MPS
- حزمة `kernels`:

```bash
pip install kernels
```

تُحمَّل نوى Metal تلقائيًا من Hub عند الاستخدام الأول — دون الحاجة إلى تجميع يدوي.

## Quantize on-the-fly

قم بتحميل أي نموذج وكمّته أثناء التحميل عن طريق تمرير [MetalConfig](/docs/transformers/main/ar/main_classes/quantization#transformers.MetalConfig). يتم استبدال جميع طبقات `nn.Linear` المؤهلة بنسخ كمّية منها.

```python
from transformers import AutoModelForCausalLM, AutoTokenizer, MetalConfig

quantization_config = MetalConfig(bits=4, group_size=64)
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.2-1B",
    device_map="mps",
    quantization_config=quantization_config,
)

tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.2-1B")
inputs = tokenizer("Apple Silicon is", return_tensors="pt").to("mps")
output = model.generate(**inputs, max_new_tokens=50)
print(tokenizer.decode(output[0], skip_special_tokens=True))
```

## تحميل نموذج مُكمَّم مسبقًا

إذا كان نقطة التفتيش تحتوي بالفعل على أوزان مُكمّمة (`weight` كـ uint32 مُجمّعة، `scales`، `qbiases`)، يتم تحميلها مباشرةً — دون الحاجة إلى إعادة التكميم.

```python
from transformers import AutoModelForCausalLM, MetalConfig

model = AutoModelForCausalLM.from_pretrained(
    "your-org/model-metal-4bit",
    device_map="mps",
)
```

## إلغاء التكميم

على الأجهزة التي لا تدعم MPS، يتم إلغاء تكميم نقطة التفتيش المُكمّمة مسبقًا تلقائيًا وإعادتها إلى نوع float حتى يظل النموذج قابلاً للاستخدام على وحدة المعالجة المركزية (CPU) أو CUDA. كما يمكنك فرض هذا السلوك بشكل صريح:

```python
from transformers import AutoModelForCausalLM, MetalConfig

config = MetalConfig(dequantize=True)
model = AutoModelForCausalLM.from_pretrained(
    "your-org/model-metal-4bit",
    quantization_config=config,
    device_map="cpu",
)
```

## استبعاد الطبقات

يمكن استبعاد طبقات معينة (مثل `lm_head`) من التكميم عبر `modules_to_not_convert`:

```python
config = MetalConfig(bits=4, group_size=64, modules_to_not_convert=["lm_head"])
```

## خيارات التهيئة

| معامل | افتراضي | الوصف |
|---|---|---|
| `bits` | `4` | عرض البتات لاختزال الأوزان (2 أو 4 أو 8) |
| `group_size` | `64` | عدد العناصر في مجموعة التكميم |
| `modules_to_not_convert` | `None` | قائمة بأسماء الوحدات التي يجب إبقاؤها بدقة كاملة |
| `dequantize` | `False` | فرض فك التكميم إلى float (لأجهزة غير MPS) |