YoloDotNet v4.2 🚀

面向 .NET 的极速、生产就绪的 YOLO 推理

YoloDotNet 是一个模块化、轻量级的 C# 库，用于在 .NET 中实现实时计算机视觉和基于 YOLO 的推理。

它为现代 YOLO 模型系列（从 YOLOv5u 到 YOLOv26、YOLO-World、YOLO-E 和 RT-DETR）提供高性能推理，并对执行、内存和预处理进行显式控制。

YoloDotNet 基于 .NET 8、ONNX Runtime 和 SkiaSharp 构建，有意避免使用 OpenCV 等重量级计算机视觉框架。
没有 Python 运行时、隐藏的预处理或隐式行为——只有在 Windows、Linux 和 macOS 上实现快速、可预测推理所需的组件。

无需 Python，没有魔法，只有高效、确定性的 YOLO——专为 .NET 打造。

⭐ 为什么选择 YoloDotNet？

YoloDotNet 专为需要以下特性的开发者设计：

• ✅ 纯 .NET — 无 Python 运行时，无脚本
• ✅ 真正的性能 — 支持 CPU、CUDA / TensorRT、OpenVINO、CoreML、DirectML
• ✅ 明确的配置 — 可预测的精度和内存使用
• ✅ 生产就绪 — 引擎缓存、长时间运行稳定性
• ✅ 多任务支持 — 目标检测、定向边界框检测、分割、姿态估计、分类

非常适合需要确定性行为和完全控制的 桌面应用、后端服务和实时视觉流水线。

🆕 v4.2 新特性

• 新增 感兴趣区域 (ROI) 支持，允许在图像或视频流的选定区域上运行推理
  (适用于监控、区域监测以及性能优先的流水线)
• 新增在分割对象上绘制边缘的选项，以提高视觉清晰度
• 新增用于 JSON 导出 的辅助方法：
  • ToJson() — 将推理结果转换为 JSON
  • SaveJson() — 将推理结果直接保存为 JSON 文件
• 新增用于 YOLO 格式标注 的辅助方法：
  • ToYoloFormat() — 将结果转换为 YOLO 注释格式
  • SaveYoloFormat() — 将结果保存为 YOLO 兼容的训练数据
• 新增 GetContourPoints() 辅助方法，用于从分割对象中提取 有序轮廓点
• 更新了 YOLOv26 推理执行，使其与其他任务保持一致，从而提升 一致性及整体执行效率

📖 完整发布历史：CHANGELOG.md

[!TIP] 查看演示
演示项目中提供了展示 YoloDotNet 功能的实用、可运行示例：
👉 浏览演示文件夹

🚀 快速入门

💡 ONNX 模型导出要求

• 对于 YOLOv26 模型，请使用 opset=18 导出
• 对于 YOLOv5u–YOLOv12，请使用 opset=17 导出

[!IMPORTANT] 使用正确的 opset 可确保与 ONNX Runtime 的最佳兼容性和性能。
有关如何将模型导出为 ONNX 的更多信息，请参阅 https://docs.ultralytics.com/modes/export/

导出命令示例（Ultralytics CLI）：

# 对于 YOLOv5u–YOLOv12（opset 17）
yolo export model=yolov8n.pt format=onnx opset=17

# 对于 YOLOv26（opset 18）
yolo export model=yolo26n.pt format=onnx opset=18

[!WARNING] 模型许可说明：
YoloDotNet 采用 MIT 许可证，但 大多数 Ultralytics YOLO 模型采用 AGPL-3.0 许可证，或在商业用途中需要商业许可证。
您有责任确保您对任何模型的使用符合其许可条款。
详情请参阅 Ultralytics 模型许可。

1️⃣ 安装核心包

dotnet add package YoloDotNet

2️⃣ 安装 恰好一个(!) 执行提供程序

# CPU（推荐起点）
dotnet add package YoloDotNet.ExecutionProvider.Cpu

# 硬件加速执行（任选其一）
dotnet add package YoloDotNet.ExecutionProvider.Cuda
dotnet add package YoloDotNet.ExecutionProvider.OpenVino
dotnet add package YoloDotNet.ExecutionProvider.CoreML
dotnet add package YoloDotNet.ExecutionProvider.DirectML

