Hugging Face's logo

Diffusers documentation

Quantification

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

and get access to the augmented documentation experience

to get started

Quantification

Les techniques de quantification réduisent les coûts mémoire et de calcul en représentant les poids et les activations avec des types de données de précision inférieure, tels que les entiers 8 bits (int8). Cela permet de charger des modèles plus volumineux que vous ne pourriez normalement pas faire tenir en mémoire, et d’accélérer l’inférence.

Apprenez à quantiser des modèles dans le guide Quantization.

PipelineQuantizationConfig

classe 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 )

Paramètres

  • quant_backend (str) — Backend de quantification à utiliser. Lorsque cette option est utilisée, nous supposons que le backend est disponible à la fois pour diffusers et transformers.
  • quant_kwargs (dict) — Paramètres pour initialiser la classe du backend de quantification.
  • components_to_quantize (list) — Composants d'un pipeline à quantiser.
  • quant_mapping (dict) — Mapping définissant les spécifications de quantification à utiliser pour les composants du pipeline. Lors de l’utilisation de cet argument, les utilisateurs ne sont pas censés fournir quant_backend, quant_kawargs et components_to_quantize.

Classe de configuration à utiliser lors de l'application de la quantification à la volée sur from_pretrained().

BFLQuantizationConfig

classe diffusers.BFLQuantizationConfig

< >

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

Paramètres

  • compute_dtype (torch.dtype, par défaut torch.bfloat16) — Le dtype des activations et des couches non quantifiées. Les appareils sans noyaux FP8 ou NVFP4 fusionnés déquantifient les poids vers ce dtype à chaque passe avant.

Configuration pour charger des points de contrôle quantifiés avec les schémas fp8r et nvfp4 de Black Forest Labs.

Les deux schémas sont lus depuis le point de contrôle via ~FromSingleFileMixin.from_single_file ; la quantification d'un modèle à la volée n'est pas prise en charge. Une couche linéaire est quantifiée lorsque son poids est accompagné de tenseurs d'échelle :

  • fp8r : weight est de type float8_e4m3fn avec la forme [N, K] et weight_scale est une échelle fp32 par ligne [N].
  • nvfp4 : weight est de type uint8 avec la forme [N, K/2] (deux valeurs E2M1 par octet), weight_scale est une échelle de bloc float8_e4m3fn de forme [N, K/16], et weight_scale_2 et input_scale sont des scalaires fp32 contenant l'échelle globale des poids et l'échelle d'activation calibrée (disposition NVFP4 de ModelOpt).

BitsAndBytesConfig

classe 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 )

