Hugging Face's logo

Transformers documentation

量化

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

量化

量化技术通过使用较低精度的数据类型（如 8 位整数 int8）来表示权重和激活值，从而降低内存和计算成本。这使得能够加载通常无法装入内存的更大模型，并加快推理速度。Transformers 支持 AWQ 和 GPTQ 量化算法，并支持通过 bitsandbytes 进行 8 位和 4 位量化。

HfQuantizer 类可用于添加 Transformers 中尚未支持的量化技术。

了解如何在量化指南中对模型进行量化。

QuantoConfig

class transformers.QuantoConfig

< >

( weights = 'int8'activations = Nonemodules_to_not_convert: list | None = None**kwargs )

参数

  • weights (str, 可选, 默认为 "int8") — 量化后权重的目标 dtype。支持的值为（“float8”、“int8”、“int4”、“int2”）
  • activations (str, 可选) — 量化后激活的目标 dtype。支持的值为 (None,“int8”,“float8”)
  • modules_to_not_convert (list，可选，默认为 None) — 不进行量化的模块列表。对于明确要求某些模块保留原始精度（例如 Whisper encoder、Llava encoder、Mixtral gate layers）的模型进行量化时，此参数非常有用。

这是一个封装类，涵盖了使用 quanto 加载的模型中所有可操作的属性和功能。

post_init

< >

( )

用于检查参数是否正确

AqlmConfig

class transformers.AqlmConfig

< >

( 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) — 用于编码单个码本向量的比特数。码本的大小为 2**nbits_per_codebook。
  • linear_weights_not_to_quantize (Optional[list[str]], 可选) — 不应进行量化的 nn.Linear 权重参数的完整路径列表。
  • kwargs (dict[str, Any]，可选) — 用于初始化配置对象的额外参数。

这是一个关于 aqlm 参数的包装类。

post_init

< >

( )

用于检查参数是否正确的安全检查器——同时会将某些 NoneType 参数替换为其默认值。

VptqConfig

class transformers.VptqConfig

< >

( enable_proxy_error: bool = Falseconfig_for_layers: dict[str, typing.Any] = {}shared_layer_config: dict[str, typing.Any] = {}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 参数的包装类。

post_init

< >

( )

用于检查参数是否正确

AwqConfig

class transformers.AwqConfig

< >

( 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) — 是否使用零点量化。
  • 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

class transformers.EetqConfig

< >

( weights: str = 'int8'modules_to_not_convert: list | None = None**kwargs )

参数

  • weights (str，可选，默认为 "int8") — 权重的目标数据类型。仅支持的值是 “int8”
  • modules_to_not_convert (list，可选，默认为 None) — 不进行量化的模块列表，适用于那些明确要求某些模块保持原始精度的模型量化场景。

这是一个封装类，涵盖了使用 eetq 加载的模型中所有可操作的属性和功能。

post_init

< >

( )

用于检查参数是否正确

GPTQConfig

class transformers.GPTQConfig

< >

( 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, 可选) — 用于处理数据集的 tokenizer。您可以传入以下任一内容：
    • 自定义的 tokenizer 对象。
    • 一个字符串，即托管在 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, 可选) — 填充 token 的 id。当 batch_size > 1 时，准备数据集需要此参数。
  • max_input_length (int, 可选) — 最大输入长度。初始化依赖于预期最大输入长度的缓冲区时需要此参数。该参数仅适用于使用 act-order 的 exllama 后端。
  • cache_block_outputs (bool，可选，默认为 True) — 是否缓存 block 的输出，以便将其作为后续 block 的输入进行复用。
  • 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 量化的模型的所有可用属性和功能。

from_dict_optimum

< >

( config_dict )

使用 optimum 的 gptq 配置字典获取兼容的类

post_init

< >

( )

用于检查参数是否正确

to_dict_optimum

< >

( )

获取适用于 optimum gptq 配置的兼容字典

