企业官网建设流程全解析

开篇说明一下，这篇东西不是我临时看了几个帖子就能总结出来的，是实打实在一台CentOS 7服务器上把tensorrtx和yolov5跑通，又折腾了自训练模型之后沉淀下来的完整记录。如果你正在搜“CentOS 7 tensorrtx yolov5”，说明你已经走到了模型部署这一步，前面那些训练、调参的事搞定了，现在卡在“怎么把pt模型变成能快速推理的engine”上。这篇文章会把预训练模型跑通、自己训练的模型做转换这两条路径都拆开讲，包括环境搭建、wts生成、engine构建、推理验证和常见报错排查。不管你用的是yolov5s还是yolov5m，是80类还是自定义的类别，照着流程走总能把结果跑出来，少走很多弯路。

1. 先搞清楚tensorrtx在整个项目里的位置

1.1 tensorrtx到底帮你做了什么事情

很多人第一眼看到tensorrtx会误以为它是一个可以直接加载yolov5权重并进行推理的框架，其实它的核心作用更接近一个“适配器”。深度学习模型在训练框架里是一套结构，到了TensorRT引擎里又是另一套结构。TensorRT本身不认识.pt文件，也不直接认识ONNX的所有算子，尤其是YOLO里那些后处理、解码、nms环节，用TensorRT原生的方式去转换会非常痛苦。tensorrtx帮你把YOLO系列模型里那些特殊算子，比如decode、meshgrid、sigmoid、nms，实现成了TensorRT能做的东西，这块工作如果全部自己来写，没有一两周根本搞不定。

具体来说，tensorrtx通过两步把PyTorch模型“塞”进TensorRT：第一步，先用gen_wts.py把PyTorch训练出来的权重提取成统一的.wts文本格式，这个文件就是把每个卷积层、批归一化层的参数按顺序导出来；第二步，在C++工程里，代码会逐层读取.wts的参数，重新构造一个TensorRT网络，然后再调用TensorRT的构建器生成engine。所以它的工作模式不是“PyTorch模型直接换壳”，而是“参数搬运+网络复现”。

我在实际操作中的感受是，只要你的yolov5模型结构没有动过，用tensorrtx是很快的；但一旦你改了结构，比如替换了激活函数、加了自定义模块，那你就要连tensorrtx的C++源码一起改。这也是后面我自己训练模型时最需要小心的点。

1.2 为什么要绕一圈走wts，而不是直接用pt或者onnx

这是被我周围好多刚入门的朋友问过的问题：yolov5本身就能导出onnx，TensorRT也能直接把onnx转engine，为什么还要绕道.wts？如果你的需求是能跑就行，那直接用trtexec --onnx=xxx.onnx确实是你最快的路径，但有经验的部署人员通常会发现这条路径没那么顺畅。

问题往往出在YOLO的后处理上。yolov5的检测头输出包含三个尺度的特征图，每个特征图上都有大量的候选框信息，包括中心点坐标、宽高、置信度、类别分数。这些信息要还原成最终的检测框，需要进行解码、筛选、偏移计算甚至nms操作。TensorRT对卷积、全连接、激活这些标准层项处理得很完美，但对一些层层堆叠、循环遍历式的后处理逻辑，网络结构又复杂又容易超出它的表达能力范围。

而tensorrtx的yolov5实现思路是：把卷积主干和检测头这些能标准化的部分完整保留，但在最后一个特征图输出之后，用自定义的YoloLayer层去接管解码和置信度处理，这样后处理就是C++代码直接控制的，不会受到TensorRT的算子限制。而且这种方式做出来的engine，在调用端无需再做额外的解码逻辑，输入一张图像、输出一组已经框好的结果，工程集成起来特别方便。

所以，“绕到.wts”本质上是让你能复用tensorrtx为你写好的YoloLayer实现。从我实际使用的经验看，它比直接从onnx转出来的方案更稳，尤其是自定义类别数量变化时，改一处配置就行，不用把整个后处理链路都重写。

1.3 这套方案合适什么样的场景

如果你做的是边缘端或者服务端的实时视频流推理，那这套CentOS 7 + TensorRT + yolov5的部署方式就非常合适。我个人的一个项目里，需要在4路视频流上同时做目标检测，每帧图像大小是1920x1080，如果直接用PyTorch跑，GPU占用率会被拉得很高，延迟也不稳定。换成TensorRT engine以后，同样的显存和算力下，吞吐量能提升两到三倍，这个收益在长期运行时非常明显。

