illegalCreed

中文

English

中文

English

Appearance

参考 ​

基于 ONNX 标准 1.22（IR 13 / opset 27）+ ONNX Runtime 1.28.0 API 文档整理

速查 ​

  • 标准库：pip install onnx（创建/加载/校验/操作模型）
  • 推理引擎：pip install onnxruntime（CPU）/ onnxruntime-gpu（CUDA）
  • IR 版本：当前 13（随 ONNX 1.22）
  • 标准 opset：当前 27（ai.onnx 域）
  • ORT 版本：1.28.0（2026-07-25）
  • Python API：onnx.load/save/checker、onnxruntime.InferenceSession
  • 数据类型：TensorProto.FLOAT(1) / UINT8(2) / INT8(3) / INT64(7) / FLOAT16(10) / BFLOAT16(16) / STRING(8)
  • 量化类型：QuantType.QInt8/QUInt8/QInt4/QUInt4
  • 量化格式：QuantFormat.QDQ/QOperator
  • 优化级别：GraphOptimizationLevel.ORT_DISABLE_ALL/BASIC/EXTENDED/ALL
  • EP 列表：CPU/CUDA/TensorRT/TensorRT-RTX/CoreML/OpenVINO/oneDNN/DirectML/QNN/NNAPI/CANN/ROCm/MIGraphX/Vitis-AI/WebGPU/ACL/ArmNN/TVM/RKNPU/XNNPACK/Azure
  • 模型格式：.onnx（protobuf）；.ort（ORT 优化后的预编译格式）

模型结构（Protobuf） ​

ModelProto
├── ir_version
├── opset_import: [OperatorSetIdProto]    # {domain: "", version: 27}
├── producer_name / producer_version
├── graph: GraphProto
│   ├── name
│   ├── node: [NodeProto]
│   │   ├── name
│   │   ├── op_type                        # "Conv" / "MatMul" / ...
│   │   ├── domain                         # "" 表示标准域
│   │   ├── input: [str]                   # 边名
│   │   ├── output: [str]
│   │   └── attribute: [AttributeProto]    # 算子属性
│   ├── input: [ValueInfoProto]            # 含 shape 与 dtype
│   ├── output: [ValueInfoProto]
│   └── initializer: [TensorProto]         # 权重张量
  • ValueInfoProto：描述张量的 name/shape/dtype，shape 中 -1 或 dim_param 表示动态
  • AttributeProto：算子属性（int/float/string/tensor/列表），如 Conv 的 kernel_shape、strides、pads

onnx Python API ​

python
import onnx

# 加载与保存
model = onnx.load("model.onnx")
onnx.save(model, "out.onnx")

# 校验
onnx.checker.check_model(model)                    # 抛异常即不合规

# 查看结构
print(model.ir_version)                            # 13
print([(opset.domain, opset.version) for opset in model.opset_import])  # [("", 27)]
graph = model.graph
for node in graph.node:
    print(node.op_type, node.input, "->", node.output)

# 版本转换
from onnx import version_converter
model_old = version_converter.convert_version(model, 21)

# 形状推断
import onnx.shape_inference
model_inferred = onnx.shape_inference.infer_shapes(model)

onnxruntime Python API ​

python
import onnxruntime as ort
import numpy as np

# 创建会话
sess = ort.InferenceSession(
    "model.onnx",
    providers=["CUDAExecutionProvider", "CPUExecutionProvider"],
)

# 元信息
inputs = sess.get_inputs()                         # [Input: name/shape/type]
outputs = sess.get_outputs()
print(inputs[0].name, inputs[0].shape, inputs[0].type)

# 推理
feed = {inputs[0].name: np.random.randn(*shape).astype(np.float32)}
result = sess.run(None, feed)                      # None=全部输出；或指定 [output_name]
result = sess.run(["logits"], feed)                # 只要 logits

# 多输出与绑定（避免重复拷贝）
binding = sess.io_binding()                        # 高性能 IO 绑定（CUDA 上零拷贝）

# 性能分析
sess.enable_profiling("trace.json")                # 输出 Chrome trace

SessionOptions 完整参数 ​

python
opts = ort.SessionOptions()
opts.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
opts.intra_op_num_threads = 8
opts.inter_op_num_threads = 4
opts.execution_mode = ort.ExecutionMode.ORT_SEQUENTIAL  # 或 ORT_PARALLEL
opts.enable_cpu_mem_arena = True                    # 默认开（预分配池）
opts.enable_mem_pattern = True                      # 内存复用模式
opts.add_free_dimension_override_by_denotation("batch", 1)  # 固定动态维度
opts.log_severity_level = 3                         # 日志级别