💡 注意： CUDA 执行提供程序包含可选的 TensorRT 加速功能。无需单独安装 TensorRT 包。

3️⃣ 运行目标检测

using SkiaSharp;
using YoloDotNet;
using YoloDotNet.Models;
using YoloDotNet.Extensions;
using YoloDotNet.ExecutionProvider.Cpu;

using var yolo = new Yolo(new YoloOptions
{
    ExecutionProvider = new CpuExecutionProvider("model.onnx")
});

using var image = SKBitmap.Decode("image.jpg");

// 注意：IoU 参数仅用于基于 NMS 的模型。
// 对于 YOLOv10 和 YOLOv26，由于后处理由模型内部完成，因此会忽略 IoU。
var results = yolo.RunObjectDetection(image, confidence: 0.25, iou: 0.7);

image.Draw(results);
image.Save("result.jpg");

现在您已成功使用 纯 C# 运行 YOLO 推理。

💡 重要提示：精度取决于配置

YOLO 推理的精度并非自动获得。

图像缩放模式、采样方法以及置信度/IoU 阈值等预处理设置必须与模型的训练方式保持一致。
这些设置直接决定了精度与性能之间的权衡，应被视为模型本身的一部分。

📖 在调整模型或比较结果之前，请阅读：
👉 精度与配置指南

支持的任务

分类	目标检测	OBB 检测	分割	姿态估计
pexels.com	pexels.com	pexels.com	pexels.com	pexels.com

✅ 已验证的 YOLO 模型

以下 YOLO 模型已使用 YoloDotNet，并通过 Ultralytics 官方导出及默认头部进行了 测试和验证。

分类	目标检测	分割	姿态估计	旋转目标检测
YOLOv8-cls YOLOv11-cls YOLOv12-cls YOLOv26-cls	YOLOv5u YOLOv8 YOLOv9 YOLOv10 YOLOv11 YOLOv12 YOLOv26 RT-DETR	YOLOv8-seg YOLOv11-seg YOLOv12-seg YOLOv26-seg YOLO-World (v2)	YOLOv8-pose YOLOv11-pose YOLOv12-pose YOLOv26-pose	YOLOv8-obb YOLOv11-obb YOLOv12-obb YOLOv26-obb

📁 示例

演示文件夹中提供了动手示例：

👉 浏览演示项目

包括图像推理、视频流、GPU 加速、分割以及大图像工作流。

执行提供者

提供者	Windows	Linux	macOS	文档
CPU	✅	✅	✅	CPU README
CUDA / TensorRT	✅	✅	❌	CUDA README
OpenVINO	✅	✅	❌	OpenVINO README
CoreML	❌	❌	✅	CoreML README
DirectML	✅	❌	❌	DirectML README

ℹ️ 只能引用 一个 执行提供者包。
混用不同提供者会导致原生运行时冲突。

⚡ 性能特性

YoloDotNet 致力于稳定且低开销的推理，其运行时成本主要由执行提供者和模型决定。

📊 基准测试：/test/YoloDotNet.Benchmarks

• 预热后延迟稳定
• 从 CPU → GPU → TensorRT 的性能可预测扩展
• 内存分配行为可预测
• 适用于实时和长时间运行的服务

🚀 模块化执行提供者

• 核心包与具体提供者无关
• 执行提供者为独立的 NuGet 包
• 原生 ONNX Runtime 依赖被隔离

这样做的意义： 减少冲突、部署更可预测，且在生产环境中更加安全。

支持 YoloDotNet

⭐ 给仓库加星
💬 分享反馈
🤝 赞助开发

GitHub Sponsors
PayPal

许可证

MIT 许可证

版权所有 © Niklas Swärd

特此授予任何人免费获取本软件及其相关文档文件（“软件”）副本的权利，以进行处理。在不受限制的情况下，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利；并允许向任何接收该软件的人提供服务，但须遵守以下条件：

上述版权声明和本许可声明应包含在所有副本或软件的重要部分中。

“软件”按“原样”提供，不提供任何形式的保证，无论是明示还是暗示，包括但不限于适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权所有者均不对因合同、侵权或其他原因引起的任何索赔、损害赔偿或其他责任负责，这些责任可能源于或与软件的使用有关。

---

模型许可与责任

• YoloDotNet 采用 MIT 许可证，并为使用 Ultralytics YOLO 工具导出的 YOLO 模型提供 ONNX 推理引擎。