但如果你只是想在桌面系统上做一个小demo，或者对集成度要求不高，那其实没必要引入tensorrtx。它毕竟要编译C++工程，还要处理版本兼容问题，学习成本是真实存在的。适合的人应该是已经决定长期走TensorRT推理路线、不愿意在每次部署时手动调整网络后处理细节的开发者。

2. 环境准备：CentOS 7上最容易翻车的几个前置条件

2.1 显卡驱动与CUDA版本的匹配问题

在CentOS 7上装CUDA相关环境，第一件让人痛苦的事就是系统默认的gcc版本非常老旧。CentOS 7.6到7.9自带的gcc是4.8.5，而现代CUDA工具链通常要求gcc版本至少是5.x或者更高，TensorRT的编译过程又会对gcc版本有严格检查。我第一次编译tensorrtx时，cmake阶段就直接报错说编译器版本太老，后面单独给系统升了gcc才算过。

如果说这台机器只是做部署，不用本地编译TensorRT，那其实可以沿用系统自带驱动工具的路径，但只要你需要构建engine，编译器版本就是绕不过去的一道坎。我的建议是优先使用devtoolset提供的较新版本gcc，比如devtoolset-7或者devtoolset-9，直接用source /opt/rh/devtoolset-9/enable，就能在当前shell里切到新版本。这样做的好处是切换成本低，不会破坏系统原来的gcc环境。

驱动与CUDA版本的对应关系也很重要。CentOS 7下，如果显卡较新，就需要用较新版本的驱动，而CUDA 10.2对应老驱动，CUDA 11.x对应中后期驱动，CUDA 12系则要求更新版本的驱动。我在实际选择时，是按TensorRT版本来反推的。比如用TensorRT 8.5版本时，配CUDA 11.8是最顺滑的，因为官方对这套组合测试得比较充分。

2.2 安装cuDNN和TensorRT的路径规划

我踩过的最多一个坑，是把cuDNN和TensorRT当作系统库来安装，结果后面升级或者换版本时，老库文件和新库文件混在一起，导致程序链接到错误的版本。稳妥一点的做法是把它们安装在独立的目录下，比如/opt/cuda、/opt/cudnn、/opt/tensorrt，然后用环境变量的方式去指定路径。

TensorRT下载安装包通常是一个tar包，解压到指定目录后需要设置两个环境变量。第一个是LD_LIBRARY_PATH，指向TensorRT的lib目录；第二个是PATH，指向bin目录，这样trtexec工具才可以直接在终端使用。cuDNN的安装更简单，它本质上是一堆头文件和库文件，你只需要把include和lib拷贝进对应的CUDA目录，或者通过软链接配置好就行。我个人更偏向拷贝的方式，因为软链接一旦失效，那些按动态库名去找文件的程序会瞬间崩掉。

这里还需要提醒一句：TensorRT和CUDA、cuDNN之间的版本对应关系，官方文档写得非常清楚，任何一个版本不齐，后续都会出现各种奇怪的symbol not found错误。我的配置组合是本地的CUDA 11.8、cuDNN 8.6、TensorRT 8.5，这套组合在CentOS 7上编译tensorrtx的yolov5工程没有遇到兼容性问题。

2.3 编译工具准备：cmake、make和opencv

tensorrtx自带的yolov5工程是用CMake构建的，它还依赖OpenCV来做图像读取和预处理。CentOS 7系统自带的OpenCV版本非常老，所以在编译之前，你大概率需要先装一个相对较新的OpenCV。如果不想自己从源码编译OpenCV，可以通过pip安装opencv-python，然后让CMake检测到Python环境里对应的头文件和库文件，但这个过程可能并不顺利，因为C++库和Python包的编译路径常常对不上。

我的建议是不要在这里省时间，直接用源码编译一次OpenCV，编一个开发版安装到/usr/local下。编译参数里记得打开OPENCV_GENERATE_PKGCONFIG，这样后面CMake可以通过pkg-config找到它。OpenCV编译本身需要的时间大概在二十分钟到半小时，取决于机器性能，但这部分时间花得值，后面所有图像解码、预处理和显示环节都会依赖它。

