PyTorch PTQ静态量化失败主因是校准不合理与关键层未保留浮点：需用真实分布数据校准、显式配置qconfig并融合BN、禁用输出层/拼接分支/动态算子所在层，且必须通过TorchScript导出才能真正压缩体积。
PyTorch 的 PTQ（Post-Training Quantization）静态量化能显著减小模型体积并加速推理，但默认配置下极易因校准数据偏差或算子不支持导致精度暴跌甚至报错——关键不是“能不能做”，而是“校准是否合理”和“哪些层必须保留浮点”。
为什么 torch.quantization.quantize_static 一跑就报错或掉点严重
常见错误现象包括：RuntimeError: Could not run 'aten::quantize_per_tensor'（输入未校准）、AttributeError: 'Conv2d' object has no attribute 'qconfig'（未设置量化配置），或量化后准确率下降 >10%。
根本原因有三：
- 模型中存在未覆盖的自定义算子或动态控制流（如
if x.sum() > 0:），PTQ 无法插入伪量化节点 - 校准数据集太小、分布偏移（例如只用 10 张图校准 ImageNet 模型），导致 scale/zero_point 计算失真
-
qconfig未正确传播到所有可量化子模块（尤其是嵌套的nn.Sequential或自定义forward中跳过的层）
如何正确配置 qconfig 并完成校准
PyTorch 不会自动为所有层分配量化策略，必须显式指定。推荐使用 get_default_qconfig('fbgemm')（CPU）或 get_default_qconfig('qnnpack')（移动端），但需注意：
立即学习“Python免费学习笔记（深入）”；
- 仅对
nn.Conv2d、nn.Linear、nn.ReLU等少数模块生效；nn.BatchNorm2d会被融合进卷积，不能单独量化 - 必须调用
model.eval()后再设置qconfig，否则QuantStub/DeQuantStub插入失败 - 校准阶段需用真实分布的前 100–500 张样本（非随机噪声），且必须调用
model(input)至少一次触发 observer 更新
示例关键片段：
model.eval()
model.fuse_model() # 融合 Conv+BN+ReLU
model.qconfig = torch.quantization.get_default_qconfig('fbgemm')
torch.quantization.prepare(model, inplace=True)
# 此处用真实校准数据循环喂入
for i, (x, _) in enumerate(calib_loader):
if i >= 200: break
model(x)
# 完成校准后转换
quantized_model = torch.quantization.convert(model, inplace=False)哪些层必须手动禁用量化？
不是所有层都适合量化。以下情况必须用 torch.quantization.disable_observer 或设 qconfig = None：
- 输出层（如分类头的
nn.Linear后接nn.LogSoftmax），量化后 softmax 输入范围畸变会导致 top-1 准确率骤降 - 含非常小数值的层（如归一化后的 embedding 输出），
int8无法表达微小差异，scale 接近 0 会溢出 - 存在
torch.cat、torch.stack等拼接操作的分支结构，不同路径的 scale 不一致会导致拼接后数值错乱 - 任何用了
torch.nonzero、torch.where或索引切片的动态逻辑，observer 无法建模其量化误差传播
量化后模型体积没变小？检查 state_dict 是否真的压缩
调用 torch.quantization.convert 后，模型参数类型仍是 float32（只是加了 _packed_params 属性），磁盘体积不会下降——必须用 torch.jit.trace 或 torch.jit.script 导出为 TorchScript，并保存为 .pt 才真正转为 int8 存储：
- 直接
torch.save(quantized_model, 'q.pt')仍存 float32 权重，体积几乎不变 - 正确做法：先
traced = torch.jit.trace(quantized_model, example_input)，再traced.save('q_traced.pt')，此时权重以 int8 形式序列化 - 验证方式：用
torch.load('q_traced.pt', map_location='cpu')后检查._c.state_dict()['0.weight'].dtype == torch.qint8
真正压缩体积的关键不在量化本身，而在导出时是否启用底层整数张量序列化——这点极易被忽略，导致白忙一场。
