零基础也能跑通目标检测：YoloDotNet 完整上手指南
项目地址: https://gitcode.com/gh_mirrors/yo/YoloDotNet 不少开发者第一次接触 YOLO，都倒在了"环境配置"这道坎上：Python 版本对不上、CUDA 装崩了、模型导出报错……今天介绍一个让你摆脱这些烦恼的方案——YoloDotNet，一个纯 C# .NET 8.0 的开源视觉库，支持目标检测、图像分类、OBB 检测、图像分割和姿态估计，既能处理单张图片，也能跑实时视频流。全程无需 Python 运行时，从克隆代码到跑出第一张带框的检测图，按下面的路线走，大约十几分钟就能完成。
先搞清楚它到底能帮你做什么
YoloDotNet 的核心思路很朴素：把 YOLO 推理这件事，在 .NET 生态里做"干净"。它没有裹一层厚重的计算机视觉框架，而是基于 ONNX Runtime 与 SkiaSharp 构建，开箱即用。这意味着：
- ✅ 不需要安装 Python，也不依赖脚本环境
- ✅ 支持 YOLOv5u 到 YOLOv26、YOLO-World、YOLO-E、RT-DETR 等主流模型家族
- ✅ 可选的硬件加速提供方：CPU、CUDA/TensorRT、OpenVINO、CoreML、DirectML
- ✅ 图片推理与视频流推理共用一套 API，学习成本低
用目标检测处理人群密集的街道图片，行人与道路目标可以被自动框出并标注置信度。
环境准备三步走
动手之前，先把地基打好，总共三件事。
第一步：确认 .NET 8 环境。 在终端执行：
dotnet --version
如果输出的是 8.0 或更高的版本号，说明 SDK 就绪；如果提示找不到命令，先到 .NET 官网下载安装 .NET 8 SDK。
第二步：拿到项目代码。 通过 Git 克隆仓库：
git clone https://gitcode.com/gh_mirrors/yo/YoloDotNet
cd YoloDotNet
第三步：认识项目里的资源。 项目自带了演示程序和测试素材。预训练模型放在 test/assets/Models/ 目录（如 yolov8s.onnx、yolov11s.onnx），测试图片在 test/assets/Media/ 目录。这意味着你不需要联网下载任何模型，就能跑通第一个示例。
💡 运行前检查清单：
dotnet --version有输出了吗？项目克隆完成了吗？模型文件确实在test/assets/Models/下吗？三项都满足，就继续。
第一次运行：让目标检测跑起来
以最直观的目标检测演示为例。进入演示目录并还原依赖：
cd Demo/ObjectDetectionDemo
dotnet restore
然后直接运行：
dotnet run
程序会加载默认的 ONNX 模型，处理一张测试图片，把检测结果保存到桌面的 YoloDotNet_Results 文件夹，同时在控制台打印检测到的类别和置信度。
预期输出大致是这样的：
Loaded ONNX Model: YoloDotNet v4.2 ... (ObjectDetection)
Inference Results: 3 objects
person (87.23%)
car (92.01%)
...
对于包含车辆与行人的街道场景，目标检测会为每个目标绘制边界框、类别名与置信度分数。
看懂核心调用：五段代码理清逻辑
演示程序里的主流程，其实就是五步。理解了这五步，整个库的用法你就掌握了八成。
1. 初始化 Yolo 实例。 配置模型路径、执行提供方与图片预处理方式：
using var yolo = new Yolo(new YoloOptions
{
ExecutionProvider = new CpuExecutionProvider("model.onnx"),
ImageResize = ImageResize.Proportional
});
2. 加载图片。 YoloDotNet 使用 SkiaSharp 的 SKBitmap 来承载图片：
using var image = SKBitmap.Decode("test.jpg");
3. 执行推理。 一行代码拿到检测结果列表：
var results = yolo.RunObjectDetection(image, confidence: 0.25, iou: 0.7);
4. 绘制结果。 检测框、标签、置信度会被直接画回图片：
image.Draw(results);
5. 保存输出。 指定格式与压缩质量即可写盘：
image.Save("result.jpg");
完整可运行的版本，直接参考 Demo/ObjectDetectionDemo/Program.cs，里面的注释已经把每个选项讲得很透彻。
参数调优：一张表看懂三个关键旋钮
"跑通了"和"跑得好"之间，差的往往就是几个参数。
| 参数名 | 作用 | 建议值 |
|---|---|---|
confidence | 置信度阈值，低于该值的结果会被丢弃 | 默认 0.2，误检多时调到 0.4~0.5 |
iou | 交并比阈值，控制重叠框的合并力度 | 默认 0.7，一般不需要动 |
roi | 感兴趣区域，只检测图片指定区域 | 不设置则检测全图，适合监控场景 |
比如只想要高可信度的目标，可以这样调：
var results = yolo.RunObjectDetection(image, confidence: 0.5, iou: 0.7);
还有两个容易踩坑的细节：ImageResize 建议保持 Proportional（等比缩放加填充），改成了 Stretch 会拉伸图片导致结果失真；不同的模型导出时使用不同的 opset，YOLOv26 需要 opset=18，YOLOv5u 到 YOLOv12 用 opset=17，混用可能加载失败。
从单张图片到更多玩法
目标检测只是入口，换一个方法名，就能切换任务类型：
RunClassification：图像分类，返回最可能的类别RunSegmentation：图像分割，输出像素级掩膜RunPoseEstimation：姿态估计，提取人体关键点RunObbDetection：旋转框检测，适合遥感与航拍场景
主体明确的特写图非常适合体验分类与分割任务，模型会输出类别标签或精细轮廓。
每个任务都配有独立的演示程序，位于 Demo/ 目录下：ClassificationDemo、SegmentationDemo、PoseEstimationDemo、OBBDetectionDemo，结构几乎一致，换汤不换药。
航拍图能直观展示分割效果：建筑、植被、水体各自得到独立的掩膜区域。
让检测动起来：视频流与多目标跟踪
静态图片跑通之后，最让人兴奋的就是实时视频流了。YoloDotNet 的视频处理依赖 FFmpeg 与 FFprobe，记得先把它们安装好并加入系统 PATH。
使用步骤同样简洁：
yolo.InitializeVideo(new VideoOptions
{
VideoInput = "input.mp4", // 本地文件
VideoOutput = "output.mp4", // 处理结果输出
FrameRate = FrameRate.AUTO
});
yolo.OnVideoFrameReceived = (frame, index) =>
{
var results = yolo.RunObjectDetection(frame);
frame.Draw(results);
};
yolo.StartVideoProcessing();
视频源可以是本地文件、RTMP/HTTP 直播流，也可以是摄像头（用 device=<设备名>:<宽>:<高>:<帧率> 的格式指定）。配合 SortTracker 跟踪器，还能给每个目标画上运动轨迹尾巴，实现多目标跟踪。这部分完整示例在 Demo/VideoStreamDemo/Program.cs，其中的 FrameInterval 参数还能实现"每隔 N 帧处理一次"，非常适合监控这类对性能有要求的场景。
密集行人场景最能体现跟踪的价值：为每个行人分配 ID 并追踪其移动轨迹。
常见的坑与避坑指南
把新手最容易卡住的几个问题提前讲清楚，能省下不少排查时间。
- 模型加载失败。 先确认路径写对了，再检查 opset 版本。项目自带模型都在
test/assets/Models/目录下，直接用它们做验证最稳妥。 - 只有一个执行提供方。 YoloDotNet 的核心包与执行提供方是分离的，同一时间只能引用一个提供方包，混用会产生原生运行时冲突。
- CPU 推理偏慢。 这是正常现象。可以降低输入图片分辨率，或者切换到 CUDA/TensorRT、OpenVINO 等加速方案。基准测试代码在
test/YoloDotNet.Benchmarks/目录，可以参考不同配置的性能数据。 - 结果不准先别怪模型。 预处理配置（缩放方式、采样方法、阈值）必须与模型训练时一致，这一点在
AccuracyAndConfiguration.md里有详细说明。
总结：下一步往哪走
到这里，你已经走完了"环境准备 → 首次推理 → 参数调优 → 视频流"的完整闭环。YoloDotNet 把 YOLO 推理装进了纯 C# 的世界，让你可以专注于业务逻辑本身。如果你还想继续深入，有三个方向可以探索：用 TensorRT 做 INT8 量化推理，把单帧延迟压到极致；把检测结果导出为 YOLO 标注格式，反哺自定义模型训练；或者把 YoloDotNet/Yolo.cs 的源码从头读一遍，理解模块化执行提供方背后的设计思想。挑一个感兴趣的方向，动手吧。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
