English | 简体中文

---

🚀 TensorRT-YOLO 是一款专为 NVIDIA 设备设计的易用灵活、极致高效的YOLO系列推理部署工具。项目不仅集成了 TensorRT 插件以增强后处理效果，还使用了 CUDA 核函数以及 CUDA 图来加速推理。TensorRT-YOLO 提供了 C++ 和 Python 推理的支持，旨在提供📦开箱即用的部署体验。包括 目标检测、实例分割、图像分类、姿态识别、旋转目标检测、视频分析等任务场景，满足开发者多场景的部署需求。

🌠 过去更新

• 🔥 实战课程｜TensorRT × Triton Inference Server 模型部署

  • 平台: BiliBili 课堂 | 微信公众号 🚀 HOT
  • 团队: laugh12321 | 不归牛顿管的熊猫
  • 🛠 硬核专题:
    ▸ 自定义插件开发（含Plugin注册全流程）
    ▸ CUDA Graph 原理与工程实践
    ▸ Triton Inference Server 部署技巧

• 2026-03-20: 添加对 YOLO26 的支持，包括分类、定向边界框、姿态估计以及实例分割。🌟 NEW

• 2026-01-07: 添加对 YOLO-Master 的支持，包括分类、定向边界框、姿态估计以及实例分割。🌟 NEW

• 2025-10-05：精度完美对齐，CUDA 完美复刻 LetterBox，绝大多数情况下像素误差为 0。Python 模块重大重构，易用性大幅提升。🌟 NEW

• 2025-06-09: C++仅引单头文件 trtyolo.hpp，零第三方依赖（使用模块时无需链接 CUDA 和 TensorRT），增加对带图像间距（Pitch）数据结构的支持，详见 B站。🌟 NEW

• 2025-04-19: 添加对 YOLO-World, YOLOE 的支持，包括分类、定向边界框、姿态估计以及实例分割，详见 B站。🌟 NEW

• 2025-03-29: 添加对 YOLO12 的支持，包括分类、定向边界框、姿态估计以及实例分割，详见 issues。🌟 NEW

• 性能飞跃！TensorRT-YOLO 6.0 全面升级解析与实战指南 🌟 NEW

✨ 主要特性

🎯 多样化的 YOLO 支持

• 全面兼容：支持 YOLOv3 至 YOLO26，以及 YOLO-World、YOLO-Master 等多种变体，满足多样化需求，详见 🖥️ 模型支持列表。
• 灵活切换：提供简洁易用的接口，支持不同版本 YOLO 模型的快速切换。🌟 NEW
• 多场景应用：提供丰富的示例代码，涵盖Detect、Segment、Classify、Pose、OBB等多种应用场景。

🚀 性能优化

• CUDA 加速：通过 CUDA 核函数优化前处理流程，并采用 CUDA 图技术加速推理过程。
• TensorRT 集成：深度集成 TensorRT 插件，显著加速后处理，提升整体推理效率。
• 多 Context 推理：支持多 Context 并行推理，最大化硬件资源利用率。🌟 NEW
• 显存管理优化：适配多架构显存优化策略（如 Jetson 的 Zero Copy 模式），提升显存效率。🌟 NEW

🛠️ 易用性

• 开箱即用：提供全面的 C++ 和 Python 推理支持，满足不同开发者需求。
• CLI 工具：命令行界面简洁直观，并支持自动识别模型结构，无需复杂配置。
• Docker 支持：提供 Docker 一键部署方案，简化环境配置与部署流程。
• 无第三方依赖：全部功能使用标准库实现，无需额外依赖，简化部署流程。
• 部署便捷：提供动态库编译支持，方便调用和部署。

🌐 兼容性

• 多平台支持：全面兼容 Windows、Linux、ARM、x86 等多种操作系统与硬件平台。
• TensorRT 兼容：完美适配 TensorRT 10.x 版本，确保与最新技术生态无缝衔接。

🔧 灵活配置

• 预处理参数自定义：支持多种预处理参数灵活配置，包括 通道交换 (SwapRB)、归一化参数、边界值填充。🌟 NEW