Paramètres

  • load_in_8bit (bool, facultatif, par défaut False) — Ce drapeau est utilisé pour activer la quantification 8 bits avec LLM.int8().
  • load_in_4bit (bool, facultatif, valeur par défaut False) — Ce drapeau est utilisé pour activer la quantification en 4 bits en remplaçant les couches Linear par des couches FP4/NF4 de bitsandbytes.
  • llm_int8_threshold (float, facultatif, valeur par défaut 6.0) — Correspond au seuil de détection des valeurs aberrantes tel que décrit dans l'article LLM.int8() : 8-bit Matrix Multiplication for Transformers at Scale : https://huggingface.co/papers/2208.07339 Toute valeur d'état caché supérieure à ce seuil est considérée comme une valeur aberrante et les opérations sur ces valeurs sont réalisées en fp16. Les valeurs suivent généralement une distribution normale, c'est-à-dire que la plupart des valeurs se situent dans l'intervalle [-3,5, 3,5], mais il existe des valeurs aberrantes systématiques exceptionnelles, très différemment distribuées pour les grands modèles. Ces valeurs aberrantes se trouvent souvent dans l'intervalle [-60, -6] ou [6, 60]. La quantification Int8 fonctionne bien pour des valeurs d'amplitude ~5, mais au-delà, il y a une pénalité de performance significative. Un bon seuil par défaut est 6, mais un seuil plus bas peut être nécessaire pour les modèles plus instables (petits modèles, fine-tuning).
  • llm_int8_skip_modules (list[str], facultatif) — Une liste explicite des modules que nous ne souhaitons pas convertir en 8 bits. Cela est utile pour des modèles tels que Jukebox qui possède plusieurs têtes à différents endroits et pas nécessairement à la dernière position. Par exemple, pour les modèles CausalLM, le dernier lm_head est généralement conservé dans son dtype d'origine.
  • llm_int8_enable_fp32_cpu_offload (bool, facultatif, valeur par défaut False) — Ce drapeau est destiné aux cas d’utilisation avancés et aux utilisateurs connaissant cette fonctionnalité. Si vous souhaitez diviser votre modèle en différentes parties et exécuter certaines parties en int8 sur GPU et d’autres en fp32 sur CPU, vous pouvez utiliser ce drapeau. Cela est utile pour décharger de grands modèles tels que google/flan-t5-xxl. Notez que les opérations int8 ne seront pas exécutées sur CPU.
  • llm_int8_has_fp16_weight (bool, facultatif, valeur par défaut False) — Ce drapeau exécute LLM.int8() avec des poids principaux en 16 bits. C’est utile pour le fine-tuning, car les poids n’ont pas à être convertis à l’aller-retour pour le passage arrière.
  • bnb_4bit_compute_dtype (torch.dtype ou str, facultatif, par défaut torch.float32) — Définit le type de calcul, qui peut différer du type d'entrée. Par exemple, les entrées peuvent être en fp32, mais le calcul peut être défini en bf16 pour gagner en vitesse.
  • bnb_4bit_quant_type (str, facultatif, valeur par défaut "fp4") — Définit le type de données de quantification dans les couches bnb.nn.Linear4Bit. Les options sont les types de données FP4 et NF4, spécifiés par fp4 ou nf4.
  • bnb_4bit_use_double_quant (bool, facultatif, valeur par défaut False) — Ce drapeau est utilisé pour la quantification imbriquée, où les constantes de quantification issues de la première quantification sont à nouveau quantifiées.
  • bnb_4bit_quant_storage (torch.dtype ou str, facultatif, par défaut torch.uint8) — Définit le type de stockage pour empaqueter les paramètres quantifiés sur 4 bits.
  • kwargs (dict[str, Any], facultatif) — Paramètres supplémentaires à partir desquels initialiser l'objet de configuration.

Il s’agit d’une classe enveloppe regroupant l’ensemble des attributs et fonctionnalités possibles avec lesquels vous pouvez manipuler un modèle chargé à l’aide de bitsandbytes.

Cela remplace load_in_8bit ou load_in_4bit, les deux options étant donc mutuellement exclusives.

Prend actuellement en charge uniquement la quantification LLM.int8(), FP4 et NF4. Si d'autres méthodes sont ajoutées à bitsandbytes, d'autres arguments seront ajoutés à cette classe.

is_quantizable

< >

( )

Retourne True si le modèle est quantifiable, False sinon.

post_init

< >

( )

Vérificateur de sécurité qui s'assure que les arguments sont corrects - remplace également certains arguments de type NoneType par leurs valeurs par défaut.

quantization_method

< >

( )

Cette méthode renvoie la méthode de quantification utilisée pour le modèle. Si le modèle n'est pas quantifiable, elle renvoie None.

to_diff_dict

< >

( ) → dict[str, Any]

Retourne

dict[str, Any]

Dictionnaire de tous les attributs qui composent cette instance de configuration,

Supprime tous les attributs de config qui correspondent aux attributs de la config par défaut, pour une meilleure lisibilité, et sérialise en dictionnaire Python.

GGUFQuantizationConfig

classe diffusers.GGUFQuantizationConfig

< >

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

