# AutoRound

[AutoRound](https://github.com/intel/auto-round) هو خوارزمية تكميم متقدمة توفر دقة عالية حتى عند دقة 2 بت. يستفيد من هبوط التدرج الموقّع لضبط قيم التقريب وحدود القص الدنيا والعليا في 200 خطوة فقط. صُمم لضمان توافق واسع، ويدعم بسلاسة مجموعة كبيرة من نماذج LLM، وهو يتوسع بنشاط ليشمل المزيد من نماذج VLM. كما يدعم التكميم والاستدلال عبر منصات أجهزة متعددة، بما في ذلك CPU وXPU وCUDA.

يوفر AutoRound أيضًا مجموعة متنوعة من الميزات المفيدة، بما في ذلك الضبط والاستدلال التلقائيان بتعدد البتات، ودعم أنواع البيانات MXFP4 وNVFP4، والكمّية بدون نموذج، والتصدير إلى صيغ مثل GPTQ وAWQ وGGUF وLLM-Compressor، ووصفات ضبط مرنة. للحصول على نظرة شاملة وأحدث التحديثات، اطّلع على [README](https://github.com/intel/auto-round) الخاص بـ AutoRound.

AutoRound was originally developed as part of the [Intel Neural Compressor](https://github.com/intel/neural-compressor), serving as a general-purpose model compression library for deep learning. It has since evolved into a standalone library focused specifically on low-precision optimization for large language models (LLMs). AutoRound remains fully integrated with the Intel Neural Compressor, and you can explore the repository for more details.

## التثبيت

```bash
pip install auto-round
```

## إعدادات التكميم المدعومة

يدعم AutoRound تهيئة التكميم التالية:

1. **وزن فقط INT2–INT8**
2. **أوزان فقط بتعدد البتات**
3. **GGUF Q\*_K**
4. **MXFP** (دعم محدود)
5. **NVFP4** (دعم محدود)

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

وحدات المعالجة المركزية (CPU) ووحدات المعالجة المخصصة (XPU) ووحدات CUDA لكل من التكميم والاستدلال.

## التكميم والتسلسل (خارج الخط)

حاليًا، يُدعم وضع عدم الاتصال فقط لتوليد النماذج المُكمّاة.

### الاستخدام من سطر الأوامر

```bash
auto-round \
    --model Qwen/Qwen3-0.6B \
    --scheme "W4A16" \
    --group_size 128 \
    --output_dir ./tmp_autoround
```

توفر AutoRound أيضًا أربع وصفات أخرى، هي `auto-round-best` و`auto-round-light` و`auto-round-opt-rtn` و`auto-round-rtn`، مصممة على التوالي لتحقيق دقة مثالية وتحسين السرعة. بالنسبة إلى 2 بت، نوصي باستخدام `auto-round-best` مع `--enable_alg_ext`.

### استخدام AutoScheme

AutoScheme هو ميزة تختار تلقائيًا أفضل مخطط تكميم من بين الخيارات المتاحة لكل طبقة خاضعة للتكميم خلال دقائق، وذلك وفقًا لعرض بت متوسط مستهدف.

```bash
auto-round \
    --model Qwen/Qwen3-0.6B \
    --options "W4A16,W2A16G64" \
    --target_bits 3.5 \
    --output_dir ./tmp_autoround
```

### توليفات الخوارزميات

يدعم AutoRound دمج خوارزميات متعددة، مثل AutoRound، وAutoRound + AWQ، وAutoRound + AWQ + Hadamard (مع دعم محدود للغاية). نحن حالياً نوسّع نطاق الدعم ليشمل المزيد من الخوارزميات. وهذا يتيح تحسيناً إضافياً لنتائج التكميم، لا سيما في السيناريوهات التي تتضمن تفعيلات مكمّمة.

```bash
auto-round \
    --model Qwen/Qwen3-0.6B \
    --algs "autoround,awq" \
    --output_dir ./tmp_autoround
```

### استخدام واجهة برمجة تطبيقات AutoRound

توفر هذه الإعدادية توازنًا أفضل بين الدقة وتكلفة الضبط، وهي موصى بها في جميع السيناريوهات.

```python
from auto_round import AutoRound

model_name = "Qwen/Qwen3-0.6B"
# mixed bits config
# layer_config = {"model.decoder.layers.6.self_attn.out_proj": {"bits": 2, "group_size": 32}}
ar = AutoRound(
    model_name,
    scheme="W4A16",
    # enable_torch_compile=True,
    # layer_config=layer_config,
)

output_dir = "./tmp_autoround"
# format= 'auto_round'(default), 'llm_compressor', "gguf:q4_k_m", 'auto_gptq', 'auto_awq'
ar.quantize_and_save(output_dir, format='auto_round') 
```

### AutoRound أفضل وصفة

توفر هذه الإعدادية أفضل دقة في معظم السيناريوهات، لكنها أبطأ بمقدار 4–5 أضعاف من وصفة AutoRound القياسية. وهي موصى بها بشكل خاص لاختزال 2-بت، وتُعد خياراً جيداً إذا كانت الموارد الكافية متاحة.

```python
from auto_round import AutoRound

model_name = "Qwen/Qwen3-0.6B"
ar = AutoRound(
    model_name,
    scheme="W4A16",
    nsamples=512,
    iters=1000,
)

output_dir = "./tmp_autoround"
ar.quantize_and_save(output_dir, format='auto_round') 
```

### وصفة AutoRoundLight

توفر هذه الإعدادية أفضل سرعة (أسرع بمرتين إلى ثلاث مرات من AutoRound)، لكنها قد تسبب انخفاضاً كبيراً في الدقة للنماذج الصغيرة وتكميم 2-بت. يُنصح باستخدامها مع إعدادات 4-بت والنماذج التي يتجاوز حجمها 3B.

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
from auto_round import AutoRound

model_name = "Qwen/Qwen3-0.6B"
ar = AutoRound(
    model_name,
    iters=50,
    lr=5e-3,
)

output_dir = "./tmp_autoround"
ar.quantize_and_save(output_dir, format='auto_round') 
```

متوسط دقة 13 مهمة (mmlu-pro, if_eval, gsm8k، إلخ) ونتائج تكلفة الوقت لـ W4G128 (تم إجراء الاختبار على Nvidia A100 80G باستخدام إصدار PyTorch 2.6.0 مع تفعيل enable_torch_compile):

| النموذج   | Qwen2.5-0.5B-Instruct | Falcon3-3B    | Qwen2.5-7B-Instruct | Meta-Llama-3.1-8B-Instruct | Falcon3-10B   | Qwen2.5-72B-Instruct |
|---------|--------------------|---------------|------------------|----------------------------|---------------|-------------------|
| 16bits  | 0.4192             | 0.5203        | 0.6470           | 0.6212                     | 0.6151        | 0.7229            |
| أفضل    | **0.4137**(7m)     | **0.5142**(23m) | 0.6426(58m)      | **0.6116**(65m)            | **0.6092**(81m) | 0.7242(575m)      |
| افتراضي | 0.4129(2m)         | 0.5133(6m)    | 0.6441(13m)      | 0.6106(13m)                | 0.6080(18m)   | **0.7252**(118m)  |
| فاتح   | 0.4052(2m)         | 0.5108(3m)    | **0.6453**(5m)   | 0.6104(6m)                 | 0.6063(6m)    | 0.7243(37m)       |

## الاستدلال

يختار AutoRound تلقائيًا أفضل واجهة خلفية متاحة بناءً على المكتبات المثبتة، ويطلب من المستخدم تثبيت مكتبات إضافية عند العثور على واجهة خلفية أفضل.

### وحدة المعالجة المركزية

يدعم 2 و4 و8 بتات. ننصح باستخدام واجهة ARK (AutoRound Kernel) للاستدلال. يتطلب استخدام ARK إصدار PyTorch 2.8.0 أو أحدث.

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "OPEA/Qwen2.5-1.5B-Instruct-int4-sym-inc"
model = AutoModelForCausalLM.from_pretrained(model_name, device_map="cpu", dtype="auto")
tokenizer = AutoTokenizer.from_pretrained(model_name)
text = "There is a girl who likes adventure,"
inputs = tokenizer(text, return_tensors="pt").to(model.device)
print(tokenizer.decode(model.generate(**inputs, max_new_tokens=50, do_sample=False)[0]))
```

### XPU

يدعم 2 و4 و8 بتات. ننصح باستخدام واجهة ARK (AutoRound Kernel) للاستدلال. يتطلب استخدام ARK إصدار PyTorch 2.8.0 أو أحدث.

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "OPEA/Qwen2.5-1.5B-Instruct-int4-sym-inc"
model = AutoModelForCausalLM.from_pretrained(model_name, device_map="xpu", dtype="auto")
tokenizer = AutoTokenizer.from_pretrained(model_name)
text = "There is a girl who likes adventure,"
inputs = tokenizer(text, return_tensors="pt").to(model.device)
print(tokenizer.decode(model.generate(**inputs, max_new_tokens=50, do_sample=False)[0]))
```

### CUDA

يدعم من 2 إلى 8 بتات. ننصح باستخدام GPTQModel للاستدلال على 4 و8 بتات.

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "OPEA/Qwen2.5-1.5B-Instruct-int4-sym-inc"
model = AutoModelForCausalLM.from_pretrained(model_name, device_map="cuda", dtype="auto")
tokenizer = AutoTokenizer.from_pretrained(model_name)
text = "There is a girl who likes adventure,"
inputs = tokenizer(text, return_tensors="pt").to(model.device)
print(tokenizer.decode(model.generate(**inputs, max_new_tokens=50, do_sample=False)[0]))
```

### تحديد واجهة الاستدلال

يختار AutoRound تلقائيًا الواجهة الخلفية (backend) لكل طبقة بناءً على التوافق. بشكل عام، ترتيب الأولوية هو Marlin > ExLLaMAV2 > Triton، لكن الاختيار النهائي يعتمد على عوامل مثل حجم المجموعة، وعرض البت، وصيغة التغليف، وجهاز العتاد، وتفاصيل التنفيذ الأخرى. لمزيد من التفاصيل، يُرجى الرجوع إلى [الواجهات الخلفية](https://github.com/intel/auto-round?tab=readme-ov-file#specify-backend)،

قد لا يكون الواجهة الخلفية (backend) دائمًا الأنسب لبعض الأجهزة. يمكنك تحديد الواجهة الخلفية المفضلة لديك، مثل "ark" للمعالج المركزي (CPU) ووحدات المعالجة المخصصة (XPU)، أو "marlin/exllamav2/triton" لـ CUDA، وفقًا لاحتياجاتك أو توافق العتاد. يرجى ملاحظة أنه قد تكون هناك حاجة إلى مكتبات إضافية مقابلة.

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

model_name = "OPEA/Qwen2.5-1.5B-Instruct-int4-sym-inc"
quantization_config = AutoRoundConfig(backend="ark")
model = AutoModelForCausalLM.from_pretrained(model_name, device_map="cpu", quantization_config=quantization_config, dtype="auto")
tokenizer = AutoTokenizer.from_pretrained(model_name)
text = "There is a girl who likes adventure,"
inputs = tokenizer(text, return_tensors="pt").to(model.device)
print(tokenizer.decode(model.generate(**inputs, max_new_tokens=50, do_sample=False)[0]))
```

### تحويل GPTQ/AWQ إلى AutoRound

يمكن تحويل معظم نماذج GPTQ/AWQ إلى صيغة AutoRound لتحسين التوافق والدعم مع أجهزة Intel. يرجى ملاحظة أن إعدادات التكميم (quantization config) ستتغير إذا تم تسلسل النموذج (serialized).

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

model_name = "ybelkada/opt-125m-gptq-4bit"
quantization_config = AutoRoundConfig()
model = AutoModelForCausalLM.from_pretrained(model_name, device_map="cpu", quantization_config=quantization_config, dtype="auto")
tokenizer = AutoTokenizer.from_pretrained(model_name)
text = "There is a girl who likes adventure,"
inputs = tokenizer(text, return_tensors="pt").to(model.device)
print(tokenizer.decode(model.generate(**inputs, max_new_tokens=50, do_sample=False)[0]))
```

## المشكلات

إذا واجهت أي مشاكل مع تكامل transformers، فيرجى فتح مشكلة في مستودع [transformers](https://github.com/huggingface/transformers/issues). وإذا واجهت أي مشاكل مع auto-round، فيرجى فتح مشكلة في مستودع [AutoRound](https://github.com/intel/auto-round/issues).

## إقرار

شكر خاص لمكتبات الدقة المنخفضة مفتوحة المصدر مثل AutoGPTQ وAutoAWQ وGPTQModel وTriton وMarlin وExLLaMAV2، لتوفيرها نوى CUDA منخفضة الدقة، والتي يتم الاستفادة منها في AutoRound.

## المساهمة

نرحّب بالمساهمات في [AutoRound](https://github.com/intel/auto-round/pulls) ونقدّرها حقّ التقدير! سواء كان الأمر إصلاح أخطاء، أو تحسين التوثيق، أو إضافة ميزات جديدة، أو اقتراح تحسينات، فإنّ مساهمتكم تُقدَّر دائماً.