3. IPluginV2与IPluginV2DynamicExt接口解析
在 TensorRT 的插件体系中，IPluginV2 是承上启下的核心抽象。它既继承了更早期的 IPlugin 与 IPluginV2Base 的元数据能力，又通过引入 IPluginV2Ext 和 IPluginV2DynamicExt 两个派生接口，把插件从"固定形状"逐步推进到"动态形状"。理解这条继承链，是判断一个自定义算子该实现哪个接口、以及每个虚函数在什么时机被调用的前提。
继承关系：从元数据到动态形状
整条继承链可以概括为：IPluginV2Base 提供最基础的版本号、类型名、序列化与克隆能力；IPluginV2 在其上补齐了 getOutputDimensions、enqueue、configurePlugin 等执行期接口；IPluginV2Ext 进一步引入 getOutputDataType、supportsFormat 等格式协商能力；而 IPluginV2DynamicExt 则把维度从静态的 Dims 升级为可含 -1 的 DimsExprs，并新增 getOutputDimensions 的表达式版本、supportsFormatCombination 以及 configurePlugin 的动态版本。选择接口时，一个实用的判断是：如果算子输出形状只依赖输入形状且构建期即可确定，用 IPluginV2Ext 足够；一旦需要支持 -1 维度、运行时才确定的形状，就必须落到 IPluginV2DynamicExt。
生命周期：五个关键时机
插件对象的生命周期大致分为五个阶段。第一阶段是 createPlugin，由插件创建器在反序列化或网络构建时调用，负责构造插件实例并完成成员初始化。第二阶段是 configurePlugin，在构建期被调用，用于把输入输出数量、维度、数据类型、格式以及 cudaStream 之外的执行上下文信息交给插件，插件应在此完成 workspace 大小计算、kernel 选择等一次性准备。第三阶段是 getOutputDimensions，在构建期被反复调用，用于推导输出形状；在 IPluginV2DynamicExt 中它接收 DimsExprs，可以处理 -1 维度。第四阶段是 enqueue，在运行期每次推理时被调用，是真正执行 CUDA kernel 的地方，必须使用传入的 cudaStream_t 保证异步正确性。第五阶段是 serialize 与 clone，前者把插件状态写入序列化缓冲，后者在需要复制插件时被调用，二者共同保证引擎可被保存与复用。
关键虚函数职责与调用时机
下面这张表把最常被重写的虚函数、职责与调用时机对应起来，便于在实现时快速定位。
| 虚函数 | 职责 | 调用时机 |
|---|---|---|
getPluginType | 返回插件类型名，用于注册与查找 | 构建期、序列化期 |
getPluginVersion | 返回版本号，配合类型名做兼容判断 | 构建期、序列化期 |
getNbOutputs | 返回输出张量数量 | 构建期 |
getOutputDimensions | 根据输入维度推导输出维度 | 构建期，可能多次 |
supportsFormat / supportsFormatCombination | 声明支持的输入输出格式与数据类型组合 | 构建期 |
configurePlugin | 接收维度、格式、数据类型，完成一次性准备 | 构建期 |
getWorkspaceSize | 返回所需 workspace 字节数 | 构建期 |
enqueue | 在给定 stream 上执行 kernel | 运行期，每次推理 |
serialize / deserialize | 保存与恢复插件状态 | 序列化期 |
clone | 复制插件实例 | 需要复制时 |
实现要点与常见陷阱
实现 IPluginV2DynamicExt 时，最容易出错的是 getOutputDimensions 与 configurePlugin 的职责边界。前者只负责形状推导，不应在其中分配显存或启动 kernel；后者负责资源准备，但不应假设维度已经固定。另一个常见问题是 enqueue 中忘记使用传入的 stream，导致 kernel 与 TensorRT 的执行流不同步，表现为结果偶发错误或性能异常。此外，supportsFormatCombination 必须对每一种输入输出组合给出明确判断，返回 false 的组合会被 TensorRT 排除，若判断过严会导致插件无法被选中，过松则可能在运行期触发格式不匹配。
configurePlugin 中把输入输出维度、数据类型、格式缓存为成员变量，并在 enqueue 中直接使用，避免在运行期重复查询。对于动态形状插件，getOutputDimensions 应尽量写成纯函数，只依赖输入 DimsExprs 与插件参数，不依赖任何运行期状态。
IPluginV2Ext 与 IPluginV2DynamicExt 的 configurePlugin 签名不同，前者接收 Dims，后者接收 DimsExprs。混用会导致编译期报错或运行期维度解析失败。迁移旧插件时，应优先确认目标接口，再逐项调整虚函数签名。
把继承链、生命周期与虚函数职责三者对齐之后，后续实现自定义算子时就能明确：哪些逻辑放在构建期、哪些放在运行期、哪些必须序列化。这也是判断一个插件实现是否健壮的核心依据。