BitsAndBytesConfig

class transformers.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) — 此标志用于启用 4 位量化，通过用 bitsandbytes 中的 FP4/NF4 层替换 Linear 层来实现。
  • 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 位的模块。这对于像 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 加载的模型中所有可用的属性和功能。

目前仅支持 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 中对应于默认配置属性的所有属性，以提高可读性，并将其序列化为 Python 字典。

HfQuantizer

class transformers.quantizers.HfQuantizer

< >

( quantization_config: QuantizationConfigMixin**kwargs )

HuggingFace 量化器的抽象类。目前支持对 HF transformers 模型进行推理和/或量化。 该类目前仅用于 transformers.PreTrainedModel.from_pretrained，尚无法轻松地在该方法的作用域之外使用。

Attributes quantization_config (transformers.utils.quantization_config.QuantizationConfigMixin)： 用于定义您想要量化的模型的量化参数的量化配置。 requires_calibration (bool)： 该量化方法是否要求在使用模型之前对其进行校准。

adjust_max_memory

< >

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

如果量化需要额外的内存，请调整 infer_auto_device_map() 的 max_memory 参数

dequantize

< >

( modeldtype = None )

可能会反量化模型以恢复原始模型，但会损失一定的精度/性能。 请注意，并非所有量化方案都支持此操作。

get_load_operations

< >

( )

加载序列化张量的 Op 类，例如 {"deserialize": Mxfp4Deserialize, "dequantize": Mxfp4Dequantize}。 反序列化用于构建单个模块的参数，因此仅在通用转换器上运行。反量化 同样在模型转换器的 Op 之前运行，例如在按专家合并之前。

get_new_dtype

< >

( converterparamdtype: torch.dtype | None )

这发生在张量实例化时，即张量从磁盘发送到设备时。dtype 用于将预量化的检查点张量 param 转换为目标数据类型。 如果该参数未被量化（即浮点类型），则使用来自已初始化的 nn.Module 的输入 dtype。

如果量化方法具有 Deserializer 或 Dequantizer（加载函数），则返回 None，由它们进行处理。

get_state_dict_and_metadata

< >

( model )

获取状态字典和元数据。在需要因量化而对状态字典进行少量修改时非常有用

get_weight_conversions

< >

( )

返回对模型转换器未匹配到的任何参数所执行的加载操作

param_needs_quantization

< >

( model: PreTrainedModelparam_name: str**kwargs )

检查给定的参数是否需要量化。

postprocess_model

< >

( model: PreTrainedModel**kwargs )

参数

  • model (~transformers.PreTrainedModel) — 要量化的模型
  • kwargs (dict, 可选) — 传递给 _process_model_after_weight_loading 的关键字参数。

在加载权重后对模型进行后处理。 请确保重写抽象方法 _process_model_after_weight_loading。

preprocess_model

< >

( model: PreTrainedModeldtype = None**kwargs )

参数

  • model (~transformers.PreTrainedModel) — 要量化的模型
  • kwargs (dict, 可选) — 传递给 _process_model_before_weight_loading 的关键字参数。

在加载权重之前设置模型属性和/或转换模型。此时，模型应已在 meta 设备上初始化，因此您可以自由操作模型的骨架，以便就地替换模块。请确保重写抽象方法 _process_model_before_weight_loading。

remove_quantization_config

< >

( model )

从模型中移除量化配置。

update_attn_implementation

< >

( config )

在模型构建之前查看请求的 attn_implementation，以便量化器可以为其设置默认值。

update_device_map

< >

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

参数

  • device_map (Union[dict, str]，可选) — 通过 from_pretrained 方法传递的 device_map。

