简介面向计算机、人工智能、自动化等专业的毕设与课程设计需求这里提供一套把 mmdetection 与 TensorRT 集成到 ROS2 中的 YOLOX 目标检测部署方案运行环境为 Ubuntu 22.04 与 ROS2 Humble技术栈以 C、CMake 为主侧重推理加速与机器人节点对接适合想把检测模型真正跑进 ROS2 的中高阶学习者复现。整包共 190 个文件、约 2.58MB其中 34 个 py 脚本与 11 个 C 源文件、11 个头文件构成主要代码另有 38 张 jpg、12 张 png 截图11 个 json 配置及若干 txt、md 说明文档配套文档与教程齐全目录清晰便于按模块查阅。已有 41 人学习下载。读者可获得可编译运行的完整工程、TensorRT 推理与 ROS2 通信的对接代码、参数配置思路及常见环境排错参考既可直接用作毕设框架也能扩展为其他检测任务。1. TensorRT8 ROS2 部署 YOLOX这套方案要解决什么问题先把结论放在前面这套方案要解决的问题是让 YOLOX 在机器人的计算平台上以实时帧率跑起来并接进 ROS2 的话题体系。PyTorch 权重直接推理x86 上勉强能用放到 Jetson 这类设备上 GPU 利用率上不去TensorRT8 负责把网络编译成针对特定 GPU 的 engineFP16 下通常能拿到 1.5 到 2 倍端到端加速ROS2 则把检测结果变成话题、变成可视化、变成下游导航和规划的输入。这个组合适合机器人目标检测、移动巡检以及把「模型部署到真机」当核心论点的毕设课题。整条链路分模型导出、engine 生成、ROS2 节点推理三段下文按这个顺序展开。2. YOLOX 导出 ONNX 再转 TensorRT8 engine 的完整链路2.1 解耦头结构决定了导出姿势YOLOX 用的是解耦检测头回归、类别、objectness 各走一个分支这跟 YOLOv5 的耦合头不一样。训练时这个结构收敛更稳部署时却要额外处理导出 ONNX 时把三个分支拼成一个输出张量。常见的输出 shape 是(1, 8400, 85)8400 是 640x640 输入下三层特征图的锚点总数等于 80x80 加 40x40 加 20x2085 是 4 个回归量、1 个 objectness、80 个类别分数。# 在 YOLOX 仓库根目录执行常见做法 python tools/export_onnx.py -n yolox_s -c yolox_s.pth -f 80-n指定模型结构名-c指向训练好的权重-f是类别数COCO 就是 80。导出后用python -m onnxsim yolox_s.onnx yolox_s_sim.onnx过一遍简化能去掉不少对 TensorRT 不友好的动态 reshape 和 if 节点之后的解析报错会明显变少。官方脚本带一个--nms参数会把 NMS 以插件形式打进 ONNX配合 TensorRT 的 EfficientNMS 可以在 GPU 上直接出框。我一般不用它插件版本跟着 TensorRT 走8.4 和 8.6 之间常不兼容换个环境就要重新折腾另外 ROS2 侧通常还要做业务过滤只保留特定类别、按置信度二次筛选把 NMS 留在自己的后处理里更灵活。2.2 trtexec 转 engine 的最小命令与参数解释拿到 ONNX 后多数情况不用写 C 转换程序直接用 TensorRT 自带的 trtexec 即可。先确认当前 TensorRT 版本再执行转换# 查看版本确认当前环境里 TensorRT 的具体小版本 trtexec --version # 转 FP16 engine声明 batch 1~4 的动态输入范围 trtexec --onnxyolox_s_sim.onnx --saveEngineyolox_s.engine \ --fp16 \ --minShapesimages:1x3x640x640 \ --optShapesimages:1x3x640x640 \ --maxShapesimages:4x3x640x640参数说明--fp16开启半精度显存占用和延迟一起降--minShapes、--optShapes、--maxShapes三件套声明动态 batch 范围images必须和 ONNX 输入名完全一致写错会直接报[E]错误。如果确认只推单张可以删掉这三行生成的 engine 体积更小、加载更快。注意TensorRT 生成的 engine 和版本、GPU 型号强绑定。8.4 的 engine 在 8.6 上反序列化会失败x86 台式机转出来的也不能直接拷到 Orin 上跑。锁环境比调参重要。Orin 这类板子出厂自带的 TensorRT 往往不是最新版网上教程让pip install tensorrt很容易把系统版本搞乱出现deserializeCudaEngine failed时先用dpkg -l | grep tensorrt查清楚是谁把环境改了。所谓「orin 降 tensorrt 版本」这个折腾本质上就是版本锁定没做好。2.3 FP16 与 INT8 怎么选先看任务再看板子engine 跑通之后很多人第一反应是把 INT8 也开了。先看收益和成本再决定动不动 INT8精度相对 FP32 的端到端加速mAP 损失额外工作量FP321x无无FP16约 1.5~2x1~2%无INT8约 2~3x2~5%需要标定数据集和量化调优FP16 基本是白捡的绝大多数检测任务直接开。INT8 需要准备 500 到 1000 张有代表性的图片做校准校准集如果和真实场景分布差太远小目标检测的掉点会非常明显。实际项目里我只有帧率实在上不去、且目标以中大尺寸为主时才考虑 INT8毕设答辩场景下FP16 的实时性已经足够说明部署效果。3. 在 ROS2 包里写 TensorRT 推理节点结构与代码骨架3.1 创建功能包与依赖声明以 Ubuntu 22.04 加 ROS2 Humble 为例先建工作空间和功能包。用ros2 pkg create最省事依赖一次性声明好不用手改 CMakeLists 的 find_packagemkdir -p ~/yolox_ws/src cd ~/yolox_ws/src ros2 pkg create yolox_trt --build-type ament_cmake \ --dependencies rclcpp sensor_msgs std_msgs cv_bridge生成的 package.xml 里会列出四个依赖项它们各管一段依赖在节点里的职责rclcpp节点生命周期、话题订阅与发布sensor_msgs图像消息 sensor_msgs/msg/Imagecv_bridgeImage 消息和 OpenCV Mat 互转std_msgsFloat32MultiArray 发送检测结果编译前确认环境里已经装了ros-humble-cv-bridge缺了会在 colcon build 时报找不到头文件。功能包结构上我习惯把 TensorRT 相关代码单独放一个目录和 ROS2 话题逻辑分开编译这样在 x86 上做纯推理单元测试时不需要拉起整个节点排查问题更快。3.2 读取 engine 并执行推理的核心代码推理节点的骨架可以写得很短构造时读 engine、反序列化、创建执行上下文每帧图像进来后先预处理拷到显存执行推理再把结果拷回内存。下面是关键片段// 读取 engine 文件并反序列化 std::ifstream file(engine_path, std::ios::binary); std::vectorchar data((std::istreambuf_iteratorchar(file)), std::istreambuf_iteratorchar()); auto runtime std::unique_ptrnvinfer1::IRuntime( nvinfer1::createInferRuntime(gLogger)); auto engine std::unique_ptrnvinfer1::ICudaEngine( runtime-deserializeCudaEngine(data.data(), data.size())); auto ctx std::unique_ptrnvinfer1::IExecutionContext( engine-createExecutionContext()); // 动态 batch 场景下推理前必须按当前 batch 设置输入维度 ctx-setBindingDimensions(0, nvinfer1::Dims4(batch, 3, 640, 640)); // 执行推理stream 是创建好的 cudaStream_t ctx-enqueueV2(bindings.data(), stream, nullptr); cudaStreamSynchronize(stream);这段代码有几个容易写错的地方。第一createInferRuntime和createExecutionContext返回的都是裸指针必须用unique_ptr管理否则节点反复创建销毁时会泄漏显存。第二bindings数组装的是所有输入输出 binding 的设备指针地址顺序要和 engine 的 binding 顺序一致可以用engine-getBindingIndex(images)查下标不要手写 0、1、2。第三enqueueV2是异步的一定要cudaStreamSynchronize之后再读输出否则拿到的是上一帧的结果。3.3 YOLOX 输出的解码与话题发布engine 的输出是(1, 8400, 85)的原始预测要变成检测框需要自己解码先按锚点计算中心坐标和宽高再把 objectness 和类别分数相乘得到最终分数过滤之后做 NMS。这一步讲究性能可以写成 CUDA kernel但 ROS2 节点通常跑在 30 帧以下CPU 端解码完全够用代码还好维护// 假设 out 是 GPU 拷回内存的 float 数组8400 个锚点每个 85 维 for (int i 0; i 8400; i) { float* p out i * 85; float obj p[4]; int cls_id std::max_element(p 5, p 85) - (p 5); float score obj * p[5 cls_id]; if (score conf_thresh) continue; // 根据锚点所在特征图层级还原原图坐标再送入 NMS } // 结果打包成 Float32MultiArray 发布下游直接订阅消费 auto msg std_msgs::msg::Float32MultiArray(); msg.data {x1, y1, x2, y2, score, (float)cls_id, /* 其余框 */}; pub_-publish(msg);这里有个 YOLOX 特有的坑它的类别分数是解耦头单独输出的 sigmoid 结果直接和 objectness 相乘做过滤没问题但如果拿 PyTorch 里decode_outputs的写法去套 TensorRT 输出会发现坐标还原时缺了特征图尺度和网格偏移两组信息。正确做法是先根据锚点序号反推它属于 80x80、40x40 还是 20x20 的哪一层再用该层 stride 乘回原图坐标这一步错了框会整体偏移。话题用Float32MultiArray最省事后续接 RViz2 可视化或者下游避障逻辑都不用再引入自定义消息。4. 部署实战中的高频坑位TensorRT 版本、预处理与显存调优4.1 TensorRT 版本不一致导致 engine 白转这一条排在坑位第一位。engine 文件是二进制序列化产物从 TensorRT 8.2 到 8.6 每个小版本的序列化格式都可能有变化最常见的报错是deserializeCudaEngine failed或者[E] 4: ... invalid engine。排查顺序固定三步先trtexec --version看当前版本再确认 engine 生成时的版本最后检查是不是从别处拷来的文件。Orin 降 tensorrt 版本的问题本质就是板子出厂镜像自带 8.4 或 8.5用户按网上教程装了新版本后老 engine 全部失效。解决思路不是卸载重装而是把 TensorRT 的安装目录作为编译依赖的一部分锁进 Dockerfile 或部署脚本让模型转换和运行在同一个容器里进行engine 永远在生成它的环境里加载。如果必须混用就在代码里用getInferLibVersion()打个日志启动时先校验再推理省得排查半天。4.2 预处理不一致检测精度掉一半的头号原因模型在 PyTorch 里的预处理是 letterbox 等比缩放加归一化到 0~1TensorRT 推理时如果直接cv::resize拉伸到 640x640或者忘了除以 255检测精度会肉眼可见地掉。letterbox 和直接 resize 的区别在于直接 resize 会改变目标长宽比小目标检测场景下框会偏、置信度会掉letterbox 在缩放后填充灰边保持原始比例。// 预处理letterbox 等比缩放 居中填充记录偏移量供后处理使用 float scale std::min(640.0f / img.cols, 640.0f / img.rows); int new_w (int)(img.cols * scale); int new_h (int)(img.rows * scale); int pad_x (640 - new_w) / 2; int pad_y (640 - new_h) / 2; cv::resize(img, resized, cv::Size(new_w, new_h)); cv::Mat canvas cv::Mat::zeros(640, 640, CV_8UC3); resized.copyTo(canvas(cv::Rect(pad_x, pad_y, new_w, new_h))); // 在 GPU 上完成 BGR-RGB 与 /255 归一化再拷进输入 buffer注意两个配套细节cv_bridge 出来的图像是 BGR 顺序YOLOX 训练时用的是 RGB颜色通道不转会导致特定类别比如红色目标召回率骤降letterbox 的pad_x、pad_y要记录下来后处理把框还原到原图坐标时必须先减左上角偏移再除以scale否则框整体向右下偏移。4.3 上下文与 CUDA 流的线程安全ROS2 节点默认单线程执行回调看起来和 CUDA 不冲突但只要开了多线程执行器或者想在回调里用std::async并行处理两路相机问题就来了一个IExecutionContext同时被两个线程调用时内部状态会互相覆盖结果是框乱跳或者直接cudaErrorIllegalAddress。正确做法是一个线程一个 contextengine 可以共享context 不能共享。显存方面输入输出缓冲区和 CUDA stream 应该在节点初始化时分配一次不要每帧cudaMalloc和cudaFree。实测里每帧重复分配会让 30 帧的任务掉到 15 帧左右显存碎片还会越积越多。用固定缓冲区加cudaMemcpyAsync配合 stream 的写法长期跑下来显存占用是平的。4.4 性能瓶颈看哪些指标Host Latency 还是 GPU 时间部署完别只看帧率帧率太粗。用 trtexec 自带的--benchmark模式可以拿到每个阶段的时间trtexec --loadEngineyolox_s.engine --benchmark --fp16输出里重点看Host Latency和GPU Compute Time两列。如果 Host Latency 远大于 GPU Compute Time瓶颈在预处理、内存拷贝或话题序列化不在推理本身。此时优化优先级是把预处理改成 GPU 上的 kernel、用cudaMemcpyAsync加双缓冲重叠拷贝与计算、检查发布消息时是否做了不必要的拷贝。如果 GPU Compute Time 本身高再看 GPU 利用率是否跑满Jetson 上用tegrastatsx86 上用nvidia-smi dmon。现象优先排查方向Host Latency 高预处理、memcpy、话题发布拷贝GPU Compute Time 高engine 精度档位、输入分辨率、batch 大小显存持续增长context/stream 每帧重建、engine 对象泄漏5. 用 RViz2 验证 YOLOX 检测结果的最小方案5.1 先验证话题数据流推理节点跑起来后第一件事不是开可视化而是用命令行确认数据流ros2 topic echo /yolox_detections --once ros2 topic hz /yolox_detectionstopic echo能看到框的坐标和分数topic hz给出发布频率。如果 hz 明显低于推理帧率说明话题发布或消息构造有拷贝开销如果 hz 为 0先检查节点是否在运行、话题名是否拼错用ros2 topic list核对。这一步能快速区分是推理慢了还是数据没发出来。5.2 在 RViz2 里叠加检测框可视化最省事的方案是发布visualization_msgs/Marker用 CUBE 或 LINE_LIST 画框。关键是把 Marker 的 frame_id 设为相机光轴坐标系这样检测框和图像能对齐。RViz2 里把 Fixed Frame 设置成相同的坐标系再添加 Marker 显示即可如果用的是 gazebo 或 RTAB-Map 这类自带 TF 的环境直接把检测框 frame_id 和相机 TF 对上就行不用自己发 TF。一个小技巧把类别 ID 和置信度拼进 Marker 的 text 字段RViz2 里同时显示框和文本截图放进论文里的信息量比单纯画框大得多。验证通过后把前面记录的 letterbox 偏移、缩放系数、类别映射表整理成 YAML 配置文件后续换模型或调阈值就不用改代码。迁移到真机时把Float32MultiArray换成自定义消息注意在消息体里带上 frame_id 和检测时间戳下游做帧对齐和传感器融合能省掉大量对账工作。本文还有配套的精品资源点击获取