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

BFLQuantizationConfig[[diffusers.BFLQuantizationConfig]]

diffusers.BFLQuantizationConfig[[diffusers.BFLQuantizationConfig]]

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[[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-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[[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 속성에 해당하는 모든 속성을 제거하여 가독성을 높이고, 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 모델 아키텍처와 정확히 일치해야 합니다. 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[[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은 비추천(deprecated)되며 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 대신 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.

Reference: 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 하위 클래스 인스턴스입니다. 사용 가능한 설정 클래스(예: 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[[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()

소스

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

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): 양자화 방법이 사용 전에 모델을 보정(calibrate)해야 하는지 여부입니다.

adjust_max_memory[[diffusers.DiffusersQuantizer.adjust_max_memory]]

adjust_max_memory(max_memory: dict)

소스

양자화에 추가 메모리가 필요한 경우 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입니다.

from_pretrained에서 str인 경우 device_map을 계산하는 데 사용되는 target_dtype 변수를 조정하려면 이 메서드를 오버라이드하세요. 예를 들어 bitsandbytes의 경우 target_dtype을 torch.int8으로 강제 설정하고, 4-bit의 경우 커스텀 enum인 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, **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.

양자화되지 않은 모듈의 dtypes를 반환합니다 - device_map에 str을 전달하는 경우 device_map 계산에 사용됩니다. 이 메서드는 _process_model_before_weight_loading에서 수정되는 modules_to_not_convert를 사용합니다. diffusers 모델에는 아직 modules_to_not_convert 속성이 없지만, 가까운 미래에 변경될 수 있습니다.

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 device에 초기화되어 있어야 하므로, 모듈을 제자리에서 교체하기 위해 모델의 골격을 자유롭게 조작할 수 있습니다. 추상 메서드 _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, 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에 통합되는 모든 향후 quantizer에 대해 이 메서드를 정의해야 합니다. 명시적인 확인이 필요하지 않은 경우 아무것도 반환하지 않으면 됩니다.