构建tensorrtx前，还要确认cmake版本不低于3.12，最好大于3.16，否则生成Makefile的时候会少掉一些关键选项。CentOS 7默认的cmake是2.8，一定不能偷懒直接用，要么升级系统包，要么用pip安装一个cmake二进制版本。

2.4 Python端导出工具的依赖

做预训练模型转换时，你的命令行里需要调用yolov5仓库里的export.py或者gen_wts.py，这些脚本运行在Python环境里。这里建议单独建一个conda环境或者venv，Python版本用3.8或3.9就够了，再装上torch、torchvision和onnx这几个核心包。

为什么要单独建环境？因为yolov5这类项目对torch的版本有一定要求，如果把你正在用的训练环境直接拿来做导出，很可能因为依赖版本冲突导致导出出来的权重数值不对，或者运行时直接启动失败。我遇到过一次很诡异的情况：用某个较新版本的torch导出onnx完全正常，但gen_wts.py读.pt文件时却读不到权重数值，最后检查发现是torch和模型权重在序列化格式上不匹配，重新安装指定版本torch以后就正常了。

在CentOS 7上装torch也有一点需要注意，老系统对主流的wheel包支持程度不一样，如果碰到GLIBC_2.29 not found这种报错，说明系统glibc版本太老，需要升级系统或者换一个旧版本轮子。

3. 预训练模型从pt到engine的完整落地

3.1 拿到预训练权重并转成ONNX

预训练模型的路径比较直接，从yolov5官方仓库下载对应的权重，比如yolov5s.pt还是yolov5m.pt，根据自己的算力和精度需求选择。我这次用的是yolov5s，也就是最小最快的那个，在单卡GPU上做演示和验证都比较合适。

下载完成后，第一步是进入yolov5工程目录，执行导出命令把.pt转成ONNX。命令长这样：

python export.py --weights yolov5s.pt --include onnx --img-size 640 640

这一步能顺利通过，说明你的torch和onnx环境没问题。如果报opset相关的错误，通常是因为你的onnx版本过新或者过旧，可以把命令里加上--opset 11或者--opset 12固定算子版本。导出结束后，工作目录下会出现一个yolov5s.onnx，这个ONNX文件其实已经包含了整个检测网络的计算图，TensorRT理论上已经可以解析它了。但在tensorrtx的流程里，它主要作为一个中间检查点，真正用于生成engine的是后面的.wts文件。

3.2 用gen_wts.py生成wts权重文件

这一步是在tensorrtx仓库的yolov5目录下操作的。先进入该目录，找到gen_wts.py脚本，然后执行：

python gen_wts.py -w ../../你的路径/yolov5s.pt -o yolov5s.wts

这个脚本的原理非常简单，它会遍历PyTorch模型里的所有state_dict，把每一层的名字和对应的权重数值逐行写进一个纯文本文件里。之所以要用纯文本，是为了让C++端不依赖Python和torch也能读取参数。

我提醒一下，如果yolov5的版本比较新，比如v6.0之后的版本，gen_wts.py必须和它匹配。tensorrtx仓库通常对应某个固定的yolov5版本，如果你的yolov5权重结构与gen_wts.py预期的不一致，会直接提示找不到某些键值。最简单的方法是看tensorrtx目录里有没有对应的版本说明，如果没有，就改一下权重访问的方式。

生成的.wts文件大小和模型大小成正比，yolov5s大概几十MB，yolov5l会更大。文件内容可以用head看一眼，如果前几行是i开头的一行，然后后面跟着很多层的名字和数字，就说明生成正常。

3.3 编译并生成engine文件

有了.wts，接下来进入tensorrtx的yolov5工程目录，执行编译：

mkdir build cd build cmake .. make -j8

如果cmake找不到OpenCV或者TensorRT的头文件，就会停在配置阶段，这时需要检查环境变量和pkg-config配置。编译完成后，build目录下会生成一个名叫yolov5的可执行文件。

然后就是最关键的一步，用这个可执行文件把.wts转成engine：

./yolov5 -s yolov5s.wts yolov5s.engine s