Paramètres

  • compute_dtype — (torch.dtype, par défaut torch.float32) : Définit le type de calcul, qui peut différer du type d'entrée. Par exemple, les entrées peuvent être en fp32, mais le calcul peut être défini en bf16 pour gagner en vitesse.

Il s’agit d’une classe de configuration pour les techniques de quantification GGUF.

NunchakuLiteQuantizationConfig

classe diffusers.NunchakuLiteQuantizationConfig

< >

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

Paramètres

  • compute_dtype (torch.dtype, par défaut torch.bfloat16) — Type de données utilisé à l'exécution par les tampons à virgule flottante des modules quantifiés.
  • svdq_w4a4 (dict, facultatif) — Configuration explicite de la cible SVDQ W4A4 avec precision, group_size, rank et targets.
  • awq_w4a16 (dict, facultatif) — Configuration explicite de la cible AWQ W4A16 avec precision, group_size et targets.

Configuration pour le chargement des points de contrôle Nunchaku Lite.

La prise en charge de Nunchaku Lite dans Diffusers charge des points de contrôle pré-quantifiés. Pour créer un point de contrôle compatible, utilisez diffuse-compressor pour choisir ou adapter une configuration cible pour l'architecture du modèle, quantifier et exporter le transformeur, puis l'empaqueter en tant que pipeline Diffusers avec la configuration compacte quantization_config stockée dans config.json.

Le state dict exporté doit correspondre exactement à l’architecture du modèle Diffusers cible. Les points de contrôle quantifiés avec des projections QKV fusionnées ne peuvent pas être chargés dans une configuration de modèle qui s’attend à des modules de projection Q, K et V séparés.

Exemple de configuration compacte 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

classe diffusers.QuantoConfig

< >

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

Paramètres

  • weights_dtype (str, facultatif, par défaut "int8") — Le type de données cible pour les poids après quantification. Les valeurs prises en charge sont (« float8 », « int8 », « int4 », « int2 »)

Il s’agit d’une classe enveloppe regroupant l’ensemble des attributs et fonctionnalités possibles avec lesquels vous pouvez manipuler un modèle chargé à l’aide de quanto.

QuantoConfig est obsolète et sera supprimé dans la version 1.0.0. Pensez à passer à l’un des autres backends de quantification pris en charge, tels que BitsAndBytesConfig ou TorchAoConfig.

modules_to_not_convert (list, facultatif, par défaut None) : La liste des modules à ne pas quantiser, utile pour quantiser des modèles qui nécessitent explicitement de laisser certains modules dans leur précision d'origine (par ex. l'encodeur Whisper, l'encodeur Llava, les couches de porte de Mixtral).

post_init

< >

( )

Vérificateur de sécurité qui vérifie que les arguments sont corrects

SDNQConfig

classe diffusers.SDNQConfig

< >

( *args**kwargs )

Paramètres

  • weights_dtype (str, facultatif, par défaut "int8") — Le type de données cible pour les poids après quantification, par exemple "int8", "uint4", "float8_e4m3fn". Voir sdnq.common.accepted_weight_dtypes pour toutes les valeurs prises en charge.
  • group_size (int, facultatif, valeur par défaut 0) — Nombre d'éléments d'un tenseur partageant le même groupe de quantification. 0 sélectionne automatiquement en fonction de weights_dtype, -1 désactive le groupement et utilise la quantification par ligne.
  • use_svd (bool, facultatif, par défaut False) — Indique s'il faut appliquer l'algorithme SVDQuant par-dessus la quantification SDNQ.
  • use_quantized_matmul (bool, facultatif, valeur par défaut False) — Indique s'il faut utiliser la multiplication matricielle quantisée INT8 / FP8 / FP16 lors du passage avant plutôt que BF16 / FP16.
  • modules_to_not_convert (list, facultatif, par défaut None) — La liste des modules à ignorer lors de la quantification.
  • kwargs (dict[str, Any], facultatif) — Arguments supplémentaires transmis à sdnq.SDNQConfig (par ex. quantized_matmul_dtype, svd_rank, use_hadamard, quant_conv, quant_embedding, modules_dtype_dict).

