Hugging Face's logo

Diffusers documentation

التكميم

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.43.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

التكميم

تُقلّل تقنيات الكمّية من تكاليف الذاكرة والحساب من خلال تمثيل الأوزان والتفعيلات بأنواع بيانات ذات دقة أقل، مثل الأعداد الصحيحة الثمانية البتات (int8). وهذا يتيح تحميل نماذج أكبر مما لا تستطيع عادةً استيعابه في الذاكرة، وتسريع الاستدلال.

تعلّم كيفية تكميم النماذج في دليل Quantization.

PipelineQuantizationConfig

فئة diffusers.PipelineQuantizationConfig

< >

( quant_backend: str = Nonequant_kwargs: dict[str, str | float | int | dict] = Nonecomponents_to_quantize: list[str] | str | None = Nonequant_mapping: dict[str, DiffQuantConfigMixin | 'TransformersQuantConfigMixin'] = None )

المعاملات

  • quant_backend (str) — مُحرّك التكميم (Quantization backend) الذي سيتم استخدامه. عند استخدام هذا الخيار، نفترض أن المُحرّك متاح لكلٍّ من diffusers وtransformers.
  • quant_kwargs (dict) — المعاملات اللازمة لتبنيئة فئة واجهة التكميم.
  • components_to_quantize (list) — مكوّنات خط الأنابيب التي سيتم تكميمها.
  • quant_mapping (dict) — تعيين يحدد مواصفات التكميم (quantization) التي سيتم استخدامها لمكونات خط المعالجة. عند استخدام هذا الحُجج، لا يُتوقع من المستخدمين تقديم quant_backend، quant_kawargs، وcomponents_to_quantize.

فئة التكوين المستخدمة عند تطبيق التكميم أثناء التشغيل على from_pretrained().

BFLQuantizationConfig

فئة diffusers.BFLQuantizationConfig

< >

( compute_dtype: 'torch.dtype' | None = None )

المعاملات

  • compute_dtype (torch.dtype، القيمة الافتراضية torch.bfloat16) — نوع البيانات (dtype) للتفعيلات (activations) وللطبقات غير المُكمّاة. الأجهزة التي لا تحتوي على نواة FP8 أو NVFP4 مدمجة تقوم بإلغاء تكميم الأوزان إلى هذا النوع من البيانات في كل تمريرة أمامية.

إعدادات لتحميل نقاط التفتيش المُكمّمة باستخدام مخططي fp8r وnvfp4 من Black Forest Labs.

تُقرأ كلا المخططين من نقطة الحفظ عبر ~FromSingleFileMixin.from_single_file؛ ولا يُدعم تكميم النموذج أثناء التشغيل. يتم تكميم طبقة خطية عندما يأتي وزنها مع مصفوفات مقياس:

  • fp8r: weight هو float8_e4m3fn بالشكل [N, K] وweight_scale هو مقياس fp32 لكل صف [N].
  • nvfp4: weight هو uint8 بشكل [N, K/2] (قيمتان E2M1 لكل بايت)، وweight_scale هو مقياس كتلة float8_e4m3fn بشكل [N, K/16]، بينما weight_scale_2 وinput_scale هما قيمتان قياسية fp32 تحملان مقياس الأوزان العام ومقياس التنشيط المُعايَر (تخطيط ModelOpt NVFP4).

BitsAndBytesConfig

فئة diffusers.BitsAndBytesConfig

< >

( load_in_8bit = Falseload_in_4bit = Falsellm_int8_threshold = 6.0llm_int8_skip_modules = Nonellm_int8_enable_fp32_cpu_offload = Falsellm_int8_has_fp16_weight = Falsebnb_4bit_compute_dtype = Nonebnb_4bit_quant_type = 'fp4'bnb_4bit_use_double_quant = Falsebnb_4bit_quant_storage = None**kwargs )

