Transformers documentation

GPTQ

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

GPTQ

GPTQ quantizes a model one layer at a time and uses a small calibration dataset to update the remaining weights so they compensate for each layer’s rounding error. Transformers runs GPTQ through Optimum and the GPT-QModel library. Use it to quantize a model to 2 to 8 bits with calibration while it loads, or to load one of the many GPTQ checkpoints on the Hub.

تلخص الجدول أدناه ما يدعمه GPTQ في Transformers.

إعدادGPTQConfig
quant_methodgptq
سير العملQuantize while loading, with calibration
بت2, 3, 4, 8
الأجهزةCUDA، XPU، CPU
حفظ✅
ضبط✅
التجميع التلقائي❌

تثبيت GPTQ

قم بتثبيت Optimum 1.24.0 أو أحدث وGPT-QModel 1.4.3 أو أحدث.

pip install -U "optimum>=1.24.0"
pip install -U "gptqmodel>=1.4.3" --no-build-isolation

كمّ نموذج باستخدام GPTQ

أنشئ GPTQConfig مع dataset للمعايرة، وقم بتمريره إلى from_pretrained(). يتم تكميم الأوزان بعد تحميلها. يوصي GPTQ باستخدام fp16، لذا يضبط المثال أدناه dtype=torch.float16.

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, GPTQConfig

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B")
quantization_config = GPTQConfig(bits=4, dataset="c4", tokenizer=tokenizer)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    quantization_config=quantization_config,
    dtype=torch.float16,
    device_map="auto",
)

dataset مطلوب لتكميم النموذج. مرر اسم مجموعة بيانات من ورقة GPTQ، مثل "wikitext2" أو "c4" أو "c4-new"، أو قائمة من النصوص. يقوم tokenizer بإعداد مجموعة البيانات. إذا لم تمرر واحدًا، فإن GPTQ يحمّل tokenizer من مستودع النموذج.

تعمل المعايرة على تشغيل النموذج كتلةً تلو الأخرى، لذا تستغرق وقتًا أطول بكثير من التحميل. قبل أن تقوم بتكميم نموذج، تحقق من Hub عن نقطة تحقق GPTQ موجودة مسبقًا.

تحميل نقطة تحقق GPTQ

مرّر نقطة التفتيش إلى from_pretrained() دون GPTQConfig. يقرأ Transformers إعدادات التكميم من إعدادات نقطة التفتيش.

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-1.5B-Instruct-GPTQ-Int4",
    device_map="auto",
)

لتغيير حجم النواة أو المخزن المؤقت، مرّر GPTQConfig يحتوي على backend أو max_input_length الجديد. تعيد Transformers تعيين هذين السمتين فقط عند التحميل وتحتفظ ببقية إعدادات نقطة الحفظ.

تهيئة GPTQ

تُغيّر هذه المعلمات من GPTQConfig طريقة تكميم الأوزان. راجع GPTQConfig لمعرفة البقية.

معاملافتراضيالتأثير
bitsمطلوبعدد البتات لكل وزن. يدعم 2 و3 و4 و8.
group_size128عدد الأوزان التي تتشارك مقياسًا واحدًا. -1 يستخدم مقياسًا واحدًا لكل عمود.
damp_percent0.1النسبة من القطر المتوسط لمصفوفة هيسن التي تُضاف من أجل الاستقرار العددي. يجب أن تكون بين 0 و 1.
desc_actFalseيكمّم الأعمدة حسب ترتيب حجم التنشيط تنازليًا (act-order). يمكن أن يحسّن الدقة ويبطئ الاستدلال. ضبطه على True يُطفئ act_group_aware.
symTrueيستخدم التكميم المتماثل. اضبطه على False للتكميم غير المتماثل.
modules_in_block_to_quantizeNoneقوائم بأسماء الوحدات في كل كتلة ليتم تكميمها، بالترتيب. تبقى طبقات Linear غير المدرجة غير مكمّمة. مع الإعداد الافتراضي، يتم تكميم كل طبقة Linear في الكتلة. يتطلب Optimum الإصدار 1.15.0 أو أحدث.

اختر واجهة أساسية للنواة

تشغّل GPT-QModel الطبقات المُكمّاة عبر أحد الأنوية المتعددة. يحدد المعامل backend نواةً واحدة، وقيمتُه الافتراضية هي "auto"، مما يتيح لـ GPT-QModel اختيار نواة مناسبة لعطائياتك ونقطة الحفظ الخاصة بك. يحمّل المثال أدناه نقطة حفظ باستخدام نواة ExLlamaV2.

from gptqmodel import BACKEND
from transformers import AutoModelForCausalLM, GPTQConfig

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-1.5B-Instruct-GPTQ-Int4",
    quantization_config=GPTQConfig(bits=4, backend=BACKEND.EXLLAMA_V2),
    device_map="auto",
)

راجع قائمة الخوادم الخلفية الخاصة بـ GPT-QModel للقيم المتاحة.

القيود

  • يدعم GPTQ نماذج النصوص فقط. يؤدي تحميل نموذج لا يكون مدخله الرئيسي input_ids إلى حدوث RuntimeError.
  • يؤدي تكميم نموذج يحتوي على تفريغ إلى القرص في device_map الخاص به إلى رفع ValueError.
  • يؤدي التحميل دون تثبيت GPT-QModel إلى ظهور خطأ ImportError. ولا يُدعم AutoGPTQ.
  • بدون device_map، يتم تحميل النموذج على وحدة المعالجة المركزية (CPU).

الموارد

Update on GitHub