4. 模型转换流程

在DeepStream应用中，nvinfer插件本身并不直接加载PyTorch或TensorFlow的权重文件，而是要求输入一个经过TensorRT优化后的Engine文件（通常为.engine或.trt）。因此，将训练好的模型转换为TensorRT Engine是整个部署链路中最关键的一步。本章将系统讲解从PyTorch/TensorFlow/ONNX到TensorRT Engine的完整转换流程，涵盖trtexec命令行工具与Python API两种方式，并深入分析动态形状、精度校准（FP16/INT8）以及常见排障方法。

模型转换全流程：从训练框架到TensorRT Engine PyTorch .pth / .pt TensorFlow .pb / .h5 ONNX .onnx 统一中间表示 ONNX（推荐） 或直接使用框架解析器 trtexec 命令行工具 Python API TensorRT Python绑定 TensorRT Engine .engine / .trt FP32 / FP16 / INT8 关键配置参数 • --fp16 / --int8 精度 • --minShapes / --optShapes • --maxShapes 动态形状 • --calib 校准数据 DeepStream nvinfer 加载

4.1 核心原理：为什么需要中间表示与Engine序列化

TensorRT之所以不能直接读取PyTorch或TensorFlow的权重，是因为其底层优化引擎建立在网络图的层融合、内核自动调优和显存复用之上。训练框架的图结构包含大量动态控制流、自动求导节点和算子变体，这些在推理阶段是冗余的。因此，转换流程的核心思想是：将训练框架的图结构“净化”为静态推理图，再交给TensorRT进行深度优化。

ONNX（Open Neural Network Exchange）作为中间表示层，起到了“通用语言”的作用。它将PyTorch的TorchScript或TensorFlow的SavedModel统一映射为标准的算子集合。TensorRT的ONNX解析器（onnx-tensorrt）会逐节点解析ONNX图，并将其转换为TensorRT的Network Definition。这一过程中，每个ONNX算子都会被映射到TensorRT的ILayer实现，无法映射的算子则会被标记为“不支持”，需要开发者手动替换或使用Plugin扩展。

Engine文件本质上是一个序列化后的优化执行计划，它包含了层融合后的内核选择、权重重排、显存池分配策略等全部信息。在DeepStream中，nvinfer通过gst-tensorrt后端直接反序列化该文件，无需重新构建网络，从而将加载时间从分钟级缩短到秒级。

关键认知：Engine文件与硬件绑定。在Xavier上生成的Engine无法在Orin或x86_64+GPU上直接使用，因为TensorRT会根据具体GPU架构（如Ampere、Turing、Volta）选择不同的CUDA内核。跨设备部署必须重新生成Engine。

4.2 操作流程：使用trtexec命令行工具转换

trtexec是TensorRT自带的命令行工具，适合快速验证模型可转换性和生成基准Engine。其基本调用格式如下：

# 基本FP32转换
trtexec --onnx=model.onnx --saveEngine=model_fp32.engine

# FP16转换（推荐用于DeepStream）
trtexec --onnx=model.onnx --fp16 --saveEngine=model_fp16.engine

# INT8转换（需要校准数据）
trtexec --onnx=model.onnx --int8 --calib=calibration.txt --saveEngine=model_int8.engine

# 动态形状转换
trtexec --onnx=model.onnx --minShapes=input:1x3x224x224 \
        --optShapes=input:8x3x224x224 --maxShapes=input:16x3x224x224 \
        --fp16 --saveEngine=model_dynamic.engine

对于DeepStream场景，推荐使用固定形状的Engine，因为nvinfer的批处理大小通常在配置文件中固定。如果必须支持动态分辨率（如不同视频源的输入尺寸），则需要使用动态形状参数，并在nvinfer配置中设置input-shape与batch-size匹配。

转换完成后，务必使用trtexec的基准测试功能验证性能：

trtexec --loadEngine=model_fp16.engine --shapes=input:8x3x224x224 --iterations=100

该命令会输出平均延迟、吞吐量（FPS）以及显存占用等关键指标，帮助判断Engine是否满足实时性要求。

4.3 操作流程：使用Python API转换

当需要更精细的控制（如自定义Plugin、动态校准、层级剪枝）时，Python API是更灵活的选择。以下是一个完整的转换脚本模板：

import tensorrt as trt
import pycuda.driver as cuda
import pycuda.autoinit

# 创建Logger与Builder
logger = trt.Logger(trt.Logger.WARNING)
builder = trt.Builder(logger)
network = builder.create_network(1 << int(trt.NetworkDefinitionCreationFlag.EXPLICIT_BATCH))
parser = trt.OnnxParser(network, logger)

# 解析ONNX模型
with open("model.onnx", "rb") as f:
    if not parser.parse(f.read()):
        for i in range(parser.num_errors):
            print(parser.get_error(i))
        raise RuntimeError("ONNX解析失败")

