TensorRT：推理内存、执行上下文与版本迁移

从构建到一次推理请求

TensorRT 把支持的模型图编译成面向目标环境的推理引擎。先阅读 模型导出与部署流程 理解验证顺序；本文集中解释运行时对象、内存和版本迁移。

对象或阶段	作用	需要保存或管理的状态
Network / Parser	表达网络并解析 ONNX	运算、类型、输入输出及解析错误
Builder / Config	选择实现并构建	形状 profile、内存预算、精度、插件等
序列化 engine / plan	持久化构建结果	文件来源、模型哈希与兼容环境
Runtime	反序列化受信任的 engine	运行时依赖、插件及错误处理
Engine	描述已优化的网络	I/O 元数据、profile 与运行资源要求
ExecutionContext	执行某次推理所需的可变状态	当前形状、地址、工作内存与执行状态

Engine 不是跨任意 GPU、平台和 TensorRT 版本都通用的交换格式。某些版本提供特定兼容选项，但必须按条件构建、验证，不能由文件扩展名推断兼容性。Engine compatibility

动态形状与内存的先后关系

一次请求通常遵循：

1. 选择适用的 optimization profile。
2. 按请求设置动态输入维度，以及模型要求的 shape tensor 输入。
3. 推导并检查输出形状；若输出尺寸由数据决定，按该版本机制使用输出分配器或有效上界。
4. 分配或复用符合类型、格式、位置和尺寸要求的缓冲区。
5. 绑定输入输出地址，按流顺序上传输入并启动推理。
6. 等待正确的完成事件后消费输出，再复用内存。

遇到 -1 维度时不能直接把各维相乘分配内存。先区分“尚未设置的动态输入”与“只有运行后才知道的输出尺寸”。线性连续张量常按元素数乘 dtype 字节数计算容量；向量化格式、对齐和特殊 I/O 格式需要遵守实际元数据。

多个并发请求不能任意改写同一个 context 的形状和地址。按版本的线程安全约定管理 context、流与缓冲区，保证正在执行的请求不受后续请求覆盖。运行时架构说明

8.x、10.x 与 11.x 的迁移边界

主题	较旧的接口	迁移时要处理什么
I/O 枚举	binding 索引、num_bindings	10.x 命名张量接口，如 num_io_tensors 和 get_tensor_name
Python 提交	execute_async_v2(bindings, stream_handle)	先为各 I/O 调用 set_tensor_address，再 execute_async_v3
C++ 提交	enqueueV2(bindings, stream, ...)	先 setTensorAddress，再 enqueueV3(stream)
动态形状	binding 相关 shape 方法	使用对应版本的命名张量与 profile 接口
精度选择	弱类型图上的 FP16/INT8 flags	11.x 移除弱类型精度开关，改用明确表达类型/量化的模型

仅把 V2 改成 V3 会遗漏地址绑定。下面的 10.x Python 接口片段只展示这两步，context、设备地址和流必须已经按前述流程正确准备；它不是可独立运行的程序。

if not context.set_tensor_address("x", input_device_address):
    raise RuntimeError("failed to bind input x")
if not context.set_tensor_address("y", output_device_address):
    raise RuntimeError("failed to bind output y")
if not context.execute_async_v3(stream_handle=stream_handle):
    raise RuntimeError("failed to enqueue inference")
# 等待对应的 CUDA 流或完成事件，再读取输出或复用缓冲区。

片段中的 x、y 必须与 engine 实际名称一致；地址不能指向已经释放的内存。执行返回成功仅表示提交阶段没有报告失败，后续 CUDA 错误仍需通过同步和错误处理发现。8.x 到 10.x Python 迁移

trtexec 示例必须注明版本

旧记录来自 JetPack 5.1.1 周边的 8.x 环境。下面保留 8.x/10.x 中支持这些参数的版本所用 FP16 风格示例，假设真实输入名称是 images：

trtexec --onnx=best.onnx --minShapes=images:1x3x640x640 --optShapes=images:1x3x640x640 --maxShapes=images:1x3x640x640 --saveEngine=best.engine --fp16

这里把动态范围固定成一个尺寸，不是提供了任意图片大小的能力。FP16 是否可用、是否有收益、是否满足精度，都需要在目标环境确认。

**TensorRT 11.x 不再接受 --fp16、--int8 等旧精度开关。**先准备经过验证、具有所需类型或量化表达的 ONNX，再构建；不能只删掉参数后宣称获得了相同精度的引擎。11.x trtexec 迁移

旧 --workspace、--batch、--streams、UFF/Caffe 入口也不能混入一个所谓“通用命令表”。使用安装包对应的帮助及 8.x 到 10.x 命令迁移表 确认替代方式。

验证与排错

阶段	失败时先检查
ONNX 解析	parser 的逐项错误、算子域/opset、插件
engine 构建	profile 覆盖、精度表达、资源预算、返回值是否为空
反序列化	版本与硬件兼容性、插件、文件完整性与来源
地址与形状设置	名称、dtype、I/O 位置、动态形状、返回值
结果错误	预处理、数据布局、同步、缓冲区生命周期、输出含义
性能异常	预热、数据传输、并发、同步点、计时范围

只加载来源可信的 engine；反序列化不是读取一个惰性的文本配置。部署时保留原 ONNX 和构建记录，使 engine 可以在目标环境重新生成。

本页保留历史流程并按官方迁移文档复核接口边界，未在 GPU 上构建或执行模型；代码片段不得被当作已经完成的生产推理工程。