ONNX Runtime 动态量化怎么选择需要排除的节点

ONNX Runtime 的动态量化并不是“精度下降就排除最后几层”。nodes_to_exclude 接受的是节点名称列表，不是算子类型或张量名称。可靠的做法是先得到全量动态量化基线，再用同一批样本找出误差集中的节点，每次只排除一个节点或一个紧邻小组，重新比较任务指标与延迟。

官方文档：https://onnxruntime.ai/docs/performance/model-optimizations/quantization.html

先确认排除列表匹配的是节点名称

官方源码对 nodes_to_exclude 的说明是“要排除的节点名称列表”。因此，MatMul 这样的字符串通常是算子类型，不是可直接排除的节点；某个权重张量名也不等于节点名。先导出模型中可能参与动态量化的节点：

import onnx

model = onnx.load("model.onnx")
target_ops = {"MatMul", "Gemm", "LSTM", "GRU"}

for node in model.graph.node:
    # nodes_to_exclude 使用 node.name，不能误填输出张量名。
    if node.op_type in target_ops:
        print({
            "name": node.name,
            "op_type": node.op_type,
            "inputs": list(node.input),
            "outputs": list(node.output),
        })

如果候选节点的 name 为空，先在导出阶段为节点生成稳定名称，再开始量化对比。否则排除配置很难跨版本复用，也无法确认一次修改命中了哪个节点。

建立“全量量化”基线后再找候选节点

先保留 FP32 模型，再生成不排除任何节点的动态量化模型。两份模型必须使用同一执行环境、同一预处理和同一评测样本。动态量化会在运行时计算激活的量化参数，因此可能比静态量化多出开销；不能只看模型体积就判断收益。

from onnxruntime.quantization import QuantType, quantize_dynamic

quantize_dynamic(
    model_input="model.onnx",
    model_output="model.int8.all.onnx",
    # 先限制计划量化的算子类别，便于解释比较结果。
    op_types_to_quantize=["MatMul", "Gemm"],
    weight_type=QuantType.QInt8,
    # 基线不排除节点，后续实验只修改这一项。
    nodes_to_exclude=[],
)

基线至少记录三类结果：业务任务指标、端到端延迟、模型文件大小。任务指标可以是分类准确率、F1、困惑度或业务自定义评分，但必须固定样本和计算方式。延迟要包含预热，并明确批量大小与执行提供程序。

用差异定位，而不是按层名猜测

ONNX Runtime 提供 qdq_loss_debug 相关 API，可匹配量化前后的权重和中间激活。它们的价值不是自动给出排除名单，而是帮助找到差异最大的张量，再回查产生这些张量的节点。动态量化模型的可比较范围取决于模型结构与量化方式，因此最终仍要以任务指标为准。

候选节点可以按下面的证据顺序进入列表：首先是量化后任务指标明显恶化的样本；其次是这些样本中差异集中的权重或激活；最后才是对应的具名节点。若一次排除大量同类节点才能恢复精度，应该重新检查 op_types_to_quantize、预处理、权重类型或目标硬件，而不是无限扩张排除列表。

每轮只排除一个节点或一个小组

下面的节点名只是格式示例，必须替换成当前模型里真实存在的 node.name：

from onnxruntime.quantization import QuantType, quantize_dynamic

# 示例名称来自假想模型，仅演示精确节点排除的写法。
excluded_nodes = [
    "encoder.layer.11.output.dense/MatMul",
]

quantize_dynamic(
    model_input="model.onnx",
    model_output="model.int8.exclude-01.onnx",
    op_types_to_quantize=["MatMul", "Gemm"],
    weight_type=QuantType.QInt8,
    nodes_to_exclude=excluded_nodes,
)

先测试单个节点；只有相邻节点共同影响同一误差时，才把它们作为一个小组。若任务指标恢复但延迟接近 FP32，说明排除范围过大。若精度没有变化，应撤回该项，避免把偶然相关写进长期配置。

冻结配置前检查四个边界

• 名称边界：排除项都能在当前 ONNX 图中按 node.name 唯一命中。
• 数据边界：候选节点由代表性评测集产生，不只对一条异常样本有效。
• 性能边界：排除后仍保留可接受的端到端加速，且目标硬件实际受益。
• 版本边界：重新导出或优化模型后再次核对节点名，不盲目复用旧列表。

相关问题

可以直接把 LayerNorm、Softmax 全部排除吗？

不建议。它们是否进入当前动态量化范围取决于支持的算子和配置。先查看实际被量化的节点，再根据差异证据决定；不要把经验名单当成模型无关规则。

nodes_to_exclude 和 op_types_to_quantize 怎么配合？

前者适合保留少量例外节点，后者适合定义允许量化的算子类别。排除项不断增多时，优先重新收紧算子类别或检查量化参数。

排除节点后还需要比较 FP32 吗？

需要。每轮实验都应同时参照 FP32 与全量量化基线，才能区分“恢复质量”和“只是改变了结果”，并判断性能收益是否仍然存在。