Hugging Face's logo

Diffusers documentation

Quantização

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Quantização

Técnicas de quantização reduzem os custos de memória e computacionais ao representar pesos e ativações com tipos de dados de menor precisão, como inteiros de 8 bits (int8). Isso permite carregar modelos maiores que normalmente não caberiam na memória e acelerar a inferência.

Aprenda como quantizar modelos no guia 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 )

Parâmetros

  • quant_backend (str) — Backend de quantização a ser usado. Ao usar esta opção, assumimos que o backend está disponível tanto para o diffusers quanto para o transformers.
  • quant_kwargs (dict) — Parâmetros para inicializar a classe do backend de quantização.
  • components_to_quantize (list) — Componentes de um pipeline a serem quantizados.
  • quant_mapping (dict) — Mapeamento que define as especificações de quantização a serem usadas para os componentes do pipeline. Ao usar este argumento, não se espera que os usuários forneçam quant_backend, quant_kawargs e components_to_quantize.

Classe de configuração a ser usada ao aplicar quantização em tempo de execução no from_pretrained().

BFLQuantizationConfig

classe diffusers.BFLQuantizationConfig

< >

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

Parâmetros

  • compute_dtype (torch.dtype, padrão torch.bfloat16) — O dtype das ativações e das camadas não quantizadas. Dispositivos sem kernels FP8 ou NVFP4 fundidos desquantizam os pesos para este dtype em cada passagem de frente.

Config para carregar checkpoints quantizados com os esquemas fp8r e nvfp4 da Black Forest Labs.

Ambos os esquemas são lidos do checkpoint por meio de ~FromSingleFileMixin.from_single_file; a quantização de um modelo em tempo de execução não é suportada. Uma camada linear é quantizada quando seu peso vem acompanhado de tensores de escala:

  • fp8r: weight é float8_e4m3fn com forma [N, K] e weight_scale é uma escala fp32 por linha [N].
  • nvfp4: weight é uint8 com forma [N, K/2] (dois valores E2M1 por byte), weight_scale é uma escala de bloco float8_e4m3fn [N, K/16], e weight_scale_2 e input_scale são escalares fp32 que armazenam a escala global de pesos e a escala de ativação calibrada (o layout NVFP4 do 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 )

Parâmetros

  • load_in_8bit (bool, opcional, padrão False) — Este sinalizador é usado para habilitar a quantização de 8 bits com LLM.int8().
  • load_in_4bit (bool, opcional, padrão False) — Este sinalizador é usado para habilitar a quantização de 4 bits, substituindo as camadas Linear por camadas FP4/NF4 do bitsandbytes.
  • llm_int8_threshold (float, opcional, padrão 6.0) — Corresponde ao limiar de outliers para a detecção de outliers, conforme descrito no artigo LLM.int8() : 8-bit Matrix Multiplication for Transformers at Scale: https://huggingface.co/papers/2208.07339 Qualquer valor de estado oculto que esteja acima deste limiar será considerado um outlier e a operação sobre esses valores será executada em fp16. Os valores geralmente seguem uma distribuição normal, ou seja, a maioria dos valores está no intervalo [-3.5, 3.5], mas existem alguns outliers sistemáticos excepcionais que são distribuídos de forma muito diferente em modelos grandes. Esses outliers frequentemente estão no intervalo [-60, -6] ou [6, 60]. A quantização Int8 funciona bem para valores de magnitude ~5, mas além disso, há uma penalidade significativa de desempenho. Um bom limiar padrão é 6, mas um limiar menor pode ser necessário para modelos mais instáveis (modelos pequenos, fine-tuning).
  • llm_int8_skip_modules (list[str], opcional) — Uma lista explícita dos módulos que não queremos converter para 8 bits. Isso é útil para modelos como Jukebox, que possui várias cabeças em diferentes posições e não necessariamente na última posição. Por exemplo, para modelos CausalLM, o último lm_head é tipicamente mantido em seu dtype original.
  • llm_int8_enable_fp32_cpu_offload (bool, opcional, padrão False) — Este sinalizador é usado para casos de uso avançados e para usuários que conhecem esse recurso. Se você deseja dividir seu modelo em diferentes partes e executar algumas partes em int8 na GPU e outras em fp32 na CPU, você pode usar este sinalizador. Isso é útil para descarregar modelos grandes, como google/flan-t5-xxl. Observe que as operações int8 não serão executadas na CPU.
  • llm_int8_has_fp16_weight (bool, opcional, padrão False) — Este sinal executa o LLM.int8() com pesos principais de 16 bits. Isso é útil para fine-tuning, pois os pesos não precisam ser convertidos de volta para o passo de retropropagação.
  • bnb_4bit_compute_dtype (torch.dtype ou str, opcional, padrão torch.float32) — Isso define o tipo de cálculo, que pode ser diferente do tipo de entrada. Por exemplo, as entradas podem ser fp32, mas o cálculo pode ser definido como bf16 para ganhos de velocidade.
  • bnb_4bit_quant_type (str, opcional, padrão "fp4") — Isso define o tipo de dados de quantização nas camadas bnb.nn.Linear4Bit. As opções são os tipos de dados FP4 e NF4, especificados por fp4 ou nf4.
  • bnb_4bit_use_double_quant (bool, opcional, padrão False) — Este sinalizador é usado para quantização aninhada, na qual as constantes de quantização da primeira quantização são quantizadas novamente.
  • bnb_4bit_quant_storage (torch.dtype ou str, opcional, padrão torch.uint8) — Isso define o tipo de armazenamento para empacotar os parâmetros quânticos de 4 bits.
  • kwargs (dict[str, Any], opcional) — Parâmetros adicionais a partir dos quais inicializar o objeto de configuração.