المعاملات

  • load_in_8bit (bool، اختياري، القيمة الافتراضية False) — يُستخدم هذا العلم لتفعيل التكميم بدقة 8 بت باستخدام LLM.int8().
  • load_in_4bit (bool، اختياري، القيمة الافتراضية False) — يُستخدم هذا العلم لتفعيل التكميم بدقة 4 بت عن طريق استبدال طبقات Linear بطبقات FP4/NF4 من bitsandbytes.
  • llm_int8_threshold (float, اختياري، القيمة الافتراضية 6.0) — يتوافق هذا مع عتبة القيم الشاذة لاكتشاف القيم الشاذة كما هو موصوف في ورقة LLM.int8() : 8-bit Matrix Multiplication for Transformers at Scale: https://huggingface.co/papers/2208.07339 أي قيمة لحالة مخفية تتجاوز هذه العتبة تُعتبر قيمة شاذة، وتُنفَّذ العمليات على تلك القيم في fp16. عادةً ما تكون القيم موزعة بشكل طبيعي، أي أن معظم القيم تقع في النطاق [-3.5, 3.5]، لكن هناك بعض القيم الشاذة المنهجية الاستثنائية التي تكون موزعة بشكل مختلف تمامًا في النماذج الكبيرة. غالبًا ما تقع هذه القيم الشاذة في الفترة [-60, -6] أو [6, 60]. يعمل تكميم Int8 بشكل جيد للقيم ذات الحجم ~5، لكن ما يتجاوز ذلك، هناك عقوبة أداء كبيرة. عتبة افتراضية جيدة هي 6، لكن قد تكون هناك حاجة إلى عتبة أقل للنماذج الأقل استقرارًا (النماذج الصغيرة، الضبط الدقيق).
  • llm_int8_skip_modules (list[str], اختياري) — قائمة صريحة بالوحدات التي لا نرغب في تحويلها إلى 8 بت. وهذا مفيد للنماذج مثل Jukebox التي تحتوي على عدة رؤوس في مواقع مختلفة وليس بالضرورة في الموقع الأخير. على سبيل المثال في نماذج CausalLM، يُحافظ عادةً على lm_head الأخير في dtype الأصلي الخاص به.
  • llm_int8_enable_fp32_cpu_offload (bool، اختياري، القيمة الافتراضية False) — يُستخدم هذا العلم لحالات الاستخدام المتقدمة وللمستخدمين الذين على دراية بهذه الميزة. إذا كنت ترغب في تقسيم نموذجك إلى أجزاء مختلفة وتشغيل بعض الأجزاء بصيغة int8 على وحدة معالجة الرسوميات GPU وبعض الأجزاء بصيغة fp32 على وحدة المعالجة المركزية CPU، يمكنك استخدام هذا العلم. يكون هذا مفيدًا لنقل النماذج الكبيرة مثل google/flan-t5-xxl. لاحظ أن عمليات int8 لن تُنفَّذ على وحدة المعالجة المركزية CPU.
  • llm_int8_has_fp16_weight (bool، اختياري، القيمة الافتراضية False) — تشغّل هذا العلم دالة LLM.int8() بأوزان رئيسية بدقة 16 بت. وهذا مفيد للضبط الدقيق (fine-tuning) لأن الأوزان لا تحتاج إلى التحويل ذهابًا وإيابًا لمرحلة الرجوع (backward pass).
  • bnb_4bit_compute_dtype (torch.dtype أو str، اختياري، القيمة الافتراضية torch.float32) — يحدد هذا نوع الحساب الذي قد يختلف عن نوع الإدخال. على سبيل المثال، قد تكون المدخلات من نوع fp32، لكن يمكن ضبط الحساب على bf16 لتحقيق تسريع.
  • bnb_4bit_quant_type (str، اختياري، القيمة الافتراضية "fp4") — يحدد هذا نوع بيانات التكميم في طبقات bnb.nn.Linear4Bit. الخيارات المتاحة هي أنواع بيانات FP4 و NF4، والتي تُحدد بواسطة fp4 أو nf4.
  • bnb_4bit_use_double_quant (bool، اختياري، القيمة الافتراضية False) — يُستخدم هذا العلم للكمّية المتداخلة حيث تُكمَّم ثوابت الكمّية من الكمّية الأولى مرة أخرى.
  • bnb_4bit_quant_storage (torch.dtype أو str، اختياري، القيمة الافتراضية torch.uint8) — يحدد هذا نوع التخزين لتجميع المعاملات الكمية ذات 4 بت.
  • kwargs (dict[str, Any], اختياري) — معاملات إضافية تُستخدم لتهيئة كائن الإعدادات.

