Diffusers 量化 API 完全指南PipelineQuantizationConfig、主流量化后端与 DiffusersQuantizer 架构解析【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers量化Quantization通过用 8-bit 整数int8等低精度数据类型表示权重与激活同时降低显存占用与计算开销是让大型扩散模型如 FLUX、SDXL在消费级 GPU 上得以运行的常用手段。本篇指南以docs/source/en/api/quantization.md所列的量化 API 为骨架深入剖析 Diffusers 量化模块的完整体系从管线级量化入口PipelineQuantizationConfig到BitsAndBytesConfig、GGUFQuantizationConfig、NunchakuLiteQuantizationConfig、QuantoConfig、SDNQConfig、TorchAoConfig等后端配置类再到量化器基类DiffusersQuantizer的生命周期钩子。读完本文你将掌握 Diffusers 量化 API 的每个配置参数、自动分发机制与底层加载流程并能在自己的推理脚本中正确选用和组合量化后端。量化 API 全景quantizers 模块结构与自动分发Diffusers 的量化能力集中在 src/diffusers/quantizers 目录下其模块组织直接对应本 API 文档的条目划分模块文件/目录职责pipe_quant_config.py定义管线级量化配置PipelineQuantizationConfigquantization_config.py定义各后端的配置类BitsAndBytesConfig、TorchAoConfig等与公共基类QuantizationConfigMixinbase.py定义量化器抽象基类DiffusersQuantizerauto.py定义DiffusersAutoQuantizer自动分发器与后端注册表bitsandbytes/、gguf/、torchao/、quanto/、sdnq/、nunchaku/、modelopt/、autoround/各后端的量化器实现从 auto.py 可以看到Diffusers 内部维护两张注册表AUTO_QUANTIZER_MAPPING把量化方法名映射到具体的量化器类AUTO_QUANTIZATION_CONFIG_MAPPING则把方法名映射到对应的配置类。目前注册的后端包括bitsandbytes_4bit/bitsandbytes_8bit→BitsAndBytesConfiggguf→GGUFQuantizationConfigquanto→QuantoConfig已标记弃用见下文torchao→TorchAoConfigmodelopt→NVIDIAModelOptConfigNVIDIA ModelOptFP8/INT8 等auto-round→AutoRoundConfigIntel AutoRoundW4A16 权重量化nunchaku_lite→NunchakuLiteQuantizationConfigsdnq→SDNQConfig每个配置类都通过quant_method字段与 quantization_config.py 中定义的QuantizationMethod枚举绑定该枚举完整列出了所有受支持的量化方法标识符。DiffusersAutoQuantizer.from_pretrained会读取模型config.json中的quantization_config自动实例化正确的配置类与量化器这也是加载预量化 checkpoint 无需手动传参的原理所在。PipelineQuantizationConfig管线级量化统一入口PipelineQuantizationConfig 是 Diffusers 特有的、面向整条 pipeline 的量化配置类用于在DiffusionPipeline.from_pretrained加载模型时对管线内的多个组件transformer、text encoder 等按需量化。构造函数参数参数类型说明quant_backendstr量化后端名称要求该后端在diffusers与transformers中同时可用如bitsandbytes_4bit、torchao等即上文注册表键名quant_kwargsdict传递给量化后端配置类的初始化参数components_to_quantizelist[str] \| str需要量化的 pipeline 组件名列表传单个字符串时内部会包装成列表不传则默认量化全部组件quant_mappingdict[str, config]逐组件指定量化配置的精细映射键为组件名值为 diffusers 或 transformers 的量化配置实例这四个参数的使用存在严格的约束post_init中的_validate_init_args会执行以下校验见 pipe_quant_config.pyquant_backend与quant_mapping不能同时指定二者至少提供一个否则报错指定quant_backend时必须同时提供quant_kwargs指定quant_mapping时会逐一校验每个组件映射的配置实例是否属于 diffusers 或 transformers 已知的配置类指定quant_backend时还会通过inspect.signature对比 diffusers 与 transformers 同名配置类__init__的签名是否一致不一致时提示改用quant_mapping。配置内部维护config_mapping字典{module_name: quant_config}用于记录每个组件最终采用的量化配置并有一个is_granular标志区分精细映射模式与全局后端模式见 pipe_quant_config.py。在全局模式下若指定了components_to_quantize则只量化列表内的组件否则量化所有组件。基础用法单一后端统一量化最简单的做法是同时给出quant_backend、quant_kwargs与components_to_quantize官方示例见 量化入门指南以bitsandbytes_4bit后端量化 FLUX.1-dev 的 transformer 与 T5 text encoderimport torch from diffusers import DiffusionPipeline from diffusers.quantizers import PipelineQuantizationConfig pipeline_quant_config PipelineQuantizationConfig( quant_backendbitsandbytes_4bit, quant_kwargs{load_in_4bit: True, bnb_4bit_quant_type: nf4, bnb_4bit_compute_dtype: torch.bfloat16}, components_to_quantize[transformer, text_encoder_2], ) pipe DiffusionPipeline.from_pretrained( black-forest-labs/FLUX.1-dev, quantization_configpipeline_quant_config, dtypetorch.bfloat16, ).to(cuda) # 也可用 mps、xpu、cpu image pipe(photo of a cute dog).images[0]components_to_quantize接受字符串或列表用于指定 pipeline 中计算密集的组件通常优先量化 transformer。quant_kwargs的具体键名随后端不同而变化详见下文各配置类参数。进阶用法quant_mapping 混合多后端quant_mapping允许对同一 pipeline 的不同组件使用不同后端。关键注意点pipeline 中来自 Transformers 的组件如FluxPipeline的text_encoder_2是T5EncoderModel必须使用transformers.BitsAndBytesConfig而 diffusers 自带的组件使用diffusers.BitsAndBytesConfigimport torch from diffusers import DiffusionPipeline from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig from diffusers.quantizers import PipelineQuantizationConfig from transformers import BitsAndBytesConfig as TransformersBitsAndBytesConfig pipeline_quant_config PipelineQuantizationConfig( quant_mapping{ transformer: DiffusersBitsAndBytesConfig(load_in_4bitTrue, bnb_4bit_compute_dtypetorch.bfloat16), text_encoder_2: TransformersBitsAndBytesConfig( load_in_4bitTrue, compute_dtypetorch.bfloat16 ), } ) pipe DiffusionPipeline.from_pretrained( black-forest-labs/FLUX.1-dev, quantization_configpipeline_quant_config, dtypetorch.bfloat16, ).to(cuda)如果不想区分组件来源、或不确定组件属于哪个库直接使用上面的基础用法即可由PipelineQuantizationConfig自动决定用 diffusers 还是 transformers 的配置类对应_resolve_quant_config中的is_diffusers分支见 pipe_quant_config.py。BitsAndBytesConfigLLM.int8 与 4-bitFP4/NF4量化BitsAndBytesConfig 是对bitsandbytes库能力的完整封装取代了旧的load_in_8bit/load_in_4bit参数两者互斥。当前支持LLM.int8()、FP4 与 NF4 三种量化方法完整参数如下参数默认值说明load_in_8bitFalse启用 LLM.int8() 8-bit 量化load_in_4bitFalse启用 4-bit 量化将 Linear 层替换为 bitsandbytes 的 FP4/NF4 层llm_int8_threshold6.0LLM.int8() 的离群值检测阈值绝对值高于该值的隐藏状态按 fp16 计算。权重通常服从正态分布多数值落在 [-3.5, 3.5]但大模型中存在落在 [-60, -6] 或 [6, 60] 区间的系统性离群值int8 对量级 ~5 的值表现良好超出后性能明显下降。不稳定模型小模型、微调中可能需要调低阈值llm_int8_skip_modulesNone不转换为 8-bit 的模块名列表例如保留lm_head的原始精度llm_int8_enable_fp32_cpu_offloadFalse高级用法部分模块在 GPU 上以 int8 运行、部分在 CPU 上以 fp32 运行用于卸载超大模型llm_int8_has_fp16_weightFalse以 16-bit 主权重运行 LLM.int8()微调时避免前向/反向过程中反复转换权重bnb_4bit_compute_dtypetorch.float32计算精度可与输入精度不同例如输入 fp32 而计算用 bf16 加速接受torch.dtype或字符串bnb_4bit_quant_typefp44-bit 量化数据类型可选fp4或nf4bnb_4bit_use_double_quantFalse嵌套量化对第一次量化产生的量化常数再次量化bnb_4bit_quant_storagetorch.uint84-bit 参数的打包存储类型接受字符串float16/float32/int8/uint8/float64/bfloat16或torch.dtype该类的实现细节值得注意源码位于 quantization_config.pyload_in_4bit与load_in_8bit同时为True会直接抛出ValueError且二者作为 property 提供类型校验与互斥 setterpost_init会检查bitsandbytes0.39.04-bit 量化的硬性版本要求quantization_method()依据load_in_8bit/bnb_4bit_quant_type返回llm_int8、fp4或nf4to_dict()序列化时会将 dtype 转换为可 JSON 化的字符串形式。GGUFQuantizationConfigGGUF 预量化格式GGUFQuantizationConfig 是面向 GGUF 量化技术的配置类其设计目标是配合from_single_file加载 GGUF 格式的权重。参数极为精简compute_dtypetorch.dtype默认torch.float32计算精度可与输入精度不同例如输入 fp32 但计算用 bf16 加速。该配置将pre_quantized硬编码为True即只支持加载已经量化好的 GGUF checkpoint不支持运行时在线量化。从 量化入门指南 的对比表可知GGUF 后端通过 Model 类的from_single_file使用暂不支持 pipeline 级加载。NunchakuLiteQuantizationConfigNunchaku Lite 紧凑配置NunchakuLiteQuantizationConfig 用于加载 Nunchaku Lite 预量化 checkpoint。与 GGUF 类似它只支持加载预量化模型pre_quantizedTrue需要借助diffuse-compressor工具链先将模型量化导出为带quantization_config的 Diffusers pipeline。其参数为compute_dtypetorch.dtype默认torch.bfloat16量化模块中浮点缓冲区的运行时精度接受字符串或torch.dtypesvdq_w4a4dictSVDQ W4A4 目标配置包含precision、group_size、rank与targets字段awq_w4a16dictAWQ W4A16 目标配置包含precision、group_size与targets字段。该配置的post_init校验逻辑相当严格svdq_w4a4与awq_w4a16至少提供一个每个节必须包含指定字段且类型正确precision只允许int4或nvfp4group_size必须为正SVDQ 的rank必须非负且precisionnvfp4时强制group_size16、其他精度要求group_size64AWQ 目标必须使用precisionint4。官方文档还给出了一个紧凑型config.json示例见 quantization_config.py{ _class_name: ErnieImageTransformer2DModel, quantization_config: { quant_method: nunchaku_lite, compute_dtype: bfloat16, svdq_w4a4: { precision: nvfp4, group_size: 16, rank: 32, targets: [layers.0.self_attention.to_q] }, awq_w4a16: { precision: int4, group_size: 64, targets: [final_linear] } } }需要特别提醒导出的 state dict 必须与目标 Diffusers 模型架构严格一致例如使用融合 QKV 投影导出的 checkpoint 无法加载到要求分离 Q、K、V 投影模块的模型配置中。TorchAoConfigPyTorch 官方量化方案TorchAoConfig 封装 torchao 的量化/稀疏化能力。其核心参数quant_typeAOBaseConfig子类实例指定量化类型官方文档列举了Int4WeightOnlyConfig、Int8WeightOnlyConfig、Float8WeightOnlyConfig、Float8DynamicActivationFloat8WeightConfig等可用配置类modules_to_not_convertlist[str]默认None不量化的模块列表适用于需要保留原始精度的模块。源码层面的约束与序列化细节见 quantization_config.py要求torchao0.15.0否则直接抛错提示pip install -U torchaopost_init会校验quant_type确实是AOBaseConfig实例to_dict()通过torchao.core.config.config_to_dict将quant_type序列化为{default: {...}}形式from_dict()则用config_from_dict反序列化目前假定每个 Transformer 只有一个默认配置未来可能支持按 FQN 分别配置。官方示例演示了对 FLUX.1-Dev 的 transformer 进行 int8 权重量化from diffusers import FluxTransformer2DModel, TorchAoConfig from torchao.quantization import Int8WeightOnlyConfig quantization_config TorchAoConfig(Int8WeightOnlyConfig()) transformer FluxTransformer2DModel.from_pretrained( black-forest-labs/Flux.1-Dev, subfoldertransformer, quantization_configquantization_config, torch_dtypetorch.bfloat16, )QuantoConfig已弃用的轻量量化方案QuantoConfig 封装quanto库。源码 docstring 中带有明确的弃用警告QuantoConfig已被弃用将在 1.0.0 版本移除官方建议迁移到BitsAndBytesConfig或TorchAoConfig等其他后端。其参数为weights_dtypestr默认int8量化后权重的目标 dtype支持float8、int8、int4、int2post_init会校验取值合法性modules_to_not_convertlist默认None不量化的模块列表例如 Whisper encoder、Llava encoder、Mixtral gate 层。在旧代码中使用时传入不受支持的weights_dtype会抛出ValueError并列出合法取值。SDNQConfig委托给 sdnq 库的薄工厂SDNQConfig 的实现方式与其他配置类不同它是一个薄工厂__new__中先通过_check_sdnq_requirement()检查sdnq库是否安装需要pip install sdnq然后直接返回sdnq.SDNQConfig实例从而让quant_methodsdnq的 checkpoint 可以原生被 diffusers 加载。其转发参数包括weights_dtypestr默认int8量化后权重目标 dtype例如int8、uint4、float8_e4m3fn完整取值见sdnq.common.accepted_weight_dtypesgroup_sizeint默认0共享同一量化组张量元素数0表示按weights_dtype自动选择-1表示禁用分组、使用逐行量化use_svdbool默认False是否在 SDNQ 量化之上叠加 SVDQuant 算法use_quantized_matmulbool默认False前向传播中是否使用量化 INT8/FP8/FP16 matmul 替代 BF16/FP16modules_to_not_convertlist默认None跳过量化的模块列表其余kwargs会转发给sdnq.SDNQConfig如quantized_matmul_dtype、svd_rank、use_hadamard、quant_conv、quant_embedding、modules_dtype_dict。DiffusersQuantizer量化器基类与模型加载生命周期DiffusersQuantizer 是所有量化器实现的抽象基类ABC其作用域限定于diffusers.models.modeling_utils.ModelMixin.from_pretrained的加载流程。理解它的关键类属性与钩子方法就理解了量化在模型加载时何时被触发、如何被改写。类属性与初始化requires_calibration默认False量化方法是否需要先对模型进行校准calibrationrequired_packages使用该量化器前需要安装的 pip 包列表初始化时从 kwargs 提取modules_to_not_convert不转换模块列表与pre_quantized默认True若pre_quantizedFalse而requires_calibrationTrue会抛出ValueError阻止错误使用。关键钩子方法方法作用update_torch_dtype(torch_dtype)某些量化方法要求显式指定模型 dtype需覆写以保持该行为update_device_map(device_map)覆写 device_map例如 bitsandbytes 依赖 accelerate未传 device_map 时会被设为autoadjust_target_dtype(torch_dtype)调整from_pretrained中用于计算 device_map 的target_dtype例如 bitsandbytes 8-bit 强制为torch.int84-bit 使用accelerate.CustomDtype.int4get_special_dtypes_update(model, torch_dtype)返回未量化模块的 dtype用于字符串形式 device_map 的计算默认基于modules_to_not_convert遍历named_parameters()adjust_max_memory(max_memory)若量化需要额外内存调整infer_auto_device_map()的max_memorycheck_if_quantized_param(...)/create_quantized_param(...)/check_quantized_param_shape(...)对需要新建量化参数的方法校验 state dict 分量并创建量化参数validate_environment(...)校验from_pretrained传入参数是否有冲突preprocess_model(model, **kwargs)在权重加载前执行设置model.is_quantizedTrue与model.quantization_method并调用抽象方法_process_model_before_weight_loading。此时模型应处于 meta device便于原位替换模块骨架postprocess_model(model, **kwargs)权重加载后处理调用抽象方法_process_model_after_weight_loadingdequantize(model)反量化还原原模型部分方案不支持并删除model.hf_quantizer、复位is_quantizedget_cuda_warm_up_factor()返回caching_allocator_warmup预热因子默认 4即分配空模型一半内存对应权重加载前未知位宽的情况is_serializable/is_trainable/is_compileable只读属性模型是否可序列化、可训练、可编译is_compileable默认False其中_process_model_before_weight_loading与_process_model_after_weight_loading是两个必须实现的抽象方法is_serializable与is_trainable也是必须实现的抽象属性——这构成了新增量化后端的接口契约。supports_parallel_loading与supports_safetensors_serialization属性则分别标识是否支持并行加载与 safetensors 序列化。自动分发与预量化 checkpoint 加载尽管 API 文档主体是配置类理解加载链路上的自动分发对实际使用至关重要。DiffusersAutoQuantizer 提供三个类方法from_dict(quantization_config_dict)根据quant_method字段实例化配置类对 bitsandbytes 有特殊处理——根据load_in_8bit/load_in_4bit自动推导bitsandbytes_8bit/bitsandbytes_4bit后缀缺少quant_method或方法名未知时抛错并列出受支持类型from_config(quantization_config, **kwargs)从配置实例分发到具体量化器类同样对 bitsandbytes 做 8/4-bit 分支from_pretrained(pretrained_model_name_or_path, **kwargs)读取模型config.json中的quantization_config自动完成配置实例化并附加用户传入的 kwargs。因此对于 bitsandbytes、torchao、GGUF、AutoRound、Nunchaku Lite、ModelOpt、SDNQ 这类支持预量化 checkpoint 的后端只需直接加载模型即可自动恢复量化配置无需手动构造配置对象。各后端的能力差异总结如下详见 量化入门指南bitsandbytes配置保存在config.json既支持运行时在线量化也支持加载预量化 checkpointtorchao同上GGUF仅支持通过 Model 类的from_single_file加载不支持 pipeline 级加载AutoRound仅支持加载需先用 AutoRound CLI 或 Python API 完成量化Nunchaku Lite配置保存在config.json需要kernels包仅支持加载ModelOpt仅支持加载预量化模型SDNQ既支持在线量化也支持加载预量化模型需要sdnq包。结语Diffusers 的量化 API 形成了配置类描述量化规格→ 自动分发器按quant_method匹配→ 量化器在from_pretrained生命周期内改写模型的三层架构。PipelineQuantizationConfig把多组件管线的量化需求收敛为一个入口参数而每个后端的配置类在 quantization_config.py 中沉淀了完整的参数校验与序列化逻辑。实际选型时可以按是否需要在线量化、组件属于 diffusers 还是 transformers、是否已有预量化 checkpoint三个维度快速决策需要在线量化且追求显存极致压缩时选 bitsandbytes 4-bitPyTorch 生态用户优先考虑 torchao已有 GGUF 或 Nunchaku Lite 预量化权重时则直接加载。更深入的单后端使用教程可继续阅读 bitsandbytes、torchao、gguf、nunchaku 与 sdnq 等指南。【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考