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

量子化

量子化技術は、8ビット整数（int8）などの低精度データ型で重みと活性化を表現することで、メモリおよび計算コストを削減します。これにより、通常ではメモリに収まらない大きなモデルの読み込みが可能になり、推論の高速化も実現できます。

Quantizationガイドで、モデルの量子化方法について学びましょう。

PipelineQuantizationConfig

class 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) — 使用する量子化バックエンド。このオプションを使用する場合、diffusers と transformers の両方でバックエンドが利用可能であると仮定します。
  • quant_kwargs (dict) — 量子化バックエンドクラスを初期化するための引数。
  • components_to_quantize (list) — 量子化対象のパイプラインのコンポーネント。
  • quant_mapping (dict) — パイプラインのコンポーネントに使用される量子化仕様を定義するマッピング。この引数を使用する場合、ユーザーはquant_backend、quant_kawargs、およびcomponents_to_quantizeを指定する必要はありません。

from_pretrained()にオンザフライで量子化を適用する際に使用する設定クラス。

BFLQuantizationConfig

class diffusers.BFLQuantizationConfig

< >

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

パラメータ

  • compute_dtype (torch.dtype、デフォルトは torch.bfloat16) — アクティベーションおよび非量子化レイヤーの dtype です。フュージョンされた FP8 または NVFP4 カーネルを備えていないデバイスでは、この dtype に重みをデクォアンタイズして、すべてのフォワードパスで処理します。

Black Forest Labsのfp8rおよびnvfp4スキームで量子化されたチェックポイントを読み込むための設定です。

どちらのスキームも、~FromSingleFileMixin.from_single_file を通じてチェックポイントから読み込まれます。モデルのオンザフライ量子化はサポートされていません。重みにスケールテンソルが伴う場合、線形層は量子化されます。

  • fp8r: weight は float8_e4m3fn 型で、形状は [N, K] です。weight_scale は行ごとの fp32 スケールで、形状は [N] です。
  • nvfp4: weight は uint8 型で、形状は [N, K/2]（1バイトあたり2つのE2M1値）、weight_scale は float8_e4m3fn 型のブロックスケール [N, K/16]、weight_scale_2 と input_scale は、グローバルな重みスケールとキャリブレーション済みの活性化スケールを保持するfp32のスカラーです（ModelOpt NVFP4レイアウト）。

BitsAndBytesConfig

class 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) — このフラグは、LLM.int8() による 8 ビット量子化を有効にするために使用されます。
  • load_in_4bit (bool、任意、デフォルトはFalse) — このフラグは、Linear層をbitsandbytesのFP4/NF4層に置き換えることで、4ビット量子化を有効にするために使用されます。
  • llm_int8_threshold (float、任意、デフォルト値は 6.0) — LLM.int8() : 8-bit Matrix Multiplication for Transformers at Scale 論文で説明されている、アウター検出のためのアウター閾値に対応します: https://huggingface.co/papers/2208.07339 この閾値を超える hidden states の値はアウターとみなされ、それらの値に対する演算は fp16 で行われます。値は通常、正規分布に従っており、ほとんどの値は [-3.5, 3.5] の範囲内に収まりますが、大規模モデルでは分布が大きく異なる、例外として系統的なアウターが存在します。これらのアウターは、しばしば [-60, -6] または [6, 60] の区間にあります。Int8 量子化は、大きさ ~5 の値に対してはよく機能しますが、それを超えると、顕著な性能の低下が生じます。適切なデフォルトの閾値は 6 ですが、より不安定なモデル（小規模モデル、ファインチューニング）では、より低い閾値が必要になる場合があります。
  • llm_int8_skip_modules (list[str]、任意) — 8-bit に変換したくないモジュールの明示的なリストです。これは、Jukebox のように複数のヘッドが異なる位置に存在し、必ずしも最後の位置にあるとは限らないモデルに有用です。例えば、CausalLM モデルでは、最後の lm_head は通常、元の dtype のまま保持されます。
  • llm_int8_enable_fp32_cpu_offload (bool、任意、デフォルトはFalse) — このフラグは、高度なユースケースや、この機能について理解しているユーザー向けに使用されます。モデルを異なる部分に分割し、一部の部分を GPU 上で int8 として、別の部分を CPU 上で fp32 として実行したい場合に、このフラグを使用できます。これは、google/flan-t5-xxlのような大規模モデルのオフロードに有用です。なお、int8 演算は CPU 上では実行されません。
  • llm_int8_has_fp16_weight (bool、任意、デフォルトはFalse) — このフラグを指定すると、LLM.int8() が 16 ビットのメインウェイトで実行されます。バックワードパスのためにウェイトを往復変換する必要がないため、ファインチューニングに有用です。
  • 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]、省略可) — 設定オブジェクトの初期化に使用する追加のパラメータ。

これは、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 属性に対応するすべての属性を config から削除し、可読性を向上させます。その後、Python の辞書にシリアライズします。

GGUFQuantizationConfig

class diffusers.GGUFQuantizationConfig

< >

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

パラメータ

  • compute_dtype — (torch.dtype、デフォルトはtorch.float32): 入力タイプとは異なる計算タイプを設定します。例えば、入力がfp32であっても、高速化のために計算をbf16に設定できます。

これは、GGUF量子化手法用の設定クラスです。

NunchakuLiteQuantizationConfig

class 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, 任意) — precision、group_size、rank、targets を指定した、明示的な SVDQ W4A4 ターゲット設定。
  • awq_w4a16 (dict, 任意) — precision、group_size、targets を持つ、明示的な AWQ W4A16 ターゲット設定。

