Triton Inference Server 自定义算子(Custom Operations)集成指南:TensorRT / PyTorch / ONNX 加载与验证
Triton Inference Server 自定义算子(Custom Operations)集成指南:TensorRT / PyTorch / ONNX 加载与验证
导读
Triton Inference Server 允许用户在构建时或服务启动时将建模框架的自定义算子(Custom Operations)加载进服务器,从而让加载的模型可以使用框架标准算子之外的扩展能力。本文以 docs/user_guide/custom_operations.md 为主线,系统讲解 TensorRT 自定义层、PyTorch(TorchScript)自定义算子与 ONNX Runtime 自定义算子三种场景的加载方式、启动命令、模型配置写法、版本一致性要求与已知限制,并结合仓库内 qa/L0_custom_ops 的端到端测试与 qa/common/gen_qa_custom_ops_models.py 的模型生成脚本,给出可复现的实操依据。
一、Triton 对自定义算子的支持方式概述
允许自定义算子的建模框架在 Triton Inference Server 中只获得"部分支持"(partially supported)。具体而言:
- 自定义算子可以在**构建时(build time)或启动时(startup)**加入 Triton;
- 一旦加载成功,这些自定义算子对所有已加载的模型可用(TensorRT 与 PyTorch 场景),或对指定模型可用(ONNX 场景);
- 支持的框架当前包括 TensorRT、PyTorch(TorchScript)与 ONNX Runtime,三种框架的接入机制各不相同:
- TensorRT / PyTorch:把自定义实现编译成共享库(shared library),通过环境变量
LD_PRELOAD在启动tritonserver时注入; - ONNX Runtime:在**模型配置文件(config.pbtxt)**中通过
model_operations字段声明算子库文件。
- TensorRT / PyTorch:把自定义实现编译成共享库(shared library),通过环境变量
下文逐一展开。
二、TensorRT:通过 LD_PRELOAD 加载自定义层
TensorRT 允许用户创建自定义层(custom layer,参见 NVIDIA TensorRT 开发者指南中 "Extending TensorRT" 章节),这些自定义层可以进一步被用在 TensorRT 模型中。要让这类模型在 Triton 中运行,必须先把自定义层提供给 Triton。
2.1 编译与加载步骤
把 TensorRT 自定义层实现编译进一个或多个共享库,然后使用 LD_PRELOAD 将这些库加载进 Triton。例如,假设自定义层已编译为 libtrtcustom.so,用如下命令启动 Triton,即可让这些自定义层对所有 TensorRT 模型可用:
$ LD_PRELOAD=libtrtcustom.so:${LD_PRELOAD} tritonserver --model-repository=/tmp/models ...
注意命令中的 :${LD_PRELOAD} 表示在已有预加载列表之前追加该库,避免覆盖服务器自身依赖的预加载库。--model-repository 指向你的模型仓库,其余参数按实际部署场景补充(如 --http-port、--grpc-port 等)。
2.2 已知限制
- 自定义层必须独立于模型仓库管理,无法随模型一起打包分发;
- 更严重的是,如果多个共享库之间出现自定义层名称冲突,目前 Triton 没有任何机制来处理这种冲突——后加载的符号会覆盖先加载的同名符号,可能导致行为不可预期。
2.3 版本一致性要求
构建自定义层共享库时,必须使用与 Triton 内置的相同版本 TensorRT。Triton 所使用的 TensorRT 版本可以从 Triton Release Notes 中查到。一个确保版本一致的最简单做法是:
- 使用与 Triton 容器同标签(tag)的 NGC TensorRT 容器进行编译;
- 例如,使用 Triton 24.12 版本时,就用 24.12 版本的 TensorRT 容器来构建自定义层库。
三、PyTorch:通过 LD_PRELOAD 加载 TorchScript 自定义算子
TorchScript 允许用户注册自定义算子(custom operations),并在 TorchScript 模型中使用。与 TensorRT 类似,通过 LD_PRELOAD 可以把自定义 C++ 算子加载进 Triton。
3.1 编译与加载步骤
按照 PyTorch 官方扩展脚本(extension-script)教程编译出自定义算子共享库(例如 libpytcustom.so)后,使用如下命令启动 Triton:
$ LD_LIBRARY_PATH=/opt/tritonserver/backends/pytorch:$LD_LIBRARY_PATH LD_PRELOAD=libpytcustom.so:${LD_PRELOAD} tritonserver --model-repository=/tmp/models ...
这条命令比 TensorRT 场景多了 LD_LIBRARY_PATH 的设置,原因在于:所有 PyTorch 自定义算子都依赖一个或多个 PyTorch 共享库,这些库必须在自定义共享库加载时可用。实践中意味着必须保证 /opt/tritonserver/backends/pytorch 位于库搜索路径上。控制库搜索路径的方式有多种,最常见的就是 LD_LIBRARY_PATH,如上例所示。
这一要求在仓库的 QA 测试中得到了原样印证:qa/L0_custom_ops/test.sh 明确注释"必须仅为服务器启动设置 LD_LIBRARY_PATH,使自定义算子能找到 libtorch.so 及其它 PyTorch 依赖",并执行:
LD_LIBRARY_PATH=/opt/tritonserver/backends/pytorch:$LD_LIBRARY_PATH
随后在启动服务器时设置预加载库(test.sh):
SERVER_LD_PRELOAD="/usr/lib/x86_64-linux-gnu/libpython3.12.so.1:/data/inferenceserver/${REPO_VERSION}/qa_custom_ops/libtorch_custom_ops/libtorch_modulo/custom_modulo.so"
该测试还注释说明:由于自定义算子库是在不同 Python 版本的 PyTorch 容器中编译的,需要预先加载系统 Python 库来满足符号定义(对应内部问题 DLIS-4152)——这是一个值得注意的实操细节,当你的自定义库与 Triton 容器内 Python 版本不一致时,可参考此做法。
3.2 TorchScript 自定义算子的真实生成示例
仓库中的 qa/common/gen_qa_custom_ops_models.py 给出了一个完整的自定义算子 + TorchScript 模型生成流程,可作为实战模板:
- 用 C++ 源码定义算子并通过
torch::RegisterOperators注册(L40-L48):
#include <torch/script.h>
torch::Tensor custom_modulo(torch::Tensor input1, torch::Tensor input2) {
torch::Tensor output = torch::fmod(input1, input2);
return output.clone();
}
static auto registry =
torch::RegisterOperators("my_ops::custom_modulo", &custom_modulo);
- 用
torch.utils.cpp_extension.load_inline现场编译该算子为共享库(L50-L55):
torch.utils.cpp_extension.load_inline(
name="custom_modulo",
cpp_sources=op_source,
is_python_module=False,
verbose=True,
)
- 在
nn.Module中通过torch.ops.my_ops.custom_modulo调用该算子,并用torch.jit.trace导出 TorchScript 模型(L57-L76):
class ModuloCustomNet(nn.Module):
def __init__(self):
super(ModuloCustomNet, self).__init__()
def forward(self, input0, input1):
return torch.ops.my_ops.custom_modulo(input0, input1)
moduloCustomModel = ModuloCustomNet()
example_input0 = torch.arange(1, 11, dtype=torch.float32)
example_input1 = torch.tensor([2] * 10, dtype=torch.float32)
traced = torch.jit.trace(moduloCustomModel, (example_input0, example_input1))
traced.save(model_version_dir + "/model.pt")
对应模型的 config.pbtxt 使用 platform: "pytorch_libtorch"、max_batch_size: 0,并声明 INPUT__0、INPUT__1 两个 FP32 输入和 OUTPUT__0 输出(gen_qa_custom_ops_models.py)。QA 客户端 mod_op_test.py 会对输入 1..10 与 2 逐元素取模,校验输出是否等于 input % 2 的期望交替值,从而端到端验证自定义算子在 Triton 中正确工作。
3.3 TorchVision 算子说明
从 Triton 20.07 版本开始,TorchVision 算子已随 PyTorch backend 一起内置,因此无需再显式地作为自定义算子添加。仓库测试同样覆盖了这一场景:gen_qa_custom_ops_models.py 中 create_visionop_modelfile 直接在一个 TorchScript 网络里使用 torchvision.ops.roi_align,vision_op_test.py 对其发起推理验证。
3.4 已知限制
- 与 TensorRT 相同,自定义算子必须独立于模型仓库管理;
- 更严重的是,如果多个共享库之间存在算子名称冲突,或者注册算子的 PyTorch handle 冲突,目前 Triton 没有任何处理机制。
3.5 版本一致性要求
构建自定义算子共享库时,必须使用与 Triton 内置的相同版本 PyTorch,版本号可在 Triton Release Notes 中确认。最稳妥的做法是:使用与 Triton 容器同标签的 NGC PyTorch 容器进行编译——例如使用 Triton 24.12 时,就用 24.12 版本的 PyTorch 容器。
四、ONNX Runtime:通过模型配置注册自定义算子
ONNX Runtime 允许用户添加自定义算子(add-custom-op),并可在 ONNX 模型中使用。与 TensorRT / PyTorch 的全局 LD_PRELOAD 机制不同,ONNX Runtime 自定义算子库通过模型配置注册,作用范围限定于声明它的那个特定 ONNX 模型。
4.1 配置方法
按照 ONNX Runtime 官方示例(onnxruntime/test/shared_lib/test_inference.cc)把自定义算子编译为共享库(例如 libonnxcustom.so)后,在目标模型的 config.pbtxt 中添加如下字段:
$ model_operations { op_library_filename: "/path/to/libonnxcustom.so" }
其中 op_library_filename 指向自定义算子共享库的路径。Triton 加载该模型时会把此库加载进 ONNX Runtime session,从而让该模型可以使用其中的自定义算子。
4.2 测试中的实际配置
qa/L0_custom_ops/test.sh 给出了完整可复现的 ONNX 自定义算子部署流程:把 custom_op_test.onnx 放入模型仓库版本目录 onnx_custom_ops/custom_op/1/model.onnx,并生成如下 config.pbtxt:
name: "custom_op"
platform: "onnxruntime_onnx"
max_batch_size: 0
model_operations { op_library_filename: "./libcustom_op_library.so" }
然后以 --model-repository=onnx_custom_ops --strict-model-config=false 启动 Triton,再用 onnx_op_test.py 对两个 3×5 全 1 输入做加法推理,逐元素校验输出等于 2。这说明自定义算子库既可以写绝对路径(如文档示例),也可以写相对路径(如测试中的 ./libcustom_op_library.so,相对模型仓库目录解析)。
4.3 版本一致性要求
构建 ONNX Runtime 自定义算子共享库时,必须使用与 Triton 内置的相同版本 ONNXRuntime,版本号可在 Triton Release Notes 中确认。
五、三种接入方式对比与选择建议
| 框架 | 接入机制 | 作用范围 | 配置/命令关键点 | 冲突风险 |
|---|---|---|---|---|
| TensorRT | LD_PRELOAD 注入共享库 |
全局(所有 TensorRT 模型) | 编译期对齐 TensorRT 版本 | 跨库自定义层名称冲突无法处理 |
| PyTorch | LD_PRELOAD 注入共享库 + LD_LIBRARY_PATH 指向 pytorch backend |
全局(所有 PyTorch 模型) | 保证 /opt/tritonserver/backends/pytorch 在库路径;对齐 PyTorch 版本 |
算子名或注册 handle 冲突无法处理 |
| ONNX Runtime | model_operations 模型配置字段 |
单个指定 ONNX 模型 | op_library_filename 指向算子库;对齐 ONNXRuntime 版本 |
冲突仅影响声明该库的模型 |
选择建议:
- 若算子需要被多个模型共享且属于 TensorRT / PyTorch 体系,优先使用
LD_PRELOAD全局注入; - 若算子仅服务于某一个 ONNX 模型,应使用
model_operations配置,作用域更可控; - 无论哪种方式,版本一致性(算子库编译框架版本 == Triton 内置框架版本)是成败关键,推荐统一使用与 Triton 同 tag 的 NGC 框架容器编译。
六、验证与排障要点
仓库的 QA 测试链路(qa/L0_custom_ops)本身就是一个完整的验证范本:
- 启动阶段:观察
tritonserver启动日志,确认服务器成功启动(若LD_PRELOAD的库缺失或符号不满足,服务器通常会在启动时报动态链接错误); - 推理阶段:用 tritonclient 发起推理(HTTP 或 gRPC),比对输出是否与自定义算子的数学语义一致(如 mod_op_test.py 校验取模、onnx_op_test.py 校验加法);
- 版本排查:若加载失败,优先核对自定义库编译所用框架版本与 Triton 内置版本是否一致,并确认 PyTorch 场景下
LD_LIBRARY_PATH是否包含/opt/tritonserver/backends/pytorch; - 冲突排查:多库同名算子导致的异常通常没有报错提示,需要自行通过
nm -D等工具检查共享库导出的符号是否与其它预加载库冲突。
此外,TensorRT 插件的 QA 测试(qa/L0_trt_plugin/test.sh)同样依赖 LD_PRELOAD 注入机制,可作为 TensorRT 自定义插件部署的参考样例。
七、总结
Triton Inference Server 对自定义算子的支持遵循"框架各自接入、启动或配置时注入"的设计:TensorRT 与 PyTorch 通过 LD_PRELOAD(PyTorch 还需配合 LD_LIBRARY_PATH)在服务器启动时全局注入共享库,ONNX Runtime 则在模型配置中以 model_operations { op_library_filename: ... } 声明算子库。三者共同的前提是算子库编译框架版本与 Triton 内置版本严格对齐,并各自承担"算子独立于模型仓库管理、同名冲突无解"的限制。本文给出的启动命令、config.pbtxt 写法与 QA 测试源码,均可直接作为你在自己的 Triton 部署中集成自定义算子的起点。