هذه فئة غلاف (wrapper class) حول جميع الخصائص والميزات الممكنة التي يمكنك التعامل معها في نموذج تم تحميله باستخدام bitsandbytes.

يستبدل هذا الخيار load_in_8bit أو load_in_4bit وبالتالي فإن كلا الخيارين متنافيان.

يدعم حاليًا LLM.int8()، FP4، وNF4 فقط. إذا أُضيفت طرق أخرى إلى bitsandbytes، فسيتم إضافة حُجج إضافية إلى هذه الفئة.

is_quantizable

< >

( )

يعيد True إذا كان النموذج قابلًا للكمّية، وإلا يعيد False.

post_init

< >

( )

فاحص الأمان الذي يتحقق من صحة الحُجج - كما يستبدل بعض حُجج نوع NoneType بقيمها الافتراضية.

quantization_method

< >

( )

تعيد هذه الطريقة طريقة التكميم المستخدمة للنموذج. إذا لم يكن النموذج قابلاً للتكميم، فإنها تعيد None.

to_diff_dict

< >

( ) → dict[str, Any]

يعيد

dict[str, Any]

قاموس بجميع السمات التي تُشكّل هذا المثال من التهيئة،

يزيل جميع الخصائص من config التي تتوافق مع خصائص الإعداد الافتراضي لتحسين قابلية القراءة، ويُسلسل إلى قاموس Python.

GGUFQuantizationConfig

فئة diffusers.GGUFQuantizationConfig

< >

( compute_dtype: 'torch.dtype' | None = None )

المعاملات

  • compute_dtype — (torch.dtype، القيمة الافتراضية torch.float32): يحدد هذا نوع الحساب الذي قد يختلف عن نوع الإدخال. على سبيل المثال، قد تكون المدخلات من نوع fp32، لكن يمكن ضبط الحساب على bf16 لتحقيق تسريع.

هذا هو فئة إعدادات لتقنيات تكميم GGUF.

NunchakuLiteQuantizationConfig

فئة diffusers.NunchakuLiteQuantizationConfig

< >

( compute_dtype: 'torch.dtype' | str | None = Nonesvdq_w4a4: dict[str, Any] | None = Noneawq_w4a16: dict[str, Any] | None = None**kwargs )

المعاملات

  • compute_dtype (torch.dtype، الافتراضي torch.bfloat16) — نوع البيانات (dtype) المستخدم وقت التشغيل في المخازن المؤقتة ذات الفاصلة العائمة داخل الوحدات المُكمّمة.
  • svdq_w4a4 (dict، اختياري) — إعداد صريح لهدف SVDQ W4A4 يتضمن precision وgroup_size وrank وtargets.
  • awq_w4a16 (dict, اختياري) — إعدادات صريحة لهدف AWQ W4A16 تتضمن precision وgroup_size وtargets.

إعدادات لتحميل نقاط التفتيش الخاصة بـ Nunchaku Lite.

يدعم Nunchaku Lite في Diffusers تحميل نقاط التفتيش المُكمّاة مسبقًا. لإنشاء نقطة تفتيش متوافقة، استخدم diffuse-compressor لاختيار أو تكييف إعداد مستهدف لبنية النموذج، ثم قم بتكميم وتصدير المحوّل (transformer)، وعبّئها كخط أنابيب Diffusers مع إعداد التكميم المدمج quantization_config المخزّن في config.json.

يجب أن يطابق state dict المُصدَّر بنية نموذج Diffusers المستهدف تمامًا. لن يتم تحميل نقاط التفتيش المُكمّاة باستخدام إسقاطات QKV المدمجة في إعدادات نموذج يتوقع وحدات إسقاط منفصلة لكل من Q وK وV.

مثال على إعداد config.json مضغوط:

