4、模型转换流程：从PyTorch/TensorFlow/ONNX到TensorRT的完整转换路径与工具链（trtexec、polygraphy）

模型转换是TensorRT部署流程中最关键、也最容易出问题的一环。很多开发者习惯于“训练完直接转engine”，结果在推理阶段遇到精度下降、算子不支持、动态shape报错等问题。实际上，从PyTorch/TensorFlow到TensorRT的转换并非单一操作，而是一条包含多个中间表示、多种工具链、多级验证的工程链路。本章将系统梳理从训练框架到TensorRT引擎的完整转换路径，重点讲解trtexec与polygraphy这两个核心工具的使用方法、适用场景与排障技巧，帮助读者建立一套可复用的转换方法论。

TensorRT模型转换完整链路 PyTorch torch.onnx.export TensorFlow tf2onnx / saved_model PaddlePaddle paddle2onnx ONNX Runtime onnxruntime-gpu验证 ONNX 中间表示 算子集版本 / 动态轴 / 静态shape trtexec 引擎构建 --onnx --saveEngine --fp16 --minShapes --optShapes --maxShapes --builderOptimizationLevel --timingCache Polygraphy 精度对比/层间调试 --trt --onnx --validate TensorRT Engine (.engine / .plan) 序列化 / 反序列化 / 运行时加载 精度/性能验证反馈 路径1: 训练框架 → ONNX → trtexec → Engine（标准路径） 路径2: 训练框架 → ONNX → Polygraphy → Engine（调试路径）

上图展示了模型转换的完整链路。核心思路是：所有训练框架最终都先统一到ONNX中间表示，再通过trtexec或Polygraphy构建TensorRT引擎。ONNX作为“通用语言”解决了框架差异问题，而trtexec和Polygraphy则分别承担“快速构建”和“深度验证”的职责。下面我们逐一拆解每个环节的具体操作与注意事项。

4.1 从PyTorch/TensorFlow导出ONNX：统一中间表示

ONNX（Open Neural Network Exchange）是微软主导的开放式神经网络交换格式，它定义了一套与框架无关的算子集合和计算图表示。将训练好的模型转换为ONNX，是进入TensorRT世界的第一步，也是后续所有优化工作的基础。

核心原理：ONNX作为“翻译层”

ONNX的核心价值在于算子层面的标准化。PyTorch的autograd图、TensorFlow的GraphDef、PaddlePaddle的ProgramDesc，各自有完全不同的内部表示。ONNX通过定义一组标准算子（如Conv、MatMul、Relu、Reshape等），将不同框架的计算逻辑“翻译”成统一格式。TensorRT的解析器（ONNX Parser）只需要理解ONNX这一种格式，就能将计算图映射到TensorRT的层（Layer）上。

导出ONNX时，最关键的两个参数是算子集版本（opset_version）和动态轴（dynamic_axes）。算子集版本决定了ONNX中可用的算子种类和属性格式，TensorRT对ONNX算子集的支持范围通常滞后于最新版本，建议使用opset_version=11~17之间的稳定版本。动态轴则决定了导出的模型是否支持可变输入尺寸，这对后续TensorRT的dynamic shape配置至关重要。

操作流程：PyTorch导出ONNX的标准步骤

import torch
import torch.onnx

# 假设model是训练好的PyTorch模型，已切换到eval模式
model.eval()

# 构造一个示例输入，shape需与训练时一致
dummy_input = torch.randn(1, 3, 224, 224).cuda()

# 导出ONNX
torch.onnx.export(
    model,                      # 模型
    dummy_input,                # 示例输入
    "model.onnx",               # 输出路径
    export_params=True,         # 导出权重
    opset_version=13,           # 算子集版本
    do_constant_folding=True,   # 常量折叠优化
    input_names=["input"],      # 输入节点名
    output_names=["output"],    # 输出节点名
    dynamic_axes={
        "input": {0: "batch_size"},   # 第0维为动态batch
        "output": {0: "batch_size"}
    }
)
print("ONNX导出完成")

对于TensorFlow模型，推荐使用tf2onnx工具：

# 安装: pip install tf2onnx
python -m tf2onnx.convert \
    --saved-model ./saved_model_dir \
    --output model.onnx \
    --opset 13 \
    --inputs input:0 \
    --outputs output:0

导出完成后，务必使用onnxruntime-gpu做一次推理验证，确认ONNX模型的输出与原始框架一致。这一步能提前暴露算子兼容性问题，避免问题累积到TensorRT阶段。

经验提醒：导出ONNX时，如果模型包含自定义算子（如自定义ROI Align、自定义激活函数），需要先注册ONNX自定义算子，或者将这些算子替换为ONNX标准算子组合。否则后续TensorRT解析会直接报“Unsupported Operator”错误。

4.2 trtexec：快速构建引擎的瑞士军刀

