Transformers 量化配置全景指南：从 BitsAndBytes 到 HfQuantizer 的源码级解析

Transformers 量化配置全景指南从 BitsAndBytes 到 HfQuantizer 的源码级解析【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers量化Quantization通过将权重与激活以 8-bit 整数int8、4-bit 等更低精度的数据类型表示显著降低模型的内存占用与计算开销让原本放不进显存的大模型可以被加载推理并加速推理过程。这篇指南以 docs/source/en/main_classes/quantization.md 为骨架系统讲解 Transformers 当前内置的全部量化配置类Quanto、AQLM、VPTQ、AWQ、EETQ、GPTQ、bitsandbytes、HIGGS、HQQ、Metal、MXFP4、NVFP4、FBGEMM-FP8、CompressedTensors、TorchAO、BitNet、SpQR、FineGrainedFP8、Quark、FourOverSix、FPQuant、AutoRound、SINQ以及量化器抽象基类HfQuantizer并结合 量化配置源码 与 量化器实现目录 展开参数含义与底层调用链。读完本文你将掌握每一种内置量化方案的配置参数与适用场景、如何通过quantization_config在from_pretrained中加载量化模型、以及如何基于HfQuantizer为 Transformers 尚未原生支持的量化算法编写自定义量化器。量化在 Transformers 中的总体架构Transformers 的量化生态围绕两个核心概念展开量化配置Quantization Config一类以quant_method字段标识算法的配置对象绝大多数继承自 QuantizationConfigMixin。它定义了如何量化的全部参数并可通过to_json_file()/to_json_string()序列化进模型的config.json。量化器HfQuantizer一个插入到PreTrainedModel.from_pretrained加载流程中的抽象类负责把配置落地为真实的模块替换、权重转换与环境校验参见 quantizers/base.py。配置与量化器之间由自动分发表连接。quantizers/auto.py 中的AUTO_QUANTIZER_MAPPING将每个量化方法与具体的量化器类一一对应如gptq→GptqHfQuantizer、bitsandbytes_4bit→Bnb4BitHfQuantizerAUTO_QUANTIZATION_CONFIG_MAPPING 则完成quant_method字符串到配置类的映射。当你在from_pretrained中传入quantization_config参数时底层会经由 get_hf_quantizer() 完成配置合并、环境校验validate_environment、设备映射调整与张量并行计划更新从而把模型改造成量化版本。从文件布局看QuantizationMethod 枚举集中登记了bitsandbytes、gptq、awq、quanto、torchao、mxfp4、sinq等全部受支持的量化算法标识。用户在from_pretrained中手动传入的配置对象quantization_config参数和模型自身config.json中已存储的量化配置pre_quantizedTrue会经过merge_quantization_configs合并后者会以模型自带配置为主、以用户传入的加载属性如backend、dequantize覆盖部分字段。经典算法配置bitsandbytes 的 8-bit 与 4-bitBitsAndBytesConfig 是所有配置类中应用最广泛的一个它同时承载LLM.int8()8-bit 量化与 FP4/NF4 4-bit 量化两种能力。其构造约束值得注意load_in_4bit与load_in_8bit不能同时为True源码会在__init__与两个 setter 中同时校验并抛出ValueError。8-bitLLM.int8()参数参数默认值含义load_in_8bitFalse是否启用 LLM.int8() 8-bit 量化llm_int8_threshold6.0离群值检测阈值。hidden states 中超过该值的元素视为离群值其计算回退到 fp16。论文观测到大模型权重大多服从 [-3.5, 3.5] 分布但有少数系统性离群值落在 [-60,-6] 或 [6,60]int8 对量级约 5 的值效果良好超出后性能显著下降。小模型或微调等不稳定模型可能需要更低阈值llm_int8_skip_modulesNone不希望转成 8-bit 的模块显式列表例如 CausalLM 的lm_head保持原 dtypellm_int8_enable_fp32_cpu_offloadFalse高级用法将模型拆分部分在 GPU 上跑 int8、部分在 CPU 上跑 fp32适合google/flan-t5-xxl这类超大模型注意 int8 运算不会在 CPU 上执行llm_int8_has_fp16_weightFalse使用 16-bit 主权重运行 LLM.int8()便于微调反向传播无需反复转换权重4-bitFP4/NF4参数参数默认值含义load_in_4bitFalse是否将 Linear 层替换为 bitsandbytes 的 FP4/NF4 4-bit 层bnb_4bit_compute_dtypetorch.float32计算类型可与输入类型不同。例如输入 fp32、计算设为 bf16 以获得加速bnb_4bit_quant_typefp4量化数据类型可取值fp4或nf4bnb_4bit_use_double_quantFalse嵌套量化double quantization对第一次量化的量化常数再次量化进一步省显存bnb_4bit_quant_storagetorch.uint8打包 4-bit 参数的存储类型字符串取值可为float16/float32/int8/uint8/float64/bfloat16代码层面的细节可以给实战提供重要参考bnb_4bit_compute_dtype与bnb_4bit_quant_storage在源码中做了严格的类型清洗——传入字符串时通过getattr(torch, ...)解析为torch.dtype非法字符串直接抛错quantization_method()方法会根据开关返回llm_int8、fp4或nf4而post_init()对每个参数做类型检查如llm_int8_threshold必须是 float。一个值得留意的设计是单靠设置quantization_configBitsAndBytesConfig(...)而两个 load 开关都为 False 时is_quantizable()返回 False模型不会被量化。典型的 4-bit NF4 加载方式如下from transformers import AutoModelForCausalLM, BitsAndBytesConfig import torch quantization_config BitsAndBytesConfig( load_in_4bitTrue, bnb_4bit_quant_typenf4, bnb_4bit_compute_dtypetorch.bfloat16, bnb_4bit_use_double_quantTrue, ) model AutoModelForCausalLM.from_pretrained( meta-llama/Llama-3-8B, quantization_configquantization_config, device_mapauto, )权重压缩算法GPTQ 与 AWQGPTQ 与 AWQ 是两种先离线校准、再以低比特表示权重的经典方法这类方法通常在量化前需要一批校准数据其量化动作本身多数由optimum/gptqmodel、auto-awq生态完成Transformers 侧的配置类负责描述参数并在加载时正确解析预量化 checkpoint。GPTQConfigGPTQConfig 完整参数如下bits必填支持 2/3/4/8量化位宽post_init()会校验tokenizer处理数据集用的分词器可传自定义对象、模型 id 或本地目录dataset量化用的数据集字符串仅支持[wikitext2,c4,c4-new]或自定义字符串列表group_size默认 128量化分组大小推荐 128-1表示按列per-column量化必须 0 或等于 -1damp_percent默认 0.1用于阻尼的 Hessian 对角均值百分比取值必须在 (0, 1)desc_act默认 False是否按激活大小降序量化列act-order设为 False 可显著加速推理但困惑度可能略变差act_group_aware默认 Truedesc_actFalse时启用 GARgroup aware activation order提升量化质量当desc_actTrue时源码会自动将其强制关闭并打印 warningsym默认 True是否对称量化true_sequential默认 True在单个 Transformer block 内也按层序量化——每个后续层使用已经过量化层处理的输入format默认gptq权重格式gptq(v1) 由 gptqmodel 支持gptq_v2为 gptqmodel 独有兼容旧字段checkpoint_formatbackend默认 None最终回落为auto选择推理 kernelmodel_seqlen模型能处理的最大序列长度block_name_to_quantize要量化的 block 名为 None 时用常见模式如model.layers推断module_name_preceding_first_block第一个 Transformer block 之前的层batch_size默认 1、pad_token_idbatch_size1 时数据准备需要、max_input_lengthexllama act-order 后端初始化缓冲需要cache_block_outputs默认 True缓存 block 输出供下一 block 复用modules_in_block_to_quantizeblock 内要按顺序量化的模块子列表用于精细控制量化范围需要 optimum ≥ 1.15.0源码中做了版本强校验。加载一个已用 GPTQ 量化好的模型from transformers import AutoModelForCausalLM, GPTQConfig quantization_config GPTQConfig(bits4, datasetc4, tokenizertokenizer) model AutoModelForCausalLM.from_pretrained( model-id, device_mapauto, quantization_configquantization_config, )AwqConfigAwqConfig 直接继承GPTQConfig以复用其骨架并补充 AWQ 特有字段bits默认 4、group_size默认 128语义同 GPTQzero_point默认 True是否使用零点量化backend默认AwqBackend.AUTO后端枚举见 AwqBackend取值包括auto、auto_trainable、machete、marlin、exllama_v2/exllama_v1、gemm/gemm_triton、gemv/gemv_fast、torch_awq/torch_fused_awq等旧的LEGACY_AWQ即autoawq会被自动映射为AUTOformat隐藏于 kwargs默认gemm权重布局格式AwqFormat 枚举值为gemm、gemv、gemv_fast、llm-awq兼容旧字段versionmodules_to_not_convert默认 None保持原精度的模块列表对需要保留部分模块精度的模型非常有用如 Whisper encoder、Llava encoder、Mixtral gate 层。需要特别提醒源码 docstring 明确说明Transformers 不直接执行 AWQ 量化需要参考 AutoAWQ 的文档先完成模型量化Transformers 负责加载这些预量化 checkpoint。训练后量化PTQ与动态量化配置QuantoConfigQuantoConfig 面向quanto库属于训练后量化方案weights默认int8权重量化目标类型仅支持float8、int8、int4、int2activations默认 None激活量化目标类型仅支持 None、int8、float8modules_to_not_convert保持原精度的模块列表。源码的post_init()会对weights与activations的取值做白名单校验。EetqConfigEetqConfig 使用eetq库weights目前仅支持int8另有modules_to_not_convert。它提供的是无需校准数据、直接运行的 8-bit 参考实现路径。FbgemmFp8ConfigFbgemmFp8Config 使用 fbgemm FP8 量化核心参数activation_scale_ub默认 1200.0用于输入激活量化时的激活缩放上界modules_to_not_convert控制跳过模块。它通过get_loading_attributes()暴露activation_scale_ub作为加载期属性可在from_pretrained时被覆盖。面向新兴硬件的低比特方案HIGGS、MXFP4、NVFP4、FourOverSix、FPQuant、Metal这一类配置围绕新一代低比特数据格式如 FP4、MXFP4、NVFP4与特定硬件Blackwell、Apple Silicon展开。HiggsConfigHiggsConfigbits默认 4可为 2、3、4p默认 2量化网格维度仅 1 或 2 被支持实践中 p2 效果更好modules_to_not_convert默认含lm_headhadamard_size默认 512HIGGS 方法的 Hadamard 尺寸矩阵输入维度会 padding 到该值低于 512 会降低量化质量group_size默认 256可为 64/128/256且必须整除hadamard_size源码强制校验tune_metadata保存 kernel 调优结果的模块级元数据gemm block 形状、GPU 元数据等调优时自动写入。Mxfp4ConfigMxfp4Config 面向 mxfp4 格式仅有modules_to_not_convert与dequantize默认 False两个关键参数。dequantizeTrue表示加载时把模型反量化回 bf16此时通过get_loading_attributes()传递dequantize作为加载属性。NVFP4ConfigNVFP4Config 用于加载时即时on-the-fly的 NVFP4 权重量化仅提供modules_to_not_convert额外 kwargs 会被忽略并打印日志。它与下面的 FourOverSix/FPQuant 属于相邻但侧重点不同的方案。FourOverSixConfigFourOverSixConfig 是对 NVFP4 量化的改进——每个 16 个 FP4 值的块内自适应地把最大值缩放到 4 或 6取 6 用满 FP4 取值范围取 4 则量化误差分布更均匀。参数非常丰富dtype默认nvfp4层权重/激活的数据类型可为nvfp4或mxfp4scale_rule默认mse块缩放规则可为mse、mae、abs_maxFourOverSix或static_6标准 NVFP4、static_4所有块最大值限制为 4activation_dtype/activation_scale_rule/weight_dtype/weight_scale_rule/gradient_dtype/gradient_scale_rule分别为激活、权重、梯度指定类型与缩放规则缺省回落到dtype或scale_ruleoutput_dtype默认bfloat16层输出类型可为bfloat16或float16keep_master_weights默认 False保留高精度主权重并在每次前向中在线量化用于量化训练weight_scale_2d默认 False训练期间对权重按 2D block 计算缩放quantize_backend可选cuda通常用于推理、triton通常用于训练、pytorch非 CUDA 设备缺省自动选择matmul_backend可选cutlass或pytorchmodule_config_overrides按模块名覆盖默认量化配置modules_to_not_convert默认[lm_head]。FPQuantConfigFPQuantConfig 是用于 QAT/PTQ 的 4-bit 浮点量化配置forward_dtype默认nvfp4前向数据类型目前仅支持mxfp4与nvfp4forward_method默认abs_max前向缩放方式abs_max更适合 PTQ、quest更适合 QATnvfp4 只允许abs_maxbackward_dtype默认bf16反向类型支持bf16/mxfp8/mxfp4且非 bf16 反向目前仅兼容 mxfp4 前向store_master_weights默认 False对层权重做 QAT 时是否需要保存主权重hadamard_group_size量化前 Hadamard 变换的分组大小缺省时 nvfp4 取 16、mxfp4 取 32pseudoquantization默认 False使用基于 Triton 的伪量化非 Blackwell GPU 上必须开启无加速、仅调试用transform_init默认hadamard预处理矩阵初始化方式可为hadamard、identity、gsrmodules_to_not_convert缺省自动设为[lm_head]。MetalConfigMetalConfig 面向 Apple SiliconMPS设备使用来自 Hub 的mlx-quantization-metal-kernelsMetal kernel 做仿射量化scales qbiases量化权重打包成uint32张量前向走融合反量化 matmul 的 Metal kernelbits默认 4支持 2/4/8group_size默认 64必须为正modules_to_not_convert、dequantize默认 False。稀疏与混合方案AQLM、VPTQ、SpQR、BitNet、FineGrainedFP8、SINQAqlmConfigAqlmConfig 基于 AQLMAdditive Quantization of Language Models方法in_group_size默认 8输入维度的分组大小out_group_size默认 1输出维度分组大小官方建议恒为 1num_codebooks默认 1加性量化Additive Quantization过程的码本数量nbits_per_codebook默认 16单个码本向量编码比特数码本大小为 2^bitslinear_weights_not_to_quantize保持不量化的nn.Linear权重完整路径列表。VptqConfigVptqConfig 面向 VPTQVector Post-Training Quantizationenable_proxy_error默认 False是否计算每层代理误差——源码目前强制其为 Falseconfig_for_layers每层量化参数字典值由 VptqLayerConfig 描述enable_norm、enable_perm、group_num、group_size、num_centroids、num_res_centroids、vector_lens、outlier_size等shared_layer_config层间共享的量化参数modules_to_not_convert不量化的模块如 Whisper encoder 等需保持原精度的部分。SpQRConfigSpQRConfig 支持 SpQR 方法的 checkpoint 加载。当前实现非常专一bits仅支持 3、beta1与beta2均仅支持 16SpQR tile 宽/高三者不匹配即抛错另有shapes由于仅凭 bits/beta 无法推导各对象精确尺寸需显式给出形状字典与modules_to_not_convert。BitNetQuantConfigBitNetQuantConfiglinear_class默认bitlinear可为bitlinear或autobitlinearquantization_mode默认offlineonline模式每次前向动态计算权重量化参数可适应训练中权重变化QAToffline模式在推理前预计算量化参数并固定加载运行时开销更低modules_to_not_convert不量化的模块use_rms_norm默认 False量化前对激活做 RMSNorm对齐 BitNet 原论文做法rms_norm_eps默认 1e-6。FineGrainedFP8ConfigFineGrainedFP8Config 主要用于 DeepSeek 系列模型的细粒度 FP8 量化同时兼容 MiniMax会把ignored_layers视为modules_to_not_convert的别名activation_scheme默认dynamic激活量化方案目前仅dynamic与static被支持weight_block_size默认(128, 128)权重块大小两个正整数dequantize默认 False加载时是否反量化模型modules_to_not_convert不转换的模块scale_fmt默认float逐块权重缩放因子的存储格式floatfp32V3 风格或ue8m01 字节torch.float8_e8m0fnuV4 风格。从 quantizers/auto.py 可以看到fp8、mxfp8都复用了FineGrainedFP8HfQuantizer即 MXFP8E4M3 权重 逐块 [1,32] E8M0 缩放与 FP8 共用同一条反量化加载管线。SinqConfigSinqConfignbits默认 4权重量化比特数group_size默认 64SINQ 分组大小需为 8 的倍数源码仅给 warning后端可能拒绝tiling_mode默认1DSINQ 平铺模式method默认sinqsinq表示免校准的 weight-only SINQasinq激活感知 A-SINQ在 HF 中不被支持modules_to_not_convert保持全精度的模块名/前缀。开放生态桥接配置CompressedTensors、TorchAO、AutoRound、HQQ、Quark这些配置面向上游成熟生态如 Neural Magic 的 compressed-tensors、PyTorch 官方 torchao、Intel 的 auto-round、mobiusml 的 HQQ、AMD 的 QuarkTransformers 通过薄封装把 checkpoint 语义翻译到自身加载流程。CompressedTensorsConfigCompressedTensorsConfig 是compressed_tensors.QuantizationConfig的包装导入时需要compressed-tensors0.15.0config_groups把 group 名映射到量化方案定义QuantizationScheme或层列表的字典format默认dense权重存储格式如dense、float-quantized、pack-quantizedquantization_status默认initialized模型量化生命周期状态initialized/calibration/frozen/compressedkv_cache_schemeKV 缓存量化方案None 表示不量化 KV 缓存global_compression_ratio0-1 的模型压缩比例ignore不量化的层名或类型支持re:前缀的正则dequantize默认 False为 True 时加载期把量化权重反量化回模型 dtype如 BF16适合微调或以原 dtype 保存为 False 时保持压缩形式、首个前向时由 compressed-tensors 解压use_optimized_inference默认 False对已有专用 kernel 的层当前为 W8A8 FP8需 CUDA SM89 或 XPU走优化 kernel仅推理、需主动开启dequantizeTrue时自动忽略。源码中的post_init()与has_fp8_modules属性体现了严格的自我保护若 checkpoint 实际未压缩却要求压缩执行会强制回退到dequantizeTrue若声称开启优化推理但无 FP8 模块也会自动关闭。TorchAoConfigTorchAoConfig 的用法与其它配置类不同——quant_type直接接收一个 torchao 的AOBaseConfig实例不再是字符串from transformers import AutoModelForCausalLM, TorchAoConfig from torchao.quantization import Int4WeightOnlyConfig import torch quantization_config TorchAoConfig(Int4WeightOnlyConfig(group_size32)) model AutoModelForCausalLM.from_pretrained( model_id, device_mapcuda, torch_dtypetorch.bfloat16, quantization_configquantization_config, )modules_to_not_convert不量化的模块include_input_output_embeddings默认 False是否量化 embedding开启后输入 embedding 也会从免量化列表移除untie_embedding_weights默认 False量化与其它权重 tied 的输入 embedding 时是否解开权重。post_init()会校验torchao已安装、quant_type确为AOBaseConfig实例序列化时通过config_to_dict/config_from_dict与 torchao 双向转换实现配置随config.json持久化与回读。AutoRoundConfigAutoRoundConfigbits默认 4支持 2/3/4/8group_size默认 128、sym默认 Truebackend默认auto推理后端默认根据设备、量化设置与已装库自动选择。其from_dict允许把gptq/awqgemm 版/auto-round格式的 checkpoint 转换加载为 AutoRound 推理格式packing_format会相应改写这一兼容逻辑也对应 merge_quantization_configs 中 AutoRoundConfig 优先分发的特判。HqqConfigHqqConfig 是 hqqBaseQuantizeConfig的包装需要hqq0.2.1nbits默认 4支持 8/4/3/2/1group_size默认 64需能整除weight.shape[axis]view_as_float默认 False分布式训练时把量化权重视为 floataxis默认 None构造时自动置 1分组沿哪个轴仅 0/1 合法axis1 兼容 TorchAO/BitBlas 等更快后端dynamic_config逐层自定义量化配置键为层名值为完整量化参数skip_modules默认[lm_head]跳过的nn.Linear层列表。QuarkConfigQuarkConfig 面向 AMD Quark需amd-quark0.12。它较为特殊不提供显式的构造函数参数而是整体把 kwargs 透传给 Quark 生态去解析——quant_method取fp8/awq等值时走QuantConfigParser.from_custom_config老式路径否则走QConfig.from_dict新式路径并额外解析export段如min_kv_scale需 quark≥0.8。扩展点HfQuantizer 抽象类与自定义量化方案quantization.md 明确指出Transformers 尚未支持的量化技术可以通过HfQuantizer类接入。所有内置量化器quantizer_*.py 系列都是它的具体实现。HfQuantizer 定义了量化器在from_pretrained生命周期中的完整钩子类属性requires_calibration默认 False是否需要先校准属性is_trainable、is_serializable、is_qat_trainable、is_compileable后两者默认 False均为抽象或固定默认__init__接收quantization_config与pre_quantized权重是否已量化若要求校准却传入pre_quantizedFalse会直接报错validate_environment校验环境与from_pretrained传入参数是否冲突update_dtype/update_device_map部分方法需要强制设定 dtypebitsandbytes 则在没有 device_map 时自动补为autoupdate_tp_plan/update_ep_plan为缩放因子更新张量并行/专家并行计划preprocess_model/postprocess_model分别在权重加载前后改造模型实际工作放在_process_model_before_weight_loading/_process_model_after_weight_loading两个可覆写方法中dequantize尽力恢复原始精度模型部分方案不支持get_state_dict_and_metadata、get_quantize_ops、get_weight_conversions为自定义权重加载管线renamings → converters → dequant/merge/concat提供改写入口静态方法get_modules_to_not_convert结合 skip 列表、fp32 保留模块与默认跳过规则生成不量化模块清单。模块级工具函数 get_keys_to_not_convert() 会自动推导默认保留模块tied 权重、最后一个参数模块、输出 embedding典型如lm_head。此外 base.py 底部还维护了 MODULES_TO_PATCH_FOR_QUANTIZATION 注册表用于把特定模块类如 MoE 中的Llama4TextExperts在 meta 设备上原地替换为压缩实现SequentialLlama4TextExperts。若要接入一种全新的量化方法标准的扩展路径是定义一个继承QuantizationConfigMixin的 dataclass设置quant_method实现参数校验与可选get_loading_attributes()编写继承HfQuantizer的量化器实现is_serializable、is_trainable、validate_environment、_process_model_before_weight_loading等使用 register_quantization_config() 与 register_quantizer() 注册到自动分发映射中注册要求分别继承QuantizationConfigMixin与HfQuantizer。如何选择与使用选择量化方案时可参考 docs/source/en/quantization/overview.md 与 docs/source/en/quantization/selecting.md 的总体决策框架本文仅从配置类特性给出判断要点希望开箱即用地压缩权重并显著省显存优先考虑 bitsandbytes 4-bitload_in_4bitTrueNF4 double quant无需离线校准数据追求低比特极致压缩且可接受离线校准GPTQ/AWQ 是社区生态最成熟的方案配套文档见 quantization/gptq.md 与 quantization/awq.md面向特定硬件与格式Apple Silicon 看MetalConfigmetal.mdBlackwell 场景关注FPQuantConfig/FourOverSixConfig/NVFP4ConfigMX 格式生态看Mxfp4Configmxfp4.md、nvfp4.md、fouroversix.md模型自带预量化配置直接from_pretrained即可框架会自动从config.json的quantization_config字段解析出对应配置类与量化器pre_quantizedTrue路径并在加载后用validate_environment检查当前环境是否满足要求如 CUDA 能力、依赖版本。需要明确的能力边界本文描述的是当前仓库 transformers 中已实现的量化生态。不同配置类背后依赖的第三方库bitsandbytes、auto-awq、gptqmodel、torchao、compressed-tensors、hqq、eetq、quark等需要在环境中按各自要求安装对应版本且部分 kernel 方案有明确的 GPU 架构前提如 FP8 优化推理要求 CUDA SM89 或 XPU。建议在动手前先确认目标硬件与依赖版本再依据上文各配置类的取值约束完成参数设定。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考