简介本资源面向计算机、人工智能、自动化等专业的高校学生与科研开发者提供一套将 mmdetection 与 TensorRT 集成到 ROS2 的 YOLOX 目标检测部署方案可直接用于毕业设计、课程设计或项目立项演示。项目基于 Ubuntu 22.04 与 ROS2 Humble 环境采用 C 与 CMake 构建涵盖模型推理加速与机器人系统通信的完整链路。压缩包共 190 个文件约 2.58MB包含 34 个 Python 脚本、11 个 C 与 11 个头文件、38 张 jpg 与 12 张 png 图示、11 个 json 配置及若干工程与文档文件覆盖源码、配置、说明与测试素材。已有 41 人学习关注。资源附带设计文档与部署教程代码经测试可稳定运行便于复现与二次开发读者可据此掌握 TensorRT 加速、ROS2 节点封装与 YOLOX 模型部署的完整流程也可在现有基础上修改扩展功能。1. TensorRT8 ROS2 部署 YOLOX这套组合到底解决什么问题机器人视觉项目做到最后绕不开一个尴尬算法在 PC 上跑得挺欢一上机器人平台就掉帧。YOLOX 作为 anchor-free 的目标检测模型精度和速度平衡得不错但 PyTorch 推理在 Jetson 或工控机上往往只有个位数 FPS。TensorRT8 就是干这个的——把模型图优化、层融合、FP16/INT8 量化推理速度翻几倍不是玄学。而 ROS2 负责把检测结果以话题、服务的形式喂给下游的导航、抓取、决策模块。这套方案适合谁做机器人开发、边缘计算部署、毕设选题偏工程落地的同学。你不需要从零训模型但得懂基本的模型导出、CUDA 环境、ROS2 节点通信。整条链路是YOLOX 训练权重 → ONNX 导出 → TensorRT 引擎序列化 → ROS2 节点封装 → 话题发布检测框。中间任何一环版本对不上就是血泪经验的开始。2. 环境搭建TensorRT8 与 ROS2 的版本咬合关系2.1 为什么版本匹配比装成功更重要TensorRT8 不是一个孤立库它和 CUDA、cuDNN、PyTorch、ONNX 的版本是锁死的。常见翻车现场TensorRT 8.5 要求 CUDA 11.8你装了 CUDA 12.1编译时libnvinfer.so找不到符号或者 ONNX 用 opset 17 导出TensorRT8 的 parser 只认到 opset 16直接报Unsupported ONNX data type。我一般会先确定一条基线Ubuntu 22.04 CUDA 11.8 cuDNN 8.9 TensorRT 8.6 ROS2 Humble。这条线在 x86 和 Jetson Orin 上都验证过社区资料最多踩坑最少。如果你用 ROS2 Foxy对应 Ubuntu 20.04TensorRT 建议降到 8.4否则 glibc 版本会打架。提示不要用pip install tensorrt装 Python 包就以为完事了C 部署需要完整的 TensorRT 开发库和头文件必须走官方 tar 包或 deb 包安装。2.2 从零装 ROS2 Humble 的最小命令集ROS2 安装本身不复杂但新手容易在源和 key 上卡住。下面这套命令在 Ubuntu 22.04 上直接抄# 设置 locale避免中文环境导致的编码问题 sudo apt update sudo apt install locales sudo locale-gen en_US en_US.UTF-8 sudo update-locale LC_ALLen_US.UTF-8 LANGen_US.UTF-8 # 添加 ROS2 源和 key sudo apt install software-properties-common curl sudo add-apt-repository universe sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \ -o /usr/share/keyrings/ros-archive-keyring.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/ros-archive-keyring.gpg] \ http://packages.ros.org/ros2/ubuntu $(. /etc/os-release echo $UBUNTU_CODENAME) main | \ sudo tee /etc/apt/sources.list.d/ros2.list /dev/null # 安装 ROS2 Humble 桌面版和开发工具 sudo apt update sudo apt install ros-humble-desktop ros-dev-tools装完后source /opt/ros/humble/setup.bash再ros2 run demo_nodes_cpp talker验证。如果 talker 能跑起来说明 DDS 通信层没问题。ROS2 和 DDS 的关系这里不展开你只需要知道默认用的是 Fast DDS多机通信时组播配置不对会导致节点互相看不见。2.3 TensorRT8 安装与验证的四个检查点TensorRT 安装包从 NVIDIA 官网下载 tar 包后解压、加环境变量、装 Python wheel# 解压 TensorRT tar 包 tar -xzvf TensorRT-8.6.1.6.Linux.x86_64-gnu.cuda-11.8.tar.gz export TRT_PATH$PWD/TensorRT-8.6.1.6 export LD_LIBRARY_PATH$TRT_PATH/lib:$LD_LIBRARY_PATH export PATH$TRT_PATH/bin:$PATH # 安装 Python 绑定 cd $TRT_PATH/python pip install tensorrt-8.6.1.6-cp310-none-linux_x86_64.whl # 验证导入不报错且能打印版本 python3 -c import tensorrt as trt; print(trt.__version__)四个检查点trt.__version__输出 8.6ldconfig -p | grep nvinfer能找到库trtexec命令可用CUDA 的nvcc --version和 TensorRT 要求的版本一致。少一个后面编译 ROS2 节点时就会报链接错误。3. YOLOX 模型导出与 TensorRT 引擎构建3.1 从 PyTorch 权重到 ONNX导出脚本与三个必调参数YOLOX 官方仓库提供了export_onnx.py但直接跑往往出问题。我一般会改三个地方opset 版本、输入尺寸、是否简化图。# export_onnx_custom.py import torch from yolox.exp import get_exp from yolox.models import YOLOX # 加载实验配置和权重 exp get_exp(exps/default/yolox_s.py, None) model exp.get_model() ckpt torch.load(yolox_s.pth, map_locationcpu) model.load_state_dict(ckpt[model]) model.eval() # 构造 dummy input尺寸必须和部署时一致 dummy_input torch.randn(1, 3, 640, 640) # 导出 ONNXopset 选 11 兼容性最好 torch.onnx.export( model, dummy_input, yolox_s.onnx, opset_version11, # TensorRT8 对 opset 11 支持最稳 input_names[images], output_names[output], dynamic_axesNone # 固定 batch 和尺寸避免动态 shape 拖慢推理 )逻辑说明opset_version11是 TensorRT8 parser 的舒适区选 17 可能遇到Resize算子不支持。dynamic_axesNone表示固定输入机器人场景通常单帧推理固定 shape 能让 TensorRT 做更激进的优化。导出后用onnxsim简化一下图结构去掉多余的 Identity 和 Constant 节点。参数说明输入尺寸 640×640 是 YOLOX-S 的标准输入如果你换成 416×416mAP 会掉几个点但速度更快。batch size 设为 1因为 ROS2 节点是逐帧处理的batch 推理反而增加延迟。3.2 用 trtexec 构建引擎FP16 与 INT8 的取舍ONNX 有了接下来用trtexec转成 TensorRT 引擎。这是最直接的方式不需要写 C 代码# FP16 模式构建引擎 trtexec --onnxyolox_s.onnx \ --saveEngineyolox_s_fp16.engine \ --fp16 \ --workspace4096 \ --verbose 21 | tee build_fp16.log # INT8 模式需要校准集 trtexec --onnxyolox_s.onnx \ --saveEngineyolox_s_int8.engine \ --int8 \ --calibcalibration.cache \ --workspace4096FP16 几乎无损速度比 FP32 快 1.5 到 2 倍我一般默认用 FP16。INT8 需要准备校准集通常从训练集里抽 500 到 1000 张图跑一遍校准生成 cache 文件。INT8 速度再快一倍但小目标检测精度可能掉 3 到 5 个点。如果你的场景里小目标多比如无人机巡检建议老老实实 FP16。注意--workspace4096单位是 MB给太小会导致某些层无法选择最优 kernel给太大浪费显存。4096 在 8G 显存的机器上比较安全。构建完成后用trtexec --loadEngineyolox_s_fp16.engine --shapesimages:1x3x640x640跑一下 benchmark看吞吐和延迟。如果报Engine built successfully但推理结果全零多半是预处理没对齐——YOLOX 的输入是 RGB、归一化到 0 到 1、letterbox 填充少一步都会导致输出异常。3.3 ROS2 节点封装从引擎加载到话题发布ROS2 节点用 C 写核心是加载 TensorRT 引擎、做前处理、推理、后处理、发布vision_msgs/Detection2DArray。下面是一个最小可运行节点的关键片段// yolox_trt_node.cpp #include rclcpp/rclcpp.hpp #include vision_msgs/msg/detection2_d_array.hpp #include NvInfer.h #include opencv2/opencv.hpp class YoloXTrtNode : public rclcpp::Node { public: YoloXTrtNode() : Node(yolox_trt_node) { // 加载 TensorRT 引擎 auto engine_data readFile(yolox_s_fp16.engine); runtime_ nvinfer1::createInferRuntime(logger_); engine_ runtime_-deserializeCudaEngine(engine_data.data(), engine_data.size()); context_ engine_-createExecutionContext(); // 分配 GPU 显存 cudaMalloc(buffers_[0], 1 * 3 * 640 * 640 * sizeof(float)); cudaMalloc(buffers_[1], 100 * 85 * sizeof(float)); // 订阅图像话题发布检测结果 sub_ create_subscriptionsensor_msgs::msg::Image( /camera/image_raw, 10, std::bind(YoloXTrtNode::imageCallback, this, std::placeholders::_1)); pub_ create_publishervision_msgs::msg::Detection2DArray(/detections, 10); } private: void imageCallback(const sensor_msgs::msg::Image::SharedPtr msg) { cv::Mat img cv_bridge::toCvShare(msg, bgr8)-image; preprocess(img); // letterbox 归一化 cudaMemcpyAsync(buffers_[0], input_host_, ..., cudaMemcpyHostToDevice); context_-enqueueV2(buffers_, stream_, nullptr); cudaMemcpyAsync(output_host_, buffers_[1], ..., cudaMemcpyDeviceToHost); auto detections postprocess(output_host_); // NMS 坐标还原 pub_-publish(detections); } };逻辑说明deserializeCudaEngine把序列化的引擎反序列化到内存enqueueV2是异步推理配合 CUDA stream 做流水线。前处理里的 letterbox 必须和训练时一致否则框会偏移。后处理做 NMS 时置信度阈值和 IoU 阈值要根据场景调一般 0.5 和 0.45 起步。参数说明buffers_[0]是输入大小1×3×640×640buffers_[1]是输出YOLOX-S 输出100×85其中 100 是候选框数85 是4 坐标 1 置信度 80 类。如果你训的是自定义数据集类别数变了输出维度也要改。4. 避坑与排查部署路上最常见的五个翻车点4.1 引擎构建成功但推理结果全零现象trtexec显示Engine built successfully但推理输出全是 0 或 NaN。原因预处理没对齐。YOLOX 要求输入是 RGB 通道、像素值归一化到[0,1]、letterbox 填充到 640×640。很多人直接用 OpenCV 读图后resize通道是 BGR像素值还是[0,255]模型当然输出乱码。解决写一个和训练时完全一致的预处理函数用cv::cvtColor转 RGBimg.convertTo(img, CV_32F, 1.0/255.0)归一化letterbox 的缩放比例和填充值114也要一致。4.2 ROS2 节点编译时报undefined reference to nvinfer现象colcon build时链接阶段报 TensorRT 库找不到。原因CMakeLists.txt 里没有正确链接 TensorRT 库或者LD_LIBRARY_PATH没包含 TensorRT 的 lib 目录。解决在CMakeLists.txt里加find_library(TENSORRT_LIB nvinfer)和target_link_libraries(yolox_trt_node ${TENSORRT_LIB})同时确保source了 TensorRT 的环境变量。如果还不行用ldd检查可执行文件依赖。4.3 检测框坐标偏移或框大小不对现象推理能跑但画出来的框整体偏移或者框比实际物体大一圈。原因letterbox 的缩放比例没有正确还原。前处理时图像被缩放并填充后处理时必须先减去填充偏移再除以缩放比例才能映射回原图坐标。解决在前处理时记录scale和pad值后处理时按x (x - pad_x) / scale还原。这个逻辑在 YOLOX 官方demo_postprocess里有但 C 部署时经常被忽略。4.4 INT8 量化后小目标漏检严重现象FP16 引擎能检测到的小目标换成 INT8 后直接消失。原因INT8 量化对激活值范围敏感小目标的特征响应弱量化后被截断。解决校准集里必须包含足够多的小目标样本不要只用大目标图片校准。如果还是不行对小目标层保持 FP16其余层 INT8用trtexec --layerPrecisions做混合精度。4.5 ROS2 话题发布频率跟不上推理速度现象推理本身 20ms 一帧但 ROS2 话题发布频率只有 5Hz。原因图像回调里做了同步的cudaMemcpy和推理阻塞了 ROS2 的执行器线程。或者 QoS 配置不匹配订阅端收不到消息。解决用rclcpp::CallbackGroup把图像回调和推理放到不同线程或者用MultiThreadedExecutor。QoS 设为SensorDataQoS保证图像话题的实时性。5. 进阶技巧用ros2 topic hz和trtexec做端到端延迟验证部署完了不算完你得知道延迟花在哪。我一般会分三段测预处理耗时、推理耗时、后处理耗时。trtexec能给出纯推理的延迟ROS2 节点里用std::chrono打时间戳ros2 topic hz /detections看端到端频率。# 测推理延迟 trtexec --loadEngineyolox_s_fp16.engine \ --shapesimages:1x3x640x640 \ --iterations100 \ --avgRuns10 \ --duration10 # 测 ROS2 话题频率 ros2 topic hz /detections # 测端到端延迟在节点里打时间戳 # 图像时间戳到发布检测结果的时间差如果推理 15ms但端到端 80ms问题多半在图像传输和预处理。ROS2 图像话题用image_transport压缩传输能省不少带宽但会引入编解码延迟。我习惯在节点内部直接订阅image_raw用共享内存传输避免拷贝。另一个技巧是引擎预热。TensorRT 第一次推理会做 kernel 自动调优耗时可能是后续的 10 倍。在节点初始化时跑 10 次 dummy 推理把预热成本摊掉。这个习惯让我在机器人比赛现场少了很多尴尬——裁判一启动你的检测框就出来了而不是等三秒。最后说一个我踩过的坑别在 ROS2 回调里做cudaMalloc。显存分配是同步操作会卡住整个执行器。所有显存都在节点构造函数里分配好回调里只做cudaMemcpyAsync和enqueueV2。这个习惯值不值得养成你跑一次 30FPS 的相机就知道了。希望帮到你。本文还有配套的精品资源点击获取