如果需要覆盖现有的设备映射，请重写此方法以传入新的设备映射。例如，对于 bitsandbytes，由于 accelerate 是硬性依赖，如果未传入 device_map，则 device_map 会被设置为 `“auto”“

update_dtype

< >

( dtype: torch.dtype )

参数

  • dtype (torch.dtype) — 通过 from_pretrained 传入的输入数据类型

某些量化方法要求显式将模型的 dtype 设置为目标 dtype。如果您希望确保保留该行为，则需要重写此方法

update_parallel_plan

< >

( modelplan: dict[str, str] )

就地更新 model.tp_plan 或 model.ep_plan（由配置和所有子配置合并而成的完整计划），以纳入量化器的自定义键，例如 ‘inv_scale’

update_weight_conversions

< >

( weight_conversionsmodel )

使模型的转换器（来自转换映射）加载序列化后的名称。模型的参数决定了具体的合并方式，例如将 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，反量化操作会先执行

validate_environment

< >

( *args**kwargs )

此方法用于检查通过 from_pretrained 传入的参数是否存在潜在冲突。对于所有与 transformers 集成的未来量化器，您都需要定义此方法。如果不需要显式检查，则直接返回空值即可。

HiggsConfig

class transformers.HiggsConfig

< >

( 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) — 量化网格维度。支持 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 方法进行量化的配置类。

post_init

< >

( )

用于检查参数是否正确的安全检查器——同时会将某些 NoneType 参数替换为其默认值。

HqqConfig

class transformers.HqqConfig

< >

( nbits: int = 4group_size: int = 64view_as_float: bool = Falseaxis: int | None = Nonedynamic_config: dict | None = Noneskip_modules: list[str] = ['lm_head']**kwargs )

参数

  • nbits (int，可选，默认为 4) — 位数。支持的值为 (8, 4, 3, 2, 1)。
  • group_size (int，可选，默认值为 64) — 分组大小值。支持的值为任何可被 weight.shape[axis] 整除的值。
  • view_as_float (bool，可选，默认为 False) — 如果设置为 True，则将量化后的权重视为浮点数（用于分布式训练）。
  • axis (Optional[int]，可选) — 执行分组的轴。支持的值为 0 或 1。
  • dynamic_config (dict, 可选) — 动态配置的参数。键为层的名称标签，值为量化配置。 如果设置，则由 id 指定的每个层将使用其专用的量化配置。
  • skip_modules (list[str]，可选，默认为 ['lm_head']) — 要跳过的 nn.Linear 层列表。
  • kwargs (dict[str, Any]，可选) — 用于初始化配置对象的额外参数。

这是 hqq 的 BaseQuantizeConfig 的封装。

from_dict

< >

( config: dict[str, typing.Any] )

Override from_dict, used in AutoQuantizationConfig.from_dict in quantizers/auto.py

post_init

< >

( )

用于检查参数是否正确的安全检查器——同时会将某些 NoneType 参数替换为其默认值。

to_diff_dict

< >

( ) → dict[str, Any]

返回值

dict[str, Any]

构成此配置实例的所有属性的字典，

移除 config 中对应于默认配置属性的所有属性，以提高可读性，并将其序列化为 Python 字典。

MetalConfig

class transformers.MetalConfig

< >

( bits: int = 4group_size: int = 64modules_to_not_convert: list | None = Nonedequantize: bool = False**kwargs )

针对 Apple Silicon (MPS) 设备的 Metal 仿射量化配置类。

该量化方法使用 Hugging Face Hub 上的 mlx-quantization-metal-kernels Metal 内核，执行具有可配置位宽和分组大小的仿射量化（scales + qbiases）。 量化后的权重被打包为 uint32 张量，前向传播使用融合的 dequantization + matmul Metal 内核。

Mxfp4Config

类 transformers.Mxfp4Config

< >

( modules_to_not_convert: list | None = Nonedequantize: bool = False**kwargs )

参数

  • modules_to_not_convert (list，可选，默认为 None) — 不进行量化的模块列表，适用于那些明确要求某些模块保持原始精度的模型量化场景。
  • dequantize (bool，可选，默认为 False) — 是否将模型反量化为 bf16 精度

这是一个封装类，涵盖了使用 mxfp4 量化加载的模型中所有可操作的属性和功能。

NVFP4Config

class transformers.NVFP4Config

< >

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

参数

  • modules_to_not_convert (list[str]，可选) — 应保持原始精度的模块名称模式。
  • kwargs (dict[str, Any]，可选) — 其他值将被忽略，并通过 Transformers 日志记录器报告。

用于即时 NVFP4 权重量化的配置。

FbgemmFp8Config

class transformers.FbgemmFp8Config

< >

( activation_scale_ub: float = 1200.0modules_to_not_convert: list | None = None**kwargs )

参数

  • activation_scale_ub (float，可选，默认为 1200.0) — 激活值的缩放上限。在量化输入激活值时使用此参数。
  • modules_to_not_convert (list，可选，默认为 None) — 不进行量化的模块列表，适用于那些明确要求某些模块保持原始精度的模型量化场景。

这是一个封装类，涵盖了使用 fbgemm fp8 量化加载的模型中所有可操作的属性和功能。

CompressedTensorsConfig

class transformers.CompressedTensorsConfig

< >

( 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 浮点百分比
  • 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 会在第一次前向传播时对其进行解压缩。
  • use_optimized_inference (bool，可选，默认为 False) — 当设置为 True 时，对于已有对应 kernel 的方案，相关层将保留其量化权重并通过这些 kernel 执行（目前支持 W8A8 FP8，适用于 CUDA SM89+、XPU，或 torch >= 2.15 的 MPS）。仅用于推理，且需显式启用：若未启用，模型将走常规的 compressed-tensors 路径。当 dequantize=True 时，此参数将被忽略。

这是一个处理 compressed-tensors 量化配置选项的包装类。 它是 compressed_tensors.QuantizationConfig 的包装器。

from_dict

< >

( config_dictreturn_unused_kwargs = False**kwargs ) → QuantizationConfigMixin

参数

  • config_dict (dict[str, Any]) — 用于实例化配置对象的字典。
  • return_unused_kwargs (bool，可选，默认为 False) — 是否返回未使用的关键字参数列表。用于 PreTrainedModel 中的 from_pretrained 方法。
  • kwargs (dict[str, Any]) — 用于初始化配置对象的额外参数。

返回值

QuantizationConfigMixin

由这些参数实例化的配置对象。

从 Python 参数字典实例化一个 CompressedTensorsConfig。 可选地，解包嵌套的 quantization_config 中的任何参数。

to_dict

< >

( )

要添加到 config.json 中的量化配置

将此实例序列化为 Python 字典。返回：dict[str, Any]：包含此配置实例所有属性的字典。

to_diff_dict

< >

( ) → dict[str, Any]

返回值

dict[str, Any]

构成此配置实例的所有属性的字典，

移除 config 中对应于默认配置属性的所有属性，以提高可读性，并将其序列化为 Python 字典。

TorchAoConfig

class transformers.TorchAoConfig

< >

( quant_type: AOBaseConfigmodules_to_not_convert: list | None = Noneinclude_input_output_embeddings: bool = Falseuntie_embedding_weights: bool = False**kwargs )

参数

  • quant_type (AOBaseConfig) — 一个 torchao AOBaseConfig 实例，用于指定量化类型，例如 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) — 在量化与权重共享的输入嵌入权重时，是否解除权重绑定。

用于 torchao 量化/稀疏技术的配置类。

示例：

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
)

from_dict

< >

( config_dictreturn_unused_kwargs = False**kwargs )

从字典创建配置。

get_apply_tensor_subclass

< >

( )

返回要应用的量化配置。

post_init

< >

( )

验证配置并设置默认值。

to_dict

< >

( )

将配置转换为字典。

BitNetQuantConfig

class transformers.BitNetQuantConfig

< >

( 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") — 要使用的线性层类型。可以是 bitlinear 或 autobitlinear。
  • quantization_mode (str, 可选，默认为 "offline") — 要使用的量化模式。可以是 online 或 offline。 在 online 模式下，权重量化参数会在每次前向传播过程中动态计算（例如，基于当前的权重值）。这可以适应训练过程中的权重变化（量化感知训练 - QAT）。 在 offline 模式下，量化参数会在推理之前预先计算。这些参数随后被固定并加载到量化模型中。与在线量化相比，这通常能带来更低的运行时开销。
  • use_rms_norm (bool，可选，默认为 False) — 是否在量化前对激活值应用 RMSNorm。这与原始 BitNet 论文中在量化/打包前对激活值进行归一化的方法一致。
  • rms_norm_eps (float，可选，默认值为 1e-06) — RMSNorm 层中用于数值稳定性的 epsilon 值。
  • kwargs (dict[str, Any], 可选) — 可供特定量化后端或未来版本使用的其他关键字参数。

用于应用 BitNet 量化的配置类。

post_init

< >

( )

用于检查参数是否正确

SpQRConfig

class transformers.SpQRConfig

< >

( bits: int = 3beta1: int = 16beta2: int = 16shapes: dict[str, int] | None = Nonemodules_to_not_convert: list[str] | None = None**kwargs )

参数

  • bits (int，可选，默认为 3) — 指定权重以及一阶零点（zero-points）和缩放因子（scales）的位数。 目前仅支持 bits = 3。
  • beta1 (int，可选，默认为 16) — SpQR 瓦片宽度。目前仅支持 beta1 = 16。
  • beta2 (int，可选，默认为 16) — SpQR 瓦片高度。目前仅支持 beta2 = 16。
  • shapes（Optional，可选）— 一个字典，用于保存每个对象的形状。我们需要它，因为仅凭 bits、beta1 和 beta2 无法推断出参数的确切大小。
  • modules_to_not_convert (Optional[list[str]]，可选) — 可选地，提供一个 nn.Linear 权重参数的完整路径列表，这些参数不应被量化。 默认为 None。
  • kwargs (dict[str, Any]，可选) — 用于初始化配置对象的额外参数。

这是一个关于 spqr 参数的包装类。有关更多详细信息，请参阅原始出版物。

post_init

< >

( )

用于检查参数是否正确的安全检查器——同时会将某些 NoneType 参数替换为其默认值。

FineGrainedFP8Config

class transformers.FineGrainedFP8Config

< >

( activation_scheme: str = 'dynamic'weight_block_size: tuple[int, int] = (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) — 是否在加载模型时进行反量化。
  • modules_to_not_convert (list, 可选) — 在量化过程中不应进行转换的模块名称列表。
  • modules_to_convert (list, 可选) — 在量化过程中需要转换的额外模块名称列表，例如嵌入表。
  • scale_fmt (str，可选，默认为 "float") — 每个块权重缩放的存储数据类型："float"（fp32，V3 风格）或 "ue8m0"（1 字节 torch.float8_e8m0fnu，V4 风格）。
  • expert_dtype (str，可选，默认为 "fp8") — MoE 专家权重的格式："fp8"，或针对 DeepSeek-V4 的 FP4 打包专家使用 "fp4"。

FineGrainedFP8Config 是用于细粒度 FP8 量化的配置类，主要用于 deepseek 模型。

post_init

< >

( )

用于检查参数是否正确

QuarkConfig

class transformers.QuarkConfig

< >

( **kwargs )

FourOverSixConfig

class transformers.FourOverSixConfig

< >

( 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，则会始终保留高精度权重，并在每次前向传播中在线量化权重。这对于量化训练非常有用。
  • matmul_backend (str, 可选) — 用于矩阵乘法的后端。可以是 "cutlass" 或 "pytorch"。如果未提供，则优先使用 CUTLASS（如果可用），否则使用 PyTorch。
  • output_dtype (str，可选，默认为 "bfloat16") — 用于该层输出的数据类型。可以是 "bfloat16" 或 "float16"。
  • quantize_backend (str, 可选) — 用于量化的后端。可以是 "cuda"、"triton" 或 "pytorch"。如果未提供，将根据您的环境以及各后端支持的选项自动选择最快的后端。通常，"cuda" 用于推理，"triton" 用于训练，而 "pytorch" 用于非 CUDA 设备。
  • scale_rule (str，默认值为 “mse”，可选，默认为 "mse") — 用于选择块缩放的规则。对于 Four Over Six，可以是 "mse"、"mae" 或 "abs_max"；对于默认的 NVFP4 量化，可以是 "static_6"；或者使用 "static_4" 将所有块缩放到最大值为 4。
  • weight_dtype (str, 可选) — 量化权重张量时使用的数据类型。如果未提供，则使用 dtype。
  • weight_scale_2d (bool，默认 False，可选，默认为 False) — 是否以 2D 块为单位计算权重张量的缩放因子。此操作应在训练期间执行。
  • 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 是对 NVFP4 量化的一种改进，它会将每个包含 16 个 FP4 值的块中的最大值自适应地缩放到 4 或 6。选择缩放因子 6 会利用 FP4 值的完整范围，而选择缩放因子 4 则能使量化误差的分布更加均匀。更多详情请参阅原始论文：https://arxiv.org/abs/2512.02010。

FPQuantConfig

class transformers.FPQuantConfig

< >

( 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") — 前向传播所使用的 dtype。
  • forward_method (str，可选，默认为 "abs_max") — 前向传播所使用的缩放方式。可以是 "abs_max" 或 "quest"。"abs_max" 更适合 PTQ，"quest" 更适合 QAT。
  • backward_dtype (str，可选，默认为 "bf16") — 反向传播所使用的 dtype。
  • store_master_weights (bool，可选，默认为 False) — 是否存储主权重。对层权重进行 QAT 时需要此设置。
  • hadamard_group_size (int, 可选) — "quest" 在量化前进行 hadamard 变换时的分组大小，与 MXFP4 的分组大小（32）一致。如果为 None，则对于 "nvfp4" 会设置为 16，对于 "mxfp4" 会设置为 32。
  • pseudoquantization（bool，可选，默认为 False）— 是否使用基于 Triton 的伪量化。对于非 Blackwell GPU 是必需的。不会带来任何加速效果。仅用于调试目的。
  • transform_init（str，可选，默认为 "hadamard"）——用于初始化预处理矩阵的方法。可以是 "hadamard"、"identity" 或 "gsr"。
  • modules_to_not_convert (list, 可选) — 不进行量化的模块列表，适用于量化那些明确要求某些模块保持原始精度的模型。

FPQuantConfig 是使用 FPQuant 方法进行量化的配置类。

post_init

< >

( )

用于检查参数是否正确的安全检查器——同时会将某些 NoneType 参数替换为其默认值。

AutoRoundConfig

class transformers.AutoRoundConfig

< >

( 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 量化加载的模型时，您可以操作的所有可能属性和功能。

post_init

< >

( )

用于检查参数是否正确。

SinqConfig

类 transformers.SinqConfig

< >

( 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

< >

( gguf_file: str | None = Nonedequantize: bool = False**kwargs )

参数

  • gguf_file (str, 可选) — 保存权重的 .gguf 文件的路径。如果通过 from_pretrained(..., gguf_file=...) 指定了该名称，则可以省略此项，该参数会自动填充。
  • dequantize (bool，可选，默认为 False) — 在加载时将每个权重解包为普通的稠密模型。这种方式始终正确，但会放弃内存节省；当文件中量化类型没有可用的 matmul 内核时，也会自动回退到此方式。

加载量化后的 GGUF 检查点，并将其权重保留在 GGUF 块中。

Update on GitHub

←导出器 分词器→