用TensorRT将YOLOv8部署为C++引擎：构建与推理优化实战

简介这是一份面向C开发者的YOLOv8 TensorRT部署工程解决将PyTorch模型转换并以高性能方式接入实际检测任务的问题尤其适合X射线图像分析等需要实时推理的项目。资源共85个文件、约379.2MB包含Visual Studio解决方案与工程配置sln/vcxproj、C源文件与头文件、构建生成的obj/pdb等中间文件、测试用jpg/png图片及模型目录目录结构清晰便于直接打开工程学习。已有3355人学习浏览适合具备C与深度学习基础、希望缩短工程落地周期的开发者。包内以完整项目方式展现了模型导入、TensorRT引擎构建、C运行时推理、输入输出显存管理与后处理环节可帮助读者掌握FP16/INT8精度选择、动态形状配置等关键调优手段借助自带测试图像与X射线检测示例能够快速对比不同参数下的检测效果同时为自行接入其他YOLO模型或业务数据集提供了可供改写的代码框架。1. 用 TensorRT 给 YOLOv8 换上 C 的引擎到底在解决什么问题在 Python 里把 YOLOv8 跑起来、调出检测框对多数工程师只算入门。真正要交付到产线、车载或边缘盒子的时候会遇到两件 Python 脚本解决不了的事一是依赖链太长换一台机器就要重配 PyTorch、CUDA 乃至一堆 Python 包二是推理耗时不稳帧率波动大GPU 利用率却始终上不去。把 YOLOv8 导出成 ONNX再转成 TensorRT 的 engine最后用 C 写推理主循环是工业部署最常见也最稳妥的一条路。它换来的是可预期的延迟、更小的运行时依赖以及对显存和线程的精确控制。常见的误区是以为这一步只是把模型“变快”真正的收益其实是把整个推理流程变成你说了算。下面按“原理 → 工程 → 推理 → 验证”的顺序把从 YOLOv8 到 C 部署的完整链路拆开讲。2. 先弄清 TensorRT 优化了什么再把 YOLOv8 从 ONNX 转成 engine2.1 TensorRT 对 YOLOv8 的加速来自四个层面的改写TensorRT 不是简单地把 ONNX 算子翻译成 CUDA 调用它会在构建 engine 的时候对计算图做重写。第一层是图优化把 Conv 与 BatchNorm 合并成单一算子把没有实际输出的分支裁掉把相邻的逐元素算子做融合第二层是 kernel 自动调优同一个卷积在不同输入尺寸、不同显存带宽下会尝试多种 cuDNN 或自研 kernel选让延迟最低的那个第三层是显存规划engine 构建时会分析每个 tensor 的生存期复用中间显存避免每次推理都做 cudaMalloc第四层是数值精度重排默认 FP32 之外可以整体切换成 FP16 或 INT8让 tensor core 发挥吞吐优势。这四层对 YOLOv8 的收益并不平均。图优化和显存规划对任何模型都有效而 FP16 对 YOLOv8 这种以卷积为主的网络非常友好常见情况下精度损失不超过 0.5% 的 mAPINT8 的收益最大但需要准备校准数据而且对 YOLOv8 的检测头敏感一旦分布偏移容易出现漏检。所以工程上最常用的部署精度是 FP16只在显存和延迟都吃紧时才上 INT8。2.2 用 Ultralytics 官方导出脚本把 YOLOv8 转成 ONNX在转换之前先确认本机的 CUDA 和 TensorRT 版本一致然后安装 ultralytics 库。导出 ONNX 的命令非常简单pip install ultralytics onnx onnxsim yolo export modelyolov8n.pt formatonnx opset12 simplifyTrue dynamicFalse imgsz640这条命令会在当前目录生成 yolov8n.onnx。opset12是为了让 TensorRT 的解析器对算子支持更稳simplifyTrue会调用 onnxsim 把常量折叠、多余 reshape 清理掉dynamicFalse在这里很关键它把 batch 和输入尺寸固定成静态生成的 engine 在部署时不需要多次 setBindingDimensions代码简单、延迟也最小。如果想保留动态 batch就把dynamic设成 True并在之后用 trtexec 转换时手动指定--minShapes、--optShapes和--maxShapes。但对于大多数 YOLOv8 检测场景固定 batch1、固定 640 输入就已经够用了动态 shape 的灵活性会牺牲一点 kernel 选择的精度不是刚需就不要开。2.3 trtexec 是生成 engine 的最快路径拿到 ONNX 之后用 TensorRT 自带的 trtexec 转换/opt/TensorRT-8.6.1.6/bin/trtexec \ --onnxyolov8n.onnx \ --saveEngineyolov8n_fp16.engine \ --fp16 \ --workspace4096参数含义如下表参数作用备注--fp16允许 kernel 使用 FP16 精度延迟明显下降精度损失小--int8启用 INT8 量化需要配合--calibrator才能获得可用精度--workspace4096构建时的临时显存上限单位 MB不够会构建失败--saveEngine输出序列化的 engine 文件反序列化后直接使用--verbose打印每一层的详细日志排查转失败时非常有用转换过程快慢取决于模型大小yolov8n 在普通 GPU 上通常是几十秒到两三分钟。构建结束后会看到类似GPU Compute Time: xxx ms的日志这是 TensorRT 在固定 batch 下的自测结果可以用来预估部署后的延迟区间。这里有一个常见的坑序列化后的 engine 文件与 GPU 架构强绑定在 RTX 3090 上转出来的 engine 不能拿到 GTX 1070 上加载换机器必须用那台机器重新构建。TensorRT 10.x 的版本里也仍然支持 Pascal 架构GTX 1070 属于这一代但 INT8 的 tensor core 优化基本享受不到还是老老实实用 FP16 更划算。2.4 拿到 engine 之后的 C 使用思路engine 文件本身不是模型而是“已经编排好的执行计划”所以 C 端不需要再依赖 ONNX 解析器和模型权重运行时的依赖库只有 nvinfer、cudart 和 cublas 等几个。加载 engine 只要做两件事用getEngineStream反序列化得到 ICudaEngine再基于它创建 IExecutionContext。IExecutionContext 是实际执行推理的对象它不是线程安全的一个线程必须独占一个 context。如果要做多路视频流就得给每个线程单独创建 contextengine 本身可以多线程共享。这个设计决定了后面代码的封装方式engine 是只读资源context 是每线程一份的可变状态。3. 搭一个能跑 TRT 的 C 工程关键代码与 CMake 配置3.1 工程目录与依赖清单先规划一下目录结构避免把模型加载和业务逻辑全部塞进 main.cpp。常见的做法是分成这样yolo_trt/ ├── CMakeLists.txt ├── src/ │ ├── main.cpp │ ├── yolodetector.h │ ├── yolodetector.cpp │ └── preprocess.cu └── models/ ├── yolov8n_fp16.enginepreprocess.cu 用来写自定义的 CUDA 核函数把 BGR2RGB、归一化、HWC 到 CHW 转换合并成一个 kernelyolodetector 负责 engine 加载和推理封装main.cpp 只读取图片并调用检测接口。依赖库和对应作用如下表库用途头文件nvinferengine 构建与推理NvInfer.hnvonnxparserONNX 转 engine可选NvOnnxParser.hcudart显存操作与 streamcuda_runtime.hOpenCV图像解码与画框opencv2/opencv.hpp运行时只需要 nvinfer 和 cudartnvonnxparser 只在构建期需要。如果选择完全离线部署可以把构建过程交给 trtexecC 端彻底不引入 onnx parser。3.2 CMakeLists.txt 的可靠写法cmake_minimum_required(VERSION 3.16) project(yolo_trt) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(OpenCV REQUIRED) set(TENSORRT_ROOT /opt/TensorRT-8.6.1.6) set(CUDA_ROOT /usr/local/cuda) include_directories( ${TENSORRT_ROOT}/include ${CUDA_ROOT}/include ${OpenCV_INCLUDE_DIRS} ) link_directories( ${TENSORRT_ROOT}/lib ${CUDA_ROOT}/lib64 ) add_executable(yolo_trt src/main.cpp src/yolodetector.cpp src/preprocess.cu ) target_link_libraries(yolo_trt nvinfer cudart ${OpenCV_LIBS} ) set_target_properties(yolo_trt PROPERTIES CUDA_STANDARD 17 CUDA_STANDARD_REQUIRED ON )使用 nvcc 编译 .cu 文件是这套配置的核心逻辑。CMake 会把 preprocess.cu 交给 nvcc其他 .cpp 交给 g。TENSORRT_ROOT的路径要改成你机器上实际的版本目录。链接顺序上把 nvinfer 放在 cudart 之前一般不会出问题但遇到 undefined reference 时先检查是不是库的顺序反了。3.3 加载 engine 与创建 context 的封装engine 加载的代码是所有推理的基础我一般会这样封装class YoloDetector { public: bool loadEngine(const std::string engine_path) { std::ifstream file(engine_path, std::ios::binary); if (!file.good()) return false; file.seekg(0, std::ios::end); size_t size file.tellg(); file.seekg(0, std::ios::beg); std::vectorchar data(size); file.read(data.data(), size); file.close(); logger_ std::make_uniqueLogger(); runtime_ std::unique_ptrnvinfer1::IRuntime( nvinfer1::createInferRuntime(*logger_)); if (!runtime_) return false; engine_ std::unique_ptrnvinfer1::ICudaEngine( runtime_-deserializeCudaEngine(data.data(), size)); if (!engine_) return false; context_ std::unique_ptrnvinfer1::IExecutionContext( engine_-createExecutionContext()); return context_ ! nullptr; } private: std::unique_ptrLogger logger_; std::unique_ptrnvinfer1::IRuntime runtime_; std::unique_ptrnvinfer1::ICudaEngine engine_; std::unique_ptrnvinfer1::IExecutionContext context_; };deserializeCudaEngine的入参是二进制 buffer 和长度engine 文件读出来是什么就传什么不需要任何额外解析。IRuntime 是上下文环境一个进程只需要一个ICudaEngine 描述网络结构线程共享IExecutionContext 保存推理时的中间状态必须按线程单独创建。这三者生命周期从内到外依赖析构顺序反过来用 unique_ptr 可以防止漏释放导致显存泄露。3.4 工程期最容易出现的两个编译错误第一个是找不到 cuda_runtime.h原因是 include 路径没加 CUDA_ROOT。第二个是链接期报一堆 undefined reference to nvinfer1::通常是 CMake 里 link_directories 没有生效或者在 add_executable 之前就写了 target_link_libraries。本着先确认环境再动手的原则编译前先执行ls /opt/TensorRT-8.6.1.6/lib确认 libnvinfer.so 存在并注意区分 .so 与 .so.8链接时用不带版本号的软链。4. 推理主循环预处理、enqueueV2 和后处理的一次性对齐4.1 letterbox 预处理缩放、补边、记录坐标映射YOLOv8 训练时默认把输入图等比缩放到 640x640多余的边用灰色填充。部署时也要做同样的事否则检测精度会下降。这里不只是“resize”还需要记录缩放比例和补边偏移因为后处理要把输出的框坐标还原到原图上。cv::Mat letterbox(const cv::Mat img, int target_size, float scale, int pad_x, int pad_y) { int h img.rows, w img.cols; scale std::min((float)target_size / h, (float)target_size / w); int new_h std::round(h * scale); int new_w std::round(w * scale); pad_x (target_size - new_w) / 2; pad_y (target_size - new_h) / 2; cv::Mat resized; cv::resize(img, resized, cv::Size(new_w, new_h), 0, 0, cv::INTER_LINEAR); cv::Mat canvas(target_size, target_size, CV_8UC3, cv::Scalar(114, 114, 114)); resized.copyTo(canvas(cv::Rect(pad_x, pad_y, new_w, new_h))); return canvas; }pad_x和pad_y是通过(target_size - new_w) / 2计算的这里用整数除法取整。OpenCV 的 resize 完成等比缩放copyTo 把缩放图贴到灰色画布中央。原图不是正方形时补边位置不会完全对称所以后处理时必须用这两个偏移量做反向映射。4.2 在 GPU 上完成 BGR2RGB、归一化和 HWC 转 CHW把 letterbox 后的图像从 CPU 拷到 GPU 后TensorRT 期望的输入布局是 [1, 3, 640, 640] 的浮点张量而 OpenCV 读到的是 [640, 640, 3] 的 uint8 BGR 数据。直接在 CPU 上用循环处理会有明显的耗时常见做法是用一个 CUDA kernel 在显存里完成全部转换__global__ void preprocess_kernel(const uint8_t* src, float* dst, int channels, int height, int width) { int idx blockIdx.x * blockDim.x threadIdx.x; int total height * width; if (idx total) return; int h idx / width; int w idx % width; int c blockIdx.y; uint8_t bgr[3]; bgr[0] src[idx * 3 0]; bgr[1] src[idx * 3 1]; bgr[2] src[idx * 3 2]; float value 0.f; if (c 0) value bgr[2]; // R else if (c 1) value bgr[1]; // G else value bgr[0]; // B dst[c * total idx] value / 255.0f; }调用时令 blockDim.x 256gridDim.x 覆盖 640x640 像素blockDim.y 3 分别处理三个通道这样每个线程只负责一个像素的单个通道避免重复读取像素。此核函数将内存访问模式设计成对 src 的连续读取并直接以 CHW 的步长写入 dst免去了二次转置的开销。标准做法中这个 kernel 结束之后直接把 dst 作为 bindings[0] 传给 TensorRT而源图 src 是上一节 letterbox 的输出拷贝到显存后的结果。该阶段里融合得越狠整体延迟越可控。4.3 enqueueV2 推理与 buffer 管理推理阶段的核心代码不长但每一步都要注意显存生命周期bool infer(const cv::Mat input, std::vectorDetection detections) { // 假设已经完成 letterbox 和预处理input_tensor 是 1x3x640x640 的 float 数据 void* bindings[2]; cudaMalloc(bindings[0], 1 * 3 * 640 * 640 * sizeof(float)); cudaMalloc(bindings[1], 1 * 84 * 8400 * sizeof(float)); cudaMemcpy(bindings[0], input_tensor, input_size, cudaMemcpyHostToDevice); context_-setBindingDimensions(0, nvinfer1::Dims4{1, 3, 640, 640}); context_-enqueueV2(bindings, stream_, nullptr); cudaMemcpy(outputs, bindings[1], output_size, cudaMemcpyDeviceToHost); cudaStreamSynchronize(stream_); detections decode(outputs, 8400, 80); cudaFree(bindings[0]); cudaFree(bindings[1]); }enqueueV2是异步的它把推理任务提交到指定的 CUDA stream 后立刻返回所以后面必须有cudaStreamSynchronize等待完成。bindings[0] 是输入显存地址bindings[1] 是输出显存地址这两个地址必须在 context 执行期间保持有效。每次推理都 cudaMalloc 和 cudaFree 会引入不必要的性能抖动因为显存分配本身就是耗时操作在真实的长时间运行场景里应当用类成员变量保存这两块 buffer只在初始化和析构时分配与释放而不是放在推理函数内部。4.4 YOLOv8 的后处理没有 objectness输出 layout 是 480YOLOv8 的检测头是解耦头输出经过模型内部的 sigmoid 后在 ONNX 里表达为 [1, 84, 8400] 的布局其中 84 是 4 个框参数加 80 个类别概率8400 是 640x640 输入下三个尺度80x80 40x40 20x20加起来的总 anchor 数。相比于 YOLOv5输出的通道里没有第 5 个维度 objectness 置信度直接取每个 anchor 各类别概率的最大值即可。decode 函数的典型实现是std::vectorDetection decode( float* output, float conf_thresh, float iou_thresh, float scale, int pad_x, int pad_y) { const int num_anchors 8400; const int num_classes 80; std::vectorDetection dets; for (int i 0; i num_anchors; i) { float* ptr output i * (num_classes 4); float score ptr[4]; int class_id 0; for (int j 1; j num_classes; j) { if (ptr[4 j] score) { score ptr[4 j]; class_id j; } } if (score conf_thresh) continue; float cx ptr[0]; float cy ptr[1]; float box_w ptr[2]; float box_h ptr[3]; cx (cx - pad_x) / scale; cy (cy - pad_y) / scale; box_w / scale; box_h / scale; float x1 cx - box_w / 2.f; float y1 cy - box_h / 2.f; float x2 cx box_w / 2.f; float y2 cy box_h / 2.f; dets.push_back({x1, y1, x2, y2, score, class_id}); } std::vectorcv::Rect boxes; std::vectorfloat scores; for (auto d : dets) { boxes.emplace_back(d.x1, d.y1, d.x2 - d.x1, d.y2 - d.y1); scores.push_back(d.score); } std::vectorint indices; cv::dnn::NMSBoxes(boxes, scores, conf_thresh, iou_thresh, indices); std::vectorDetection results; for (int idx : indices) results.push_back(dets[idx]); return results; }注意 output 的读取偏移是i * (4 80)不是i * (5 80)这是 YOLOv8 与 YOLOv5 最大的不同。如果照搬 v5 的后处理类别概率会整体错位导致置信度全部偏低。cx 和 cy 要先减去 letterbox 的 pad再除以缩放比例才能映射回原图坐标。NMS 用 OpenCV 的NMSBoxes就够用需要注意它要求输入的是左上角坐标加宽高不是中心点坐标。5. 精度对拍、多线程 context 与延迟压测技巧5.1 拿 Python 端结果做数值对拍C 部署完成后第一件事不是看 FPS而是找几张典型图片用 ultralytics 的 Python 推理结果和 C 推理结果做对比。把两边输出的框坐标、类别、置信度导出成文件算出每个框的 IoU。正常来说同一张图在 FP32 engine 下坐标误差应该在 0.5 像素以内FP16 引入的误差通常也不会超过 1 到 2 个像素。如果差得远优先怀疑 letterbox 的 pad 计算方式不一致其次是预处理时 RGB/BGR 通道顺序搞反最后确认 NMS 的阈值是否设置一致。5.2 多线程部署时每个线程独立持有 context如果业务要同时处理多路视频或者多个请求C 端可以做这样一件事把配好的 engine 加载一次然后按线程池规模创建多个 IExecutionContext。每个线程在自己的 context 上调用 enqueueV2引擎内部会为不同 context 分配独立工作区避免线程互相拖慢。不过显存里中间 tensor 的占用是 per-context 的所以 8 个 context 并不等于 8 倍的显存占用但也不能忽略通常预留给每个 context 的 workspace 在几十到几百 MB 之间。5.3 用 CUDA Event 而不是 clock() 来测延迟很多人在 C 里用墙钟时间测推理把 host 端的内存拷贝和 GPU 端 kernel 混在一起算得出的时延数值不可信。用 CUDA Event 可以把 GPU 端的时间单独测出来cudaEvent_t start, stop; cudaEventCreate(start); cudaEventCreate(stop); cudaEventRecord(start, stream_); context_-enqueueV2(bindings, stream_, nullptr); cudaEventRecord(stop, stream_); cudaEventSynchronize(stop); float ms 0.f; cudaEventElapsedTime(ms, start, stop);这段代码统计的是从 event 记录点到 stop 之间 GPU 流上的耗时不包含 cudaMemcpy 的时间。如果要把完整链路打满就在 cudaMemcpy 之前再记一个事件这样可以区分预处理、推理和拷贝三段耗时。yolov8n 在 RTX 显卡上的 enqueueV2 裸推理通常在 1 到 3 毫秒量级整链路带预处理和 NMS 会到 5 到 10 毫秒具体由显卡和机器决定。性能上真正要优化的往往是 host 到 device 的拷贝和最后 decode 的循环这两处才是大多数工程里被忽略的“隐形耗时”。5.4 排查延迟异常时的三条线索第一确保推理前先跑一次“预热推理”因为首次 enqueueV2 需要初始化一些 CUDA 模块库加载和 context 激活都会产生额外开销必须把预热排除在统计之外。第二用nsys profile采样整个进程看 GPU kernel 之间有没有明显的空洞有空洞就说明 CPU 端预处理或后处理在拖后腿需要把更多计算放进 GPU。第三确认 TensorRT 的 engine 是否真的用了 FP16在 trtexec 日志里找FP16标志如果构建时因为某些算子不支持而回退到 FP32整体延迟几乎不会下降此时可以把--verbose打开看每一层的精度选择。本文还有配套的精品资源点击获取