{
  "_class_name": "ErnieImageTransformer2DModel",
  "quantization_config": {
    "quant_method": "nunchaku_lite",
    "compute_dtype": "bfloat16",
    "svdq_w4a4": {
      "precision": "nvfp4",
      "group_size": 16,
      "rank": 32,
      "targets": ["layers.0.self_attention.to_q"]
    },
    "awq_w4a16": {
      "precision": "int4",
      "group_size": 64,
      "targets": ["final_linear"]
    }
  }
}

QuantoConfig

فئة diffusers.QuantoConfig

< >

( weights_dtype: str = 'int8'modules_to_not_convert: list[str] | None = None**kwargs )

المعاملات

  • weights_dtype (str، اختياري، القيمة الافتراضية "int8") — نوع البيانات المستهدف للأوزان بعد التكميم. القيم المدعومة هي (“float8”،“int8”،“int4”،“int2”)

هذه فئة غلاف (wrapper class) حول جميع الخصائص والميزات الممكنة التي يمكنك التعامل معها في نموذج تم تحميله باستخدام quanto.

QuantoConfig لم يعد مدعومًا وسيتم إزالته في الإصدار 1.0.0. يُنصح بالانتقال إلى أحد محركات الكمّية الأخرى المدعومة، مثل BitsAndBytesConfig أو TorchAoConfig.

modules_to_not_convert (list, اختياري، الافتراضي None): قائمة الوحدات التي يجب عدم تكميمها، وهي مفيدة لتكميم النماذج التي تتطلب صراحةً إبقاء بعض الوحدات في دقتها الأصلية (مثل مشفّر Whisper، ومشفّر Llava، وطبقات بوابة Mixtral).

post_init

< >

( )

فاحص الأمان الذي يتحقق من صحة الحُجج

SDNQConfig

فئة diffusers.SDNQConfig

< >

( *args**kwargs )

