ONNX运行时架构

教程导读：ONNX 运行时架构

一句话定位：ONNX Runtime（ORT）是跨平台 ONNX 推理引擎，通过图优化、Execution Provider（EP）插件与量化工具链，把同一 .onnx 模型跑到 CPU、CUDA、TensorRT、DirectML 等设备上。本教程采用问题驱动主调：从导出失败、EP 选错、INT8 掉点、P99 抖动、部署踩坑五类故障倒查架构。

这门课解决什么问题

PyTorch 训练完模型，常见卡点不是精度，而是导出的 ONNX 在目标 EP 上跑不起来或变慢：动态 shape 未固定、LayerNorm 被拆成七步、MatMul+Gelu 未融合、INT8 校准集与线上分布不一致、intra_op_num_threads 在 GPU 上无效却占满 CPU。这些问题分散在导出、优化、执行、内存、量化、部署六个环节，彼此耦合——改线程数可能改善 P99，也可能只是掩盖了分区导致的 PCIe 拷贝。本教程按六章把 ORT 从 ONNX IR → 图优化 → EP → 内存/线程 → 量化 → Profiling/部署串成一条可倒查的排查链，每一章都给出可直接运行的代码、参数表与判断标准。

ORT 的定位远超"推理库"本身。它承担三个角色：ONNX 语义的权威解释器、异构硬件的通用适配层、以及图级优化与内存调度的编排器。理解这三个角色，就能理解为什么同一份模型在不同机器上行为不同：差异来自 EP 接管范围、优化级别、线程池与内存策略的排列组合，而不是模型本身。

适合谁读

• 要把 PyTorch/TF 模型部署到生产推理服务的工程师
• 在 Windows 上用 DirectML、在 NVIDIA 上用 TensorRT EP 的开发者
• 需要做 INT8/FP16 量化与延迟调优的 MLOps 同学
• 被"导出成功但跑不起来 / 跑起来但比框架慢 / 精度对不上"三连击折磨的部署新手

前置要求不高：会用 PyTorch 跑一个模型、会读 Python 代码即可。章节内的 mermaid 流程图、参数表和代码块互相印证，可以只挑自己踩坑的那一章读。

学习路线

五类故障与排查顺序

本教程不是按模块平铺，而是按故障倒查。下表给出五类高频故障、症状、涉及的章节与最终处置手段：

排查顺序建议：图是否合法 → EP 是否接管 → 内存/线程 → 量化 → Profile → 版本契约。跳过前两步直接调参数，往往把问题掩盖成更难查的复合故障。

配套环境与前置技能

建议在 Python 3.9+ 环境准备：onnx、onnxruntime（CPU 版即可入门，GPU 版见第3章）、onnxruntime-gpu（含 CUDA 时）、PyTorch 2.x 与 onnxscript。所有代码块标注语言，参数以 ORT 1.17+ 为准；低版本环境个别 API 需要替换，正文会标注版本差异。示例均可在 CPU 上复现，GPU 章节会额外给出验证步骤，因此没有 NVIDIA 显卡也能完成前两章的动手练习。

符号说明

• 代码块用语言标记区分：python 为 API 示例，bash 为命令行，cpp 为 Custom Op 注册，mermaid 为架构图，json 为 profile 输出片段。
• 每章开头会给出章内三节的阅读地图与前后置关系。
• ⚠️ 标记高频踩坑点，💡 标记可直接套用的判断直觉。
• 表格优先展示"决策"而不是"罗列"：选型表、参数表、故障对照表只保留能落到动作的行。

预期产出