• 本项目 不 包含、分发、下载或捆绑任何预训练模型。

• 用户必须自行提供 ONNX 模型。

• 使用 Ultralytics 工具生成的 YOLO ONNX 模型通常根据 AGPL-3.0 或 Ultralytics 的单独商业许可证进行授权。

• YoloDotNet 不会 强制、修改或转移与用户提供的模型相关的任何许可条款。

• 用户需自行负责 确保其对任何模型的使用符合适用的许可条款，包括与商业使用、分发或网络部署相关的要求。

YoloDotNet 快速上手指南

YoloDotNet 是一个专为 .NET 打造的高性能、模块化计算机视觉库。它无需 Python 运行时，支持从 YOLOv5u 到 YOLOv26、YOLO-World 及 RT-DETR 等多种模型，适用于 Windows、Linux 和 macOS 上的实时推理任务。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Windows、Linux 或 macOS。
• .NET SDK：必须安装 .NET 8 或更高版本。
• 模型文件：需自行准备 .onnx 格式的 YOLO 模型文件。
  • YOLOv5u – YOLOv12：导出时请使用 opset=17。
  • YOLOv26：导出时请使用 opset=18。
  • 导出示例 (Ultralytics CLI):

    # YOLOv5u–YOLOv12
    yolo export model=yolov8n.pt format=onnx opset=17
    
    # YOLOv26
    yolo export model=yolo26n.pt format=onnx opset=18
    

• 许可证注意：YoloDotNet 本身采用 MIT 协议，但大多数 Ultralytics YOLO 模型受 AGPL-3.0 保护或需要商业授权。请务必确认您使用的模型符合相应的许可条款。

2. 安装步骤

YoloDotNet 采用模块化设计，核心库与执行提供者（Execution Provider）分离。您需要安装核心包，并恰好选择一个执行提供者包。

第一步：安装核心库

dotnet add package YoloDotNet

第二步：安装执行提供者

根据您的硬件环境，选择其中一个命令安装对应的加速包：

# 选项 A: CPU 推理（推荐初学者或无 GPU 环境）
dotnet add package YoloDotNet.ExecutionProvider.Cpu

# 选项 B: NVIDIA GPU 加速 (CUDA / TensorRT)
dotnet add package YoloDotNet.ExecutionProvider.Cuda

# 选项 C: Intel CPU/GPU 加速 (OpenVINO)
dotnet add package YoloDotNet.ExecutionProvider.OpenVino

# 选项 D: Apple Silicon/Mac 加速 (CoreML)
dotnet add package YoloDotNet.ExecutionProvider.CoreML

# 选项 E: Windows DirectX 加速 (DirectML)
dotnet add package YoloDotNet.ExecutionProvider.DirectML

注意：切勿同时安装多个执行提供者包，否则会导致原生运行时冲突。若使用 CUDA 包，已内置可选的 TensorRT 加速支持，无需额外安装。

3. 基本使用

以下是最简单的对象检测示例。该代码加载模型和图片，执行推理并将结果绘制保存。

using SkiaSharp;
using YoloDotNet;
using YoloDotNet.Models;
using YoloDotNet.Extensions;
// 根据实际安装的包引入命名空间，例如 CPU:
using YoloDotNet.ExecutionProvider.Cpu;

// 初始化 Yolo 实例
using var yolo = new Yolo(new YoloOptions
{
    ExecutionProvider = new CpuExecutionProvider("model.onnx") // 替换为您的模型路径
});

// 加载图片
using var image = SKBitmap.Decode("image.jpg");

// 执行目标检测
// 注意：IoU 参数用于基于 NMS 的模型。
// 对于 YOLOv10 和 YOLOv26，由于后处理由模型内部完成，IoU 参数将被忽略。
var results = yolo.RunObjectDetection(image, confidence: 0.25, iou: 0.7);

// 将检测结果绘制到图片上
image.Draw(results);

// 保存结果
image.Save("result.jpg");

💡 重要提示：配置与精度

YOLO 推理的精度并非自动保证。预处理设置（如图像缩放模式、采样方法）以及置信度/IoU 阈值必须与模型训练时的设置一致。这些参数直接影响精度与性能的平衡，请将其视为模型配置的一部分进行仔细调整。