模型转换流程：从ONNX到TensorRT的转换步骤与工具使用
核心原理：为什么需要从ONNX转换到TensorRT
ONNX（Open Neural Network Exchange）是一个开放的模型表示格式，它最大的价值在于框架中立性——无论模型是用PyTorch、TensorFlow还是PaddlePaddle训练出来的，都可以导出为ONNX格式。但ONNX本身只是一个“计算图描述”，它不包含任何针对特定硬件的优化信息。当模型部署到NVIDIA GPU上时，我们需要将ONNX转换为TensorRT的引擎文件（.engine或.plan），这个过程的核心目标有三个：
- 算子融合（Layer Fusion）：将Conv+Bias+ReLU等连续小算子融合为单个CUDA核函数，减少kernel启动开销。
- 精度校准（Precision Calibration）：将FP32权重转换为FP16或INT8，在几乎不损失精度的情况下大幅提升吞吐量。
- 内存优化与内核自动调优：TensorRT会为当前GPU架构选择最优的tactic（内核实现），并优化显存布局。
转换的本质是“图优化 + 内核选择 + 权重重写”的过程，而不是简单的格式翻译。理解这一点，才能明白为什么转换后模型文件变大或变小、为什么某些算子转换失败、为什么同一模型在不同GPU上生成的engine不通用。
方法流程：标准转换路径与工具链
从ONNX到TensorRT的转换主要有三条路径，按推荐优先级排列如下：
| 工具 | 适用场景 | 精度控制 | 动态shape支持 | 推荐度 |
|---|---|---|---|---|
| TensorRT API（Python/C++） | 生产部署、需要精细控制 | FP32/FP16/INT8 | 支持（需设置优化profile） | ★★★★★ |
| trtexec命令行工具 | 快速验证、性能基准测试 | FP32/FP16/INT8 | 支持（通过min/max/opt shape指定） | ★★★★☆ |
| Polygraphy（配合ONNX-GraphSurgeon） | 调试转换失败、逐层对比精度 | FP32/FP16/INT8 | 支持 | ★★★★☆ |
最标准、可控性最强的流程是使用TensorRT Python API，核心步骤如下：
- 导出ONNX：从训练框架导出ONNX，并固定或标记动态维度。
- 创建Builder与Network：通过TensorRT的Builder加载ONNX文件，生成Network定义。
- 配置Builder：设置工作空间大小、精度标志（FP16/INT8）、动态shape优化profile。
- 构建Engine：调用builder.build_serialized_network()生成序列化engine。
- 反序列化并推理：在运行时通过Runtime加载engine，创建ExecutionContext执行推理。
import tensorrt as trt
# 创建logger和builder
logger = trt.Logger(trt.Logger.WARNING)
builder = trt.Builder(logger)
network = builder.create_network(1 << trt.NetworkDefinitionCreationFlag.EXPLICIT_BATCH)
parser = trt.OnnxParser(network, logger)
# 解析ONNX模型
with open("model.onnx", "rb") as f:
parser.parse(f.read())
# 配置builder
config = builder.create_builder_config()
config.set_memory_pool_limit(trt.MemoryPoolType.WORKSPACE, 1 << 30) # 1GB workspace
config.set_flag(trt.BuilderFlag.FP16) # 启用FP16
# 处理动态shape（如果ONNX有动态维度）
profile = builder.create_optimization_profile()
input_tensor = network.get_input(0)
profile.set_shape(input_tensor.name, (1, 3, 224, 224), (8, 3, 224, 224), (32, 3, 224, 224))
config.add_optimization_profile(profile)
# 构建engine
serialized_engine = builder.build_serialized_network(network, config)
with open("model.engine", "wb") as f:
f.write(serialized_engine)案例/场景：动态batch的YOLOv8检测模型转换
以YOLOv8检测模型为例，该模型包含C2f模块、Detect头等复杂结构，转换时经常遇到以下问题：
- ONNX导出时默认固定batch=1，导致TensorRT无法动态调整batch。
- Detect头中的
grid生成、sigmoid等操作在FP16下可能出现精度漂移。 - NMS（非极大值抑制）在ONNX中通常以自定义算子存在，TensorRT原生不支持，需要替换为EfficientNMS插件。
实际转换中，我们使用ONNX-GraphSurgeon对计算图进行预处理，将Detect头中的解码部分拆解为TensorRT原生算子，并替换NMS为TRT插件。转换完成后，通过Polygraphy对比ONNX-Runtime与TensorRT在相同输入下的输出差异，确保最大误差小于1e-3。
# 使用trtexec快速验证FP16性能
trtexec --onnx=yolov8s.onnx \
--saveEngine=yolov8s_fp16.engine \
--fp16 \
--minShapes=images:1x3x640x640 \
--optShapes=images:8x3x640x640 \
--maxShapes=images:32x3x640x640 \
--workspace=2048转换后实测数据：在RTX 4090上，FP16引擎相比ONNX-Runtime FP32推理速度提升约2.8倍，显存占用降低约35%。但若直接使用FP16而不做任何校准，mAP可能下降0.5~1.0个百分点，因此对于检测任务建议使用INT8量化并配合校准集。
误区/复盘：转换失败与精度劣化的常见原因
以下是工程师在ONNX转TensorRT过程中最常踩的坑，以及对应的排查思路：
--trt-min-layers和--trt-max-layers定位失败层，然后用ONNX-GraphSurgeon将不支持算子替换为等价的TensorRT原生算子组合，或使用TensorRT插件（Plugin）。
layer.precision = trt.float32和layer.set_output_type()实现混合精度。
另一个常见误区是忽略动态shape的profile设置。如果ONNX输入维度是动态的，但构建engine时未提供优化profile，TensorRT会默认使用输入的实际shape作为唯一优化点，导致运行时其他shape性能骤降或直接报错。正确做法是设置三个关键值：minShape（最小允许shape）、optShape（性能最优shape）、maxShape（最大允许shape），且三者必须满足包含关系。
最后，关于INT8量化有一个常见误解：认为只要设置set_flag(trt.BuilderFlag.INT8)就能自动量化。实际上，TensorRT的INT8需要提供校准数据集（Calibration Dataset），它会在校准过程中统计每层激活值的分布，从而选择最优的量化scale。如果校准集与真实数据分布差异过大，量化后精度会严重劣化。建议校准集覆盖至少500~1000张具有代表性的样本，并采用熵校准（Entropy Calibration）作为默认方法。
# 使用Polygraphy对比ONNX-RT与TensorRT的输出差异
polygraphy run model.onnx --trt --onnxrt \
--fp16 \
--atol 1e-3 --rtol 1e-3 \
--trt-min-shapes images:[1,3,640,640] \
--trt-opt-shapes images:[8,3,640,640] \
--trt-max-shapes images:[32,3,640,640] \
--validate复盘整个转换流程，最核心的经验可以总结为：先确保ONNX图干净、算子原生，再谈精度优化；先跑通FP32，再尝试FP16，最后才考虑INT8。每一步都要有可量化的验证指标（如mAP、余弦相似度、最大绝对误差），而不是凭感觉判断“看起来差不多”。TensorRT的转换不是一次性的“按钮操作”，而是一个需要反复迭代、逐层排查的工程过程。掌握trtexec、Polygraphy、ONNX-GraphSurgeon这三个工具，就能覆盖从快速验证到深度调试的全部需求。