Transformers documentation

FP-Quant

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

FP-Quant

FP-Quant يقوم بتكميم الأوزان والتفعيلات إلى صيغ MXFP4 أو NVFP4، مع تطبيق دوران (تحويل هادامارد افتراضيا) قبل التكميم، وينفّذ عمليات ضرب المصفوفات باستخدام نواة QuTLASS على معالجات NVIDIA Blackwell الرسومية. استخدمه للاستدلال بصيغة FP4 على معالجات Blackwell الرسومية، أو لمحاكاة تكميم FP4 على معالجات رسومية أخرى لتقييم الدقة أو لتشغيل التدريب الواعي بالتكميم (QAT).

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

إعدادFPQuantConfig
quant_methodfp_quant
سير العملQuantize while loading
بت4
الأجهزةوحدات معالجة رسومات NVIDIA Blackwell؛ ووحدات معالجة رسومات CUDA الأخرى ووحدات XPU من Intel مع pseudoquantization=True
حفظ✅
ضبطفقط عند استخدام store_master_weights=True
التجميع التلقائي❌

تثبيت FP-Quant

قم بتثبيت fp_quant 0.3.2 أو إصدار أحدث. لتشغيل نواة FP4 الحقيقية على معالج Blackwell، قم أيضًا ببناء QuTLASS 0.2.0 أو إصدار أحدث من المصدر.

pip install -U "fp_quant>=0.3.2"
git clone https://github.com/IST-DASLab/qutlass.git
cd qutlass && pip install --no-build-isolation .

كمّ نموذج باستخدام FP-Quant

أنشئ FPQuantConfig وقم بتمريره إلى from_pretrained(). اضبط device_map على وحدات معالجة الرسوميات الخاصة بك. يقوم الإعداد الافتراضي بتكميم كل طبقة خطية باستثناء lm_head إلى NVFP4.

from transformers import AutoModelForCausalLM, FPQuantConfig

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-8B",
    quantization_config=FPQuantConfig(),
    device_map="cuda",
)

يدعم FP-Quant نوع bf16 فقط، لذا يتم تحميل النموذج دائمًا في bf16. يتم استبدال أي dtype آخر مع إصدار تحذير.

بدون معالج رسومات Blackwell، اضبط pseudoquantization=True. ثم يحاكي FP-Quant تكميم FP4 باستخدام نواة Triton. إنه يعيد إنتاج دقة النموذج المكمّم لكنه لا يسرّعه.

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-8B",
    quantization_config=FPQuantConfig(forward_dtype="mxfp4", pseudoquantization=True),
    device_map="cuda",
)

لتحميل نموذج تم كميته مسبقًا باستخدام GPTQ للحصول على دقة أفضل، مرّر مستودع Hub الخاص به إلى from_pretrained() دون quantization_config. تستضيف منظمة ISTA-DASLab نقاط التفتيش الخاصة بـ FP-Quant، ويحتوي مستودع FP-Quant على الكود لإنشائها.

إعداد FP-Quant

تُغيّر هذه المعلمات الخاصة بـ FPQuantConfig طريقة تكميم الأوزان والتفعيلات.

معاملافتراضيالتأثير
forward_dtype"nvfp4"صيغة FP4 لمرحلة الأمامية، إما "nvfp4" أو "mxfp4".
hadamard_group_sizeNoneحجم تحويل هادامارد. عند استخدام None، يكون الحجم 16 لـ NVFP4 و32 لـ MXFP4. يقبل NVFP4 القيم 16 و32 و64 و128، بينما يقبل MXFP4 القيم 32 و64 و128.
transform_init"hadamard"كيف يتم تهيئة مصفوفة التحويل، إما "hadamard" أو "identity" أو "gsr".
pseudoquantizationFalseيحاكي FP4 باستخدام نواة Triton بدلاً من تشغيل نواة QuTLASS. مطلوب على وحدات معالجة الرسوميات الأخرى غير Blackwell.

راجع FPQuantConfig لمعرفة بقية المعلمات.

التدريب بأوزان مُكمّمة

يدعم FP-Quant تقنية QAT. اضبط store_master_weights=True للحفاظ على الأوزان عالية الدقة بحيث يمكن تحديثها، واضبط forward_method="quest"، وهو ما يعمل بشكل أفضل من "abs_max" في حالة QAT. لا تعمل طريقة "quest" إلا مع MXFP4. مع مسار أمامي من نوع MXFP4، يمكن لـbackward_dtype أيضًا تكميم المسار الخلفي إلى "mxfp8" أو "mxfp4" بدلاً من "bf16".

from transformers import AutoModelForCausalLM, FPQuantConfig

quantization_config = FPQuantConfig(
    forward_dtype="mxfp4",
    forward_method="quest",
    store_master_weights=True,
    pseudoquantization=True,
)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-8B",
    quantization_config=quantization_config,
    device_map="cuda",
)

يُشير مؤلفو FP-Quant إلى أن QAT يعمل حاليًا فقط مع pseudoquantization=True.

القيود

  • يتطلب FP-Quant معالج CUDA GPU أو Intel XPU. يؤدي التحميل دون وجود أحدهما إلى ظهور NotImplementedError.
  • بدون تثبيت QuTLASS، يؤدي التحميل باستخدام pseudoquantization=False إلى حدوث ImportError.
  • يتطلب الكمي التقريبي NVFP4 معالج CUDA بقدرة حسابية 9.0 أو أحدث (Hopper أو أحدث). على المعالجات الأقدم، يثير خطأ ValueError. استخدم forward_dtype="mxfp4" بدلاً من ذلك.
  • بدون pseudoquantization، يؤدي التحميل بدون device_map إلى حدوث ValueError. كما أن device_map الذي يوزّع النموذج على وحدة معالجة رسومية (GPU) والوحدة المركزية (CPU) يؤدي إلى حدوث ValueError أيضاً.
  • يُطلق device_map الذي يتضمن "disk" خطأً من نوع ValueError.
  • لا يدعم التكميم الوهمي استخدام وحدات معالجة رسومية متعددة.
  • لا يُدعم التدريب بدون store_master_weights=True.

الموارد

Update on GitHub