命令末尾的s代表模型规模，对应yolov5s。如果你是yolov5m，就改成m，yolov5l就改成l。这里需要注意的是，tensorrtx内置了不同规模模型的结构定义，不能把s模型权重和m模型结构混用，否则构建时会直接报网络结构不匹配。整个构建过程会执行比较长的时间，因为TensorRT要在大量优化方式里搜索一个最优解，期间GPU显存占用会暴涨，如果卡死，八成是显存不够。

构建成功后，你会看到yolov5s.engine文件生成在当前目录下。这个文件就是最终推理要用的东西，它已经包含了网络结构和推理优化后的权重。后续部署到其他机器上，不需要再带.wts和网络定义源码，只要这一个engine文件和配套的推理程序即可。

3.4 用engine跑一次预训练模型推理

生成engine之后马上验证一下效果，避免做完才发现前面一步有错。tensorrtx自带的yolov5可执行程序在推理模式下需要传入engine路径和一个图片目录，它会自动扫描目录里的图片并输出结果，命令大概是：

./yolov5 -d yolov5s.engine /path/to/images

如果你的图像放在samples目录里，就用../samples。跑完之后，程序会在当前目录生成带检测框的结果图片，文件名一般带_result后缀。打开结果图，如果能看到人、车、猫这种常见目标被正确框住，说明整条链路已经通了。

这里顺便提一个细节，tensorrtx默认的推理输入尺寸是640x640，如果你希望让它支持更大尺寸，比如1280x1280用于检测小目标，需要把配置里的输入宽高同步改掉，并且推理时传入的图像也会被resize到对应尺寸。这个改动不仅涉及构建engine，还涉及预处理段保持一致的resize逻辑，不能只改一边。

4. 自己训练的模型：同样一套流程，三个地方必须改

4.1 导出前的模型结构对齐

自训练模型和预训练模型最大的区别，在于你的数据集类别数量通常不是80，可能是几类、十几类，甚至上百类。yolov5的检测头是动态生成的，类别数不同，最后一层卷积的输出通道数就不同，对应到模型结构里就是一组尺寸完全不同的权重。如果你直接把自训练模型通过export.py导出ONNX，理论上可以出，但生成的wts再进入tensorrtx的C++构建流程时，会因为类别数量跟默认配置对不上而报错。

我在自己的模拟项目X里训练的是一个10类目标检测模型，类别数量不多，检测目标包括一些常见产品和包装箱。训练完成后，我要做的第一件事不是导出，而是确认模型的yaml配置和训练结果里的类别序号是连续的。因为TensorRT那一侧对类别的处理方式很简单，它就是根据配置的类别数创建一个一维数组，完全不关心你的类别名是什么。只要训练时不缺类，导出就正常。

结构上也建议保持原始yolov5网络不变，不要在主干网络里加CBAM、SE这类注意力模块。tensorrtx的YoloLayer和卷积定义是固定好的，它只适配原始结构，任何自定义修改都需要同时改C++代码。如果你确实因为任务需要加了模块，那么有一个思路是单独导出主干和检测头两个ONNX，再用TensorRT的API手动拼接，但这个工程量大得多，除非必要，不建议走这条路径。

4.2 修改类别数量、输入尺寸和类别名

这一步是自训练模型转换中最重要的部分。打开tensorrtx项目里的yolov5相关配置头文件，通常是yololayer.h，里面有一行定义类别的常量：

static const int CLASS_NUM = 80;

这时候把它改成你自己的类别数量，比如我的10类模型改为CLASS_NUM = 10。改完后，整个网络最后一层卷积的输出尺寸就会按10个类别来重新规划，和你的训练权重一一对应。

除了类别数，输入尺寸也要检查。如果你训练时图像输入是640x640，那保持默认即可；如果你用的是1280，那就要同步修改网络里的输入高宽常量。这个改动同时影响预处理和后处理，不能漏。

类别名列表是另一个需要注意的地方。在推理输出可视化时，程序会把预测框的类别打印成名称，如果你没有修改这个列表，程序会显示默认的COCO类别名，而实际上你的类别是另外的10个，看起来会让你以为结果出错了。tensorrtx的yolov5代码里通常会维护一个coco_names或class_names的vector，把它改成你自己的类别数组就可以。

4.3 从训练好的pt生成wts并构建engine

自训练模型也有一个训练完成后的best.pt，这个文件包含了模型所有层的权重。把它喂给同样的gen_wts.py脚本，就能生成对应的wts文件：