trtexec是TensorRT自带的命令行工具，它集成了模型解析、引擎构建、性能测试、精度验证四大功能。对于大多数标准模型，一条trtexec命令就能完成从ONNX到Engine的转换，并输出详细的性能报告。

核心原理：trtexec的构建流程

trtexec内部执行以下步骤：

  1. 解析ONNX：通过ONNX Parser将计算图转换为TensorRT的Network定义。
  2. 图优化：应用层融合（Layer Fusion）、精度校准（Calibration）、常量折叠等优化策略。
  3. 引擎构建：根据目标GPU架构（如SM86、SM89）生成优化的CUDA Kernel。
  4. 序列化：将引擎保存为.engine文件，供运行时反序列化加载。

trtexec的关键参数决定了引擎的精度模式和动态shape范围。FP16模式通过--fp16开启，INT8量化需要额外提供校准数据（--calib）。动态shape通过--minShapes、--optShapes、--maxShapes三个参数定义，分别指定输入的最小、最优、最大尺寸。

操作流程：trtexec构建引擎的完整命令

# 基础FP32引擎
trtexec --onnx=model.onnx --saveEngine=model_fp32.engine

# FP16引擎，开启动态shape
trtexec --onnx=model.onnx \
        --saveEngine=model_fp16.engine \
        --fp16 \
        --minShapes=input:1x3x224x224 \
        --optShapes=input:8x3x224x224 \
        --maxShapes=input:32x3x224x224

# 带性能测试的构建
trtexec --onnx=model.onnx \
        --saveEngine=model.engine \
        --fp16 \
        --minShapes=input:1x3x224x224 \
        --optShapes=input:8x3x224x224 \
        --maxShapes=input:32x3x224x224 \
        --avgRuns=100 \
        --warmUp=2000 \
        --duration=10

构建完成后，trtexec会输出详细的性能报告，包括GPU Compute Time、End-to-End Latency、Throughput等关键指标。这些数据可以直接用于评估模型在目标硬件上的推理性能。

案例拆解：ResNet50在Jetson Orin上的FP16转换

假设我们在Jetson Orin（GPU架构为Ampere，SM86）上部署ResNet50图像分类模型。初始使用FP32引擎，测得单张推理延迟为3.2ms，吞吐量为312 FPS。为了提升性能，我们改用FP16模式：

trtexec --onnx=resnet50.onnx \
        --saveEngine=resnet50_fp16.engine \
        --fp16 \
        --minShapes=input:1x3x224x224 \
        --optShapes=input:8x3x224x224 \
        --maxShapes=input:32x3x224x224 \
        --avgRuns=50

构建完成后，性能报告显示GPU Compute Time降至1.1ms，吞吐量提升至890 FPS，性能提升约2.9倍。同时，我们使用--verbose参数检查了构建日志，确认所有Conv层和BatchNorm层均成功融合为FP16精度，没有出现精度回退（Fallback）警告。

风险提示：FP16模式并非对所有模型都安全。如果模型包含对精度敏感的算子（如Softmax、LayerNorm），FP16可能导致精度下降。建议在转换后使用Polygraphy进行精度对比，若误差超过1%，应回退到FP32或使用混合精度（--precision=FP16+FP32）。

4.3 Polygraphy：深度验证与排障利器

Polygraphy是NVIDIA官方提供的模型调试工具，它能够对ONNX模型和TensorRT引擎进行逐层对比、精度分析、性能剖析。当trtexec构建成功但推理结果异常时，Polygraphy是定位问题的最佳工具。

核心原理：Polygraphy的对比机制

Polygraphy的核心功能是运行结果对比。它可以将ONNX Runtime的输出作为基准（Ground Truth），与TensorRT引擎的输出进行逐元素比较，计算最大误差、平均相对误差、余弦相似度等指标。更强大的是，Polygraphy支持层间调试（Layer-wise Debugging），可以逐层对比ONNX和TensorRT的中间张量，精确定位到导致精度下降的具体层。

操作流程：Polygraphy精度验证与层间调试

# 1. 基础精度对比：ONNX Runtime vs TensorRT
polygraphy run model.onnx \
    --trt --onnxrt \
    --fp16 \
    --input-shape input:1x3x224x224 \
    --atol 0.01 --rtol 0.01 \
    --validate

# 2. 层间调试：逐层对比中间张量
polygraphy run model.onnx \
    --trt --onnxrt \
    --fp16 \
    --input-shape input:1x3x224x224 \
    --trt-min-shape input:1x3x224x224 \
    --trt-opt-shape input:8x3x224x224 \
    --trt-max-shape input:32x3x224x224 \
    --validate \
    --layerwise \
    --output-dir ./polygraphy_debug

