diffusers/main/ja/api/quantization.md

量子化

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

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

PipelineQuantizationConfig[[diffusers.PipelineQuantizationConfig]]

diffusers.PipelineQuantizationConfig[[diffusers.PipelineQuantizationConfig]]

diffusers.PipelineQuantizationConfig(quant_backend: str = None, quant_kwargs: dict[str, str | float | int | dict] = None, components_to_quantize: list[str] | str | None = None, quant_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[[diffusers.BFLQuantizationConfig]]

diffusers.BFLQuantizationConfig[[diffusers.BFLQuantizationConfig]]

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[[diffusers.BitsAndBytesConfig]]

diffusers.BitsAndBytesConfig[[diffusers.BitsAndBytesConfig]]

diffusers.BitsAndBytesConfig(load_in_8bit = False, load_in_4bit = False, llm_int8_threshold = 6.0, llm_int8_skip_modules = None, llm_int8_enable_fp32_cpu_offload = False, llm_int8_has_fp16_weight = False, bnb_4bit_compute_dtype = None, bnb_4bit_quant_type = 'fp4', bnb_4bit_use_double_quant = False, bnb_4bit_quant_storage = None, **kwargs)

ソース

パラメータ:

load_in_8bit (bool、任意、デフォルトはFalse) : このフラグは、LLM.int8() による 8 ビット量子化を有効にするために使用されます。

load_in_4bit (bool、任意、デフォルトはFalse) : このフラグは、bitsandbytesのFP4/NF4レイヤーでLinearレイヤーを置き換えることで、4ビット量子化を有効にするために使用されます。

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-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[[diffusers.BitsAndBytesConfig.is_quantizable]]

is_quantizable()

ソース

モデルが量子化可能であればTrueを、そうでなければFalseを返します。

post_init[[diffusers.BitsAndBytesConfig.post_init]]

post_init()

ソース

引数が正しいことを確認するセーフティチェッカー。一部のNoneType引数をデフォルト値に置き換えることも行います。

quantization_method[[diffusers.BitsAndBytesConfig.quantization_method]]

quantization_method()

ソース

このメソッドは、モデルに使用された量子化手法を返します。モデルが量子化できない場合、Noneを返します。

to_diff_dict[[diffusers.BitsAndBytesConfig.to_diff_dict]]

to_diff_dict()

ソース

戻り値: dict[str, Any]

この設定インスタンスを構成するすべての属性の辞書、

デフォルトの config 属性に対応するすべての属性を config から削除し、可読性を向上させます。その後、Python の辞書にシリアライズします。

GGUFQuantizationConfig[[diffusers.GGUFQuantizationConfig]]

diffusers.GGUFQuantizationConfig[[diffusers.GGUFQuantizationConfig]]

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

ソース

パラメータ:

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

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

NunchakuLiteQuantizationConfig[[diffusers.NunchakuLiteQuantizationConfig]]

diffusers.NunchakuLiteQuantizationConfig[[diffusers.NunchakuLiteQuantizationConfig]]

diffusers.NunchakuLiteQuantizationConfig(compute_dtype: 'torch.dtype' | str | None = None, svdq_w4a4: dict[str, Any] | None = None, awq_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 モデルのアーキテクチャと完全に一致する必要があります。融合された 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]]

diffusers.QuantoConfig[[diffusers.QuantoConfig]]

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

ソース

パラメータ:

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

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

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

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

post_init[[diffusers.QuantoConfig.post_init]]

post_init()

ソース

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

SDNQConfig[[diffusers.SDNQConfig]]

diffusers.SDNQConfig[[diffusers.SDNQConfig]]

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[[diffusers.TorchAoConfig]]