Esta é uma classe wrapper sobre todos os atributos e recursos possíveis com os quais você pode interagir em um modelo que foi carregado usando bitsandbytes.

Isso substitui load_in_8bit ou load_in_4bit, portanto, ambas as opções são mutuamente exclusivas.

Atualmente, apenas suporta quantização LLM.int8(), FP4 e NF4. Se mais métodos forem adicionados ao bitsandbytes, mais argumentos serão adicionados a esta classe.

is_quantizable

< >

( )

Retorna True se o modelo for quantizável, False caso contrário.

post_init

< >

( )

Verificador de segurança que os argumentos estão corretos - também substitui alguns argumentos do tipo NoneType pelos seus valores padrão.

quantization_method

< >

( )

Este método retorna o método de quantização usado para o modelo. Se o modelo não for quantizável, ele retorna None.

to_diff_dict

< >

( ) → dict[str, Any]

Retorna

dict[str, Any]

Dicionário de todos os atributos que compõem esta instância de configuração,

Remove todos os atributos de config que correspondem aos atributos padrão de config para melhor legibilidade e serializa para um dicionário Python.

GGUFQuantizationConfig

classe diffusers.GGUFQuantizationConfig

< >

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

Parâmetros

  • compute_dtype — (torch.dtype, padrão torch.float32): Isso define o tipo de cálculo, que pode ser diferente do tipo de entrada. Por exemplo, as entradas podem ser fp32, mas o cálculo pode ser definido como bf16 para ganhos de velocidade.

Esta é uma classe de configuração para técnicas de quantização 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 )

Parâmetros

  • compute_dtype (torch.dtype, padrão torch.bfloat16) — dtype de tempo de execução usado pelos buffers de ponto flutuante nos módulos quantizados.
  • svdq_w4a4 (dict, opcional) — Configuração explícita do alvo SVDQ W4A4 com precision, group_size, rank e targets.
  • awq_w4a16 (dict, opcional) — Configuração explícita do alvo AWQ W4A16 com precision, group_size e targets.

Configuração para carregar checkpoints do Nunchaku Lite.

O suporte do Nunchaku Lite no Diffusers carrega checkpoints pré-quantizados. Para criar um checkpoint compatível, use diffuse-compressor para escolher ou adaptar uma configuração de destino para a arquitetura do modelo, quantizar e exportar o transformer, e empacotá-lo como um pipeline do Diffusers com o quantization_config compacto armazenado em config.json.

O state dict exportado deve corresponder exatamente à arquitetura do modelo Diffusers de destino. Checkpoints quantizados com projeções QKV fundidas não serão carregados em uma configuração de modelo que espera módulos de projeção Q, K e V separados.

Exemplo de configuração compacta 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 )

Parâmetros

  • weights_dtype (str, opcional, padrão "int8") — O dtype de destino para os pesos após a quantização. Os valores suportados são (“float8”,“int8”,“int4”,“int2”)

Esta é uma classe wrapper sobre todos os atributos e recursos possíveis com os quais você pode interagir em um modelo que foi carregado usando quanto.

