企业官网建设流程全解析

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模块的定位变化：量化开发已集中迁移至 torchao，Eager mode、FX graph mode、pt2e 三条量化流程分别给出明确的迁移目标 API，并计划在 PyTorch 2.10 移除旧模块。读完本文，你将掌握三条量化工作流的准确名称与调用方式、新旧 API 的对应关系、仍保留的公共 API 参考清单，以及迁移过程中的注意事项与源码级实现依据。

背景：量化开发为何集中迁移到 torchao

PyTorch 官方的量化文档明确指出：所有与量化相关的开发正在集中迁移到 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 量化（静态/动态后训练量化）

旧 API：

• torch.ao.quantization.quantize（后训练静态量化）
• torch.ao.quantization.quantize_dynamic（动态量化，即仅权重量化）

迁移目标：改用 torchao eager mode 的quantize_API。

从源码看，torch.ao.quantization.quantize的核心流程是"准备 → 校准 → 转换"三步（torch/ao/quantization/quantize.py）：

@typing_extensions.deprecated(DEPRECATION_WARNING) def quantize(model, run_fn, run_args, mapping=None, inplace=False): 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, inplace=True) # 1. 插入 observer，为校准做准备 run_fn(model, *run_args) # 2. 运行校准函数，收集激活值分布 convert(model, mapping, inplace=True) # 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参数支持的默认配置如下表：

qconfig_spec可传字典（模块名/类型 → QConfig）或类型集合；若提供完整 qconfig，则dtype参数被忽略。

2. FX graph mode 量化（图模式量化）

旧 API：

• torch.ao.quantization.quantize_fx.prepare_fx
• torch.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.py）：

def 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_mapping：QConfigMapping对象，配置模型如何量化。可用set_global（全局默认）、set_object_type(torch.nn.Linear, qconfig)（按算子类型）、set_module_name("linear", qconfig)（按模块名）等方式逐级覆盖；
• example_inputs：前向函数的示例输入元组，用于推断输出类型；
• prepare_custom_config：量化工具的自定义配置（见PrepareCustomConfig）；
• backend_config：描述某后端如何量化算子的配置，包括支持的量化模式（静态/动态/仅权重）、dtype（quint8/qint8 等）、observer 放置位置与融合模式。

convert_fx将校准/训练后的模型转换为量化模型（torch/ao/quantization/quantize_fx.py）：

def 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 量化流程已整体迁移到 torchao（torchao/quantization/pt2e目录），PyTorch 仓库内的相关实现不再作为主开发路径。pt2e 基于torch.export导出模型（而非 FX symbolic trace），在导出图上进行量化，与 torch.compile / 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_WARNING（torch/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_config：backend_config、executorch、fbgemm、native、onednn、qnnpack、tensorrt、utils、x86；
• fx：convert、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；
• 数值敏感性分析（ns）：torch.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.modules（reference 量化模块，对应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/子包），可作源码级查阅依据。

迁移实践建议

1. 优先评估 FX / pt2e 路径：新项目建议直接走 torchao 的 pt2e 流程（prepare_pt2e/convert_pt2e），它基于torch.export，与 torch.compile 生态对齐，也是官方未来的主开发方向。
2. 存量 Eager 代码尽早切换：quantize/quantize_dynamic已被标注弃用，且DEPRECATION_WARNING明确给出 2.10 移除计划，存量代码应在移除前完成到 torchao eagerquantize_的迁移。
3. 迁移期利用好 API 参考：若暂时无法迁移，可继续依赖 docs/source/quantization-support.md 与上述模块清单定位所需符号，但需同步跟踪移除时间线。
4. 注意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