💨 快速开始

1. 前置依赖

• CUDA：推荐版本 ≥ 11.0.1
• TensorRT：推荐版本 ≥ 8.6.1
• 操作系统：Linux (x86_64 或 arm)（推荐）；Windows 亦可支持

[!NOTE]
如果您在 Windows 下进行开发，可以参考以下配置指南：

• Windows 开发环境配置——NVIDIA 篇
• Windows 开发环境配置——C++ 篇

2. 编译安装

首先，克隆 TensorRT-YOLO 仓库：

git clone https://github.com/laugh12321/TensorRT-YOLO
cd TensorRT-YOLO

然后使用 CMake，可以按照以下步骤操作：

pip install "pybind11[global]" # 安装 pybind11，用于生成 Python 绑定
cmake -S . -B build -D TRT_PATH=/your/tensorrt/dir -D BUILD_PYTHON=ON -D CMAKE_INSTALL_PREFIX=/your/tensorrt-yolo/install/dir
cmake --build build -j$(nproc) --config Release --target install

执行上述指令后，tensorrt-yolo 库将被安装到指定的 CMAKE_INSTALL_PREFIX 路径中。其中，include 文件夹中包含头文件，lib 文件夹中包含 trtyolo 动态库和 custom_plugins 动态库（仅在使用 trtexec 构建 OBB、Segment 或 Pose 模型时需要）。如果在编译时启用了 BUILD_PYTHON 选项，则还会在 trtyolo/libs 路径下生成相应的 Python 绑定文件。

[!NOTE]
在使用 C++ 动态库之前，请确保将指定的 CMAKE_INSTALL_PREFIX 路径添加到环境变量中，以便 CMake 的 find_package 能够找到 tensorrt-yolo-config.cmake 文件。可以通过以下命令完成此操作：

export PATH=$PATH:/your/tensorrt-yolo/install/dir # linux
$env:PATH = "$env:PATH;C:\your\tensorrt-yolo\install\dir;C:\your\tensorrt-yolo\install\dir\bin" # windows

如果您希望在 Python 上体验与 C++ 相同的推理速度，则编译时需开启 BUILD_PYTHON 选项，然后再按照以下步骤操作：

pip install --upgrade build
python -m build --wheel
pip install dist/trtyolo-6.*-py3-none-any.whl

3. 模型转换

• 使用项目配套的 trtyolo-export 工具包，将已经导出的 YOLO 系列 ONNX 模型转换为兼容 TensorRT-YOLO 推理的输出结构并构建为 TensorRT 引擎。

4. 推理示例

• 使用 Python 进行推理：

  import cv2
  import supervision as sv
  
  from trtyolo import TRTYOLO
  
  # -------------------- 初始化模型 --------------------
  # 注意：task参数需与导出时指定的任务类型一致（"detect"、"segment"、"classify"、"pose"、"obb"）
  # profile参数开启后，会在推理时计算性能指标，调用 model.profile() 可获取
  # swap_rb参数开启后，会在推理前交换通道顺序（确保模型输入时RGB）
  model = TRTYOLO("yolo11n-with-plugin.engine", task="detect", profile=True, swap_rb=True)
  
  # -------------------- 加载测试图片并推理 --------------------
  image = cv2.imread("test_image.jpg")
  result = model.predict(image)
  print(f"==> result: {result}")
  
  # -------------------- 可视化结果 --------------------
  box_annotator = sv.BoxAnnotator()
  annotated_frame = box_annotator.annotate(scene=image.copy(), detections=result)
  
  # -------------------- 性能评估 --------------------
  throughput, cpu_latency, gpu_latency = model.profile()
  print(throughput)
  print(cpu_latency)
  print(gpu_latency)
  
  # -------------------- 克隆模型 --------------------
  # 克隆模型实例（适用于多线程场景）
  cloned_model = model.clone()  # 创建独立副本，避免资源竞争
  # 验证克隆模型推理一致性
  cloned_result = cloned_model.predict(input_img)
  print(f"==> cloned_result: {cloned_result}")
  

