📚 课程目录第3章 TensorRT基础

3. TensorRT基础

在进入异常排查之前，必须先建立对TensorRT工作方式的整体认知。绝大多数推理异常——无论是精度偏差、显存溢出还是推理速度不符合预期——根源都在于对TensorRT的引擎构建期与推理运行期的职责划分理解不清。本节将梳理TensorRT的核心抽象、标准推理流水线以及引擎的构建与部署方法，为后续章节的故障定位打下基础。

3.1 核心概念：从网络定义到引擎

TensorRT的本质是一个深度学习推理优化器与运行时。它接收训练框架（PyTorch、TensorFlow、ONNX等）导出的模型，经过一系列图优化、层融合、精度校准与内核自动调优，生成一个高度优化的序列化引擎文件（通常以.engine或.plan为后缀）。理解以下五个核心对象，是掌握TensorRT的起点：

Network Definition（网络定义）：描述模型的计算图结构，包含张量（ITensor）与层（ILayer）。既可以通过ONNX解析器从.onnx文件构建，也可以通过TensorRT的C++/Python API逐层手工搭建。
Builder（构建器）：负责将网络定义编译为引擎。构建器执行层融合、精度选择（FP32/FP16/INT8）、显存优化等操作。构建过程通常耗时较长，且需要较大的显存空间。
Engine（引擎）：构建器产出的优化后计算图，包含具体的执行计划。引擎可以序列化为二进制文件，也可以反序列化加载到内存中直接使用。
Context（执行上下文）：引擎的运行时实例。一个引擎可以创建多个Context，每个Context拥有独立的中间张量显存空间，用于执行推理。
Tensor（张量）：网络中的数据载体，具有名称、数据类型（DataType）、形状（Shape）和布局（Layout）。在动态形状模式下，张量的形状可以在运行时指定。

关键认知：构建期（Build Time）与运行期（Runtime）是彻底分离的。构建期完成所有耗时优化，运行期只负责高效执行。因此，引擎文件与GPU型号、CUDA版本、TensorRT版本强绑定，跨环境部署时引擎文件不可复用，必须重新构建。

3.2 标准推理流程：从模型文件到推理结果

TensorRT的典型使用流程可以归纳为五个步骤。在实际工程中，步骤1-3通常在离线环境完成（如模型训练服务器），步骤4-5在部署环境完成（如生产推理服务器）。理解这个流程的边界，有助于快速定位异常发生在哪个阶段。

模型导出：将训练好的PyTorch/TensorFlow模型导出为ONNX格式。这一步需要固定模型的输入输出名称、维度（动态轴需显式声明）和数据类型。
构建引擎：使用TensorRT Builder加载ONNX文件，配置精度、工作空间大小、动态形状范围等参数，生成引擎文件。
序列化保存：将引擎写入磁盘，得到.engine文件。该文件包含优化后的计算图与内核选择结果。
反序列化加载：在部署环境中，通过Runtime读取.engine文件，创建引擎实例。
创建上下文并推理：为引擎创建Context，绑定输入输出显存地址，调用enqueueV3（异步）或executeV2（同步）执行推理。

以下是一个典型的Python API构建引擎的代码骨架：

import tensorrt as trt

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

# 2. 解析 ONNX 模型
with open("model.onnx", "rb") as f:
    parser.parse(f.read())

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

# 4. 构建引擎
serialized_engine = builder.build_serialized_network(network, config)

# 5. 保存引擎文件
with open("model.engine", "wb") as f:
    f.write(serialized_engine)

工程建议：构建引擎时务必设置builder_optimization_level（默认3）和memory_pool_limit。前者控制优化强度，后者限制构建时使用的显存上限。如果构建时显存不足，会抛出std::bad_alloc或CUDA OOM错误，此时应降低工作空间限制或使用FP16/INT8精度。

3.3 引擎构建的关键参数与精度选择

引擎构建时的参数配置直接决定推理性能与精度。下表总结了最关键的构建参数及其影响：

参数/配置项	可选值	对推理的影响	典型异常表现
精度模式	FP32 / FP16 / INT8	FP16/INT8显著提升吞吐，但可能引入精度损失	输出NaN、精度下降
工作空间大小	MB ~ GB 级别	越大越可能选择更优内核，但显存占用更高	构建期OOM、推理期显存不足
动态形状范围	minShape / optShape / maxShape	决定运行时可接受的输入尺寸范围	输入尺寸超出范围报错
优化级别	0 ~ 5	级别越高优化越充分，构建时间越长	构建时间过长、内核选择失败
INT8校准器	校准数据集 + 校准算法	决定INT8量化缩放因子，直接影响精度	INT8精度严重下降

对于INT8量化，需要额外提供校准数据集（通常500~1000张代表性图片）。TensorRT会统计每层激活值的分布，计算最优的量化缩放因子。如果校准数据集与真实推理数据分布差异过大，会导致严重的精度退化——这是INT8推理精度异常的常见根因。

3.4 部署方式与常见误区

TensorRT的部署方式主要有三种：直接集成TensorRT C++/Python API、通过Triton Inference Server、通过TensorRT-LLM（大语言模型场景）。无论哪种方式，都需要注意以下常见误区：

误区一：引擎文件跨环境复用。很多开发者将.engine文件从开发机直接拷贝到生产服务器，结果加载失败或推理结果错误。原因在于引擎与GPU架构（如A100 vs V100）、CUDA版本、TensorRT版本严格绑定。正确做法是在目标环境重新构建引擎，或使用trtexec工具在目标环境验证后再部署。

误区二：忽略动态形状的显存预留。使用动态形状（Dynamic Shape）时，TensorRT会按maxShape分配显存。如果maxShape设置过大，即使实际推理使用小尺寸，显存占用依然很高；如果设置过小，推理时输入超出范围会直接报错。建议根据业务实际负载合理设置optShape与maxShape。

误区三：混淆同步与异步执行。executeV2是同步阻塞调用，enqueueV3是异步非阻塞调用。异步调用必须确保输入输出显存缓冲区在推理完成前不被释放或覆盖，否则会产生数据竞争，导致输出随机错误。排查推理结果不稳定时，优先检查异步调用的显存生命周期管理。

3.5 案例复盘：一次FP16精度异常的定位

某项目将PyTorch模型转换为TensorRT FP16引擎后，发现输出与PyTorch原始模型相比偏差较大，部分类别置信度下降超过5%。排查过程如下：

第一步：确认精度对比基准。使用同一输入分别运行PyTorch模型与TensorRT FP32引擎，确认FP32引擎输出与PyTorch一致（误差<1e-5），排除网络结构解析错误。
第二步：对比FP16与FP32引擎输出。发现FP16引擎在特定层（如Softmax之前的全连接层）输出差异显著，怀疑是FP16动态范围不足导致。
第三步：使用层级精度控制。通过config.set_precision()将敏感层强制回退到FP32，或使用ILayer.set_precision()逐层指定精度。最终定位到是LayerNorm层在FP16下精度损失过大。
第四步：解决方案。对LayerNorm层强制使用FP32精度，其余层保持FP16，最终精度恢复到可接受范围，推理速度仅下降约3%。

这个案例说明：FP16并非对所有层都安全，尤其是涉及大数值范围计算（如归一化、指数运算）的层。在精度敏感场景，建议使用trtexec --fp16 --verbose逐层分析精度差异，或直接对敏感层做精度回退。