Transformers documentation
양자화
양자화
양자화 기법은 8비트 정수(int8)와 같은 저정밀도 데이터 타입으로 가중치와 활성화를 표현하여 메모리 및 계산 비용을 줄입니다. 이를 통해 일반적으로 메모리에 적재할 수 없었던 더 큰 모델을 로드하고 추론 속도를 높일 수 있습니다. Transformers는 AWQ와 GPTQ 양자화 알고리즘을 지원하며, bitsandbytes를 통해 8비트 및 4비트 양자화를 지원합니다.
Transformers에서 지원되지 않는 양자화 기법은 HfQuantizer 클래스를 통해 추가할 수 있습니다.
Quantization 가이드에서 모델을 양자화하는 방법을 배워보세요.
QuantoConfig
class transformers.QuantoConfig
< source >( weights = 'int8'activations = Nonemodules_to_not_convert: list | None = None**kwargs )
매개변수
- weights (
str, 선택 사항, 기본값"int8") — 양자화 후 가중치의 대상 dtype입니다. 지원되는 값은 (“float8”,“int8”,“int4”,“int2”)입니다. - activations (
str, 선택 사항) — 양자화 후 activations의 대상 dtype입니다. 지원되는 값은 (None,“int8”,“float8”)입니다. - modules_to_not_convert (
list, 선택 사항, 기본값None) — 양자화하지 않을 모듈 목록입니다. 일부 모듈을 원래 정밀도로 유지해야 하는 모델(예: Whisper encoder, Llava encoder, Mixtral gate layers)을 양자화할 때 유용합니다.
quanto를 사용하여 로드한 모델에서 사용할 수 있는 모든 가능한 속성과 기능에 대한 래퍼 클래스입니다.
인수가 올바른지 확인하는 안전 검사기
AqlmConfig
클래스 transformers.AqlmConfig
< source >( in_group_size: int = 8out_group_size: int = 1num_codebooks: int = 1nbits_per_codebook: int = 16linear_weights_not_to_quantize: list[str] | None = None**kwargs )
매개변수
- in_group_size (
int, 선택 사항, 기본값 8) — 입력 차원 방향의 그룹 크기입니다. - out_group_size (
int, 선택 사항, 기본값 1) — 출력 차원 방향의 그룹 크기입니다. 항상 1을 사용하는 것이 권장됩니다. - num_codebooks (
int, 선택 사항, 기본값 1) — Additive Quantization 절차에 사용할 코드북의 개수입니다. - nbits_per_codebook (
int, 선택 사항, 기본값 16) — 단일 codebook 벡터를 인코딩하는 비트 수입니다. Codebook의 크기는 2**nbits_per_codebook입니다. - linear_weights_not_to_quantize (
Optional[list[str]], 선택 사항) — 양자화하지 않을nn.Linear가중치 매개변수의 전체 경로 목록입니다. - kwargs (
dict[str, Any], 선택) — 설정 객체를 초기화할 때 사용할 추가 매개변수.
aqlm 매개변수에 대한 래퍼 클래스입니다.
인수가 올바른지 확인하는 안전 검사기입니다. 또한 일부 NoneType 인수를 기본값으로 대체합니다.
VptqConfig
클래스 transformers.VptqConfig
< source >( enable_proxy_error: bool = Falseconfig_for_layers: dict = {}shared_layer_config: dict = {}modules_to_not_convert: list | None = None**kwargs )
매개변수
- enable_proxy_error (
bool, 선택, 기본값False) — 각 레이어에 대한 프록시 오류를 계산합니다 - config_for_layers (
Dict, 선택 사항, 기본값{}) — 각 레이어에 대한 양자화 매개변수 - shared_layer_config (
Dict, 선택 사항, 기본값{}) — 레이어 간 공유되는 양자화 매개변수 - modules_to_not_convert (
list, 선택 사항, 기본값None) — 양자화하지 않을 모듈 목록입니다. 일부 모듈을 원래 정밀도로 유지해야 하는 모델(예: Whisper encoder, Llava encoder, Mixtral gate layers)을 양자화할 때 유용합니다. - kwargs (
dict[str, Any], 선택) — 설정 객체를 초기화할 때 사용할 추가 매개변수.
vptq 매개변수에 대한 래퍼 클래스입니다.
인수가 올바른지 확인하는 안전 검사기
AwqConfig
클래스 transformers.AwqConfig
< source >( bits: int = 4group_size: int = 128zero_point: bool = Truebackend: AwqBackend = <AwqBackend.AUTO: 'auto'>modules_to_not_convert: list | None = None**kwargs )
매개변수
- bits (
int, 선택 사항, 기본값 4) — 양자화할 비트 수입니다. - group_size (
int, 선택 사항, 기본값 128) — 양자화에 사용할 그룹 크기입니다. 권장 값은 128이며, -1은 컬럼별 양자화를 사용합니다. - zero_point (
bool, 선택 사항, 기본값True) — zero point 양자화를 사용할지 여부. - backend (
AwqBackend, 선택 사항, 기본값AwqBackend.AUTO) — 양자화 백엔드입니다. - modules_to_not_convert (
list, 선택 사항, 기본값None) — 양자화하지 않을 모듈 목록입니다. 일부 모듈을 원래 정밀도로 유지해야 하는 모델(예: Whisper encoder, Llava encoder, Mixtral gate layers)을 양자화할 때 유용합니다. transformers를 통해 직접 양자화할 수 없으므로, HF 모델 양자화에 대해서는AutoAWQ문서를 참조하세요.
auto-awq 라이브러리의 awq 양자화를 auto_awq 백엔드에 의존하여 로드한 모델에서 사용할 수 있는 모든 가능한 속성과 기능에 대한 래퍼 클래스입니다.
EetqConfig
클래스 transformers.EetqConfig
< source >( weights: str = 'int8'modules_to_not_convert: list | None = None**kwargs )
eetq를 사용하여 로드한 모델에서 활용할 수 있는 모든 속성과 기능에 대한 래퍼 클래스입니다.
인수가 올바른지 확인하는 안전 검사기
GPTQConfig
클래스 transformers.GPTQConfig
< source >( bits: inttokenizer: Any = Nonedataset: list[str] | str | None = Nonegroup_size: int = 128damp_percent: float = 0.1desc_act: bool = Falseact_group_aware: bool = Truesym: bool = Truetrue_sequential: bool = Trueformat: str = 'gptq'meta: dict[str, typing.Any] | None = Nonebackend: str | None = Nonemodel_seqlen: int | None = Noneblock_name_to_quantize: str | None = Nonemodule_name_preceding_first_block: list[str] | None = Nonebatch_size: int = 1pad_token_id: int | None = Nonemax_input_length: int | None = Nonecache_block_outputs: bool = Truemodules_in_block_to_quantize: list[list[str]] | None = None**kwargs )
매개변수
- bits (
int) — 양자화할 비트 수입니다. 지원되는 값은 (2, 3, 4, 8)입니다. - tokenizer (
str또는PreTrainedTokenizerBase, 선택 사항) — 데이터셋을 처리하는 데 사용되는 토크나이저입니다. 다음 중 하나를 전달할 수 있습니다:- 사용자가 직접 정의한 토크나이저 객체입니다.
- huggingface.co의 모델 저장소에 호스팅된 사전 정의된 토크나이저의 model id를 나타내는 문자열
- 토크나이저에 필요한 어휘 파일을 포함하는 디렉터리의 경로입니다. 예를 들어 save_pretrained() 메서드를 사용하여 저장한 경우,
./my_model_directory/와 같습니다.
- dataset (
Union[list[str]], 선택) — 양자화에 사용되는 데이터셋입니다. 문자열 목록으로 직접 데이터셋을 제공하거나, GPTQ 논문에서 사용된 원래 데이터셋([‘wikitext2’,‘c4’,‘c4-new’])을 그대로 사용할 수 있습니다. - group_size (
int, 선택 사항, 기본값 128) — 양자화에 사용할 그룹 크기입니다. 권장 값은 128이며, -1은 컬럼별 양자화를 사용합니다. - damp_percent (
float, 선택 사항, 기본값 0.1) — 감쇠에 사용할 평균 Hessian 대각선의 비율입니다. 권장 값은 0.1입니다. - desc_act (
bool, 선택 사항, 기본값False) — 활성화 크기가 큰 순서대로 열을 양자화할지 여부입니다. False로 설정하면 추론 속도가 크게 빨라질 수 있지만, 퍼플렉시티가 약간 나빠질 수 있습니다. act-order로도 알려져 있습니다. - act_group_aware (
bool, 선택 사항, 기본값True) — 양자화 과정에서 GAR(group aware activation order)를 사용합니다. 양자화 품질에 측정 가능한 긍정적인 영향을 미칩니다.desc_act = False인 경우에만 적용됩니다.desc_act = True인 경우False로 강제 설정됩니다. - sym (
bool, 선택 사항, 기본값True) — 대칭 양자화를 사용할지 여부입니다. - true_sequential (
bool, 선택 사항, 기본값True) — 단일 Transformer 블록 내부에서도 순차적 양자화를 수행할지 여부입니다. 블록 전체를 한 번에 양자화하는 대신, 레이어별 양자화를 수행합니다. 그 결과 각 레이어는 이전에 양자화된 레이어들을 통과한 입력을 사용하여 양자화됩니다. - format (
str, 선택 사항, 기본값"gptq") — GPTQ 가중치 형식입니다.gptq(v1)은 gptqmodel에서 지원됩니다.gptq_v2는 gptqmodel에서만 사용할 수 있습니다. - meta (
dict[str, any], 선택) — 양자화나 양자 추론에 직접적으로 기여하지 않는 속성, 예를 들어 tooling:version 등은 meta에 저장됩니다. 즉,meta.quantizer: [“optimum:version”, “gptqmodel:version”] - backend (
str, 선택 사항) — 사용할 커널을 제어합니다. gptqmodel의 유효한 값은auto,auto_trainable등이 있습니다. gptqmodel 백엔드 참조: https://github.com/ModelCloud/GPTQModel/blob/main/gptqmodel/utils/backend.py - model_seqlen (
int, 선택) — 모델이 처리할 수 있는 최대 시퀀스 길이입니다. - block_name_to_quantize (
str, 선택 사항) — 양자화할 transformers 블록 이름입니다. None인 경우, 일반적인 패턴(예: model.layers)을 사용하여 블록 이름을 추론합니다. - module_name_preceding_first_block (
list[str], 선택 사항) — 첫 번째 Transformer 블록 앞에 있는 레이어입니다. - batch_size (
int, 선택 사항, 기본값 1) — 데이터셋을 처리할 때 사용하는 배치 크기 - pad_token_id (
int, 선택 사항) — 패딩 토큰 ID입니다.batch_size> 1인 경우 데이터셋을 준비하는 데 필요합니다. - max_input_length (
int, 선택 사항) — 최대 입력 길이입니다. 이는 최대 예상 입력 길이에 따라 달라지는 버퍼를 초기화하는 데 필요합니다. act-order를 사용하는 exllama 백엔드에 특화된 설정입니다. - cache_block_outputs (
bool, 선택 사항, 기본값True) — 블록 출력을 캐싱하여 후속 블록의 입력으로 재사용할지 여부입니다. - modules_in_block_to_quantize (
list[list[str]], 선택 사항) — 지정된 블록에서 양자화할 모듈 이름의 목록입니다. 이 인수는 특정 선형 모듈을 양자화 대상에서 제외하는 데 유용합니다. 양자화할 블록은block_name_to_quantize를 설정하여 지정할 수 있습니다. 각 목록을 순차적으로 양자화합니다. 설정하지 않으면 모든 선형 레이어를 양자화합니다. 예:modules_in_block_to_quantize =[["self_attn.k_proj", "self_attn.v_proj", "self_attn.q_proj"], ["self_attn.o_proj"]]. 이 예시에서는 q, k, v 레이어가 독립적이므로 먼저 동시에 양자화합니다. 그 다음, q, k, v 레이어가 양자화된 상태에서self_attn.o_proj레이어를 양자화합니다. 이렇게 하면 모델이 양자화되었을 때self_attn.o_proj가 실제로 받게 될 입력을 반영하므로 더 나은 결과를 얻을 수 있습니다.
optimum API를 사용하여 gptqmodel 백엔드에 기반한 GPTQ 양자화로 로드된 모델에서 활용할 수 있는 모든 속성과 기능에 대한 래퍼 클래스입니다.
optimum gptq config dict와 호환되는 클래스를 가져옵니다
인수가 올바른지 확인하는 안전 검사기
optimum gptq config에 호환되는 dict를 가져옵니다
BitsAndBytesConfig
class transformers.BitsAndBytesConfig
< source >( 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-bit 메인 가중치와 함께 실행합니다. 가중치를 역전파를 위해 왕복 변환할 필요가 없으므로 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를 사용하여 로드한 모델에서 활용할 수 있는 모든 속성과 기능을 감싸는 래퍼 클래스입니다.
현재 LLM.int8(), FP4, NF4 양자화만 지원합니다. bitsandbytes에 더 많은 방법이 추가되면, 이 클래스에도 더 많은 인자가 추가됩니다.
모델이 양자화 가능한 경우 True, 그렇지 않은 경우 False를 반환합니다.
인수가 올바른지 확인하는 안전 검사기입니다. 또한 일부 NoneType 인수를 기본값으로 대체합니다.
이 메서드는 모델에 사용된 양자화 방법을 반환합니다. 모델이 양자화할 수 없으면 None을 반환합니다.
더 나은 가독성을 위해 기본 config 속성에 해당하는 모든 속성을 config에서 제거하고 Python dictionary로 직렬화합니다.
HfQuantizer
클래스 transformers.quantizers.HfQuantizer
< source >( quantization_config: QuantizationConfigMixin**kwargs )
HuggingFace 양자화기의 추상 클래스입니다. 현재는 추론 및/또는 양자화를 위해 HF transformers 모델을 양자화하는 것을 지원합니다. 이 클래스는 transformers.PreTrainedModel.from_pretrained에서만 사용되며, 아직 해당 메서드의 범위를 벗어나 쉽게 사용할 수 없습니다.
Attributes
quantization_config (transformers.utils.quantization_config.QuantizationConfigMixin):
모델을 양자화할 때 사용할 양자화 매개변수를 정의하는 양자화 설정입니다.
requires_calibration (bool):
양자화 방법이 모델을 사용하기 전에 보정(calibration)을 요구하는지 여부입니다.
양자화에 추가 메모리가 필요한 경우 infer_auto_device_map()의 max_memory 인수를 조정하세요
정밀도/성능이 일부 저하될 수 있지만, 모델을 역양자화하여 원래 모델을 복원할 수 있습니다. 모든 양자화 방식이 이를 지원하지는 않습니다.
직렬화 텐서를 로드하는 Op 클래스, 예: {"deserialize": Mxfp4Deserialize, "dequantize": Mxfp4Dequantize}.
디시리얼라이제이션은 하나의 모듈의 params를 구성하므로 일반 컨버터에서만 실행됩니다. 디퀀타이제이션도
모델의 컨버터 Op, 예: per-expert merge,보다 먼저 실행됩니다.
이것은 텐서가 디스크에서 장치로 전송되는 materialization 시점에 발생합니다. 사전 양자화 체크포인트의 param 텐서를 변환할 dtype입니다.
해당 param이 양자화되지 않은 경우(부동소수점 타입)에는 초기화된 nn.Module에서 전달되는 입력 dtype을 사용합니다.
양자화 방식에 Deserializer 또는 Dequantizer(로드 함수)가 있으면 None을 반환하여 해당 함수들이 처리하도록 합니다.
state dict와 메타데이터를 가져옵니다. 양자화 때문에 state dict를 조금 수정해야 할 때 유용합니다
모델의 변환기에 매칭되지 않는 모든 파라미터에 대해 수행할 로딩을 반환합니다
주어진 param이 양자화되어야 하는지 확인합니다.
postprocess_model
< source >( model: PreTrainedModel**kwargs )
가중치 로딩 후 모델을 후처리합니다.
추상 메서드 _process_model_after_weight_loading를 오버라이드하도록 하세요.
preprocess_model
< source >( model: PreTrainedModeldtype = None**kwargs )
가중치 로딩 전에 모델 속성을 설정하고/또는 모델을 변환합니다. 이 시점에서 모델은 meta device에 초기화되어 있어야 하므로, 모듈을 제자리(in-place)로 교체하기 위해 모델의 골격을 자유롭게 조작할 수 있습니다. 추상 메서드 _process_model_before_weight_loading를 오버라이드하도록 하십시오.
모델에서 양자화 설정을 제거합니다.
모델이 빌드되기 전에 요청된 attn_implementation을 확인하므로, quantizer가 기본값으로 설정할 수 있습니다.
update_device_map
< source >( device_map: dict[str, typing.Any] | None )
새로운 device map으로 기존 device map을 덮어쓰기(override)하려면 이 메서드를 오버라이드하세요. 예를 들어 accelerate가 필수 요구 사항인 bitsandbytes의 경우, device_map이 전달되지 않으면 device_map이 `“auto”`로 설정됩니다.
update_dtype
< source >( dtype: torch.dtype )
일부 양자화 방법은 모델의 dtype를 대상 dtype으로 명시적으로 설정해야 합니다. 해당 동작이 유지되도록 확인하려면 이 메서드를 오버라이드해야 합니다
model.tp_plan 또는 model.ep_plan(설정 및 모든 하위 설정에서 병합된 전체 계획)을 업데이트하여 'inv_scale'과 같은 양자화기의 사용자 정의 키를 반영합니다.
모델의 컨버터(변환 매핑에서)가 직렬화된 이름을 로드하도록 합니다. 모델의 파라미터가, 예를 들어 experts.*.gate_proj.weight을 experts.gate_up_proj으로 병합하는 경우와 같이,
experts.gate_up_proj_scale_inv은 매개변수입니다: 복사본은experts.*.gate_proj.weight_scale_inv을 여기에 병합합니다- 그렇지 않으면 변환기가
experts.*.gate_proj.weight_scale_inv도 수집하고, dequantize op가 먼저 실행됩니다
이 메서드는 from_pretrained에 전달되는 인자와의 잠재적 충돌을 확인하는 데 사용됩니다. Transformers와 통합되는 모든 향후 quantizer에 대해 이 메서드를 정의해야 합니다. 명시적인 확인이 필요하지 않은 경우 아무것도 반환하지 않으면 됩니다.
HiggsConfig
class transformers.HiggsConfig
< source >( bits: int = 4p: int = 2modules_to_not_convert: list[str] | None = Nonehadamard_size: int = 512group_size: int = 256tune_metadata: dict[str, typing.Any] | None = None**kwargs )
매개변수
- bits (int, 선택 사항, 기본값 4) — 양자화에 사용할 비트 수입니다. 2, 3 또는 4를 사용할 수 있으며 기본값은 4입니다.
- p (int, 선택 사항, 기본값 2) — Quantization grid 차원입니다. 1과 2를 지원합니다. 실제로는 2가 항상 더 좋습니다. 기본값은 2입니다.
- modules_to_not_convert (
list, 선택 사항, 기본값 [“lm_head”]) — 양자화하지 않을 선형 레이어 목록. - hadamard_size (int, 선택 사항, 기본값 512) — HIGGS 방법에서 사용할 Hadamard 크기입니다. 기본값은 512입니다. 행렬의 입력 차원은 이 값으로 패딩됩니다. 이 값을 512보다 낮추면 양자화 품질이 저하됩니다.
- group_size (int, 선택 사항, 기본값 256) — HIGGS 방법의 그룹 크기입니다. 64, 128 또는 256을 사용할 수 있습니다. 이 값을 줄여도 성능에 거의 영향을 미치지 않습니다. 기본값은 256입니다. hadamard_size의 약수여야 합니다.
- tune_metadata (‘dict’, 선택 사항, 기본값 {}) — 커널 튜닝 결과를 저장하기 위한 모듈별 메타데이터(gemm 블록 형상, GPU 메타데이터 등)입니다. 기본값은 빈 사전입니다. 튜닝 과정에서 자동으로 설정됩니다.
HiggsConfig는 HIGGS 방법을 사용한 양자화를 위한 설정 클래스입니다.
인수가 올바른지 확인하는 안전 검사기입니다. 또한 일부 NoneType 인수를 기본값으로 대체합니다.
HqqConfig
클래스 transformers.HqqConfig
< source >( nbits: int = 4group_size: int = 64view_as_float: bool = Falseaxis: int | None = Nonedynamic_config: dict | None = Noneskip_modules: list = ['lm_head']**kwargs )
매개변수
- nbits (
int, 선택 사항, 기본값 4) — 비트 수. 지원되는 값은 (8, 4, 3, 2, 1)입니다. - group_size (
int, 선택 사항, 기본값 64) — Group-size 값. weight.shape[axis]로 나누어 떨어지는 모든 값이 지원됩니다. - view_as_float (
bool, 선택 사항, 기본값False) —True로 설정하면 양자화된 가중치를 float로 표시합니다(분산 학습에서 사용). - axis (
Optional[int], 선택 사항) — 그룹핑이 수행되는 축입니다. 지원되는 값은 0 또는 1입니다. - dynamic_config (dict, 선택 사항) — 동적 구성을 위한 매개변수입니다. 키는 레이어의 이름 태그이고 값은 양자화 구성입니다. 설정된 경우, id로 지정된 각 레이어는 전용 양자화 구성을 사용합니다.
- skip_modules (
list[str], 선택 사항, 기본값['lm_head']) — 건너뛸nn.Linear레이어 목록. - kwargs (
dict[str, Any], 선택) — 설정 객체를 초기화할 때 사용할 추가 매개변수.
hqq의 BaseQuantizeConfig를 감싸는 래퍼입니다.
Override from_dict, used in AutoQuantizationConfig.from_dict in quantizers/auto.py
인수가 올바른지 확인하는 안전 검사기입니다. 또한 일부 NoneType 인수를 기본값으로 대체합니다.
더 나은 가독성을 위해 기본 config 속성에 해당하는 모든 속성을 config에서 제거하고 Python dictionary로 직렬화합니다.
MetalConfig
클래스 transformers.MetalConfig
< source >( bits: int = 4group_size: int = 64modules_to_not_convert: list | None = Nonedequantize: bool = False**kwargs )
Apple Silicon(MPS) 장치를 대상으로 하는 Metal affine 양자화를 위한 설정 클래스입니다.
이 양자화 방법은 Hugging Face Hub의 mlx-quantization-metal-kernels Metal 커널을 사용하여, 설정 가능한 비트 폭과 그룹 크기를 가진 아핀 양자화(scales + qbiases)를 수행합니다. 양자화된 가중치는 uint32 텐서에 패킹되며, 전방 패스는 융합된 역양자화 + matmul Metal 커널을 사용합니다.
Mxfp4Config
클래스 transformers.Mxfp4Config
< source >( modules_to_not_convert: list | None = Nonedequantize: bool = False**kwargs )
mxfp4 양자화로 로드된 모델에서 활용할 수 있는 모든 속성과 기능을 다루는 래퍼 클래스입니다.
NVFP4Config
class transformers.NVFP4Config
< source >( modules_to_not_convert: list[str] | None = None**kwargs )
on-the-fly NVFP4 가중치 양자화를 위한 설정.
FbgemmFp8Config
class transformers.FbgemmFp8Config
< source >( activation_scale_ub: float = 1200.0modules_to_not_convert: list | None = None**kwargs )
fbgemm fp8 양자화로 로드한 모델에서 사용할 수 있는 모든 속성과 기능을 다루는 래퍼 클래스입니다.
CompressedTensorsConfig
class transformers.CompressedTensorsConfig
< source >( config_groups: dict[str, typing.Union[ForwardRef('QuantizationScheme'), list[str]]] | None = Noneformat: str = 'dense'quantization_status: QuantizationStatus = 'initialized'kv_cache_scheme: typing.Optional[ForwardRef('QuantizationArgs')] = Noneglobal_compression_ratio: float | None = Noneignore: list[str] | None = Nonequant_method: str = 'compressed-tensors'run_compressed: bool | None = Nonedequantize: bool = Falseuse_optimized_inference: bool = False**kwargs )
매개변수
- config_groups (
typing.dict[str, typing.Union[ForwardRef('QuantizationScheme'), typing.list[str]]], 선택) — 그룹 이름을 양자화 스킴 정의에 매핑하는 사전 - format (
str, 선택 사항, 기본값"dense") — 가중치가 저장되는 형식입니다. 예:dense,float-quantized,pack-quantized - quantization_status (
QuantizationStatus, 선택 사항, 기본값"initialized") — 양자화 라이프사이클에서 모델의 상태, 예: ‘initialized’, ‘calibration’, ‘frozen’ - kv_cache_scheme (
typing.Union[QuantizationArgs, NoneType], 선택 사항) — kv cache의 양자화를 지정합니다. None인 경우 kv cache는 양자화되지 않습니다. - global_compression_ratio (
typing.Union[float, NoneType], 선택 사항) — 모델 압축 비율을 나타내는 0-1 범위의 float 값 - ignore (
typing.Union[typing.list[str], NoneType], 선택) — 양자화하지 않을 레이어 이름 또는 유형이며, ‘re:’ 접두사가 붙은 정규식을 지원합니다 - quant_method (
str, 선택 사항, 기본값"compressed-tensors") — 재정의하지 마세요. compressed-tensors여야 합니다 - run_compressed (
bool, 선택) — 비추천됩니다. 대신dequantize를 사용하세요. 유일한 효과는dequantize를 반대값으로 설정하는 것입니다.run_compressed=False는dequantize=True를 의미합니다. - dequantize (
bool, 선택 사항, 기본값False) —True인 경우, 로드 시점에 양자화된 가중치를 모델의 원래 dtype(예: BF16)으로 역양자화합니다. 이는 모델의 미세 조정 또는 원래 dtype로 모델을 저장할 때 필요합니다.False인 경우, 가중치는 압축된 형태로 유지되며 compressed-tensors가 첫 번째 forward pass에서 이를 압축 해제합니다. - use_optimized_inference (
bool, 선택 사항, 기본값False) —True인 경우, 커널이 있는 스킴의 레이어는 양자화 가중치를 유지한 채 해당 커널을 통해 실행됩니다(현재 W8A8 FP8, CUDA SM89+, XPU, 또는 torch >= 2.15 환경의 MPS). 추론 전용이며 옵트인 방식입니다. 이 옵션이 없으면 모델은 일반적인 compressed-tensors 경로를 통해 실행됩니다.dequantize=True인 경우 무시됩니다.
이것은 compressed-tensors 양자화 설정 옵션을 처리하는 래퍼 클래스입니다.
compressed_tensors.QuantizationConfig를 감싸는 래퍼입니다.
from_dict
< source >( config_dictreturn_unused_kwargs = False**kwargs ) → QuantizationConfigMixin
Python 매개변수 사전에서 CompressedTensorsConfig를 초기화합니다. 필요에 따라 중첩된 quantization_config에서 args를 해제합니다.
config.json에 추가할 양자화 설정
이 인스턴스를 Python 딕셔너리로 직렬화합니다. 반환값: dict[str, Any]: 이 설정 인스턴스를 구성하는 모든 속성의 딕셔너리.
더 나은 가독성을 위해 기본 config 속성에 해당하는 모든 속성을 config에서 제거하고 Python dictionary로 직렬화합니다.
TorchAoConfig
class transformers.TorchAoConfig
< source >( quant_type: AOBaseConfigmodules_to_not_convert: list | None = Noneinclude_input_output_embeddings: bool = Falseuntie_embedding_weights: bool = False**kwargs )
매개변수
- quant_type (
AOBaseConfig) — 양자화 유형을 지정하는 torchaoAOBaseConfig인스턴스입니다. 예를 들어Int4WeightOnlyConfig(group_size=32),Int8WeightOnlyConfig(),Int8DynamicActivationInt8WeightConfig(),Float8WeightOnlyConfig()등이 있습니다. - modules_to_not_convert (
list, 선택 사항, 기본값None) — 양자화하지 않을 모듈 목록입니다. 일부 모듈은 원래 정밀도를 유지해야 하는 모델의 양자화에 유용합니다. - include_input_output_embeddings (
bool, 선택 사항, 기본값False) — 양자화에 임베딩을 포함할지 여부를 지정합니다. 이 플래그가 설정되면 입력 임베딩도 module_not_to_convert 목록에서 제거됩니다. - untie_embedding_weights (
bool, 선택 사항, 기본값False) — 다른 가중치와 연결(tied)된 입력 임베딩 가중치를 양자화할 때 가중치를 분리(untie)할지 여부입니다.
torchao 양자화/희소화 기법을 위한 Config 클래스입니다.
예:
from torchao.quantization import Int4WeightOnlyConfig
quantization_config = TorchAoConfig(Int4WeightOnlyConfig(group_size=32))
model = AutoModelForCausalLM.from_pretrained(
model_id, device_map="cuda", torch_dtype=torch.bfloat16, quantization_config=quantization_config
)사전에서 구성을 생성합니다.
적용할 양자화 설정을 반환합니다.
설정을 검증하고 기본값을 설정합니다.
설정을 사전으로 변환합니다.
BitNetQuantConfig
class transformers.BitNetQuantConfig
< source >( modules_to_not_convert: list | None = Nonelinear_class: str = 'bitlinear'quantization_mode: str = 'offline'use_rms_norm: bool = Falserms_norm_eps: float | None = 1e-06**kwargs )
매개변수
- modules_to_not_convert (
Optional[List], 선택) — 양자화하지 않을nn.Linear가중치 매개변수의 전체 경로를 목록으로 지정할 수 있습니다. 기본값은 None입니다. - linear_class (
str, 선택 사항, 기본값"bitlinear") — 사용할 linear class의 유형입니다.bitlinear또는autobitlinear중 하나를 사용할 수 있습니다. - quantization_mode (
str, 선택 사항, 기본값"offline") — 사용할 양자화 모드입니다.online또는offline중 하나를 지정할 수 있습니다.online모드에서는 가중치 양자화 매개변수가 각 forward pass 동안 동적으로 계산됩니다(예: 현재 가중치 값에 기반). 이를 통해 학습 중 가중치 변경에 적응할 수 있습니다(Quantization-Aware Training - QAT).offline모드에서는 양자화 매개변수가 추론 이전에 사전 계산됩니다. 이 매개변수는 고정된 상태로 양자화 모델에 로드됩니다. 일반적으로 online 양자화보다 런타임 오버헤드가 낮습니다. - use_rms_norm (
bool, 선택 사항, 기본값False) — 양자화 전에 활성화에 RMSNorm을 적용할지 여부입니다. 이는 원래 BitNet 논문에서 양자화/패킹 전에 활성화를 정규화하는 방식과 일치합니다. - rms_norm_eps (
float, 선택 사항, 기본값 1e-06) — RMSNorm 레이어에서 수치적 안정성을 위해 사용되는 epsilon 값입니다. - kwargs (
dict[str, Any], 선택) — 특정 양자화 백엔드나 향후 버전에서 사용할 수 있는 추가 키워드 인자입니다.
BitNet 양자화를 적용하기 위한 구성 클래스입니다.
인수가 올바른지 확인하는 안전 검사기
SpQRConfig
class transformers.SpQRConfig
< source >( bits: int = 3beta1: int = 16beta2: int = 16shapes: dict[str, int] | None = Nonemodules_to_not_convert: list[str] | None = None**kwargs )
매개변수
- bits (
int, 선택 사항, 기본값 3) — 가중치와 1차 zero-point 및 scale에 사용할 비트 수를 지정합니다. 현재 bits = 3만 지원됩니다. - beta1 (
int, 선택 사항, 기본값 16) — SpQR 타일 너비. 현재 beta1 = 16만 지원됩니다. - beta2 (
int, 선택 사항, 기본값 16) — SpQR 타일 높이입니다. 현재는 beta2 = 16만 지원됩니다. - shapes (
Optional, 선택) — 각 객체의 shape를 담는 dictionary입니다. bits, beta1, beta2만으로는 파라미터의 정확한 크도를 추론할 수 없기 때문에 이 정보가 필요합니다. - modules_to_not_convert (
Optional[list[str]], 선택) — 양자화하지 않을nn.Linear가중치 매개변수의 전체 경로를 목록으로 지정할 수 있습니다. 기본값은 None입니다. - kwargs (
dict[str, Any], 선택) — 설정 객체를 초기화할 때 사용할 추가 매개변수.
이것은 spqr 매개변수에 대한 래퍼 클래스입니다. 자세한 내용은 원 논문에서 확인하세요.
인수가 올바른지 확인하는 안전 검사기입니다. 또한 일부 NoneType 인수를 기본값으로 대체합니다.
FineGrainedFP8Config
class transformers.FineGrainedFP8Config
< source >( activation_scheme: str = 'dynamic'weight_block_size: tuple = (128, 128)dequantize: bool = Falsemodules_to_not_convert: list | None = Nonemodules_to_convert: list | None = Nonescale_fmt: str = 'float'expert_dtype: str = 'fp8'**kwargs )
매개변수
- activation_scheme (
str, 선택 사항, 기본값"dynamic") — 활성화에 사용되는 스킴입니다. 현재 기본값이자 유일하게 지원되는 스킴은 “dynamic”입니다. - weight_block_size (
typing.tuple[int, int], 선택 사항, 기본값(128, 128)) — 양자화를 위한 가중치 블록의 크기입니다. 기본값은 (128, 128)입니다. - dequantize (
bool, 선택, 기본값False) — 모델을 로드하는 동안 dequantize할지 여부입니다. - modules_to_not_convert (
list, 선택 사항) — 양자화 과정에서 변환하지 않아야 할 모듈 이름 목록입니다. - modules_to_convert (
list, 선택 사항) — 양자화 과정에서 변환해야 하는 임베딩 테이블과 같은 추가 모듈 이름 목록입니다. - scale_fmt (
str, 선택 사항, 기본값"float") — 블록별 가중치 스케일의 저장 dtype:"float"(fp32, V3 스타일) 또는"ue8m0"(1바이트torch.float8_e8m0fnu, V4 스타일). - expert_dtype (
str, 선택 사항, 기본값"fp8") — MoE 전문가의 가중치 형식:"fp8"또는 DeepSeek-V4의 FP4-packed 전문가를 위한"fp4".
FineGrainedFP8Config는 주로 deepseek 모델에 사용되는 세밀한 FP8 양자화를 위한 설정 클래스입니다.
인수가 올바른지 확인하는 안전 검사기
QuarkConfig
FourOverSixConfig
class transformers.FourOverSixConfig
< source >( activation_dtype: str | None = Noneactivation_scale_rule: str | None = Nonedtype: str = 'nvfp4'gradient_dtype: str | None = Nonegradient_scale_rule: str | None = Nonekeep_master_weights: bool = Falsematmul_backend: str | None = Noneoutput_dtype: str | None = 'bfloat16'quantize_backend: str | None = Nonescale_rule: str = 'mse'weight_dtype: str | None = Noneweight_scale_2d: bool = Falseweight_scale_rule: str | None = Nonemodule_config_overrides: dict[str, dict[str, typing.Any]] | None = Nonemodules_to_not_convert: list[str] | None = ['lm_head']**kwargs )
매개변수
- activation_dtype (
str, 선택 사항) — 활성화 텐서를 양자화할 때 사용할 데이터 유형입니다. 제공되지 않으면dtype가 사용됩니다. - activation_scale_rule (
str, 선택 사항) — 활성화 텐서의 블록에 스케일을 선택할 때 사용할 스케일링 규칙입니다. 제공되지 않으면scale_rule이 사용됩니다. - dtype (
str, 기본값 “nvfp4”, 선택 사항, 기본값"nvfp4") — 레이어의 가중치, 활성화, 텐서에 사용할 데이터 유형입니다."nvfp4"또는"mxfp4"를 사용할 수 있습니다. - gradient_dtype (
str, 선택 사항) — 그라디언트 텐서를 양자화할 때 사용할 데이터 유형입니다. 제공되지 않으면dtype가 사용됩니다. - gradient_scale_rule (
str, 선택 사항) — 그라디언트 텐서의 블록에 스케일을 선택할 때 사용할 스케일링 규칙입니다. 제공되지 않으면scale_rule이 사용됩니다. - keep_master_weights (
bool, 기본값 False, 선택 사항, 기본값False) — 마스터 가중치를 유지할지 여부입니다.True인 경우, 항상 고정밀도 가중치를 유지하고 각 forward pass마다 가중치를 온라인으로 양자화합니다. 이는 양자화 학습에 유용합니다. - matmul_backend (
str, 선택 사항) — 행렬 곱셈에 사용할 백엔드입니다."cutlass"또는"pytorch"를 사용할 수 있습니다. 지정하지 않으면 사용 가능한 경우 CUTLASS를 사용하고, 그렇지 않으면 PyTorch를 사용합니다. - output_dtype (
str, 선택 사항, 기본값"bfloat16") — 레이어의 출력에 사용할 데이터 유형입니다."bfloat16"또는"float16"를 사용할 수 있습니다. - quantize_backend (
str, 선택 사항) — 양자화에 사용할 백엔드입니다."cuda","triton", 또는"pytorch"를 사용할 수 있습니다. 지정하지 않으면 사용자의 환경과 각 백엔드가 지원하는 옵션에 따라 가장 빠른 백엔드가 선택됩니다. 일반적으로 추론에는"cuda"가, 학습에는"triton"가, CUDA가 아닌 디바이스에는"pytorch"가 사용됩니다. - scale_rule (
str, 기본값 “mse”, 선택 사항, 기본값"mse") — 블록 스케일을 선택할 때 사용할 규칙입니다. Four Over Six의 경우"mse","mae","abs_max"를, 기본 NVFP4 양자화의 경우"static_6"를, 모든 블록을 최대값 4로 스케일링하려면"static_4"를 사용할 수 있습니다. - weight_dtype (
str, 선택 사항) — 가중치 텐서를 양자화할 때 사용할 데이터 유형입니다. 제공되지 않으면dtype이 사용됩니다. - weight_scale_2d (
bool, 기본값 False, 선택 사항, 기본값False) — 가중치 텐서를 2D 블록 단위로 scale factor를 계산할지 여부입니다. 이 작업은 학습 중에 수행해야 합니다. - weight_scale_rule (
str, 선택 사항) — 가중치 텐서의 블록에 스케일을 선택할 때 사용할 스케일링 규칙입니다. 제공되지 않으면scale_rule이 사용됩니다. - module_config_overrides (
dict[str, dict[str, Any]], 선택) — 모듈별 구성 오버라이드를 담는 사전입니다. 키는 모듈 이름이어야 하며, 값은 해당 모듈의 양자화 구성을 포함하는 사전이어야 합니다. 이를 통해 특정 모듈의 기본 구성을 오버라이드할 수 있습니다. - modules_to_not_convert (
list[str], 선택 사항, 기본값['lm_head']) — 양자화에서 제외할 모듈 목록입니다. 기본적으로lm_head가 제외됩니다.
fouroversix를 사용한 양자화의 모든 옵션을 포함하는 래퍼 클래스입니다. 간략히 설명하면, Four Over Six는 16개의 FP4 값으로 구성된 각 블록에서 가장 큰 값을 4 또는 6으로 적응적으로 스케일링하는 NVFP4 양자화의 변형입니다. 스케일을 6으로 선택하면 FP4 값의 전체 범위를 사용할 수 있지만, 4를 선택하면 양자화 오차가 더 균일하게 분포하도록 할 수 있습니다. 자세한 내용은 원 논문 https://arxiv.org/abs/2512.02010을 참고하세요.
FPQuantConfig
class transformers.FPQuantConfig
< source >( forward_dtype: str = 'nvfp4'forward_method: str = 'abs_max'backward_dtype: str = 'bf16'store_master_weights: bool = Falsehadamard_group_size: int | None = Nonepseudoquantization: bool = Falsetransform_init: str = 'hadamard'modules_to_not_convert: list[str] | None = None**kwargs )
매개변수
- forward_dtype (
str, 선택 사항, 기본값"nvfp4") — forward pass에 사용할 dtype입니다. - forward_method (
str, 선택 사항, 기본값"abs_max") — forward pass에 사용할 스케일링입니다."abs_max"또는"quest"를 사용할 수 있습니다."abs_max"는 PTQ에,"quest"는 QAT에 더 적합합니다. - backward_dtype (
str, 선택 사항, 기본값"bf16") — backward pass에 사용할 dtype입니다. - store_master_weights (
bool, 선택 사항, 기본값False) — 마스터 가중치를 저장할지 여부입니다. 레이어 가중치에 대한 QAT에 필요합니다. - hadamard_group_size (
int, 선택 사항) —"quest"의 경우, 양자화 전 hadamard 변환에 사용되는 그룹 크기입니다. MXFP4의 그룹 크기(32)와 일치합니다.None인 경우,"nvfp4"에는 16,"mxfp4"에는 32로 설정됩니다. - pseudoquantization (
bool, 선택 사항, 기본값False) — Triton 기반의 pseudo-quantization을 사용할지 여부입니다. Blackwell이 아닌 GPU에서는 필수입니다. 속도 향상을 제공하지 않습니다. 디버깅 목적으로 사용됩니다. - transform_init (
str, 선택 사항, 기본값"hadamard") — 전처리 행렬을 초기화하는 방법."hadamard","identity"또는"gsr"를 사용할 수 있습니다. - modules_to_not_convert (
list, 선택) — 양자화하지 않을 모듈 목록입니다. 일부 모듈은 원래 정밀도를 유지해야 하는 모델의 양자화에 유용합니다.
FPQuantConfig는 FPQuant 방법을 사용한 양자화를 위한 구성 클래스입니다.
인수가 올바른지 확인하는 안전 검사기입니다. 또한 일부 NoneType 인수를 기본값으로 대체합니다.
AutoRoundConfig
class transformers.AutoRoundConfig
< source >( bits: int = 4group_size: int = 128sym: bool = Truebackend: str = 'auto'**kwargs )
매개변수
- bits (
int, 선택 사항, 기본값 4) — 양자화할 비트 수입니다. 지원되는 값은 (2, 3, 4, 5, 6, 7, 8)입니다. - group_size (
int, 선택 사항, 기본값 128) — 그룹 크기 값 - sym (
bool, 선택 사항, 기본값True) — 대칭 양자화 여부 - backend (
str, 선택 사항, 기본값"auto") — 추론 백엔드입니다. 기본적으로 AutoRound은 장치, 양자화 설정, 설치된 라이브러리를 기반으로 호환되는 백엔드를 선택합니다. 모든 백엔드 옵션은 추론 백엔드 지정을 참조하세요.
AutoRound 양자화로 로드된 모델에서 사용할 수 있는 모든 속성과 기능을 다루는 래퍼 클래스입니다.
인수가 올바른지 확인하는 안전 검사기
SinqConfig
클래스 transformers.SinqConfig
< source >( nbits: int = 4group_size: int = 64tiling_mode: str = '1D'method: str = 'sinq'modules_to_not_convert: list[str] | None = None**kwargs: Any )
매개변수
- nbits (
int, 기본값 4) — 가중치에 사용할 양자화 비트 수입니다. - group_size (
int, 기본값 64) — SINQ 가중치 양자화에 사용되는 그룹 크기(8의 배수여야 합니다). - tiling_mode (
str, 기본값 “1D”) — SINQ의 타일링 모드(일반적으로 “1D”; 백엔드에서 지원되는 경우 “2D”). - method (
str, 기본값 “sinq”) — “sinq” – 보정 없이 가중치만 적용하는 SINQ “asinq” – A-SINQ(활성화 인지), Hugging Face에서 지원되지 않습니다. 공식 SINQ 저장소를 참조하세요. - modules_to_not_convert (
list[str], 선택 사항) — 전체 정밀도를 유지할 모듈 이름/접두어 목록. - **kwargs —
추가 사용자 인자(라운드 트립을 위해
_extra_kwargs에 유지됨).
SINQ / A-SINQ에 대한 양자화 설정입니다.
다음에 전달하세요:
AutoModel.from_pretrained(…, quantization_config=SinqConfig(…))
GgufConfig
클래스 transformers.GgufConfig
< source >( gguf_file: str | None = Nonedequantize: bool = False**kwargs )
매개변수
GGUF 블록에 가중치를 그대로 유지한 양자화된 GGUF 체크포인트를 로드합니다.