QuantoConfig está obsoleto e será removido na versão 1.0.0. Considere migrar para um dos outros backends de quantização suportados, como BitsAndBytesConfig ou TorchAoConfig.

modules_to_not_convert (list, opcional, padrão None): A lista de módulos que não devem ser quantizados, útil para quantizar modelos que exigem explicitamente que alguns módulos permaneçam em sua precisão original (por exemplo, o codificador do Whisper, o codificador do Llava, as camadas de gate do Mixtral).

post_init

< >

( )

Verificador de segurança que os argumentos estão corretos

SDNQConfig

classe diffusers.SDNQConfig

< >

( *args**kwargs )

Parâmetros

  • weights_dtype (str, opcional, padrão "int8") — O dtype de destino para os pesos após a quantização, por exemplo, "int8", "uint4", "float8_e4m3fn". Consulte sdnq.common.accepted_weight_dtypes para todos os valores suportados.
  • group_size (int, opcional, padrão 0) — Quantos elementos de um tensor compartilham o mesmo grupo de quantização. 0 seleciona automaticamente com base em weights_dtype, -1 desativa o agrupamento e usa quantização por linha.
  • use_svd (bool, opcional, padrão False) — Se deve aplicar o algoritmo SVDQuant por cima da quantização SDNQ.
  • use_quantized_matmul (bool, opcional, padrão False) — Se deve usar matmul quantizado INT8 / FP8 / FP16 na forward pass em vez de BF16 / FP16.
  • modules_to_not_convert (list, opcional, padrão None) — A lista de módulos a serem ignorados durante a quantização.
  • kwargs (dict[str, Any], opcional) — Argumentos de palavra-chave adicionais encaminhados para sdnq.SDNQConfig (por exemplo, quantized_matmul_dtype, svd_rank, use_hadamard, quant_conv, quant_embedding, modules_dtype_dict).

Classe de configuração para SDNQ (SD.Next Quantization).

A biblioteca sdnq inclui seu próprio config e quantizer compatíveis com diffusers; esta classe é uma fábrica fina que delega a eles para que checkpoints com quant_method="sdnq" sejam carregados nativamente com diffusers. Todos os argumentos são encaminhados para sdnq.SDNQConfig. Requer a biblioteca sdnq: pip install sdnq.

Referência: https://github.com/Disty0/sdnq

TorchAoConfig

classe diffusers.TorchAoConfig

< >

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

Parâmetros

  • quant_type (AOBaseConfig) — Uma instância de uma subclasse de AOBaseConfig que especifica o tipo de quantização. Consulte a documentação do torchao para as classes de configuração disponíveis (por exemplo, Int4WeightOnlyConfig, Int8WeightOnlyConfig, Float8WeightOnlyConfig, Float8DynamicActivationFloat8WeightConfig, etc.).
  • modules_to_not_convert (list[str], opcional, padrão None) — A lista de módulos que não devem ser quantizados, útil para quantizar modelos que exigem explicitamente que alguns módulos permaneçam em sua precisão original.

Esta é uma classe de configuração para técnicas de quantização/esparcidade do torchao.

Exemplo:

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 )

Crie uma configuração a partir de um dicionário.

get_apply_tensor_subclass

< >

( )

Crie o método de quantização apropriado com base na configuração.

to_dict

< >

( )

Converte a configuração em um dicionário.

DiffusersQuantizer

classe diffusers.DiffusersQuantizer

< >

( quantization_config: QuantizationConfigMixin**kwargs )

Classe abstrata do quantizador do HuggingFace. Suporta, por enquanto, a quantização de modelos do HF diffusers para inferência e/ou quantização. Esta classe é usada apenas para diffusers.models.modeling_utils.ModelMixin.from_pretrained e ainda não pode ser facilmente usada fora do escopo desse método.

Atributos quantization_config (diffusers.quantizers.quantization_config.QuantizationConfigMixin): A configuração de quantização que define os parâmetros de quantização do seu modelo que você deseja quantizar. modules_to_not_convert (list[str], opcional): A lista de nomes de módulos que não devem ser convertidos ao quantizar o modelo. required_packages (list[str], opcional): A lista de pacotes pip necessários para instalar antes de usar o quantizador requires_calibration (bool): Se o método de quantização requer calibrar o modelo antes de usá-lo.

adjust_max_memory

< >

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

ajuste o argumento max_memory para infer_auto_device_map() se for necessária memória extra para quantização

adjust_target_dtype

< >

( torch_dtype: torch.dtype )

