简介：本资源面向计算机、人工智能、自动化等专业的高校学生与科研开发者，提供一套将 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.04，TensorRT 建议降到 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_ALL=en_US.UTF-8 LANG=en_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.6；ldconfig -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_location="cpu") model.load_state_dict(ckpt["model"]) model.eval() # 构造 dummy input，尺寸必须和部署时一致 dummy_input = torch.randn(1, 3, 640, 640) # 导出 ONNX，opset 选 11 兼容性最好 torch.onnx.export( model, dummy_input, "yolox_s.onnx", opset_version=11, # TensorRT8 对 opset 11 支持最稳 input_names=["images"], output_names=["output"], dynamic_axes=None # 固定 batch 和尺寸，避免动态 shape 拖慢推理 )逻辑说明：opset_version=11是 TensorRT8 parser 的舒适区，选 17 可能遇到Resize算子不支持。dynamic_axes=None表示固定输入，机器人场景通常单帧推理，固定 shape 能让 TensorRT 做更激进的优化。导出后用onnxsim简化一下图结构，去掉多余的 Identity 和 Constant 节点。
参数说明：输入尺寸 640×640 是 YOLOX-S 的标准输入，如果你换成 416×416，mAP 会掉几个点但速度更快。batch size 设为 1，因为 ROS2 节点是逐帧处理的，batch 推理反而增加延迟。
3.2 用 trtexec 构建引擎：FP16 与 INT8 的取舍
ONNX 有了，接下来用trtexec转成 TensorRT 引擎。这是最直接的方式，不需要写 C++ 代码：
# FP16 模式构建引擎 trtexec --onnx=yolox_s.onnx \ --saveEngine=yolox_s_fp16.engine \ --fp16 \ --workspace=4096 \ --verbose 2>&1 | tee build_fp16.log # INT8 模式需要校准集 trtexec --onnx=yolox_s.onnx \ --saveEngine=yolox_s_int8.engine \ --int8 \ --calib=calibration.cache \ --workspace=4096FP16 几乎无损，速度比 FP32 快 1.5 到 2 倍，我一般默认用 FP16。INT8 需要准备校准集，通常从训练集里抽 500 到 1000 张图，跑一遍校准生成 cache 文件。INT8 速度再快一倍，但小目标检测精度可能掉 3 到 5 个点。如果你的场景里小目标多，比如无人机巡检，建议老老实实 FP16。
注意：
--workspace=4096单位是 MB，给太小会导致某些层无法选择最优 kernel，给太大浪费显存。4096 在 8G 显存的机器上比较安全。
构建完成后，用trtexec --loadEngine=yolox_s_fp16.engine --shapes=images: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_subscription<sensor_msgs::msg::Image>( "/camera/image_raw", 10, std::bind(&YoloXTrtNode::imageCallback, this, std::placeholders::_1)); pub_ = create_publisher<vision_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×640；buffers_[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转 RGB，img.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 --loadEngine=yolox_s_fp16.engine \ --shapes=images:1x3x640x640 \ --iterations=100 \ --avgRuns=10 \ --duration=10 # 测 ROS2 话题频率 ros2 topic hz /detections # 测端到端延迟：在节点里打时间戳 # 图像时间戳到发布检测结果的时间差如果推理 15ms，但端到端 80ms，问题多半在图像传输和预处理。ROS2 图像话题用image_transport压缩传输能省不少带宽，但会引入编解码延迟。我习惯在节点内部直接订阅image_raw，用共享内存传输，避免拷贝。
另一个技巧是引擎预热。TensorRT 第一次推理会做 kernel 自动调优，耗时可能是后续的 10 倍。在节点初始化时跑 10 次 dummy 推理，把预热成本摊掉。这个习惯让我在机器人比赛现场少了很多尴尬——裁判一启动，你的检测框就出来了，而不是等三秒。
最后说一个我踩过的坑：别在 ROS2 回调里做cudaMalloc。显存分配是同步操作，会卡住整个执行器。所有显存都在节点构造函数里分配好，回调里只做cudaMemcpyAsync和enqueueV2。这个习惯值不值得养成？你跑一次 30FPS 的相机就知道了。
希望帮到你。
本文还有配套的精品资源，点击获取