Classe de configuration pour SDNQ (SD.Next Quantization).

La bibliothèque sdnq fournit sa propre configuration et son quantificateur compatibles avec diffusers ; cette classe est une usine fine qui leur délègue le travail afin que les points de contrôle quant_method="sdnq" soient chargés nativement avec diffusers. Tous les arguments sont transmis à sdnq.SDNQConfig. Nécessite la bibliothèque sdnq : pip install sdnq.

Référence : https://github.com/Disty0/sdnq

TorchAoConfig

classe diffusers.TorchAoConfig

< >

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

Paramètres

  • quant_type (AOBaseConfig) — Une instance d'une sous-classe de AOBaseConfig spécifiant le type de quantification. Consultez la documentation de torchao pour les classes de configuration disponibles (par exemple Int4WeightOnlyConfig, Int8WeightOnlyConfig, Float8WeightOnlyConfig, Float8DynamicActivationFloat8WeightConfig, etc.).
  • modules_to_not_convert (list[str], facultatif, par défaut None) — La liste des modules à ne pas quantiser, utile pour quantiser des modèles qui nécessitent explicitement de conserver certains modules dans leur précision d'origine.

Il s’agit d’une classe de configuration pour les techniques de quantification et de sparsité de torchao.

Exemple :

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 )

Créer une configuration à partir d'un dictionnaire.

get_apply_tensor_subclass

< >

( )

Créez la méthode de quantification appropriée en fonction de la configuration.

to_dict

< >

( )

Convertit la configuration en dictionnaire.

DiffusersQuantizer

classe diffusers.DiffusersQuantizer

< >

( quantization_config: QuantizationConfigMixin**kwargs )

Classe abstraite du quantiseur HuggingFace. Prend actuellement en charge la quantification des modèles HF diffusers pour l'inférence et/ou la quantification. Cette classe n'est utilisée que par diffusers.models.modeling_utils.ModelMixin.from_pretrained et ne peut pas encore être facilement utilisée en dehors du périmètre de cette méthode.

Attributs quantization_config (diffusers.quantizers.quantization_config.QuantizationConfigMixin) : La configuration de quantification qui définit les paramètres de quantification de votre modèle que vous souhaitez quantifier. modules_to_not_convert (list[str], facultatif) : La liste des noms de modules à ne pas convertir lors de la quantification du modèle. required_packages (list[str], facultatif) : La liste des paquets pip requis à installer avant d'utiliser le quantificateur. requires_calibration (bool) : Indique si la méthode de quantification nécessite de calibrer le modèle avant son utilisation.

adjust_max_memory

< >

( max_memory: dict )

Ajustez l'argument max_memory de infer_auto_device_map() si une mémoire supplémentaire est nécessaire pour la quantification

adjust_target_dtype

< >

( torch_dtype: torch.dtype )

Paramètres

  • torch_dtype (torch.dtype, facultatif) — Le torch_dtype utilisé pour calculer le device_map.

Écrasez cette méthode si vous souhaitez ajuster la variable target_dtype utilisée dans from_pretrained pour calculer le device_map dans le cas où device_map est un str. Par exemple, pour bitsandbytes, nous imposons target_dtype à torch.int8 et pour 4 bits, nous passons un enum personnalisé accelerate.CustomDtype.int4.

check_if_quantized_param

< >

( model: ModelMixinparam_value: torch.Tensorparam_name: strstate_dict: dict**kwargs )

vérifie si un composant de state_dict chargé fait partie des paramètres quantifiés + quelques validations ; uniquement défini pour les méthodes de quantification qui nécessitent de créer de nouveaux paramètres pour la quantisation.

check_quantized_param_shape

< >

( *args**kwargs )

vérifie que le paramètre quantifié a la forme attendue.

create_quantized_param

< >