Parâmetros

  • torch_dtype (torch.dtype, opcional) — O torch_dtype usado para calcular o device_map.

Substitua este método se você quiser ajustar a variável target_dtype usada em from_pretrained para calcular o device_map, caso o device_map seja um str. Por exemplo, para bitsandbytes, definimos target_dtype como torch.int8 e, para 4 bits, passamos um enum personalizado accelerate.CustomDtype.int4.

check_if_quantized_param

< >

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

verifica se um componente de state_dict carregado faz parte de um parâmetro quantizado + algumas validações; definido apenas para métodos de quantização que exigem a criação de novos parâmetros para quantização.

check_quantized_param_shape

< >

( *args**kwargs )

verifica se o parâmetro quantizado tem a forma esperada.

create_quantized_param

< >

( *args**kwargs )

obtem os componentes necessários de state_dict e cria o parâmetro quantizado.

dequantize

< >

( model )

Potencialmente desquantize o modelo para recuperar o modelo original, com alguma perda de precisão / desempenho. Observe que nem todos os esquemas de quantização suportam isso.

get_cuda_warm_up_factor

< >

( )

O fator a ser usado em caching_allocator_warmup para obter o número de bytes a serem pré-alocados para aquecer a cuda. Um fator de 2 significa que alocamos todos os bytes no modelo vazio (já que alocamos em fp16), um fator de 4 significa que alocamos metade da memória dos pesos residentes no modelo vazio, etc…

get_special_dtypes_update

< >

( modeltorch_dtype: torch.dtype )

Parâmetros

  • model (~diffusers.models.modeling_utils.ModelMixin) — O modelo a ser quantizado
  • torch_dtype (torch.dtype) — O dtype passado no método from_pretrained.

retorna os dtypes para módulos que não são quantizados - usado para o cálculo do device_map caso se passe um str como device_map. O método usará o modules_to_not_convert que é modificado em _process_model_before_weight_loading. Os modelos do diffusers ainda não possuem nenhum atributo modules_to_not_convert, mas isso pode mudar em breve no futuro.

postprocess_model

< >

( model: ModelMixin**kwargs )

Parâmetros

  • model (~diffusers.models.modeling_utils.ModelMixin) — O modelo a ser quantizado
  • kwargs (dict, opcional) — Os argumentos de palavra-chave que são passados ao _process_model_after_weight_loading.

Faça o pós-processamento do modelo após o carregamento dos pesos. Certifique-se de sobrescrever o método abstrato _process_model_after_weight_loading.

preprocess_model

< >

( model: ModelMixin**kwargs )

Parâmetros

  • model (~diffusers.models.modeling_utils.ModelMixin) — O modelo a ser quantizado
  • kwargs (dict, opcional) — Os argumentos de palavra-chave que são passados ao _process_model_before_weight_loading.

Definindo atributos do modelo e/ou convertendo o modelo antes do carregamento dos pesos. Neste ponto, o modelo deve estar inicializado no dispositivo meta, para que você possa manipular livremente o esqueleto do modelo a fim de substituir módulos in-place. Certifique-se de sobrescrever o método abstrato _process_model_before_weight_loading.

update_device_map

< >

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

Parâmetros

  • device_map (dict | str, opcional) — O device_map que é passado pelo método from_pretrained.

Sobrescreva este método se você deseja substituir o device map existente por um novo. Por exemplo, para bitsandbytes, como accelerate é um requisito obrigatório, se nenhum device_map for passado, o device_map será definido como `“auto”“

update_missing_keys

< >

( modelmissing_keys: list[str]prefix: str )

Parâmetros

  • missing_keys (list[str], opcional) — A lista de chaves ausentes no checkpoint em comparação com o state dict do modelo

Substitua este método se você quiser ajustar o missing_keys.

update_torch_dtype

< >

( torch_dtype: torch.dtype )

Parâmetros

  • torch_dtype (torch.dtype) — O dtype de entrada que é passado em from_pretrained

Alguns métodos de quantização exigem que o dtype do modelo seja definido explicitamente para um dtype de destino. Você precisa sobrescrever este método caso queira garantir que esse comportamento seja preservado

validate_environment

< >

( *args**kwargs )

Este método é usado para verificar possíveis conflitos com os argumentos passados em from_pretrained. Você precisa defini-lo para todos os quantizadores futuros que forem integrados ao diffusers. Se nenhuma verificação explícita for necessária, basta não retornar nada.

Update on GitHub

←Saídas Inferência remota→