Model-Optimizer 量化配置指南：深入理解 quant_cfg 的格式、优先级与组合模式

【免费下载链接】Model-OptimizerA unified library of SOTA model optimization techniques like quantization, distillation, pruning, neural architecture search, speculative decoding, etc. It compresses deep learning models for downstream deployment frameworks like TensorRT-LLM, TensorRT, vLLM, etc. to optimize inference speed.项目地址https://gitcode.com/GitHub_Trending/te/Model-Optimizer点击查看免费下载导读quant_cfg是 NVIDIA Model-OptimizerModelOpt中控制模型量化行为的核心字段它决定了模型中哪些量化器Quantizer处于激活状态、以何种精度与粒度进行量化。本篇指南将完整讲解quant_cfg的配置格式、列表条目的字段语义、默认量化行为、覆盖顺序与原子性规则并通过可复制的代码示例演示先全禁、再按需开启、最后精确排除的官方推荐组合模式。读完本文你将能够读懂仓库内所有内置量化预置配置如FP8_DEFAULT_CFG、INT4_BLOCKWISE_WEIGHT_ONLY_CFG、W4A8_NVFP4_FP8_CFG等并能自定义一套从零构建、跳过指定层、按层覆盖精度的量化方案。一、quant_cfg 概述一个 Pydantic 校验的两层结构在 ModelOpt 中一次完整的量化配置是一个 QuantizeConfigPydantic 模型包含两个顶层字段通常以 YAML 或 Pythondict形式书写config { quant_cfg: [...], # 有序的 QuantizerCfgEntry 条目列表 algorithm: max, # 校准算法 }其中quant_cfg的取值是一个有序列表列表中的每个元素是一条 QuantizerCfgEntry 条目。每条条目负责命中一组量化器模块并规定它们的配置。输入可以是 YAML、Pythondict或已经构造好的QuantizerCfgEntry实例——无论输入形式如何在 Pydantic 校验期间都会被统一规范化normalize为一条条已验证的QuantizerCfgEntry对象列表。这个规范化逻辑位于 normalize_quant_cfg 校验器中底层委托给normalize_quant_cfg_list它同时接受新格式列表、旧格式扁平字典以及包含已校验实例的列表并在遇到非法输入时抛出明确的ValueError。algorithm字段则指定校准算法如max、mse、awq等。从源码 QuantizeConfig 可见其默认值为max而quant_cfg的默认值是[{quantizer_name: *, cfg: {num_bits: 8, axis: None}}]即默认对全部量化器做 8-bit per-tensor 静态量化。提示内置配置与支持的量化格式清单见 quantization-formats如何把一份配置应用到模型上参见 pytorch-quantization。二、条目格式QuantizerCfgEntry 的字段语义每一条quant_cfg条目是一个 QuantizerCfgEntry包含以下字段写作 YAML/dict 映射校验后成为 Pydantic 实例字段是否必填说明quantizer_name是通配符字符串按量化器模块名匹配例如*weight_quantizer遵循fnmatch规则parent_class否将匹配范围限制为直接父模块属于该 PyTorch 类的量化器例如nn.Linear。省略时匹配所有模块不做类限制cfg否量化器属性类型为 QuantizerAttributeConfig或用于顺序量化的此类对象的列表。写作 mapping校验后成为QuantizerAttributeConfig实例enable否True或False独立于cfg控制被匹配量化器的开关。cfg缺席时只改变启用/禁用状态其余属性保持不变cfg存在时enable设定新配置量化器的启用状态cfg存在而enable省略时量化器被隐式启用True2.1 关键校验规则至少提供 cfg 或 enable 之一在 QuantizerCfgEntry 的校验器 中有一条硬性约束每条条目除了quantizer_name之外必须至少给出cfg或enable中的一个。只有quantizer_name、没有其他键的条目是非法的会在配置处理阶段抛出ValueError。这条规则杜绝了一种隐蔽 bug——裸写{quantizer_name: *}会被静默解释为对所有量化器执行enableTrue。此外源码还通过_normalize_cfg_shape校验器config.py#L192-L230对cfg的形状做了防御性归一化enableFalse搭配空cfg空 dict、空 list 或全为空的 dict 列表会被归一化为cfgNone避免把属性重置为默认值、导致后续重新启用时丢失原有配置enableTrue显式或隐式搭配空cfg会被直接拒绝防止cfg: {}这类笔误被静默解释为用模式默认值量化。三、默认量化器配置未显式配置时的兜底行为当一个量化器被启用、但从未被任何带cfg的条目触及——无论是列表中没有条目匹配它还是它只被 enable-only 条目命中——它都会以 QuantizerAttributeConfig 的默认属性运行{ num_bits: 8, # 8-bit 整数量化 axis: None, # per-tensor 缩放无 per-channel 轴 fake_quant: True, # 前向传播中模拟量化PTQ / QAT unsigned: False, # 有符号整数范围如 INT8 的 [-128, 127] narrow_range: False, # 全范围True 会限制为 INT8 的 [-127, 127] type: static, # 静态校准非推理期动态 block_sizes: None, # 无块量化NF4 / MXFP 格式需设置 bias: None, # 无仿射偏置校正 calibrator: max, # 使用 max-abs 校准确定 amax rotate: False, # 无 Hadamard 旋转QuaRot / SpinQuant pass_through_bwd: True, # 用于 QAT 梯度的直通估计器STE trt_high_precision_dtype: Float, # TRT StronglyType 导出时 QDQ 节点转为 fp32 backend: None, # 使用内置量化后端 backend_extra_args: None, # 自定义后端无额外参数 use_constant_amax: False, # 校准 amaxTrue 则硬编码 FP8 E4M3 最大值 448.0 }这意味着一个未配置但被启用的量化器实际执行的是INT8 per-tensor 静态 fake-quantization配以 max 校准的缩放系数。在大多数场景下这并不是想要的行为——因此每一个你希望真正生效的量化器都应该用带cfg的条目显式配置。3.1 值得注意的字段细节来自源码num_bits三种取值形式config.py#L331-L344正整数整数量化常量整数元组 (E, M)模拟 NVIDIA FPx 浮点量化支持 FP8 E4M3/E5M2、FP6 E3M2/E2M3、FP4 E2M1或字符串仅用于自定义后端。FPx 元组还有配套校验config.py#L390-L431合法组合仅为 (4,3)、(5,2)、(2,1)、(1,2)、(0,3)、(3,0)、(3,2)、(2,3)且除 E4M3、E2M1 之外的格式必须配合动态块量化使用。axis与block_sizes互斥axis用于静态 per-channel 量化如axis0得到形状为(dim0,)的缩放向量axis(-2, -1)得到二维缩放而block_sizes用于块量化config.py#L433-L445、config.py#L487-L521。二者不可同时设置校验器会直接断言报错。block_sizes的特殊键除整数轴键外还支持typedynamic/static默认 static、scale_bits对每块缩放因子再量化的位数即双重量化方案和scale_block_sizes双重量化的块大小。例如block_sizes{-1: 32}表示沿最后一维按 32 大小的块做静态校准块量化{-1: None, type: dynamic}表示 per-token 动态量化。bias仿射偏置校正支持{enable: True}、{enable: True, type: static, axis: -1}等写法type可取static/dynamicmethod可取mean/max_min默认mean。pass_through_bwdTrue默认使用直通估计器STE反向不保存输入张量、省内存False使用零化异常梯度的 STE某些格式下 QAT 精度更好但更耗内存config.py#L627-L642。use_constant_amaxvsconstant_amax前者把 amax 硬编码为 FP8 E4M3 最大值 448.0用于 KV cache 量化、下游引擎使用 FP8 attention 数学的场景且不注册_amaxbuffer后者把 amax 固定为任意正数并注册_amaxbuffer同时作用于 fake-quant 前向和导出缩放系数。二者互斥config.py#L665-L709。四、排序与优先级后写覆盖组合式优先级模型条目按列表顺序依次应用后出现的条目会覆盖先前所有匹配同一量化器的条目。由此得到一个清晰、可组合的优先级模型把宽泛规则如全部禁用放在最前面把格式专属的启用规则放在中间把细粒度的排除规则特定层、特定类放在最后。所有内置配置采用的推荐模式如下quant_cfg: [ # 1. 默认禁用所有量化器 {quantizer_name: *, enable: False}, # 2. 启用并配置目标量化器 {quantizer_name: *weight_quantizer, cfg: {num_bits: 8, axis: 0}}, {quantizer_name: *input_quantizer, cfg: {num_bits: 8, axis: None}}, # 3. 最后应用标准排除BatchNorm、LM head、MoE 路由器等 *mtq.config._default_disabled_quantizer_cfg, ]其中全禁条目{quantizer_name: *, enable: False}在仓库中已固化为_base_disable_all常量config.py#L1659-L1661它从configs/ptq/units/base_disable_all加载并被自动前置到每一个内置配置前确保未被显式命中的量化器保持禁用状态。而_default_disabled_quantizer_cfgconfig.py#L1663-L1665从 configs/ptq/units/default_disabled_quantizers.yaml 加载包含一组标准的禁用模式例如*lm_head*、*output_layer*、MoE 路由器*block_sparse_moe.gate*、*mlp.gate.*、*mlp.shared_expert_gate.*、混合注意力模型中的*linear_attn.conv1d*、*self_attention.conv1d*等。这些模式共同保证标准架构中不该被量化的模块保持原精度。五、条目原子性cfg 条目是完整自包含的配置单元quant_cfg中每条携带cfg的条目都是一个完整、自洽的配置单元。当一条带cfg的条目命中某个量化器时它会完全替换该量化器的配置——不会与之前条目留下的设置合并或增量更新。具体来说如果一条条目只指定了部分量化器属性例如只有num_bits所有未指定的属性都会用 QuantizerAttributeConfig 的默认值补齐随后这份完整配置被写入量化器之前任何匹配条目设置的内容被直接丢弃。由此得出三条推论最后一条 cfg 条目完全胜出如果两条条目都命中*weight_quantizer且都携带cfg第二条不会继承第一条的设置——它整体替换。不存在隐藏状态累积量化器的最终配置只取决于列表中最后一条命中它的带cfg条目行为易于推演。改一个字段需要写全量规格因为每条cfg条目都是完整替换想修改已配置量化器的单个属性必须在新条目中复述完整期望配置条目中省略的任何属性都会回退到默认值而非沿用此前条目的值。enable-only 条目是例外。没有cfg只有enable的条目不是完整替换——它只翻转被匹配量化器的开关状态其余属性一律不动{quantizer_name: *, enable: False}在不触碰任何已配置属性的前提下禁用全部量化器适合作为先全禁后配置模式的第一步{quantizer_name: *weight_quantizer, enable: True}无cfg会用量化器当前携带的属性若从未被cfg条目配置过则用默认值重新启用权重量化器。例如以下两条都命中*weight_quantizer的条目# 条目 1 —— 设置 FP8 per-channel {quantizer_name: *weight_quantizer, cfg: {num_bits: (4, 3), axis: 0}}, # 条目 2 —— 设置 INT4 块量化axis 不会从条目 1 继承 {quantizer_name: *weight_quantizer, cfg: {num_bits: 4, block_sizes: {-1: 128}}},应用条目 2 之后量化器为num_bits4、block_sizes{-1: 128}、axisNone默认值。条目 1 设置的axis0已消失。注意先全禁后配置模式之所以安全可预期正因为{quantizer_name: *, enable: False}只禁用量化器而不重置属性后续cfg条目因此是从一个已知的默认状态开始配置目标。这些语义在源码中均有对应实现入口 set_quantizer_by_cfg 依次遍历规范化后的条目——cfg is None时调用set_quantizer_attributes_partial只改 enable否则调用set_quantizer_attributes_full完整替换通配符匹配经由 _match_quantizer 使用fnmatch.fnmatch完成并支持parent_class过滤以及 fused-experts 逐专家量化器命名归一化。六、常见组合模式6.1 跳过特定层在现有配置之后追加一条禁用条目用路径模式排除指定层。因为它被追加在最后优先级高于所有先前条目import copy import modelopt.torch.quantization as mtq config copy.deepcopy(mtq.FP8_DEFAULT_CFG) # 跳过最终投影层 config[quant_cfg].append({quantizer_name: *lm_head*, enable: False}) model mtq.quantize(model, config, forward_loop)6.2 按模块类跳过层用parent_class只命中特定类型层内的量化器同一量化器路径在其他层类型中保持不受影响config[quant_cfg].append({ quantizer_name: *input_quantizer, parent_class: nn.LayerNorm, enable: False, })注意parent_class中的类名必须是 QuantModuleRegistry 中已注册量化等价实现的类conversion.py#L285-L294否则会抛出ValueError。6.3 为特定层覆盖量化精度后出现的、带匹配quantizer_name的条目会替换先前条目设置的配置从而无需重构整个配置即可实现按层精度覆盖config copy.deepcopy(mtq.FP8_DEFAULT_CFG) # 将注意力输出投影的权重量化器改为更高精度的 INT8而非 FP8 config[quant_cfg].append({ quantizer_name: *o_proj*weight_quantizer, cfg: {num_bits: 8, axis: 0}, })6.4 从零构建一份自定义配置对于完全自定义的配方可以直接组合列表from modelopt.torch.quantization.config import _base_disable_all, _default_disabled_quantizer_cfg MY_CUSTOM_CFG { quant_cfg: [ *_base_disable_all, {quantizer_name: *weight_quantizer, cfg: {num_bits: 4, block_sizes: {-1: 128}}}, {quantizer_name: *input_quantizer, cfg: {num_bits: 8, axis: None}}, *_default_disabled_quantizer_cfg, ], algorithm: max, } model mtq.quantize(model, MY_CUSTOM_CFG, forward_loop)需要参考现成的内置配置时仓库在 modelopt/torch/quantization/config.py#L1675-L1774 中集中定义了全部预置常量——包括INT8_DEFAULT_CFG、INT8_SMOOTHQUANT_CFG、FP8_DEFAULT_CFG、INT4_BLOCKWISE_WEIGHT_ONLY_CFG、INT4_AWQ_CFG、MXFP4_DEFAULT_CFG、NVFP4_DEFAULT_CFG、NVFP4_AWQ_LITE_CFG/CLIP_CFG/FULL_CFG、W4A8_NVFP4_FP8_CFG、NVFP4_SVDQUANT_DEFAULT_CFG等数十种它们分别从 modelopt_recipes/configs/ptq/presets/model/ 下的 YAML 加载。这些 YAML 文件本身即可作为学习quant_cfg编排的最佳范例。七、顺序量化Sequential Quantization当cfg是属性 dict 的列表时被命中的 TensorQuantizer 会被替换为 SequentialQuantizer后者依次应用每种格式。这用于例如 W4A8 量化——权重先按 INT4 量化、再按 FP8 量化{ quantizer_name: *weight_quantizer, cfg: [ {num_bits: 4, block_sizes: {-1: 128, type: static}}, {num_bits: (4, 3)}, # FP8 ], }在 set_quantizer_by_cfg 的实现中cfg为列表时会对每个子配置逐个构造QuantizerAttributeConfig并整体写入从而完成顺序量化器的安装。八、从旧版 Dict 格式迁移ModelOpt 早期版本用扁平字典表示quant_cfg。新列表格式因提供了显式排序和明确的优先级而被推荐已有的 dict 配置仍可继续使用——规范化层会自动转换——但新代码应使用列表格式。下表给出常见模式的旧新对照旧版 dict 格式新列表格式quant_cfg: {*weight_quantizer: {num_bits: 8, axis: 0}, *input_quantizer: {num_bits: 8, axis: None}, default: {enable: False}}quant_cfg: [{quantizer_name: *, enable: False}, {quantizer_name: *weight_quantizer, cfg: {num_bits: 8, axis: 0}}, {quantizer_name: *input_quantizer, cfg: {num_bits: 8, axis: None}}]按键赋值禁用config[quant_cfg][*lm_head*] {enable: False}追加到末尾后写胜出config[quant_cfg].append({quantizer_name: *lm_head*, enable: False})按类作用域quant_cfg: {nn.Linear: {*input_quantizer: {enable: False}}}quant_cfg: [{quantizer_name: *input_quantizer, parent_class: nn.Linear, enable: False}]需要牢记的关键差异旧版的default键变成放在列表开头的{quantizer_name: *, enable: False}即先全禁后配置模式。旧版的 dict 键赋值config[quant_cfg][*lm_head*] ...变成list.append()。由于后出现的条目覆盖先前的追加可以达到同样的覆盖效果。旧版nn.*作用域的 dict 键变成带parent_class字段的条目。九、参考核心 API 与配置文件速查配置数据结构QuantizerCfgEntry、QuantizerAttributeConfig、QuantizeConfig均位于modelopt/torch/quantization/config.py配置应用入口set_quantizer_by_cfg位于modelopt/torch/quantization/conversion.py其配套的set_quantizer_by_cfg_context上下文管理器可在退出时恢复量化器原状态标准排除清单configs/ptq/units/default_disabled_quantizers.yaml内置预置配置目录modelopt_recipes/configs/ptq/presets/model/以及更丰富的社区配方 modelopt_recipes/general/ptq/ 与 modelopt_recipes/models/相关指南1_quantization.rst量化总览与格式支持矩阵、11_config_system.rst配置系统整体说明总结quant_cfg的设计哲学可以概括为三句话列表有序、后写覆盖、cfg 条目原子替换。正是基于这三条规则全禁 → 定向开启 → 末尾排除的组合模式才能稳定可预期地工作。无论你是想微调内置预置配置、为特定层覆盖精度还是从零构建 W4A8、NVFP4、MXFP4 等自定义配方掌握QuantizerCfgEntry的字段语义、QuantizerAttributeConfig的默认值与互斥约束axisvsblock_sizes、use_constant_amaxvsconstant_amax都是必要前提。建议在实际动手前先对照仓库中 presets 下的 YAML 配置逐条分析其quant_cfg列表的编排逻辑再通过mtq.quantize(model, config, forward_loop)快速验证效果。赞分享【免费下载链接】Model-OptimizerA unified library of SOTA model optimization techniques like quantization, distillation, pruning, neural architecture search, speculative decoding, etc. It compresses deep learning models for downstream deployment frameworks like TensorRT-LLM, TensorRT, vLLM, etc. to optimize inference speed.项目地址https://gitcode.com/GitHub_Trending/te/Model-Optimizer点击查看免费下载相关推荐memU doctor 连接本地 embedding 服务器返回 502如何排查代理劫持memU doctor 连接本地 embedding 服务器返回 502如何排查代理劫持 在 memU 的本地模式local mode下如果你没有 em深入理解高级React模式复合组件设计模式深入理解高级React模式复合组件设计模式 引言为什么需要复合组件 你是否曾经遇到过这样的场景构建一个复杂的UI组件时API变得越来越臃肿propsNVIDIA Model Optimizer 量化格式与支持矩阵全解析从 Linux 到 Windows 的部署选型指南NVIDIA Model Optimizer 量化格式与支持矩阵全解析从 Linux 到 Windows 的部署选型指南 本指南以 docs/source/g上一篇CAS 中 OIDC 客户端 JWKS 管理静态资源、URL 资源与动态密钥注册全解析下一篇暗黑破坏神2存档修改器Diablo Edit2完全使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考