# 配置构建选项
config = builder.create_builder_config()
config.set_memory_pool_limit(trt.MemoryPoolType.WORKSPACE, 1 << 30)  # 1GB工作空间
config.set_flag(trt.BuilderFlag.FP16)  # 启用FP16

# 动态形状配置
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), (16, 3, 224, 224))
config.add_optimization_profile(profile)

# 构建Engine
serialized_engine = builder.build_serialized_network(network, config)
with open("model_fp16.engine", "wb") as f:
    f.write(serialized_engine)
print("Engine生成成功！")

Python API的核心优势在于可以在构建前对网络进行编程式修改。例如，可以遍历网络层，将特定层的精度强制设置为FP32（避免精度敏感层被降精度），或者插入自定义Plugin层。

4.4 案例拆解：YOLOv8检测模型在DeepStream中的完整转换

以YOLOv8s（COCO预训练）为例，展示从PyTorch到DeepStream可用的Engine全过程。该案例在NVIDIA Orin NX平台上完成，目标是在1080p视频流上实现实时检测（≥30 FPS）。

初始状态与约束：PyTorch权重为yolov8s.pt，输入尺寸640×640，类别80。DeepStream管道中nvinfer的批处理大小设置为4。由于Orin NX的GPU为Ampere架构，支持FP16和INT8，但INT8需要额外校准。

第一步：导出ONNX。使用Ultralytics官方导出脚本：

yolo export model=yolov8s.pt format=onnx dynamic=False imgsz=640

导出后验证ONNX的输入输出节点名称：

python -c "import onnx; m=onnx.load('yolov8s.onnx'); print([i.name for i in m.graph.input]); print([o.name for o in m.graph.output])"

输出显示输入名为images，输出名为output0（形状为[1,84,8400]）。

第二步：trtexec转换FP16 Engine。由于DeepStream的批处理固定为4，我们直接生成固定批处理大小的Engine：

trtexec --onnx=yolov8s.onnx --fp16 --saveEngine=yolov8s_fp16.engine \
        --minShapes=images:4x3x640x640 --optShapes=images:4x3x640x640 --maxShapes=images:4x3x640x640

转换耗时约2分钟，生成的Engine大小为42MB。使用--shapes=images:4x3x640x640进行基准测试，测得平均延迟为11.2ms（对应约89 FPS），满足实时性要求。

第三步：DeepStream配置集成。在nvinfer配置文件中设置：

[property]
gpu-id=0
net-scale-factor=0.003921569
model-file=yolov8s_fp16.engine
batch-size=4
network-mode=1
num-detected-classes=80
interval=0
gie-unique-id=1
output-blob-names=output0

第四步：验证与排障。运行DeepStream测试时发现检测框偏移严重。分析原因：YOLOv8的输出格式为[cx, cy, w, h, class_scores...]，且坐标是相对于输入尺寸的归一化值。需要在nvinfer的parse-bbox中设置正确的参数，或者在自定义后处理中调整。最终通过修改custom-parser函数解决了该问题。

转换阶段关键操作耗时注意事项
PyTorch → ONNXyolo export~5秒设置dynamic=False简化图结构
ONNX → FP16 Enginetrtexec --fp16~2分钟固定批处理大小避免动态形状开销
Engine验证trtexec基准测试~30秒确认延迟与吞吐量达标
DeepStream集成nvinfer配置~10分钟输出blob名称必须与ONNX一致

4.5 常见误区与总结复盘

高风险误区：直接使用PyTorch导出的TorchScript文件输入trtexec。TorchScript包含大量动态控制流，TensorRT解析器支持度极低，绝大多数情况下会解析失败。务必先转换为ONNX。

误区一：忽略动态形状的代价。动态形状Engine在每次推理时都会进行形状推断，性能比固定形状低10%-20%。在DeepStream中，如果视频源分辨率固定，应使用固定形状Engine。

误区二：FP16精度损失未验证。某些模型（如关键点检测、分割任务）对FP16敏感，转换后mAP可能下降超过1%。建议在转换后使用验证集对比FP32与FP16的精度差异，必要时对特定层强制使用FP32。

误区三：INT8校准数据不足。INT8转换需要至少500-1000张代表性图片进行校准。如果校准集与真实场景分布差异大，会导致严重的精度下降。DeepStream中推荐使用实际视频流中的帧作为校准数据。

误区四：Engine文件跨设备复用。在开发机上生成的Engine直接拷贝到部署设备（如从x86_64+RTX 3090到Orin）会导致加载失败或CUDA错误。必须使用目标设备重新生成。

经验总结：推荐的标准转换链路为：PyTorch/TF → ONNX（静态图） → trtexec（FP16） → 验证精度与性能 → DeepStream集成。对于需要INT8的场景，务必准备充分的校准数据集，并在转换后使用真实业务数据做端到端验证。

通过本章的学习，读者应能够独立完成从训练框架到TensorRT Engine的完整转换，并具备基本的排障能力。在实际项目中，建议将转换脚本固化到CI/CD流程中，确保模型更新后能够自动生成新的Engine并回归测试。

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