• 使用 C++ 进行推理：

  #include <memory>
  #include <opencv2/opencv.hpp>
  
  #include "trtyolo.hpp"
  
  int main() {
      try {
          // -------------------- 初始化配置 --------------------
          trtyolo::InferOption option;
          option.enableSwapRB();  // BGR->RGB转换
  
          // 特殊模型参数设置示例
          // const std::vector<float> mean{0.485f, 0.456f, 0.406f};
          // const std::vector<float> std{0.229f, 0.224f, 0.225f};
          // option.setNormalizeParams(mean, std);
  
          // -------------------- 模型初始化 --------------------
          // ClassifyModel、DetectModel、OBBModel、SegmentModel 和 PoseModel 分别对应于图像分类、检测、方向边界框、分割和姿态估计模型
          auto detector = std::make_unique<trtyolo::DetectModel>(
              "yolo11n-with-plugin.engine",  // 模型路径
              option                         // 推理设置
          );
  
          // -------------------- 数据加载 --------------------
          cv::Mat cv_image = cv::imread("test_image.jpg");
          if (cv_image.empty()) {
              throw std::runtime_error("无法加载测试图片");
          }
  
          // 封装图像数据（不复制像素数据）
          trtyolo::Image input_image(
              cv_image.data,     // 像素数据指针
              cv_image.cols,     // 图像宽度
              cv_image.rows     // 图像高度
          );
  
          // -------------------- 执行推理 --------------------
          trtyolo::DetectRes result = detector->predict(input_image);
          std::cout << result << std::endl;
  
          // -------------------- 结果可视化（示意） --------------------
          // 实际开发需实现可视化逻辑，示例：
          // cv::Mat vis_image = visualize_detections(cv_image, result);
          // cv::imwrite("vis_result.jpg", vis_image);
  
          // -------------------- 模型克隆演示 --------------------
          auto cloned_detector = detector->clone();  // 创建独立实例
          trtyolo::DetectRes cloned_result = cloned_detector->predict(input_image);
  
          // 验证结果一致性
          std::cout << cloned_result << std::endl;
  
      } catch (const std::exception& e) {
          std::cerr << "程序异常: " << e.what() << std::endl;
          return EXIT_FAILURE;
      }
      return EXIT_SUCCESS;
  }
  

5.推理流程图

以下是predict方法的流程图，展示了从输入图片到输出结果的完整流程：

只需将待推理的图片传递给 predict 方法，predict 内部会自动完成预处理、模型推理和后处理，并输出推理结果，这些结果可进一步应用于下游任务（如可视化、目标跟踪等）。

更多部署案例请参考模型部署示例 .

🌟 赞助与支持

开源不易，如果本项目对你有所帮助，欢迎通过赞助支持作者。你的支持是开发者持续维护的最大动力！

---

🙏 衷心感谢以下支持者与赞助商的无私支持：

[!NOTE]

以下是 GitHub Actions 自动生成的赞助者列表，每日更新 ✨。

📄 许可证

TensorRT-YOLO采用 GPL-3.0许可证，这个OSI 批准的开源许可证非常适合学生和爱好者，可以推动开放的协作和知识分享。请查看LICENSE 文件以了解更多细节。

感谢您选择使用 TensorRT-YOLO，我们鼓励开放的协作和知识分享，同时也希望您遵守开源许可的相关规定。

📞 联系方式

对于 TensorRT-YOLO 的错误报告和功能请求，请访问 GitHub Issues！

给项目点亮 ⭐ Star 可以帮助我们优先关注你的需求，加快响应速度～

🙏 致谢

🌟 Star History

TensorRT-YOLO 快速上手指南

TensorRT-YOLO 是一款专为 NVIDIA 设备设计的高效 YOLO 系列推理部署工具，支持 C++ 和 Python，具备开箱即用的特性，涵盖目标检测、实例分割、姿态识别等多种任务。

1. 环境准备

系统要求

• 操作系统：Linux (x86_64 或 ARM) 推荐；Windows 亦支持
• 硬件平台：NVIDIA GPU (支持 CUDA)