量化 API ​

python
from onnxruntime.quantization import (
    quantize_dynamic, quantize_static,
    QuantType, QuantFormat, CalibrationDataReader,
    CalibrationMethod,
)

# 动态量化
quantize_dynamic(
    model_input="model.onnx",
    model_output="model_dyn.onnx",
    weight_type=QuantType.QInt8,                    # QInt8 / QUInt8 / QInt4 / QUInt4
    op_types_to_quantize=["MatMul", "Gemm", "Conv", "LSTM"],
    per_channel=True,                               # 按通道量化（精度更高）
)

# 静态量化（需校准数据）
quantize_static(
    model_input="model.onnx",
    model_output="model_static.onnx",
    calibration_data_reader=reader,
    quant_format=QuantFormat.QDQ,                   # QDQ（默认）/ QOperator
    activation_type=QuantType.QUInt8,
    weight_type=QuantType.QInt8,
    calibrate_method=CalibrationMethod.MinMax,      # MinMax / Entropy / Percentile
    per_channel=True,
    reduce_range=False,                             # True 用 7-bit 调试精度问题
)
参数取值说明
weight_typeQInt8/QUInt8/QInt4/QUInt4权重量化类型
activation_typeQUInt8/QInt8激活量化类型（仅静态）
quant_formatQDQ/QOperator量化表示格式
calibrate_methodMinMax/Entropy/Percentile校准算法（仅静态）
per_channelbool按通道（每输出通道独立 scale） vs 按张量
op_types_to_quantizelist只量化指定算子类型

Execution Provider 列表 ​

EP（providers 字符串）厂商平台状态
CPUExecutionProvider通用全平台stable，默认
CUDAExecutionProviderNVIDIACUDA GPUstable
TensorrtExecutionProviderNVIDIATensorRTstable
TensorRTRTXExecutionProviderNVIDIARTX 显卡1.x 新增
OpenVINOExecutionProviderIntelCPU/iGPU/VPUstable
CoreMLExecutionProviderApplemacOS/iOSstable
DmlExecutionProviderMicrosoftWindows DirectMLstable
QnnExecutionProviderQualcommHTP/NPUstable
AiExecutionProvider / NnapiExecutionProviderAndroidNNAPIstable
CANNExecutionProvider华为昇腾 NPUpreview，社区维护
RocmExecutionProviderAMDROCmstable
MIGraphXExecutionProviderAMDMIGraphXstable
VitisAIExecutionProviderAMDVitis AIstable
WebGpuExecutionProviderW3C浏览器 GPU1.28 起独立插件
AclExecutionProviderArmArm Compute Librarystable
ArmNNExecutionProviderArmArm NN1.25 起移除
TvmExecutionProviderApacheTVMstable
RknpuExecutionProvider瑞芯微RKNPUstable
XnnpackExecutionProviderGoogleXNNPACKstable
AzureExecutionProviderMicrosoftAzure 云stable

opset 版本演进 ​

ONNX 版本IR 版本标准 opset关键新增
1.13919LayerNormalization、DynamicQuantizeLinear 改进
1.14919（同上版本族）
1.15920GridSample、BitwiseShift 等
1.16921AffineGrid、DeformConv 等
1.17922bicubic resize 等
1.18923Macro 扩展、更多量化算子
1.19–1.219–1024–26IR 10 引入更多类型
1.221327bfloat16 完善、新注意力算子

升级 opset 可用新算子，但目标引擎需支持对应版本——ONNX Runtime 1.28 支持 opset 27 全集。

IR 版本与 Python onnx 兼容 ​

IR 版本onnx 库版本关键变化
71.6–1.8早期稳定版
81.9–1.12引入更多类型
91.13–1.21opset 19–26 主流期
131.22+当前，支持最新算子与类型

模型格式与工具 ​

  • .onnx：标准 protobuf 格式，跨引擎通用
  • .ort：ONNX Runtime 预编译格式（prepacked），启动更快但锁定引擎版本
  • .pb：并非 ONNX 格式（是 TF 的 protobuf），勿混淆
  • ONNX Model Zoo：github.com/onnx/models 官方预训练模型仓库
  • Netron：netron.app 在线可视化工具
  • onnxsim：pip install onnxsim && onnxsim model.onnx model_sim.onnx 图简化
  • onnxoptimizer：图优化（常量折叠、融合），部分功能已并入 ORT

官方资源 ​