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.42.1).
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()에 온더플라이(On-the-fly) 양자화를 적용할 때 사용할 구성 클래스입니다.

BFLQuantizationConfig

class diffusers.BFLQuantizationConfig

< >

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

매개변수

  • compute_dtype (torch.dtype, 기본값 torch.bfloat16) — 활성화 값과 양자화되지 않은 레이어의 dtype입니다. fused FP8 또는 NVFP4 커널을 지원하지 않는 디바이스는 모든 forward pass에서 가중치를 이 dtype으로 dequantize합니다.

Black Forest Labs의 fp8r 및 nvfp4 스킴으로 양자화된 체크포인트를 로드하기 위한 설정입니다.

두 방식 모두 ~FromSingleFileMixin.from_single_file를 통해 체크포인트에서 읽습니다. 모델의 온플라이 양자화는 지원되지 않습니다. 가중치가 스케일 텐서를 함께 포함하는 경우 선형 레이어가 양자화됩니다:

  • fp8r: weight은 shape가 [N, K]인 float8_e4m3fn이고, weight_scale은 행별 fp32 스케일 [N]입니다.
  • nvfp4: weight는 uint8이며 shape가 [N, K/2]입니다(바이트당 E2M1 값 2개), 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-bit 양자화를 활성화하는 데 사용됩니다.
  • load_in_4bit (bool, 선택 사항, 기본값 False) — 이 플래그는 bitsandbytes의 FP4/NF4 레이어로 Linear 레이어를 교체하여 4-bit 양자화를 활성화하는 데 사용됩니다.
  • 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이지만, 불안정한 모델(작은 모델, fine-tuning)의 경우 더 낮은 임계값이 필요할 수 있습니다.
  • 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비트 메인 가중치와 함께 실행합니다. 가중치를 역전파를 위해 왕복 변환할 필요가 없으므로 미세 조정(fine-tuning)에 유용합니다.
  • 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 projections으로 양자화된 체크포인트는 개별 Q, K, V projection 모듈을 기대하는 모델 구성에 로드되지 않습니다.

컴팩트한 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입니다. 지원되는 값은 (“float8”,“int8”,“int4”,“int2”)입니다.

quanto를 사용하여 로드한 모델에서 사용할 수 있는 모든 가능한 속성과 기능에 대한 래퍼 클래스입니다.

QuantoConfig은 비추천(deprecated)되며 1.0.0 버전에서 제거됩니다. BitsAndBytesConfig 또는 TorchAoConfig와 같은 다른 지원되는 양자화 백엔드로 전환하는 것을 고려해 보세요.

modules_to_not_convert (list, 선택 사항, 기본값 None): 양자화하지 않을 모듈 목록입니다. 일부 모듈을 원래 정밀도로 유지해야 하는 모델(예: Whisper encoder, Llava encoder, Mixtral gate layers)을 양자화할 때 유용합니다.

post_init

< >

( )

인수가 올바른지 확인하는 안전 검사기

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 대신 forward pass에서 양자화된 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를 제공합니다. 이 클래스는 얇은 팩토리(thin factory)로, 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 하위 클래스 인스턴스입니다. 사용 가능한 설정 클래스(예: Int4WeightOnlyConfig, Int8WeightOnlyConfig, Float8WeightOnlyConfig, Float8DynamicActivationFloat8WeightConfig 등)에 대해서는 torchao 문서를 참조하세요.
  • modules_to_not_convert (list[str], 선택 사항, 기본값 None) — 양자화하지 않을 모듈 목록입니다. 일부 모듈은 원래의 정밀도를 유지해야 하는 모델의 양자화에 유용합니다.

이것은 torchao 양자화/희소화 기법을 위한 config 클래스입니다.

예:

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

< >

( )

configuration에 따라 적절한 양자화 방법을 생성합니다.

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 )

양자화에 추가 메모리가 필요한 경우 infer_auto_device_map()의 max_memory 인수를 조정합니다

adjust_target_dtype

< >

( torch_dtype: torch.dtype )

매개변수

  • torch_dtype (torch.dtype, 선택 사항) — device_map을 계산하는 데 사용되는 torch_dtype입니다.

from_pretrained에서 str인 경우 device_map을 계산하는 데 사용되는 target_dtype 변수를 조정하려면 이 메서드를 오버라이드하세요. 예를 들어 bitsandbytes의 경우 target_dtype을 torch.int8으로 강제 설정하고, 4-bit의 경우 커스텀 enum인 accelerate.CustomDtype.int4를 전달합니다.

check_if_quantized_param

< >

( model: ModelMixinparam_value: torch.Tensorparam_name: strstate_dict: dict**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입니다.

양자화되지 않은 모듈의 dtypes를 반환합니다 - 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 device에 초기화되어 있어야 하므로, 모듈을 제자리에서 교체하기 위해 모델의 골격을 자유롭게 조작할 수 있습니다. 추상 메서드 _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가 필수 요구 사항인 bitsandbytes의 경우, device_map이 전달되지 않으면 device_map이 `“auto”“`로 설정됩니다.

update_missing_keys

< >

( modelmissing_keys: listprefix: 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에 통합되는 모든 향후 quantizer에 대해 이 메서드를 정의해야 합니다. 명시적인 확인이 필요하지 않은 경우, 아무것도 반환하지 않으면 됩니다.

Update on GitHub

←출력 원격 추론→