前置依赖

请确保已安装以下基础环境：

• CUDA：版本 ≥ 11.0.1
• TensorRT：版本 ≥ 8.6.1
• CMake：用于编译构建
• Python (可选)：如需使用 Python 接口，建议 Python 3.8+

注意：Windows 用户可参考 Windows 开发环境配置指南 进行详细设置。

2. 安装步骤

步骤一：克隆仓库

git clone https://github.com/laugh12321/TensorRT-YOLO
cd TensorRT-YOLO

步骤二：编译安装 (C++ & Python)

首先安装 Python 绑定依赖，然后使用 CMake 进行编译：

# 安装 pybind11 (用于生成 Python 绑定)
pip install "pybind11[global]"

# 配置编译选项
# 请将 /your/tensorrt/dir 替换为实际 TensorRT 安装路径
# 请将 /your/tensorrt-yolo/install/dir 替换为您希望安装到的目标路径
cmake -S . -B build \
    -D TRT_PATH=/your/tensorrt/dir \
    -D BUILD_PYTHON=ON \
    -D CMAKE_INSTALL_PREFIX=/your/tensorrt-yolo/install/dir

# 编译并安装
cmake --build build -j$(nproc) --config Release --target install

步骤三：配置环境变量

为了让系统找到编译好的库文件，请将安装路径添加到环境变量中：

Linux:

export PATH=$PATH:/your/tensorrt-yolo/install/dir

Windows (PowerShell):

$env:PATH = "$env:PATH;C:\your\tensorrt-yolo\install\dir;C:\your\tensorrt-yolo\install\dir\bin"

步骤四：安装 Python 包 (可选)

如果启用了 BUILD_PYTHON，需额外执行以下步骤以在 Python 中直接使用：

pip install --upgrade build
python -m build --wheel
pip install dist/trtyolo-6.*-py3-none-any.whl

3. 基本使用

在使用前，请先使用 trtyolo-export 工具将 YOLO 模型的 ONNX 文件转换为带有插件的 TensorRT 引擎文件 (.engine)。

Python 示例

以下是最简单的目标检测推理流程：

import cv2
from trtyolo import TRTYOLO

# 1. 初始化模型
# task 需与导出时的任务类型一致 (detect, segment, classify, pose, obb)
# swap_rb=True 表示自动进行 BGR 到 RGB 的通道转换
model = TRTYOLO("yolo11n-with-plugin.engine", task="detect", swap_rb=True)

# 2. 加载图片并推理
image = cv2.imread("test_image.jpg")
result = model.predict(image)

# 3. 输出结果
print(f"检测到的目标数量：{len(result)}")
for det in result:
    print(f"类别：{det.cls}, 置信度：{det.conf}, 坐标：{det.xyxy}")

C++ 示例

C++ 接口仅需引入单个头文件即可使用：

#include <iostream>
#include <opencv2/opencv.hpp>
#include "trtyolo.hpp"

int main() {
    try {
        // 1. 配置选项
        trtyolo::InferOption option;
        option.enableSwapRB(); // 开启 BGR->RGB 转换

        // 2. 加载模型 (DetectModel 对应目标检测)
        auto detector = std::make_unique<trtyolo::DetectModel>(
            "yolo11n-with-plugin.engine", 
            option
        );

        // 3. 读取图片
        cv::Mat cv_image = cv::imread("test_image.jpg");
        if (cv_image.empty()) {
            throw std::runtime_error("无法加载图片");
        }

        // 4. 封装图像数据 (零拷贝)
        trtyolo::Image input_image(cv_image.data, cv_image.cols, cv_image.rows);

        // 5. 执行推理
        trtyolo::DetectRes result = detector->predict(input_image);
        
        // 6. 输出结果
        std::cout << result << std::endl;

    } catch (const std::exception& e) {
        std::cerr << "错误：" << e.what() << std::endl;
        return EXIT_FAILURE;
    }
    return EXIT_SUCCESS;
}

提示：更多高级用法（如实例分割、姿态估计、视频流处理）请参考项目 examples 目录下的完整示例代码。