المعاملات

  • weights_dtype (str، اختياري، القيمة الافتراضية "int8") — نوع البيانات المستهدف للأوزان بعد التكميم، مثل "int8"، "uint4"، "float8_e4m3fn". راجع sdnq.common.accepted_weight_dtypes لجميع القيم المدعومة.
  • group_size (int، اختياري، القيمة الافتراضية 0) — عدد عناصر الموتر (Tensor) التي تشترك في نفس مجموعة التكميم. يقوم 0 بالاختيار التلقائي بناءً على weights_dtype، بينما يعطّل -1 التجميع ويستخدم التكميم على مستوى الصفوف.
  • use_svd (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تطبيق خوارزمية SVDQuant فوق تكميم SDNQ.
  • use_quantized_matmul (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم استخدام ضرب المصفوفات الكمي INT8 / FP8 / FP16 في مسار الأمامي بدلاً من BF16 / FP16.
  • modules_to_not_convert (list، اختياري، القيمة الافتراضية None) — قائمة الوحدات التي يجب تجاوزها أثناء التكميم.
  • kwargs (dict[str, Any]، اختياري) — معلمات إضافية تُمرَّر إلى sdnq.SDNQConfig (مثل quantized_matmul_dtype، svd_rank، use_hadamard، quant_conv، quant_embedding، modules_dtype_dict).

فئة التهيئة لـ SDNQ (SD.Next Quantization).

تأتي مكتبة sdnq مع إعدادات ومكمِّم متوافقين مع diffusers؛ هذه الفئة هي مصنع رفيع يحوّل المهام إليهما بحيث تُحمَّل نقاط التفتيش التي تستخدم quant_method="sdnq" بشكل أصلي مع diffusers. يتم تمرير جميع الحُجج إلى sdnq.SDNQConfig. تتطلب هذه العملية مكتبة sdnq: pip install sdnq.

مرجع: https://github.com/Disty0/sdnq

TorchAoConfig

فئة diffusers.TorchAoConfig

< >

( quant_type: 'AOBaseConfig'modules_to_not_convert: list[str] | None = None**kwargs )

المعاملات

  • quant_type (AOBaseConfig) — مثال على فئة فرعية من AOBaseConfig يحدد نوع التكميم. راجع وثائق torchao للاطلاع على فئات الإعدادات المتاحة (مثل Int4WeightOnlyConfig، Int8WeightOnlyConfig، Float8WeightOnlyConfig، Float8DynamicActivationFloat8WeightConfig، وغيرها).
  • modules_to_not_convert (list[str]، اختياري، القيمة الافتراضية None) — قائمة الوحدات التي يجب عدم تكميمها، وهو مفيد لتكميم النماذج التي تتطلب صراحةً إبقاء بعض الوحدات في دقتها الأصلية.

هذا هو فئة إعدادات لتقنيات الكمّ والتخلخل في torchao.

مثال:

from diffusers import FluxTransformer2DModel, TorchAoConfig
from torchao.quantization import Int8WeightOnlyConfig

quantization_config = TorchAoConfig(Int8WeightOnlyConfig())
transformer = FluxTransformer2DModel.from_pretrained(
    "black-forest-labs/Flux.1-Dev",
    subfolder="transformer",
    quantization_config=quantization_config,
    torch_dtype=torch.bfloat16,
)

from_dict

< >

( config_dictreturn_unused_kwargs = False**kwargs )

إنشاء تكوين من قاموس.

get_apply_tensor_subclass

< >

( )

أنشئ طريقة التكميم المناسبة بناءً على الإعداد.

to_dict

< >

( )

تحويل الإعدادات إلى قاموس.

DiffusersQuantizer

فئة diffusers.DiffusersQuantizer

< >

( quantization_config: QuantizationConfigMixin**kwargs )

فئة مجردة لمُكمِّم HuggingFace. تدعم حاليًا كمّ نماذج HF diffusers للاستدلال و/أو الكمّ. تُستخدم هذه الفئة فقط في diffusers.models.modeling_utils.ModelMixin.from_pretrained ولا يمكن استخدامها بسهولة خارج نطاق تلك الطريقة بعد.

الخصائص quantization_config (diffusers.quantizers.quantization_config.QuantizationConfigMixin): إعدادات التكميم التي تحدد معاملات التكميم لنموذجك الذي تريد تكميمه. modules_to_not_convert (list[str], اختياري): قائمة أسماء الوحدات التي يجب عدم تحويلها عند تكميم النموذج. required_packages (list[str], اختياري): قائمة حزم pip المطلوبة التي يجب تثبيتها قبل استخدام مُكمِّم التكميم. requires_calibration (bool): ما إذا كانت طريقة التكميم تتطلب معايرة النموذج قبل استخدامه.

adjust_max_memory

< >

( max_memory: dict[str, int | str] )

اضبط معامل max_memory للدالة infer_auto_device_map() إذا كانت هناك حاجة إلى ذاكرة إضافية للكمّ

adjust_target_dtype

< >

( torch_dtype: torch.dtype )

المعاملات

  • torch_dtype (torch.dtype، اختياري) — قيمة torch_dtype المستخدمة لحساب device_map.

تجاوز هذه الطريقة إذا كنت ترغب في تعديل متغير target_dtype المستخدم في from_pretrained لحساب device_map في حال كان device_map من نوع str. على سبيل المثال، في حالة bitsandbytes، نجبر على تعيين target_dtype إلى torch.int8، وفي حالة 4-bit، نمرر enum مخصص accelerate.CustomDtype.int4.

check_if_quantized_param

< >

( model: ModelMixinparam_value: torch.Tensorparam_name: strstate_dict: dict[str, typing.Any]**kwargs )

يتحقق مما إذا كان مكوّن state_dict المحمّل جزءًا من معامل مُكمَّم + بعض التحقق؛ يُعرَّف فقط لطرق الكمّ التي تتطلب إنشاء معاملات جديدة للكمّ.

check_quantized_param_shape

< >

( *args**kwargs )

يتحقق من أن المعامل المُكمَّم له الشكل المتوقع.

create_quantized_param

< >

( *args**kwargs )

يستخرج المكونات المطلوبة من state_dict وينشئ معاملًا مُكمَّمًا.

dequantize

< >

( model )

قد يؤدي إلغاء التكميم إلى استعادة النموذج الأصلي، مع بعض الفقدان في الدقة / الأداء. لاحظ أن مخططات التكميم لا تدعم جميعها هذه العملية.

get_cuda_warm_up_factor

< >

( )

العامل الذي يُستخدم في caching_allocator_warmup للحصول على عدد البايتات التي يجب تخصيصها مسبقًا لإحماء cuda. يعني عامل بقيمة 2 أننا نخصص جميع البايتات في النموذج الفارغ (بما أننا نخصص في fp16)، ويعني عامل بقيمة 4 أننا نخصص نصف ذاكرة الأوزان الموجودة في النموذج الفارغ، وهكذا…

get_special_dtypes_update

< >

( modeltorch_dtype: torch.dtype )

المعاملات

  • model (~diffusers.models.modeling_utils.ModelMixin) — النموذج الذي سيتم كميته
  • torch_dtype (torch.dtype) — نوع البيانات (dtype) المُمرَّر في طريقة from_pretrained.

returns dtypes for modules that are not quantized - used for the computation of the device_map in case one passes a str as a device_map. The method will use the modules_to_not_convert that is modified in _process_model_before_weight_loading. diffusers models don’t have any modules_to_not_convert attributes yet but this can change soon in the future.

postprocess_model

< >

( model: ModelMixin**kwargs )

المعاملات

  • model (~diffusers.models.modeling_utils.ModelMixin) — النموذج الذي سيتم كميته
  • kwargs (dict، اختياري) — الحجج المُسمّاة التي تُمرَّر إلى _process_model_after_weight_loading.

قم بمعالجة النموذج بعد تحميل الأوزان. تأكد من تجاوز الطريقة المجردة _process_model_after_weight_loading.

preprocess_model

< >

( model: ModelMixin**kwargs )

المعاملات

  • model (~diffusers.models.modeling_utils.ModelMixin) — النموذج الذي سيتم كميته
  • kwargs (dict، اختياري) — الحجج المُسمّاة التي تُمرَّر مع _process_model_before_weight_loading.

ضبط سمات النموذج و/أو تحويل النموذج قبل تحميل الأوزان. في هذه المرحلة يجب أن يكون النموذج مُهيأً على جهاز meta حتى تتمكن من التلاعب بحُزمة النموذج بحرية من أجل استبدال الوحدات في مكانها. تأكد من تجاوز الطريقة المجردة _process_model_before_weight_loading.

update_device_map

< >

( device_map: dict[str, typing.Any] | None )

المعاملات

  • device_map (dict | str، اختياري) — خريطة الأجهزة التي يتم تمريرها عبر طريقة from_pretrained.

Override this method if you want to pass a override the existing device map with a new one. E.g. for bitsandbytes, since accelerate is a hard requirement, if no device_map is passed, the device_map is set to `“auto”“

update_missing_keys

< >

( modelmissing_keys: list[str]prefix: str )

المعاملات

  • missing_keys (list[str]، اختياري) — قائمة المفاتيح المفقودة في نقطة الحفظ مقارنةً بـ state dict الخاص بالنموذج

استبدل هذه الطريقة إذا كنت ترغب في تعديل missing_keys.

update_torch_dtype

< >

( torch_dtype: torch.dtype )

المعاملات

  • torch_dtype (torch.dtype) — نوع البيانات المدخل الذي يُمرَّر في from_pretrained

تتطلب بعض طرق التكميم ضبط نوع البيانات (dtype) للنموذج بشكل صريح على نوع بيانات مستهدف. يجب عليك تجاوز هذه الطريقة إذا كنت ترغب في التأكد من الحفاظ على هذا السلوك

validate_environment

< >

( *args**kwargs )

يُستخدم هذا الأسلوب للتحقق من وجود تعارضات محتملة مع الحُجج المُمرَّرة في from_pretrained. يجب عليك تعريفه لجميع مُكمِّسات المستقبل المُدمجة مع diffusers. إذا لم تكن هناك حاجة إلى تحقق صريح، فبمجرد عدم إرجاع أي شيء.

Update on GitHub

←المخرجات الاستدلال عن بُعد→