PyTorch 2.1 已弃用 torch.ao.quantization，必须改用 torch.ao.quantize_pt2e；该新路径要求模型先通过 torch.export.export 导出为 ExportedProgram，且需 model.eval()、匹配设备与 dtype 的具体输入，不支持控制流和未捕获算子。
PyTorch 2.1 的 torch.ao.quantization 已弃用，必须切到 torch.ao.quantize_pt2e
PyTorch 2.1 彻底移除了旧版动态/静态量化 API（如 prepare/convert），继续用会报 ModuleNotFoundError: No module named 'torch.ao.quantization'。新路径统一走 torch.ao.quantize_pt2e，它依赖 TorchDynamo 和 FX Graph，只支持已通过 torch.compile 或 torch.export 转为 FX graph 的模型。
实操要点：
- 模型必须先用
torch.export.export导出为ExportedProgram，不能直接对原始nn.Module量化 - 不支持 Python 控制流（如
if x > 0:）、自定义 C++ 算子、或未被 Dynamo 捕获的高阶函数 - 典型错误现象：
RuntimeError: ExportedProgram contains unflattened modules—— 说明没正确导出，需检查是否漏掉model.eval()或输入示例不匹配
量化前必须用 torch.export.export 固定图结构
旧版 torch.quantization.prepare 允许在训练中动态插入 observer，新版要求图完全静态。导出时输入必须是具体张量（不能是 symbolic shape），且 dtype、device、requires_grad 都要与部署环境一致。
常见踩坑点：
- 忘记调用
model.eval()：导致 dropout/batchnorm 行为异常，导出失败或量化后精度崩塌 - 输入用
torch.randn(1, 3, 224, 224).to('cpu')，但模型在 CUDA 上 —— 导出会报Device mismatch - 使用
torch.compile(model, backend='inductor')后再导出？不行，torch.export必须作用于原始模块，编译后的对象无法导出
最小可行导出示例：
from torch.export import export model.eval() example_inputs = (torch.randn(1, 3, 224, 224),) exported_model = export(model, example_inputs)
选择 QConfigMapping 时，backend 决定算子映射和数据类型
PyTorch 2.1 不再提供预设的 get_default_qconfig，必须显式配置每个子模块的量化策略。关键不是“选精度”，而是“选后端”——qconfig_mapping 中的 backend 字段（如 "x86"、"qnnpack"、"cuda"）会自动绑定 observer 类型、weight quantizer、以及是否启用 per-channel 权重量化。
实际影响：
-
backend="x86"：默认启用PerChannelMinMaxObserver对 weight，MinMaxObserver对 activation，适合 Intel CPU -
backend="qnnpack"：强制所有量化使用 uint8，且 activation observer 默认为MinMaxObserver（非EMAMinMaxObserver），在 ARM 设备上更稳定 - 若指定
backend="cuda"却在 CPU 上运行，量化会静默失败，推理结果全为 NaN
部署时 torch.ao.quantize_pt2e.convert_pt2e 输出的是可直接 torch.jit.script 的模块
量化后得到的是标准 nn.Module，但内部已替换为 quantized_ops（如 torch.ao.nn.quantized.dynamic.Linear）。它不依赖 observer，也不再需要 calibration 数据，可直接保存为 TorchScript 或通过 torch._C._jit_pass_remove_mutation 做进一步图优化。
注意点：
- 不能用
torch.save(model.state_dict())保存量化模型 —— 量化参数（scale/zero_point）存在 buffer 中，需用torch.save(model, "qmodel.pt") - 加载后必须调用
model.to(device)，否则部分量化算子（如 CUDA 后端）会因 device 不匹配而崩溃 - 如果后续要用 ONNX，PyTorch 2.1 的量化模型暂不支持直接导出，需先用
torch.ao.quantize_pt2e.load_quantized_state_dict恢复权重再手动替换算子
真正容易被忽略的是：量化后的模型在不同 PyTorch 小版本间不兼容 —— torch==2.1.0 量化的模型，在 torch==2.1.2 加载可能触发 AttributeError: 'QuantizedLinear' object has no attribute '_weight_qscheme'。生产部署务必锁死 PyTorch 版本。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