( *args**kwargs )

récupère les composants nécessaires depuis state_dict et crée le paramètre quantifié.

déquantiser

< >

( model )

Déquantifier éventuellement le modèle pour récupérer le modèle d'origine, avec une perte de précision / de performances. Notez que tous les schémas de quantification ne prennent pas en charge cette opération.

get_cuda_warm_up_factor

< >

( )

Le facteur à utiliser dans caching_allocator_warmup pour obtenir le nombre d'octets à préallouer afin de réchauffer cuda. Un facteur de 2 signifie que nous allouons tous les octets du modèle vide (puisque nous allouons en fp16), un facteur de 4 signifie que nous allouons la moitié de la mémoire des poids résidant dans le modèle vide, etc…

get_special_dtypes_update

< >

( modeltorch_dtype: torch.dtype )

Paramètres

  • model (~diffusers.models.modeling_utils.ModelMixin) — Le modèle à quantiser
  • torch_dtype (torch.dtype) — Le dtype transmis à la méthode from_pretrained.

retourne les dtypes des modules qui ne sont pas quantifiés - utilisé pour le calcul de device_map dans le cas où l'on passe une str en tant que device_map. La méthode utilise modules_to_not_convert, qui est modifié dans _process_model_before_weight_loading. Les modèles diffusers ne possèdent pas encore d'attributs modules_to_not_convert, mais cela pourrait changer à l'avenir.

postprocess_model

< >

( model: ModelMixin**kwargs )

Paramètres

  • model (~diffusers.models.modeling_utils.ModelMixin) — Le modèle à quantiser
  • kwargs (dict, facultatif) — Les arguments par mot-clé transmis à _process_model_after_weight_loading.

Post-traitez le modèle après le chargement des poids. Assurez-vous de surcharger la méthode abstraite _process_model_after_weight_loading.

preprocess_model

< >

( model: ModelMixin**kwargs )

Paramètres

  • model (~diffusers.models.modeling_utils.ModelMixin) — Le modèle à quantiser
  • kwargs (dict, facultatif) — Les arguments par mot-clé transmis à _process_model_before_weight_loading.

Définition des attributs du modèle et/ou conversion du modèle avant le chargement des poids. À ce stade, le modèle doit être initialisé sur le périphérique meta, ce qui vous permet de manipuler librement le squelette du modèle afin de remplacer les modules en place. Assurez-vous de surcharger la méthode abstraite _process_model_before_weight_loading.

update_device_map

< >

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

Paramètres

  • device_map (dict | str, facultatif) — La device_map transmise par la méthode from_pretrained.

Écrasez cette méthode si vous souhaitez remplacer la carte de dispositifs existante par une nouvelle. Par exemple, pour bitsandbytes, étant donné que accelerate est une exigence stricte, si aucune device_map n'est transmise, la device_map est définie sur `“auto”“

update_missing_keys

< >

( modelmissing_keys: listprefix: str )

Paramètres

  • missing_keys (list[str], facultatif) — La liste des clés manquantes dans le point de contrôle par rapport au dictionnaire d'état du modèle

Écrasez cette méthode si vous souhaitez ajuster missing_keys.

update_torch_dtype

< >

( torch_dtype: torch.dtype )

Paramètres

  • torch_dtype (torch.dtype) — Le dtype d'entrée transmis à from_pretrained

Certaines méthodes de quantification nécessitent de définir explicitement le dtype du modèle sur un dtype cible. Vous devez réécrire cette méthode si vous souhaitez vous assurer que ce comportement est préservé

validate_environment

< >

( *args**kwargs )

Cette méthode est utilisée pour vérifier d’éventuels conflits avec les arguments passés à from_pretrained. Vous devez la définir pour tous les quantificateurs futurs qui seront intégrés à diffusers. Si aucune vérification explicite n’est nécessaire, il suffit de ne rien retourner.

Update on GitHub

←Sorties Inférence à distance→