简介这份资源面向计算机、人工智能、自动化、通信工程等专业的高校学生与科研开发者提供一套将 mmdetection 与 TensorRT 集成到 ROS2 的 YOLOX 目标检测部署方案可在 Ubuntu 22.04 与 ROS2 Humble 环境下运行适合作为毕业设计、课程设计或项目立项演示也便于在此基础上二次开发。压缩包共 190 个文件约 2.58MB包含 34 个 Python 脚本、38 张 jpg 与 12 张 png 效果图、22 个 js 与 5 个 css 前端资源、11 个 C 与 11 个头文件、若干 json 配置及 md 说明文档覆盖模型推理、节点通信与界面展示等模块。已有 41 人学习关注。资源附带设计文档与部署教程代码经测试可稳定复现能帮助读者理解 TensorRT 加速推理、ROS2 节点封装与 YOLOX 模型接入的完整链路并掌握常见环境配置与排错思路。1. TensorRT8 ROS2 YOLOX一条把检测延迟压到 20ms 的工程链路在 ROS2 里跑目标检测很多人第一次跑通 YOLO 之后都会遇到同一个尴尬Python 推理节点一上 1080p 图像单帧耗时直接飙到 80150ms话题队列开始堆积rviz2 里的框比画面慢半拍。TensorRT8 ROS2 YOLOX 这套组合解决的正是这个「模型能跑但跑不快」的问题——用 TensorRT 把 YOLOX 的 ONNX 图编译成 FP16/INT8 引擎再包成 ROS2 的 C 节点把单帧推理压到 1025ms 量级让 1080p 视频流在消费级显卡上也能实时出框。这套方案适合三类人一是做毕设或课程设计、需要在机器人平台上展示实时检测效果的学生二是手里有 Jetson 或带独显的工控机、想把检测塞进 ROS2 感知链路的工程师三是已经跑通 YOLOX 训练、卡在部署环节的算法同学。它不要求你从零写推理框架但要求你会用 CMake、看得懂 ONNX 的输入输出维度剩下的就是照着链路一步步搭。2. 为什么选 YOLOX TensorRT8 而不是直接上 ultralytics2.1 YOLOX 的 anchor-free 结构对 TensorRT 更友好YOLOX 相比 YOLOv5/v8 最大的结构差异是去掉了 anchor改用 decoupled head SimOTA 标签分配。这件事在训练阶段是精度收益在部署阶段是实打实的省事没有 anchor 就少了一组需要按特征图尺寸动态生成的先验框导出 ONNX 时不会出现「anchor 网格在 TensorRT 里被常量折叠掉、导致解码对不上」的经典翻车。YOLOX 的 head 输出是三个尺度的[1, H*W, 85]80 类 4 坐标 1 obj解码逻辑就是简单的 grid stride 还原用 CUDA kernel 或者 TensorRT 的 plugin 都好写。另一个现实原因是版本可控。ultralytics 的 YOLOv8/v11 迭代很快model.export(formatengine)一行就能出 engine但内部封装了太多东西一旦要改 NMS 阈值、改输入分辨率、改 batch就得进它的源码里翻。YOLOX 的导出脚本是显式的你能清楚看到每一步在做什么出问题时排查路径短。对于毕设这种需要「讲清楚每一环」的场景显式链路比黑盒封装更值。2.2 TensorRT8 的 FP16/INT8 与 ROS2 节点的时间预算先算一笔账。1080p25fps 意味着每帧 40ms 的预算检测节点通常还要和相机驱动、编码、其他感知节点共享 CPU。如果用 PyTorch 直接推理 YOLOX-s640 输入在 T4 上大约 1520ms看起来够但 Python 的 GIL、图像拷贝、后处理 NMS 加起来经常翻倍。TensorRT8 把推理部分压到 FP16 后YOLOX-s 在 T4 上约 46msYOLOX-m 约 812ms留出的余量足够做后处理和话题收发。关于热搜里那个「T4 1080p 25 帧用 TensorRT YOLO 640 分辨率能支持多少路」的问题给个工程估算T4 的 FP16 算力约 65 TFLOPSYOLOX-s 640 单帧约 46ms理论上限 150 路但实际受限于显存带宽、图像解码和 PCIe 拷贝单卡跑 816 路 1080p 是比较稳的区间再往上就要看你的预处理是不是也放到 GPU 上。这个数字不是拍脑袋是显存和拷贝带宽卡住的后面第 5 章会讲怎么用 CUDA stream 把多路流水线叠起来。2.3 ROS2 节点选 C 还是 Python结论先给推理节点用 C调试和可视化可以用 Python。ROS2 的 rclcpp 和 rclpy 在功能上对等但 C 节点在图像话题sensor_msgs/Image的零拷贝和 TensorRT 的 CUDA 内存对接上更顺。Python 节点每次bridge.imgmsg_to_cv2都会产生一次内存拷贝1080p 一帧就是 6MB25fps 下 150MB/s 的额外拷贝在嵌入式平台上很致命。常见做法是C 写一个yolox_trt_node订阅/camera/image_raw内部用cv_bridge转成 cv::Mat再上传到 GPU 做预处理和推理最后把检测框通过自定义 msg 发出去。Python 那边只留一个订阅检测结果、画框发布/detection_image的调试节点方便你随时改颜色和阈值。3. 从 ONNX 到 engineYOLOX 模型转换的完整命令链3.1 导出 ONNX 时必须固定的三个维度YOLOX 官方仓库的tools/export_onnx.py默认导出动态 batch但 TensorRT8 在构建 engine 时如果遇到动态维度会生成多个 optimization profile显存占用和首次构建时间都会上去。毕设和单路部署场景建议直接固定成静态 shape。# 在 YOLOX 根目录下执行导出 640x640 静态输入 python tools/export_onnx.py \ --output-name yolox_s.onnx \ -f exps/default/yolox_s.py \ -c weights/yolox_s.pth \ --opset 11 \ --batch-size 1 \ --input-size 640 640这里三个参数必须盯死--opset 11是 TensorRT8 兼容性最好的版本opset 12/13 里某些算子比如Resize的 coordinate_transformation_mode在旧版 TensorRT 上会 fallback 到 CPU--batch-size 1固定 batch多路场景靠多 engine 实例而不是动态 batch--input-size 640 640固定分辨率避免预处理阶段做 letterbox 之外的缩放。导出后务必用onnxsim简化一遍YOLOX 的 Focus 层早期版本和 slice 操作会产生大量冗余节点pip install onnxsim onnxsim yolox_s.onnx yolox_s_sim.onnx简化后节点数通常从 600 降到 300 左右TensorRT 构建时间能省一半。3.2 trtexec 构建 engine 的参数怎么设trtexec是 TensorRT 自带的命令行工具比写 Python API 构建 engine 更直观也方便你把构建参数记进文档。trtexec \ --onnxyolox_s_sim.onnx \ --saveEngineyolox_s_fp16.engine \ --fp16 \ --workspace2048 \ --minShapesimages:1x3x640x640 \ --optShapesimages:1x3x640x640 \ --maxShapesimages:1x3x640x640 \ --verbose 21 | tee build.log参数逐个说--fp16开启半精度T4/30 系以上显卡都支持精度损失在 YOLOX 上通常 mAP 掉 0.3 以内--workspace2048是 2GB 显存工作区YOLOX-s 用 1024 就够YOLOX-m/l 建议 20484096三个 shape 参数都设成一样就是告诉 TensorRT 这是静态 shape别生成 profile。--verbose加tee是为了留构建日志engine 构建失败时错误信息全在 log 里比在 Python 里 catch 异常清楚得多。构建完成后用trtexec --loadEngineyolox_s_fp16.engine --shapesimages:1x3x640x640 --iterations100跑一遍 benchmark看GPU Compute Time那一行这才是真实推理耗时别拿构建日志里的数字当性能。3.3 验证 engine 输出与 PyTorch 对齐engine 构建成功不等于结果正确。YOLOX 的输出是三个尺度的 raw tensor没有内置解码所以必须自己写后处理。验证方法是用同一张图分别过 PyTorch 和 engine对比 raw output 的数值。import numpy as np import tensorrt as trt import pycuda.driver as cuda import pycuda.autoinit # 加载 engine logger trt.Logger(trt.Logger.WARNING) with open(yolox_s_fp16.engine, rb) as f: engine trt.Runtime(logger).deserialize_cuda_engine(f.read()) context engine.create_execution_context() # 分配输入输出显存注意 YOLOX 输出是三个尺度 input_shape (1, 3, 640, 640) # 输出维度从 engine 里读不要硬编码 for i in range(engine.num_bindings): name engine.get_binding_name(i) shape engine.get_binding_shape(i) print(fbinding {i}: {name}, shape{shape}, dtype{engine.get_binding_dtype(i)})这段代码的作用是打印所有 binding 的名字和维度。YOLOX-s 640 输入下你会看到类似output的 bindingshape 是[1, 8400, 85]三个尺度 concat 后。如果打印出来的 shape 和你预期不符八成是导出 ONNX 时--input-size没对上或者 onnxsim 把某个 reshape 折叠错了。对齐数值时用np.testing.assert_allcloseFP16 的容差设rtol1e-2, atol1e-2超过这个范围说明有算子被 TensorRT 用不同精度实现了需要回退到 FP32 构建对比。4. ROS2 节点封装话题、内存与后处理的三个关键决策4.1 图像话题的零拷贝与 cv_bridge 的取舍ROS2 默认的sensor_msgs/Image在 intra-process 通信下可以做到零拷贝但前提是发布者和订阅者在同一个进程且开启了 intra-process。跨进程时图像数据还是要走 DDS 序列化。工程上的折中是相机驱动和检测节点放同一个 component container 里用rclcpp_components注册这样image_transport的raw传输能走 loaned message。// 检测节点订阅时的 QoS 设置必须和相机发布端匹配 auto qos rclcpp::QoS(rclcpp::KeepLast(1)) .best_effort() .durability_volatile(); subscription_ this-create_subscriptionsensor_msgs::msg::Image( /camera/image_raw, qos, std::bind(YoloxTrtNode::imageCallback, this, std::placeholders::_1));KeepLast(1)是关键检测节点永远只处理最新帧队列深度大了只会增加延迟。best_effort匹配大多数相机驱动的默认 QoS如果你用reliable而相机是best_effort会直接收不到数据这是 ROS2 新手最常见的「话题有发布但订阅没回调」原因。4.2 预处理放到 GPUletterbox 的 CUDA 实现思路YOLOX 的预处理是 letterbox保持长宽比缩放短边补灰边到 640。如果这一步在 CPU 上用 OpenCV 做1080p 一帧大约 35ms看起来不多但它是串行的。把 letterbox 写成 CUDA kernel 或者用cv::cuda::resizecopyMakeBorder能和推理流水线重叠。// 用 OpenCV CUDA 模块做预处理的骨架 cv::cuda::GpuMat gpu_src, gpu_resized, gpu_padded; gpu_src.upload(cpu_mat); // 这一步是同步的可以用 stream 异步化 float scale std::min(640.0f / w, 640.0f / h); int new_w static_castint(w * scale); int new_h static_castint(h * scale); cv::cuda::resize(gpu_src, gpu_resized, cv::Size(new_w, new_h), 0, 0, cv::INTER_LINEAR); cv::cuda::copyMakeBorder(gpu_resized, gpu_padded, (640 - new_h) / 2, 640 - new_h - (640 - new_h) / 2, (640 - new_w) / 2, 640 - new_w - (640 - new_w) / 2, cv::BORDER_CONSTANT, cv::Scalar(114, 114, 114));注意upload是同步操作真正要压延迟得用cv::cuda::Stream把 upload、resize、normalize 串成异步链。另外归一化除以 255、减均值最好也放进 CUDA kernel别在 CPU 上做完再传那样等于白折腾。4.3 后处理 NMS 的阈值与 ROS2 消息设计YOLOX 的 raw output 解码后是[x1, y1, x2, y2, obj, cls...]需要先按 obj 阈值筛再按类别做 NMS。工程上建议把 obj 阈值设 0.3、NMS IoU 设 0.45 作为起点这两个值在大多数场景下平衡了召回和误检。自定义消息比复用vision_msgs更省事因为vision_msgs/Detection2DArray的嵌套结构在 rviz2 里显示要额外写插件。简单做法是定义一个Detectionmsg包含x1 y1 x2 y2 score class_id再发一个DetectionArray。# 生成自定义 msg 的 CMake 片段 rosidl_generate_interfaces(${PROJECT_NAME} msg/Detection.msg msg/DetectionArray.msg DEPENDENCIES std_msgs )后处理本身建议用 CUDA 写因为 8400 个候选框在 CPU 上做 NMS 大约 24msGPU 上能压到 0.5ms 以内。如果时间紧先用 CPU 版本跑通再优化。5. 避坑与排查engine 构建和 ROS2 联调的五个血泪记录5.1 engine 换机器后反序列化失败现象在开发机上构建好的.engine拷到目标机deserialize_cuda_engine返回 nullptr日志里提示serialization version mismatch。原因TensorRT engine 不是跨平台可移植的它绑定了构建时的 GPU 架构SM 版本、TensorRT 版本和 CUDA 版本。T4 是 SM 7.530 系是 SM 8.6engine 不通用。解决engine 必须在目标机上构建或者用trtexec的--saveEngine在目标机重新生成。如果目标机没有 ONNX 环境可以把 ONNX 拷过去用目标机的 TensorRT 构建。毕设交付时文档里要写清楚「engine 需在目标机重新构建」别直接把 engine 打进压缩包当成品。5.2 ROS2 节点收不到图像话题现象ros2 topic list能看到/camera/image_rawros2 topic hz也有频率但检测节点的回调一次都不进。原因QoS 不匹配。相机驱动常用best_effortvolatile而 rclcpp 默认订阅是reliablevolatile两者不兼容时 ROS2 不会报错只是静默不投递。解决用ros2 topic info /camera/image_raw --verbose看发布端的 QoS订阅端照着设。或者干脆在代码里显式写rclcpp::SensorDataQoS()它对应best_effortKeepLast(5)是传感器话题的通用配置。5.3 检测框位置整体偏移现象框能出来但位置比实际目标偏上或偏左偏移量随图像分辨率变化。原因letterbox 的 padding 计算和还原时 scale 用错。常见错误是还原时用了new_w/orig_w而不是640/orig_w或者在 padding 不对称时奇数差值取整方向不一致。解决把预处理时的scale、pad_x、pad_y存下来后处理还原时严格用同一组值x_orig (x_model - pad_x) / scale。建议写一个单元测试用一张已知目标位置的图跑一遍对比还原后的坐标。5.4 FP16 后小目标漏检明显现象FP32 engine 能检出的小目标换 FP16 后消失置信度从 0.4 掉到 0.1 以下。原因FP16 的动态范围有限YOLOX 的 obj 分支在浅层特征上数值较小量化后容易丢精度。另外如果用了 INT8 校准校准集不覆盖小目标场景也会导致漏检。解决先回退 FP16 到 FP32 确认是精度问题然后对 obj 分支的输出层用--precisionConstraints强制 FP32或者直接用 FP16 但把 obj 阈值从 0.3 降到 0.2 补偿。INT8 场景必须用包含小目标的校准集至少 500 张。5.5 多路推理时显存溢出现象单路跑得好好的起第二路节点时cudaMalloc失败或者 engine 构建时 workspace 不够。原因每个 engine 实例都会占用独立的显存包括输入输出 binding 和 workspace。YOLOX-s FP16 单实例约 200300MB如果 workspace 设了 2GB两路就是 4GBT4 的 16GB 显存看着够但加上相机缓冲和其他节点就容易爆。解决多路场景把 workspace 降到 512MB1GB或者用 TensorRT 的IExecutionContext共享同一个 engineengine 可以多 context但要注意线程安全。更彻底的做法是用 batch 推理把多路图像拼成一个 batch但那样要改预处理和 ROS2 节点的同步逻辑复杂度上去了。6. 把延迟再压一半CUDA stream 流水线与多路复用技巧单路跑通之后真正拉开差距的是流水线设计。默认写法是「收图 → 上传 → 预处理 → 推理 → 后处理 → 发结果」串行执行每一段都在等上一段。用 CUDA stream 把上传、预处理、推理、后处理拆到不同 stream 上能让它们重叠起来。核心思路是双缓冲准备两块 GPU 内存 A 和 B当推理在用 A 的时候预处理往 B 里写下一帧。这样推理时间和预处理时间就重叠了总延迟从t_pre t_infer t_post降到max(t_pre, t_infer) t_post。// 双缓冲流水线的骨架 cudaStream_t stream_pre, stream_infer; cudaStreamCreate(stream_pre); cudaStreamCreate(stream_infer); // 帧 N 的预处理在 stream_pre 上 preprocessAsync(frame_n, buffer_a, stream_pre); // 帧 N-1 的推理在 stream_infer 上与上面重叠 context-enqueueV2(bindings_b, stream_infer, nullptr); // 用 event 同步确保推理读的 buffer 已经写完 cudaEventRecord(pre_done, stream_pre); cudaStreamWaitEvent(stream_infer, pre_done, 0);这里的关键是cudaStreamWaitEvent它让推理 stream 等预处理 stream 的 event而不是用cudaDeviceSynchronize全局同步。全局同步会把所有重叠都打断等于白做流水线。多路复用的另一个技巧是共享 engine、多 context。TensorRT 的ICudaEngine是线程安全的可以创建多个IExecutionContext每个 context 绑定自己的输入输出显存。这样多路视频流共用一份权重显存占用从 N 份降到 1 份权重 N 份 binding。实测在 T4 上YOLOX-s FP16 用这种方式跑 8 路 1080p每路稳定在 25fpsGPU 利用率约 70%还有余量。验证流水线是否真的重叠用nsys profile或者nvprof看 timeline如果看到 preprocess 和 inference 的 kernel 在时间轴上交错说明成了如果还是串行检查是不是哪里插了cudaDeviceSynchronize或者用了默认 stream默认 stream 是同步的会破坏所有重叠。最后说个我自己的习惯每次改完流水线我都会先用一路视频跑 1000 帧记录 P50 和 P99 延迟而不是只看平均值。P99 才是决定 rviz2 里卡不卡的那个数平均值好看但 P99 飙到 100ms 的情况太常见了。这套方案值不值得做取决于你能不能接受「花两天调流水线换 10ms 延迟」——对毕设来说这 10ms 就是答辩时演示流畅和卡顿的区别。希望帮到你。本文还有配套的精品资源点击获取