PyTorch 量化生态迁移指南torch.ao.quantization 的现状、API 全景与 torchao 迁移路线【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch本文以 docs/source/quantization.md 为核心脉络系统梳理 PyTorch 官方文档对torch.ao.quantization模块的定位变化量化开发已集中迁移至 torchaoEager mode、FX graph mode、pt2e 三条量化流程分别给出明确的迁移目标 API并计划在 PyTorch 2.10 移除旧模块。读完本文你将掌握三条量化工作流的准确名称与调用方式、新旧 API 的对应关系、仍保留的公共 API 参考清单以及迁移过程中的注意事项与源码级实现依据。背景量化开发为何集中迁移到 torchaoPyTorch 官方的量化文档明确指出所有与量化相关的开发正在集中迁移到 torchao 项目。torch.ao.quantization作为历史沉淀下来的量化模块其演进重心已转移至新的仓库与 API 体系。从当前仓库源码可以印证这一趋势。在 torch/ao/quantization/utils.py 中定义了一个统一的弃用警告字符串torch.ao.quantization is deprecated and will be removed in 2.10. For migrations of users: 1. Eager mode quantization (torch.ao.quantization.quantize, torch.ao.quantization.quantize_dynamic), please migrate to use torchao eager mode quantize_ API instead 2. FX graph mode quantization (torch.ao.quantization.quantize_fx.prepare_fx, torch.ao.quantization.quantize_fx.convert_fx), please migrate to use torchao pt2e quantization API instead (prepare_pt2e, convert_pt2e) 3. pt2e quantization has been migrated to torchao该警告通过typing_extensions.deprecated(DEPRECATION_WARNING)装饰在quantize、quantize_dynamic、prepare_fx、convert_fx等核心入口函数上见 torch/ao/quantization/quantize.py 与 torch/ao/quantization/quantize_fx.py意味着调用这些旧接口时用户会收到明确的迁移提示。注意本仓库为 PyTorch 源码仓库torchao 是其独立的衍生项目。迁移后的具体 API 行为请以 torchao 项目自身的文档为准本文聚焦于 PyTorch 仓库内旧量化 API 的现状、用法与迁移方向。三大量化流程的现状与迁移路径原文档将现存量化流程划分为三类每一类都有明确的迁移目标1. Eager mode 量化静态/动态后训练量化旧 APItorch.ao.quantization.quantize后训练静态量化torch.ao.quantization.quantize_dynamic动态量化即仅权重量化迁移目标改用 torchao eager mode 的quantize_API。从源码看torch.ao.quantization.quantize的核心流程是准备 → 校准 → 转换三步torch/ao/quantization/quantize.pytyping_extensions.deprecated(DEPRECATION_WARNING) def quantize(model, run_fn, run_args, mappingNone, inplaceFalse): torch._C._log_api_usage_once(quantization_api.quantize.quantize) if mapping is None: mapping get_default_static_quant_module_mappings() if not inplace: model copy.deepcopy(model) model.eval() prepare(model, inplaceTrue) # 1. 插入 observer为校准做准备 run_fn(model, *run_args) # 2. 运行校准函数收集激活值分布 convert(model, mapping, inplaceTrue) # 3. 依据校准得到的量化参数转换为量化模型 return model其参数含义model输入的浮点模型run_fn校准函数负责运行 prepared 模型一般用代表性数据集前向几次run_args传给run_fn的位置参数mapping原模块类型到量化模块类型的映射默认取get_default_static_quant_module_mappings()inplace是否原地修改模型False时内部先copy.deepcopy。quantize_dynamic则针对仅权重量化场景默认对参数量大的层Linear 与各类 RNN做动态量化torch/ao/quantization/quantize.py。其dtype参数支持的默认配置如下表dtype默认覆盖模块说明torch.qint8nn.Linear、nn.LSTM、nn.GRU、nn.LSTMCell、nn.RNNCell、nn.GRUCell8 位动态量化默认torch.float16同上16 位动态量化torch.quint8nn.EmbeddingBag、nn.Embedding浮点参数仅权重量化torch.quint4x2nn.EmbeddingBag4 位仅权重量化qconfig_spec可传字典模块名/类型 → QConfig或类型集合若提供完整 qconfig则dtype参数被忽略。2. FX graph mode 量化图模式量化旧 APItorch.ao.quantization.quantize_fx.prepare_fxtorch.ao.quantization.quantize_fx.convert_fx迁移目标改用 torchao pt2e 量化 API即prepare_pt2e与convert_pt2e分别对应torchao.quantization.pt2e.quantize_pt2e.prepare_pt2e/convert_pt2e。FX 图模式量化通过torch.fx.symbolic_trace将模型转换为 GraphModule 后在图上完成算子融合、插入 observer、量化/反量化算子替换支持更细粒度的算子级控制。prepare_fx的核心签名torch/ao/quantization/quantize_fx.pydef prepare_fx( model: torch.nn.Module, qconfig_mapping: QConfigMapping | dict[str, Any], example_inputs: tuple[Any, ...], prepare_custom_config: PrepareCustomConfig | dict[str, Any] | None None, _equalization_config: QConfigMapping | dict[str, Any] | None None, backend_config: BackendConfig | dict[str, Any] | None None, ) - GraphModule:关键参数qconfig_mappingQConfigMapping对象配置模型如何量化。可用set_global全局默认、set_object_type(torch.nn.Linear, qconfig)按算子类型、set_module_name(linear, qconfig)按模块名等方式逐级覆盖example_inputs前向函数的示例输入元组用于推断输出类型prepare_custom_config量化工具的自定义配置见PrepareCustomConfigbackend_config描述某后端如何量化算子的配置包括支持的量化模式静态/动态/仅权重、dtypequint8/qint8 等、observer 放置位置与融合模式。convert_fx将校准/训练后的模型转换为量化模型torch/ao/quantization/quantize_fx.pydef convert_fx( graph_module: GraphModule, convert_custom_config: ConvertCustomConfig | dict[str, Any] | None None, _remove_qconfig: bool True, qconfig_mapping: QConfigMapping | dict[str, Any] | None None, backend_config: BackendConfig | dict[str, Any] | None None, keep_original_weights: bool False, ) - GraphModule:其中qconfig_mapping的键必须包含prepare_fx时传入的键值相同或为None值为None的条目表示跳过量化例如qconfig_mapping QConfigMapping() \ .set_global(qconfig_from_prepare) \ .set_object_type(torch.nn.functional.add, None) # 跳过对 add 的量化转换过程会先将模型转为 reference quantized model再 lowering 到目标后端源码注释中提到 fbgemm/onednn 与 qnnpack/xnnpack 共享同一套量化算子与 lowering 流程。同文件还提供convert_to_reference_fx用于输出不依赖具体后端的标准参考量化模型便于迁移到加速器等自定义后端。3. pt2e 量化已迁移现状pt2e 量化流程已整体迁移到 torchaotorchao/quantization/pt2e目录PyTorch 仓库内的相关实现不再作为主开发路径。pt2e 基于torch.export导出模型而非 FX symbolic trace在导出图上进行量化与 torch.compile / export 生态天然衔接。迁移对应速查表旧 APIPyTorch 内已弃用迁移目标torchao适用场景torch.ao.quantization.quantizetorchao eagerquantize_后训练静态量化模型结构简单、习惯手工控制torch.ao.quantization.quantize_dynamictorchao eagerquantize_仅权重仅权重量化追求部署体积与内存收益torch.ao.quantization.quantize_fx.prepare_fxprepare_pt2eFX 图模式静态量化torch.ao.quantization.quantize_fx.convert_fxconvert_pt2eFX 图模式量化转换pt2e旧实现在 PyTorch 内torchaotorchao/quantization/pt2e基于 export 的量化移除时间线2.10 及以后的计划原文档明确给出了删除计划We plan to deletetorch.ao.quantizationin 2.10 if there are no blockers, or in the earliest PyTorch version until all the blockers are cleared.即若无阻塞问题torch.ao.quantization计划在 PyTorch 2.10 中被删除若有阻塞则推迟到阻塞清除后的最早版本。这意味着依赖旧量化 API 的存量代码应尽早规划迁移避免被上游删除后无法升级。DEPRECATION_WARNINGtorch/ao/quantization/utils.py与各入口函数上的deprecated装饰器正是为这一移除时间线做的运行时提示铺垫。仍保留的 Quantization API Reference虽然模块整体进入迁移期但由于这些 API 目前仍是公开接口官方文档保留了完整的 API 参考见 Quantization API Reference对应仓库内的 docs/source/quantization-support.md涵盖量化 pass如fuse_modules、fuser_method_mappings量化张量操作fake_quantize、observer如MinMaxObserver、qconfig、qconfig_mapping量化模块与函数torch.ao.nn.quantized.*、torch.ao.nn.qat.*、torch.ao.nn.quantizable.*、torch.ao.nn.intrinsic.*等。原文档还通过automodule/py:module指令维护了一份详尽的模块清单docs/source/quantization.md覆盖torch.ao.quantization与torch.quantization旧命名空间别名下的全部子模块包括backend_configbackend_config、executorch、fbgemm、native、onednn、qnnpack、tensorrt、utils、x86fxconvert、custom_config、fuse、fuse_handler、graph_module、lower_to_fbgemm、lower_to_qnnpack、prepare、qconfig_mapping_utils、quantize_handler、tracer、utils等核心组件fake_quantize、observer、qconfig、qconfig_mapping、quant_type、quantize_jit、stubs、fuse_modules数值敏感性分析nstorch.ao.ns.fx.*并保留三个关键工具函数compute_sqnr(x, y)信号量化噪声比、compute_normalized_l2_error(x, y)归一化 L2 误差、compute_cosine_similarity(x, y)余弦相似度用于量化前后数值对比分析稀疏化与剪枝torch.ao.nn.sparse.quantized.*、torch.ao.pruning.sparsifier.*如base_sparsifier、weight_norm_sparsifier、nearly_diagonal_sparsifier与torch.ao.pruning.scheduler.*QAT 相关torch.ao.nn.qat.modules.conv/linear/embedding_ops、torch.ao.nn.intrinsic.qat.modules.*量化模块族torch.ao.nn.quantized.modules下的activation、batchnorm、conv、dropout、embedding_ops、linear、normalization、rnn、functional_modules、utils以及torch.ao.nn.quantized.reference.modulesreference 量化模块对应convert_to_reference_fx的输出形态。同时文档包含torch.nn.quantized、torch.nn.qat、torch.nn.intrinsic等命名空间下的对应模块引用docs/source/quantization.md提示这些公共符号在迁移期内依旧可导入使用。仓库中对应实现位于 torch/ao/quantization/ 目录含quantize.py、quantize_fx.py、quantize_jit.py、observer.py、qconfig.py、qconfig_mapping.py、fake_quantize.py、stubs.py等以及fx/、backend_config/子包可作源码级查阅依据。迁移实践建议优先评估 FX / pt2e 路径新项目建议直接走 torchao 的 pt2e 流程prepare_pt2e/convert_pt2e它基于torch.export与 torch.compile 生态对齐也是官方未来的主开发方向。存量 Eager 代码尽早切换quantize/quantize_dynamic已被标注弃用且DEPRECATION_WARNING明确给出 2.10 移除计划存量代码应在移除前完成到 torchao eagerquantize_的迁移。迁移期利用好 API 参考若暂时无法迁移可继续依赖 docs/source/quantization-support.md 与上述模块清单定位所需符号但需同步跟踪移除时间线。注意torch.quantization别名torch.quantization.*与torch.ao.quantization.*共享同一实现如torch.quantization.quantize与torch.ao.quantization.quantize迁移判断对两者同样适用。小结torch.ao.quantization正处于维护但不演进的过渡期三条量化流程Eager、FX graph mode、pt2e均已明确迁移至 torchao 对应 API模块计划于 PyTorch 2.10 移除但现有公共 API 与完整参考文档在迁移期内继续保留可用。对开发者而言理解旧 API 的调用契约quantize/quantize_dynamic的默认配置、prepare_fx/convert_fx的参数体系有助于在新旧 API 间平滑过渡也能更准确地把握 PyTorch 量化生态的演进方向。【免费下载链接】pytorchTensors and Dynamic neural networks in Python with strong GPU acceleration项目地址: https://gitcode.com/GitHub_Trending/py/pytorch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