# 3. 提取引擎中间层输出
polygraphy run model.onnx \
    --trt \
    --fp16 \
    --input-shape input:1x3x224x224 \
    --trt-outputs mark all \
    --save-engine engine.engine

当--validate检测到误差超限时，Polygraphy会输出详细的对比报告，指出哪些层的输出差异最大。例如，报告可能显示Conv_124层的最大误差为0.05，而其他层误差均在0.001以下。这时我们可以针对性地检查该层的实现，或者考虑将该层强制回退到FP32精度。

实战场景：FP16精度下降的定位与修复

某目标检测模型在FP16转换后，检测框坐标偏移明显。使用Polygraphy进行层间调试：

polygraphy run yolov5s.onnx \
    --trt --onnxrt \
    --fp16 \
    --input-shape input:1x3x640x640 \
    --layerwise \
    --validate \
    --atol 0.001 --rtol 0.001

调试报告显示，Sigmoid_210层的输出误差达到0.02，而其他层误差均小于0.001。进一步分析发现，该层位于检测头的坐标解码部分，对精度极其敏感。解决方案是在TensorRT中对该层强制使用FP32精度：

# 使用Polygraphy的精度覆盖功能
polygraphy run yolov5s.onnx \
    --trt --onnxrt \
    --fp16 \
    --layer-precision Sigmoid_210:float32 \
    --input-shape input:1x3x640x640 \
    --validate

修复后，最大误差降至0.0008，检测框坐标恢复正常。这个案例说明，Polygraphy的层间调试能力是解决精度问题的关键工具，它避免了“全模型回退FP32”这种低效方案。

核心要点：trtexec负责“快”，Polygraphy负责“准”。在实际项目中，先用trtexec快速构建引擎并评估性能，再用Polygraphy验证精度。如果精度不达标，使用Polygraphy的层间调试定位问题层，然后通过精度覆盖或算子替换修复。这套流程可以覆盖90%以上的模型转换场景。

4.4 转换路径选择与常见误区

模型转换并非只有一条路，根据模型类型和部署需求，可以选择不同的转换路径。同时，开发者经常在转换过程中踩入一些“坑”，了解这些误区能显著提升转换效率。

转换路径对比

转换路径 适用场景 优点 缺点
PyTorch → ONNX → trtexec 标准CNN、Transformer模型 流程简单、工具成熟、支持动态shape ONNX算子覆盖不全时需手动处理
TensorFlow → ONNX → trtexec TF SavedModel或Keras模型 tf2onnx工具链完善 TF自定义算子转换困难
PyTorch → trtexec（直接解析） PyTorch模型且算子简单 跳过ONNX中间层，减少转换损耗 TensorRT不直接支持PyTorch，需通过torch2trt等第三方库
ONNX → Polygraphy → Engine 精度敏感模型、需要层间调试 可定位精度问题、支持精度覆盖 构建速度比trtexec慢

常见误区与规避策略

  • 误区一：忽略ONNX验证。很多开发者导出ONNX后直接转TensorRT，结果精度异常时无法判断是ONNX导出问题还是TensorRT优化问题。正确做法是先用ONNX Runtime验证ONNX输出与原始框架一致。
  • 误区二：动态shape配置不当。minShapes设置过小会导致GPU显存分配不足，maxShapes设置过大会导致引擎构建失败或推理性能下降。建议根据实际部署场景统计输入尺寸分布，合理设置三个shape参数。
  • 误区三：盲目使用FP16/INT8。FP16能带来近2倍性能提升，但并非所有模型都适用。INT8量化需要校准数据集，且对量化敏感模型（如检测头、分割头）效果不佳。建议先用FP16，再根据精度需求决定是否尝试INT8。
  • 误区四：忽略Timing Cache。TensorRT引擎构建耗时较长，尤其是动态shape模型。使用--timingCache=./timing.cache可以缓存构建过程中的计时数据，加速后续构建。

总结复盘：一套可复用的转换流程

基于以上分析，推荐以下标准转换流程：

  1. 导出ONNX：设置合适的opset版本和动态轴，用ONNX Runtime验证输出。
  2. trtexec快速构建：先构建FP32引擎，确认功能正确，再尝试FP16。
  3. Polygraphy精度验证：对比ONNX Runtime和TensorRT输出，确认误差在可接受范围。
  4. 层间调试（如有必要）：定位精度问题层，使用精度覆盖或算子替换修复。
  5. 性能调优：使用trtexec的--builderOptimizationLevel参数（0-5）调整优化强度，找到性能与构建时间的平衡点。
  6. 保存与部署：将最终引擎序列化保存，在推理程序中反序列化加载。

这套流程已经在多个实际项目中验证，覆盖了从简单分类模型到复杂检测、分割模型的转换需求。掌握trtexec和Polygraphy这两个工具，就等于掌握了TensorRT模型转换的核心能力。

← 上一章 📖 返回目录 下一章 →