Transformers documentation

量化

Transformers

快速入门

Transformers 安装快速入门

基类

模型

预处理器

推理

Pipeline API

生成 API

优化

与模型对话

服务

训练

快速入门

自定义

参数高效微调

性能

分布式训练

硬件

量化

生态系统集成

资源

API

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

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 = {}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 参数的包装类。

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 )

如果量化需要额外的内存，请调整 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 )

就地更新 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 = ['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 )

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 = (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

←导出器分词器→