Nunchaku Liteのチェックポイントを読み込むための設定。

Diffusers における Nunchaku Lite のサポートでは、事前量子化されたチェックポイントを読み込みます。互換性のあるチェックポイントを作成するには、diffuse-compressor を使用して、モデルアーキテクチャに合わせたターゲット設定を選択または調整し、transformer を量子化してエクスポートし、config.json にコンパクトな quantization_config を保存した Diffusers パイプラインとしてパッケージングします。

エクスポートされた state dict は、対象の Diffusers モデルのアーキテクチャと完全に一致する必要があります。fused 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

class diffusers.QuantoConfig

< >

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

パラメータ

  • weights_dtype (str、任意、デフォルトは"int8") — 量子化後の重みのターゲット dtype です。サポートされる値は（"int8"、"float8"、"int4"、"int2"）です。

これは、quantoを使用して読み込まれたモデルで操作可能なすべての属性や機能に関するラッパークラスです。

QuantoConfig は非推奨となり、バージョン 1.0.0 で削除されます。BitsAndBytesConfig や TorchAoConfig など、他のサポートされている量子化バックエンドへの切り替えをご検討ください。

modules_to_not_convert (list, 任意、デフォルトは None): 量子化しないモジュールのリストです。一部のモジュールを元の精度のまま残すことが明示的に求められるモデル（例: Whisper エンコーダー、Llava エンコーダー、Mixtral のゲート層）を量子化する際に有用です。

post_init

< >

( )

引数が正しいことを確認するセーフティチェッカー

SDNQConfig

class diffusers.SDNQConfig

< >

( *args**kwargs )

パラメータ

  • weights_dtype (str、任意、デフォルトは "int8") — 量子化後の重みのターゲット dtype。例: "int8"、"uint4"、"float8_e4m3fn"。サポートされているすべての値については、sdnq.common.accepted_weight_dtypes を参照してください。
  • group_size (int、任意、デフォルトは 0) — テンソルのどの程度の要素数が同じ量子化グループを共有するかを示します。0 を指定すると weights_dtype に基づいて自動的に選択され、-1 を指定するとグループ化が無効になり、行ごとの量子化が使用されます。
  • use_svd (bool、任意、デフォルトはFalse) — SDNQ量子化の上にSVDQuantアルゴリズムを適用するかどうかを指定します。
  • use_quantized_matmul (bool、任意、デフォルトは False) — BF16 / FP16 の代わりに、フォワードパスで量子化された INT8 / FP8 / FP16 の matmul を使用するかどうか。
  • 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 互換の config と quantizer を同梱しています。このクラスは薄いファクトリであり、それらを委譲することで、quant_method="sdnq" のチェックポイントを diffusers でネイティブにロードできるようにします。すべての引数は sdnq.SDNQConfig に転送されます。sdnq ライブラリが必要です: pip install sdnq。

参考: https://github.com/Disty0/sdnq

TorchAoConfig

class diffusers.TorchAoConfig

< >

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

パラメータ

  • quant_type (AOBaseConfig) — 量子化タイプを指定するAOBaseConfigのサブクラスインスタンスです。利用可能な設定クラス（例: Int4WeightOnlyConfig、Int8WeightOnlyConfig、Float8WeightOnlyConfig、Float8DynamicActivationFloat8WeightConfig など）については、torchaoのドキュメントを参照してください。
  • 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

class diffusers.DiffusersQuantizer

< >

( quantization_config: QuantizationConfigMixin**kwargs )

HuggingFace の量子化器の抽象クラスです。現時点では、推論および/または量子化のための HF diffusers モデルの量子化をサポートしています。このクラスは diffusers.models.modeling_utils.ModelMixin.from_pretrained のみで使用され、現時点ではそのメソッドのスコープ外で簡単に使用することはできません。

Attributes 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] )

量子化に追加のメモリが必要な場合は、infer_auto_device_map() の max_memory 引数を調整してください

adjust_target_dtype

< >

( torch_dtype: torch.dtype )

パラメータ

  • torch_dtype (torch.dtype, optional) — The torch_dtype that is used to compute the device_map.

from_pretrained で device_map を計算するために使用される target_dtype 変数を調整したい場合は、このメソッドをオーバーライドします。device_map が str の場合です。例えば、bitsandbytes では target_dtype を torch.int8 に強制設定し、4-bit の場合はカスタム列挙型 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) — from_pretrained メソッドに渡された dtype です。

量子化されていないモジュールの dtype を返します - device_map に str を渡した場合の device_map の計算に使用されます。このメソッドは、_process_model_before_weight_loading で変更される modules_to_not_convert を使用します。diffusers モデルにはまだ modules_to_not_convert 属性がありませんが、近いうちに状況が変わる可能性があります。

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 メソッドに渡される device_map です。

既存の device map を新しいものに上書きして渡す場合は、このメソッドをオーバーライドしてください。例えば、accelerate は必須要件であるため、device_map が渡されない場合、bitsandbytes では device_map が `“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

一部の量子化手法では、モデルのdtypeをターゲットのdtypeに明示的に設定する必要があります。その動作を維持したい場合は、このメソッドをオーバーライドする必要があります。

validate_environment

< >

( *args**kwargs )

このメソッドは、from_pretrainedに渡される引数との潜在的な競合を、必要に応じてチェックするために使用されます。diffusersに統合される将来のすべての量子化器に対して、これを定義する必要があります。明示的なチェックが不要な場合は、何も返さないだけで構いません。

Update on GitHub

←出力 リモート推論→