diffusers.TorchAoConfig[[diffusers.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]、optional、デフォルトは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[[diffusers.TorchAoConfig.from_dict]]

from_dict(config_dict, return_unused_kwargs = False, **kwargs)

ソース

辞書から設定を作成します。

get_apply_tensor_subclass[[diffusers.TorchAoConfig.get_apply_tensor_subclass]]

get_apply_tensor_subclass()

ソース

設定に基づいて適切な量子化手法を作成します。

to_dict[[diffusers.TorchAoConfig.to_dict]]

to_dict()

ソース

設定を辞書に変換します。

DiffusersQuantizer[[diffusers.DiffusersQuantizer]]

diffusers.DiffusersQuantizer[[diffusers.DiffusersQuantizer]]

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[[diffusers.DiffusersQuantizer.adjust_max_memory]]

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

ソース

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

adjust_target_dtype[[diffusers.DiffusersQuantizer.adjust_target_dtype]]

adjust_target_dtype(torch_dtype: torch.dtype)

ソース

パラメータ:

torch_dtype (torch.dtype、任意) : device_map を計算するために使用される torch_dtype。

str 型の device_map を指定して device_map を計算する際に、from_pretrained で使用される target_dtype 変数を調整したい場合は、このメソッドをオーバーライドしてください。例えば、bitsandbytes の場合は target_dtype を torch.int8 に強制設定し、4-bit の場合はカスタム列挙型 accelerate.CustomDtype.int4 を渡します。

check_if_quantized_param[[diffusers.DiffusersQuantizer.check_if_quantized_param]]

check_if_quantized_param(model: ModelMixin, param_value: torch.Tensor, param_name: str, state_dict: dict[str, typing.Any], **kwargs)

ソース

読み込まれた state_dict のコンポーネントが量子化パラメータの一部であるかどうかを確認し、いくつかの検証を行います。量子化のために新しいパラメータの作成が必要な量子化手法でのみ定義されます。

check_quantized_param_shape[[diffusers.DiffusersQuantizer.check_quantized_param_shape]]

check_quantized_param_shape(*args, **kwargs)

ソース

量子化されたパラメータが期待される形状を持っているかどうかを確認します。

create_quantized_param[[diffusers.DiffusersQuantizer.create_quantized_param]]

create_quantized_param(*args, **kwargs)

ソース

state_dictから必要なコンポーネントを取得し、量子化されたパラメータを作成します。

dequantize[[diffusers.DiffusersQuantizer.dequantize]]

dequantize(model)

ソース

モデルをデクアンタイズして元のモデルを復元できますが、精度やパフォーマンスが多少低下する可能性があります。なお、すべてのクアンタイズ方式がこの操作をサポートしているわけではありません。

get_cuda_warm_up_factor[[diffusers.DiffusersQuantizer.get_cuda_warm_up_factor]]

get_cuda_warm_up_factor()

ソース

caching_allocator_warmup で CUDA のウォームアップ用に事前割り当てるバイト数を取得するために使用する係数です。係数が 2 の場合、空のモデル内のすべてのバイトを割り当てます（fp16 で割り当てるため）、係数が 4 の場合、空のモデルに存在する重みのメモリを半分割り当てます、などです。

get_special_dtypes_update[[diffusers.DiffusersQuantizer.get_special_dtypes_update]]

get_special_dtypes_update(model, torch_dtype: torch.dtype)

ソース

パラメータ:

model (~diffusers.models.modeling_utils.ModelMixin) : 量子化対象のモデル

torch_dtype (torch.dtype) : from_pretrained メソッドに渡された dtype。

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[[diffusers.DiffusersQuantizer.postprocess_model]]

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[[diffusers.DiffusersQuantizer.preprocess_model]]

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[[diffusers.DiffusersQuantizer.update_device_map]]

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

ソース

パラメータ:

device_map (dict | str、任意) : from_pretrained メソッドに渡される device_map です。

既存の device map を新しいものの上書きで渡す場合は、このメソッドをオーバーライドしてください。例えば、accelerate は必須要件であるため、bitsandbytes の場合、device_map が渡されない場合は、device_map は "auto" に設定されます。

update_missing_keys[[diffusers.DiffusersQuantizer.update_missing_keys]]

update_missing_keys(model, missing_keys: list[str], prefix: str)

ソース

パラメータ:

missing_keys (list[str], 任意) : モデルの state dict と比較した際の、チェックポイントに欠落しているキーのリスト

missing_keys を調整したい場合は、このメソッドをオーバーライドしてください。

update_torch_dtype[[diffusers.DiffusersQuantizer.update_torch_dtype]]

update_torch_dtype(torch_dtype: torch.dtype)

ソース

パラメータ:

torch_dtype (torch.dtype) : from_pretrained に渡される入力 dtype

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

validate_environment[[diffusers.DiffusersQuantizer.validate_environment]]

validate_environment(*args, **kwargs)

ソース

このメソッドは、from_pretrainedに渡される引数との潜在的な競合を、必要に応じてチェックするために使用されます。diffusersに統合される将来のすべてのクオンタイザーに対して、このメソッドを定義する必要があります。明示的なチェックが不要な場合は、何も返さないようにしてください。