构建引擎流程：从ONNX模型到TensorRT引擎的完整步骤

核心原理：为什么需要“构建”而不是“加载”

ONNX是一种中间表示格式，它描述的是模型的计算图结构，而非实际在GPU上执行的指令序列。TensorRT引擎构建的本质，是将ONNX的图结构编译、优化并绑定到具体GPU架构的过程。这一过程之所以被称为“构建”，是因为它包含大量与硬件相关的决策：算子融合、显存复用规划、kernel自动调优、精度校准等。构建完成后得到的.engine文件是硬件专属的二进制序列化产物，它不再需要解析图结构，而是直接由TensorRT运行时反序列化并加载到显存中执行。

理解这一原理的关键在于：构建期（build time）与运行期（runtime）是分离的。构建期消耗大量计算资源（尤其是自动调优阶段），但运行期只做轻量级加载和推理。因此，在服务部署场景中，通常将构建好的引擎文件持久化到磁盘，运行时直接加载，避免每次启动都重新构建。

重要概念：TensorRT 8.x之后，构建引擎的推荐API是Builder + NetworkDefinition + BuilderConfig的组合。旧版caffeToModel等接口已废弃，ONNX解析统一走OnnxParser。

方法流程：六步构建法

从ONNX模型到可部署的TensorRT引擎，标准流程可拆解为以下六个步骤。每一步都有对应的API调用和关键参数，下面以Python API为例说明。

创建Builder与Network：初始化Builder，创建NetworkDefinition并设置explicit_precision或explicit_batch标志（现代TensorRT要求显式指定batch维度）。
解析ONNX模型：使用OnnxParser读取.onnx文件，将图结构填充到Network中。此阶段会做初步的图校验和常量折叠。
配置BuilderConfig：设置工作空间大小、精度模式（FP32/FP16/INT8）、动态形状范围、DLA核心等参数。这是影响最终引擎性能的关键环节。
构建引擎：调用builder.build_serialized_network()或build_engine()触发编译。此过程包含层融合、kernel选择、显存规划等优化。
序列化与保存：将构建好的引擎序列化为字节流，写入.engine文件。该文件可直接用于部署。
反序列化与推理：运行时通过Runtime加载.engine文件，创建ExecutionContext执行推理。

import tensorrt as trt

# 步骤1：创建Builder与Network
logger = trt.Logger(trt.Logger.WARNING)
builder = trt.Builder(logger)
network = builder.create_network(1 << int(trt.NetworkDefinitionCreationFlag.EXPLICIT_BATCH))
config = builder.create_builder_config()
config.set_memory_pool_limit(trt.MemoryPoolType.WORKSPACE, 1 << 30)  # 1GB

# 步骤2：解析ONNX
parser = trt.OnnxParser(network, logger)
with open("model.onnx", "rb") as f:
    parser.parse(f.read())

# 步骤3：配置精度与形状
config.set_flag(trt.BuilderFlag.FP16)  # 启用FP16
# 动态形状需设置profile
profile = builder.create_optimization_profile()
profile.set_shape("input", (1, 3, 224, 224), (4, 3, 224, 224), (8, 3, 224, 224))
config.add_optimization_profile(profile)

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

# 步骤5：保存到文件
with open("model.engine", "wb") as f:
    f.write(serialized_engine)

# 步骤6：运行时加载
runtime = trt.Runtime(logger)
engine = runtime.deserialize_cuda_engine(serialized_engine)
context = engine.create_execution_context()

常见陷阱：步骤3中如果启用了FP16但模型中有对精度敏感的操作（如某些归一化层），可能导致精度下降。建议在构建前使用trt.OnnxParser的clear()方法重新解析，或通过network.mark_output()检查输出张量精度。

案例：ResNet50的构建参数对比

以ResNet50图像分类模型为例，不同配置对构建时间和推理延迟的影响如下表所示。测试环境为NVIDIA A10 GPU，输入尺寸1×3×224×224。

配置项	FP32	FP16	INT8（校准）
构建时间（秒）	8.2	12.5	45.7（含校准）
推理延迟（毫秒）	1.82	0.94	0.61
显存占用（MB）	210	118	96
Top-1精度（ImageNet）	76.1%	76.0%	75.8%

从表中可见，FP16相比FP32在延迟上几乎减半，而INT8进一步压缩延迟但引入了校准流程。实际项目中，精度与性能的权衡需要根据业务场景决定：如果模型输出用于辅助决策（如医疗影像），优先保证精度；如果用于高并发实时推理（如视频流分析），则优先考虑INT8。

误区与复盘：构建期最容易踩的四个坑

误区一：忽略动态形状配置。如果模型输入尺寸可变，但未设置OptimizationProfile，构建时默认使用固定形状，运行时一旦输入尺寸超出范围就会报错。复盘建议：在构建前明确业务输入范围，设置min/opt/max三个档位。
误区二：工作空间设置过大或过小。工作空间（workspace）是构建期用于层融合和kernel选择的临时显存。设置过小会导致部分融合策略被跳过，过大则可能因显存不足构建失败。复盘建议：从1GB开始尝试，观察构建日志中的Total Activation Memory。
误区三：FP16/INT8精度模式盲目开启。某些算子（如Softmax、LayerNorm）在FP16下可能产生较大误差。复盘建议：构建后使用engine.create_execution_context()跑一组校验数据，对比输出张量的余弦相似度。
误区四：忽略序列化版本兼容性。TensorRT不同小版本之间引擎文件可能不兼容。复盘建议：在部署环境使用与构建环境完全相同的TensorRT版本，或使用trt.Runtime.deserialize_cuda_engine()时捕获版本异常。

  复盘清单：每次构建引擎后，建议记录以下信息——TensorRT版本、CUDA版本、GPU型号、输入形状范围、精度模式、工作空间大小、构建耗时、引擎文件大小、首次推理延迟。这些数据在后续排查性能问题或升级环境时至关重要。

构建引擎的完整流程虽然只有六步，但每一步都包含大量可调参数。实际项目中，建议先以FP32构建一个基线引擎，验证正确性后再逐步切换到FP16或INT8。同时，善用trt.Builder的get_error_state()方法检查构建状态，以及trt.OnnxParser的get_error()获取解析错误详情。掌握这些细节，才能在生产环境中稳定地完成从ONNX到TensorRT引擎的转换。