python gen_wts.py -w /path/to/best.pt -o custom.wts

这里有一个容易踩的坑：best.pt的包装方式可能与官方yolov5的权重不完全一样，因为自训练的pt里可能会包含一些额外的info，比如anchor、stride、训练配置。gen_wts.py默认只提取model状态里的权重部分，如果你的文件结构不同，脚本会报错或者生成一个空的wts。解决办法是先在Python里手动加载一下模型：

import torch model = torch.load('best.pt', map_location='cpu') print(model.keys())

看看里面是model键还是直接就是state_dict，然后在gen_wts.py里改用对应的取值方式。这一步看似不起眼，却是最容易卡住新手的地方。

生成custom.wts之后，回到build目录，执行：

./yolov5 -s custom.wts custom.engine s

如果你的自训练模型输入尺寸不是640，那么构建过程对应的scale传递也要保持一致。构建时间跟模型规模有关，我的10类自定义模型比预训练80类模型快很多，因为最后的输出通道数少了一大截，计算量更小。

4.4 验证自训练模型的实际推理效果

拿到custom.engine之后，用一套你自己拍好的或者测试集里的图片跑一下推理。这里不能只看有没有框，还要确认框的类别和置信度是不是合理。如果你的类别名没改，那可能会出现框的位置正确但名称显示为COCO类别的情况，那不是推理逻辑出错，只是渲染层的名称映射没对齐，改一下类别列表重新编译就能解决。

我在验证时就发现过一个很有意思的现象：自训练模型对某个类别的置信度普遍偏低，检测框经常一闪一闪地不稳定。后来分析发现不是TensorRT的问题，而是训练时的那一类正样本太少，模型本身就没学够。这提醒我们，TensorRT只是提速，不会改变模型已有的检测能力，如果基础模型有缺陷，部署端再怎么优化也补不回来。

如果你的自训练模型需要跑视频流，可以通过修改yolov5的C++代码，把单张图片的推理循环改成摄像头或视频解码的循环。tensorrtx原始工程里已经留了输入接口，只要在循环里对每一帧执行相同的预处理和推理调用就行。这个操作不复杂，但需要理解程序内部的doInference流程，后面我会简单提一下。

5. 常见报错与排查经验速查

5.1 编译时报找不到TensorRT头文件

这个报错十有八九是cmake搜索路径没配置好。tensorrtx的CMakeLists.txt会尝试用find_path去找NvInfer.h，如果你把TensorRT解压到了自定义目录，需要手动在CMake命令后追加一句：

cmake .. -DTENSORRT_ROOT=/opt/tensorrt

另一种情况是环境变量LD_LIBRARY_PATH没设，导致即使头文件找到了，链接时还是会报libnvinfer.so找不到。把TensorRT的lib目录加进去即可，同时确认一下libnvinfer.so的版本和头文件版本是一致的，千万不能多个TensorRT版本混在同一个LD_LIBRARY_PATH里。

编译时报OpenCV相关错误也是一样，如果不想折腾pkg-config，也可以直接在CMakeLists.txt里手动指定OpenCV的路径，编译原理都是一样的，关键是要让编译器找到它需要的头文件和库文件。

5.2 构建engine过程中显存不足或者进程被杀死

TensorRT构建引擎的过程中，需要反复尝试不同的优化策略，这个阶段的开销往往比最终推理时还要高。我在一台显存8GB的卡上构建yolov5s时，中间出现过一次OOM，整个进程被系统杀掉。解决办法有两个方向：一是降低模型规模，换个更小的模型；二是通过配置TensorRT构建器的setMaxWorkspaceSize来控制预分配的工作区大小。

如果使用trtexec或代码构建，还可以开启fp16模式，这个过程会大幅降低显存占用，但同时精度会有一点损失。为了速度牺牲一点点精度，在很多目标检测场景中是可以接受的。如果你依然想保持fp32的高精度，那就只能换更大显存的硬件，或者把batch size调小，减少构建时的临时张量显存占用。

5.3 推理结果全为0或者输出大量错乱框

看到这个现象，先不要怀疑TensorRT出了问题，更可能是预处理和后处理的尺寸或顺序不对。TensorRT输入的是一个排布为CHW的浮点数张量，并且需要先除以255归一化，不同工程里，有的会把RGB转BGR，有的不会，如果这些细节和训练时不一致，模型输出的特征图就已经出错，后面的解码自然全是噪声。

还有一个可能原因是你的wts文件生成不完整。gen_wts.py在遍历模型时，如果因为在某个自定义层上读取失败而中断，生成的wts文件只有前半部分权重，后半部分缺失。这种情况下构建engine不会报错，但推理时输出基本就是乱跳的框。排查方式很简单，统计一下wts文件的行数，和模型总层数对比一下，如果相差太远，就回到Python端重新生成。

5.4 检测框位置完全不对，但类别识别正常

这种情况我之前在调整输入尺寸时遇到过。训练时模型是按640x640来设计anchor的，如果推理时输入尺寸改成了1280，但anchor尺寸和缩放逻辑没有同步更新，就会出现检测框整体偏移或大小严重不符的问题。用tensorrtx时，后处理逻辑默认假设输入尺寸是640，如果你的输入变了，不仅要改网络的输入尺寸，还要改YoloLayer里关于stride和anchor的计算常数。

正确的做法是保持训练时的配置和推理时的配置完全一致，包括图像缩放、letterbox填充方式、归一化顺序。很多新手为了图省事，直接用cv2.resize把图片压到640x640，这样会导致图片的长宽比例被拉伸，目标的真实坐标和实际位置发生偏差。官方yolov5用的是letterbox策略，即等比缩放后填充灰色边，这样一个640x640的推理图不会破坏原始比例。tensorrtx对这一点做了兼容，但需要你在预处理代码里实现同样的逻辑，不能随意替换成resize。

5.5 常见问题速查表

这份速查表虽然不是万能药，但绝大多数刚跑通tensorrtx时遇到的问题都能覆盖到。我每次在新部署一台CentOS 7机器时，都会先把这些问题列出，然后根据现象直接定位，省掉了很多重复的排查时间。

6. 一些没写在README里的经验

6.1 engine文件换机器部署的坑

engine文件是绑定硬件和TensorRT版本的，它不是普通的模型文件，不能想拷到哪就拷到哪。换到另一张不同型号的显卡上，很可能直接加载失败；换到相同型号但TensorRT版本不同的环境，也可能因为算子版本不一致而报错。所以部署时要依照目标机器的具体环境来重新生成engine，或者把生成engine的流程写成一个脚本，放到每台机器上单独执行。

如果面对的是大量相同配置的机器，可以先在一台机器上生成好engine，然后分发给其他机器。因为在相同驱动、相同TensorRT、相同张卡型号的情况下，engine的二进制是可以直接复用的。我在部署某公司的多台边缘节点时，就采用了这种“生成一次、批量复制”的方式，节省了大量构建时间。

6.2 最佳实践：把转换和推理拆成两个独立步骤

我在实际工程里，强烈建议把“转engine”和“跑推理”这两件事拆开。转换步骤可以做成离线脚本，定期更新；推理程序则保持只加载engine文件，不依赖任何PyTorch环境。这样生产环境的镜像里连torch都不需要安装，可以大幅度减小镜像体积和启动时间，也减少了Python环境带来的安全隐患。

具体做法是，在开发机上用Python完成pt到wts的转换，然后在同一台开发机上编译出转换用的yolov5可执行程序，生成engine后，把engine和编译好的推理程序一起交付给生产环境。生产环境只需要准备CentOS 7的基础环境以及TensorRT的动态库，不需要安装CUDA Toolkit的全部组件，只要运行时所需的库存在就行。

6.3 最后分享一个小技巧

如果你想在自训练模型上快速验证不同类别的检测效果，可以在推理程序里增加一个参数，用来动态指定过滤的类别ID，这样就不用每改一次类别就重新编译一次。具体就是根据待绘制框的class_id和过滤条件决定是否跳过绘制，改动很小，但调试时将特别省心。

从我个人的体会来说，tensorrtx不是那种装好就跑的工具，它需要你理解整个模型转换链路，但一旦建立起正确的流程，后续不管换新的数据集还是新的模型配置，复用性都很高。调试过程中最大的敌人其实是版本错配和预处理不一致，这两个问题一旦解决，剩下的事情就都是水到渠成。