简介面向C#开发者的YOLOX目标检测部署源码基于WinForm与OpenCvSharp 4.8.0实现可将ONNX格式的YOLOX模型无缝集成到桌面应用。资源内置完整Visual Studio 2019工程涵盖窗体界面、模型管理与推理调用核心逻辑适合需要在.NET Framework 4.7.2环境下快速落地目标检测功能的软件工程师。压缩包共53个文件以C#源码、OpenCvSharp依赖dll、配置与资源文件为主另含模型文件、示例图片、可执行程序及调试符号整体约91.62MB解压后可直接打开解决方案运行验证。目前已有1170人学习下载。除了可复用的检测代码框架还附有YOLOX模型管理器与界面设计资源便于二次开发或迁移到其他视觉项目。对于希望避开环境配置陷阱、直接获取可运行示例的开发者而言是一份扎实的参考实现。 这是一篇写好的博文供你参考发布。1. 从零开始为什么我选择C# WinForm OpenCvSharp跑YOLOX最近在做一个工业质检的小项目需要在Windows上位机上实时检测工件缺陷模型用的是YOLOX训练好的权重是PyTorch格式。客户环境没有Python运行时也不允许装显卡驱动以外的重型依赖唯一能用的就是纯C#的WinForm程序。调研了一圈最终选型定为C# WinForm OpenCvSharp加载YOLOX导出的ONNX模型。目前这套方案已经在产线电脑上稳定跑了两周帧率能到25~30 FPSCPU推理1080P输入完全满足需求。这个方案解决的核心问题是在纯.NET生态下不引入Python进程不依赖大型第三方AI框架用相对简洁的代码完成YOLOX模型的加载、推理、结果绘制和界面展示。如果你是以下人群这篇笔记应该能帮到你做C#上位机、桌面软件需要接入目标检测AI能力手里有YOLOX的PyTorch模型想转成ONNX并用OpenCvSharp部署看网上教程大多是Python OpenCV或ONNX Runtime想找一个纯C#的完整落地案例。下面我会从模型导出、C#项目搭建、前处理、推理、后处理到优化踩坑把完整链路讲一遍。代码不是片段摘抄是能直接跑通的源码逻辑。2. 整体设计与选型为什么是YOLOX ONNX OpenCvSharp2.1 这几样东西是怎么组合起来的YOLOX是旷视开源的目标检测器核心优势是Anchor-Free Decoupled Head在精度和速度之间平衡得很不错而且不同硬件平台部署都很方便。ONNX是微软主导的开放神经网络交换格式把PyTorch训练好的模型冻结成计算图不依赖Python环境。OpenCvSharp是OpenCV的C#封装其中DNN模块可以直接读取ONNX模型并做推理。链条其实是这样的PyTorch训练权重 (.pth) → 导出为 ONNX 模型 → C# WinForm 里用 OpenCvSharp.Dnn.ReadNetFromOnnx 加载 → 对输入图像做 letterbox 缩放和归一化 → net.Forward 前向推理 → 拿到特征图输出1, 8400, 85 → decode 坐标 类别置信度 → NMS 去除重叠框 → 在 PictureBox 上显示结果2.2 为什么不是 ONNX Runtime而是 OpenCvSharp我当时纠结过用Microsoft.ML.OnnxRuntime还是OpenCvSharp。最后选了后者原因很实际OpenCvSharp 环境配置简单两个NuGet包就能跑ONNX Runtime 虽然性能略好但要额外处理内存分配和多个程序集OpenCvSharp 自带图像读取、缩放、绘制、NMS等全套函数和WinForm的PictureBox配合起来很顺不用在C#里再引一堆图像处理库对于YOLOX这种目标检测模型OpenCV DNN的CPU算力完全够用特别是Intel平台会走OpenVINO后端提速明显如果后面要接摄像头、视频流OpenCvSharp直接支持VideoCapture一站式搞定。当然ONNX Runtime 也不是没有优势它对量化模型、动态输入的支持更完善如果模型特别复杂或需要GPU推理还是建议用它。但就YOLOX常规版本来说OpenCvSharp这套方案性价比最高维护成本也低。2.3 项目结构预览我最终的项目结构大致如下你可以参考YoloxWinForm/ ├── Models/ │ ├── YoloxDetector.cs // 核心推理类 │ └── DetectionResult.cs // 检测结果实体 ├── Utils/ │ ├── ImageProcessor.cs // 前处理letterbox、归一化 │ └── YoloxDecoder.cs // 后处理decode、NMS ├── MainForm.cs // WinForm界面选择图片-检测-显示 └── weights/ └── yolox_s.onnx // 导出的模型3. 前置环节把YOLOX的PyTorch模型导出为ONNX这一步是整套部署中最容易出问题的环节。YOLOX官方仓库其实已经提供了导出脚本如果你用的是yolox官方代码基本直接跑就行。3.1 官方导出方式在YOLOX项目根目录执行python tools/export_onnx.py --output-name yolox_s.onnx -n yolox-s -c yolox_s.pth参数含义-n yolox-s指定模型规模这里以s为例-c yolox_s.pth训练好的权重路径--output-name导出文件名。导出成功后会生成一个yolox_s.onnx文件。这个脚本默认固定输入尺寸为640x640如果之后在C#端处理别的分辨率需要保持统一。3.2 手动导出可能遇到的问题我遇到过几个比较典型的坑如果你自己写导出脚本建议注意opset版本导出的opset版本建议11以上OpenCV DNN对高版本opset支持虽在改善但用11最稳妥。如果后续推理报“Unsupported op”可以先查opset是否过高动态轴导出脚本默认把输入和输出都固定成静态shape好处是OpenCV读取方便。如果你需要动态尺寸要在torch.onnx.export里加dynamic_axes但OpenCV DNN对动态shape的支持有限所以我个人建议固定尺寸导出省心非极大值抑制层不要把NMS加进模型里YOLOX官方导出默认是不带NMS的NMS我们放到C#后处理里做灵活度更高也避免导出的模型在某些后端不兼容。导出的模型可以用Netron可视化看一下确认输出节点形状是不是类似(1, 8400, 85)。这里8400就是特征图上的候选框数量85表示4个坐标x,y,w,h 1个objectness 80个类别概率。如果你用的是自定义类别数量比如只有5类那么输出就是(1, 8400, 5510?)不对是41num_classes要算清楚。3.3 验证ONNX模型是否可读拿到onnx后别急着写C#先用Python快速验证一次import cv2 import numpy as np net cv2.dnn.readNetFromOnnx(yolox_s.onnx) img np.zeros((640, 640, 3), dtypenp.float32) blob cv2.dnn.blobFromImage(img, 1/255.0, (640, 640), (0,0,0), swapRBTrue) net.setInput(blob) out net.forward() print(out.shape)如果这一步输出正常说明模型和OpenCV的兼容性没问题C#里大概率也顺利。这个验证习惯能帮你把问题快速隔离在“模型本身”还是“C#代码”。4. C# WinForm项目搭建与核心推理源码4.1 新建项目与安装依赖在Visual Studio里创建Windows窗体应用(.NET Framework 4.8)或者.NET 6/8都行。我用的.NET Framework 4.8因为客户环境更老兼容性好。通过NuGet安装三个包包名作用OpenCvSharp4OpenCV核心库的C#封装OpenCvSharp4.runtime.win包含Windows运行所需native dllOpenCvSharp4.Extensions和Bitmap互转等扩展方法安装时注意OpenCvSharp4.runtime.win是运行时依赖一定不能少。如果没有它运行时会报OpenCvSharp.NativeMethods相关异常找不到opencv_world之类的dll。4.2 模型推理核心类下面这段是YoloxDetector的核心加载逻辑using OpenCvSharp; using OpenCvSharp.Dnn; public class YoloxDetector : IDisposable { private Net _net; private float _confThreshold 0.3f; private float _nmsThreshold 0.5f; private int _inputSize 640; public YoloxDetector(string modelPath) { // 读取onnx模型 _net CvDnn.ReadNetFromOnnx(modelPath); if (_net null) throw new Exception(模型加载失败); // 如果检测到OpenCL可用可以启用一般默认就好 //_net.SetPreferableBackend(Net.Backend.OPENCV); //_net.SetPreferableTarget(Net.Target.CPU); } public ListDetectionResult Detect(Mat image) { // 1. letterbox前处理 var (blob, resizeRatio, padX, padY) LetterBox(image); // 2. 设置输入并推理 _net.SetInput(blob, images); // 输入节点名称一般叫images可用Netron确认 Mat output _net.Forward(output); // 输出节点名称 // 3. 后处理解码 var boxes DecodeOutput(output, resizeRatio, padX, padY); output.Dispose(); return boxes; } public void Dispose() { _net?.Dispose(); } }这里我用了元组返回前处理中间变量实际项目建议建一个PreProcessResult类可读性更好。4.3 前处理letterbox缩放与归一化YOLOX官方训练时对图像做了letterbox就是保持长宽比缩放到640x640剩余区域填充114灰度值。如果你直接用Resize拉伸到640x640测试时精度会掉得很厉害尤其对于细长物体。public (Mat blob, float ratio, int padX, int padY) LetterBox(Mat image) { int h image.Rows; int w image.Cols; float ratio Math.Min((float)_inputSize / w, (float)_inputSize / h); int newW (int)Math.Round(w * ratio); int newH (int)Math.Round(h * ratio); // 先等比缩放 Mat resized new Mat(); Cv2.Resize(image, resized, new Size(newW, newH)); // 创建640x640的画布填充114 Mat canvas new Mat(_inputSize, _inputSize, MatType.CV_8UC3, new Scalar(114, 114, 114)); // 将缩放后的图放到画布左上角 int padX (_inputSize - newW) / 2; int padY (_inputSize - newH) / 2; resized.CopyTo(canvas[new Rect(padX, padY, newW, newH)]); // 转换成blobBGR-RGB缩放至[0,1] Mat blob CvDnn.BlobFromImage(canvas, 1.0 / 255.0, new Size(_inputSize, _inputSize), new Scalar(0, 0, 0), true, false); resized.Dispose(); canvas.Dispose(); return (blob, ratio, padX, padY); }注意几个细节BlobFromImage的第一个参数是mean这里设为0因为归一化已经在除以255里做了swapRBtrue表示将BGR转为RGBYOLOX训练时是基于RGB的cropfalse表示不裁剪因为我们之前已经做了letterbox如果croptrue它会直接居中裁剪效果不一样。4.4 推理与输出结构调用_net.Forward()后返回的Mat形状是(1, 8400, 85)我们固定输入尺寸640x640时。这在C#中得到的是一个三维数组需要手动遍历。如果你的模型有多个输出节点比如后处理已经拆分了可以用string[] outNames _net.GetUnconnectedOutLayersNames(); Mat[] outs new Mat[outNames.Length]; for (int i 0; i outNames.Length; i) outs[i] new Mat(); _net.Forward(outs, outNames);但常规情况下我们只forward一个输出直接拿Mat操作其实不太方便因为OpenCvSharp的Mat索引器性能一般。这里我另一种做法是把Mat转换成一维float数组再手动解析。4.5 后处理解码坐标、置信度过滤与NMSYOLOX的输出是cx, cy, w, h, obj_score, class_scores...注意原始输出里坐标是相对于640x640输入图的并且是中心点坐标。我们需要转成相对于原图的左上角坐标。public ListDetectionResult DecodeOutput(Mat output, float ratio, int padX, int padY) { int rows output.Size(1); // 8400 int cols output.Size(2); // 85 // 将Mat展开为float数组便于索引 float[] data new float[rows * cols]; Marshal.Copy(output.Data, data, 0, rows * cols); ListRect boxes new ListRect(); Listfloat confidences new Listfloat(); Listint classIds new Listint(); for (int i 0; i rows; i) { int offset i * cols; float objScore data[offset 4]; if (objScore _confThreshold) continue; // 找最大类别概率 int classId 0; float maxClassScore 0; for (int j 5; j cols; j) { if (data[offset j] maxClassScore) { maxClassScore data[offset j]; classId j - 5; } } float score objScore * maxClassScore; if (score _confThreshold) continue; float cx data[offset 0]; float cy data[offset 1]; float w data[offset 2]; float h data[offset 3]; // 转成原图坐标 float left (cx - padX - w / 2) / ratio; float top (cy - padY - h / 2) / ratio; float right (cx - padX w / 2) / ratio; float bottom (cy - padY h / 2) / ratio; // 越界处理 left Math.Max(0, left); top Math.Max(0, top); right Math.Min(right, imageWidth); // imageWidth要传进来 bottom Math.Min(bottom, imageHeight); boxes.Add(new Rect((int)left, (int)top, (int)(right - left), (int)(bottom - top))); confidences.Add(score); classIds.Add(classId); } // NMS int[] indices new int[boxes.Count]; CvDnn.NMSBoxes(boxes, confidences, _confThreshold, _nmsThreshold, out indices); ListDetectionResult results new ListDetectionResult(); for (int i 0; i indices.Length; i) { int idx indices[i]; results.Add(new DetectionResult { Rect boxes[idx], ClassId classIds[idx], Confidence confidences[idx] }); } return results; }这里面最容易翻车的点坐标换算输出坐标是在640x640画布上的先减去padX/padY再除以缩放比ratio才能映射回原图。如果letterbox时把图放到了右下角有人喜欢居中或偏右偏移量会不一样图像宽高上面对越界的限制里imageWidth和imageHeight要用原图的尺寸这个值从外面传入不要用640NMSBoxes的重载OpenCvSharp中有多个重载有些输出int[]有些输出Index结构体注意看NuGet版本。我用的4.8版本是CvDnn.NMSBoxes(boxes, confidences, threshold, nmsThreshold, out int[] indices)。4.6 在WinForm中显示结果界面很简单一个Button选择图片一个PictureBox显示结果。核心就是要把Mat转成Bitmap。private void btnDetect_Click(object sender, EventArgs e) { using (OpenFileDialog ofd new OpenFileDialog()) { if (ofd.ShowDialog() DialogResult.OK) { using (Mat image new Mat(ofd.FileName, ImreadModes.Color)) using (Mat resultImg image.Clone()) { // 推理 var detections _detector.Detect(image); // 绘制 foreach (var det in detections) { Cv2.Rectangle(resultImg, det.Rect, new Scalar(0, 255, 0), 2); string label ${_className[det.ClassId]} {det.Confidence:F2}; Cv2.PutText(resultImg, label, new Point(det.Rect.X, det.Rect.Y - 5), HersheyFonts.HersheySimplex, 0.5, new Scalar(0, 255, 0), 1); } // Mat转Bitmap显示 using (var bmp OpenCvSharp.Extensions.BitmapConverter.ToBitmap(resultImg)) { pictureBox1.Image (Bitmap)bmp.Clone(); } } } } }如果你在using块里直接pictureBox1.Image bmp关闭bmp会导致PictureBox显示异常所以需要Clone或者不让bmp销毁。这是我踩过的坑。5. 常见问题与排查技巧实录5.1 模型读取出错Cant read ONNX fileOpenCV读取ONNX失败常见原因可能性解决方法模型路径不对检查AppDomain.CurrentDomain.BaseDirectory下的路径调试时把模型放在bin\Debug\weights下OpenCvSharp的dll找不到确认安装了OpenCvSharp4.runtime.win并检查输出目录有没有opencv_world4100.dllonnx包含不支持的算子用Python的OpenCV先试读如果Python能读C#不能读多半是C#版本的OpenCV较老更新NuGet包导出的onnx损坏重新导出建议opset115.2 Forward输出shape不对不是(1, 8400, 85)这种情况一般是模型导出时改了输入尺寸或加了特殊分支。建议用Netron打开onnx看输出节点的名称和shape。然后在C#里用下面的代码打印出来var shape output.Size(); Console.WriteLine($dims: {shape[0]}, {shape[1]}, {shape[2]});如果shape是(1, 85, 8400)说明你的导出脚本输出类型是别人那种转置过的。这时需要调整数据读取顺序把rows和cols交换即data[col * rows row]。YOLOX官方输出是(batch, num_anchors, num_classes5)但在某些自定义导出中可能会变成(batch, num_classes5, num_anchors)。这个不能抄作业一定要看模型。5.3 检测结果偏移或乱框先检查letterbox的pad位置是否居中我见过有人填充在左上角那么坐标偏移公式也会变检查ratio计算用的是Math.Min还是Math.Max如果搞反了长边超出640短边不满结果全乱检查BlobFromImage的swapRB如果忘记转换RGB对颜色敏感的模型比如红绿灯会识别错但对COCO这种通用目标影响可能不大。5.4 C# UI卡顿问题如果你的程序是点击一次检测一张图片UI不会有卡顿。但如果你接摄像头实时检测千万别直接在UI线程里跑推理。解决方案private async void btnStart_Click(object sender, EventArgs e) { await Task.Run(() { while (capture.IsOpened()) { using (Mat frame new Mat()) { capture.Read(frame); if (frame.Empty()) break; var dets _detector.Detect(frame); // 用Invoke更新UI pictureBox1.Invoke(new Action(() { // 绘制并显示 })); } } }); }注意在释放frame之前如果要跨线程显示最好做成拷贝或者直接同步处理。另外Task.Run里长时间循环要注意取消令牌不然窗口关闭了线程还在跑会报错。5.5 性能优化从3 FPS到25 FPS我一开始直接裸跑640输入在i5-8500上只有3 FPS后来做了几个优化打开OpenVINO后端_net.SetPreferableBackend(Net.Backend.OPENVINO); _net.SetPreferableTarget(Net.Target.CPU);这是性能提升最大的一步直接跑到20 FPS以上。前提是你的OpenCV版本编译了OpenVINO支持OpenCvSharp4.runtime.win自带的dll默认支持实测有效。关闭反色和跳过冗余代码不要在循环里创建大对象Mat、Bitmap都尽量复用。推理线程优先级把工作线程ThreadPriority设为AboveNormalUI响应会好一些。图像缩放如果原图是3000x3000letterbox本身耗时也不小可以先用Cv2.Resize把最长边缩到1280再做检测精度损失很小。6. 优化经验补充OpenCvSharp DNN与ONNX Runtime的取舍再补充一点我后来的实践心得。如果你部署的模型对后处理要求很高比如YOLOX的某些变体带DCN卷积、或者模型包含自定义算子OpenCV DNN可能不支持这时候必须用ONNX Runtime。改到ONNX Runtime其实不复杂using Microsoft.ML.OnnxRuntime; using Microsoft.ML.OnnxRuntime.Tensors; var session new InferenceSession(yolox_s.onnx); var input new DenseTensorfloat(data, new[] { 1, 3, 640, 640 }); var inputs new ListNamedOnnxValue { NamedOnnxValue.CreateFromTensor(images, input) }; using (var results session.Run(inputs)) { var output results.First().AsTensorfloat(); // 后处理和上面类似 }好处是ONNX Runtime大概率跑得比OpenCV快一点而且支持C# Tensor操作更方便。坏处是多引入一个原生依赖项目发布时要额外拷贝onnxruntime.dll和对应的DirectML或CPUdll。从维护角度讲OpenCvSharp给的是一整套图像处理链路对WinForm开发更顺手ONNX Runtime更纯粹只负责推理。没有绝对的好坏我目前方案倾向于OpenCvSharp只要它兼容你的模型就够了。7. 把项目发布成成品的一些建议最后聊点离线的、实际交付的问题。你写完程序要发布给客户记得模型路径外置不要硬编码C:\yolox_s.onnx把模型放在exe同目录下的weights文件夹用Path.Combine(AppDomain.CurrentDomain.BaseDirectory, weights, yolox_s.onnx)读取发布配置如果是.NET Framework项目请选Release x64OpenCV的native库只有64位性能最好运行时检测客户机器上如果没有VC运行库OpenCvSharp4.runtime.win会启动崩溃。把vcruntime140.dll、msvcp140.dll一并拷到exe目录或者用Inno Setup打包时加入这些依赖日志记录在模型加载和首次推理时做try-catch把异常写入文本日志方便远程排查。我之前遇到一个客户机器上显卡驱动太老导致OpenCL初始化失败就是靠日志定位的。我个人在实际部署中的体会是C#做AI推理其实没有想象中那么“水土不服”。OpenCvSharp足够成熟YOLOX导出ONNX也是标准流程真正的坑往往不在推理本身而在图像坐标换算、模型输入输出对齐、运行时依赖这三个地方。把这三块搞定整个项目就顺了。如果你也正在用C#集成YOLOX卡在哪一步了可以按这篇文章的思路理一遍大概率能解决。本文还有配套的精品资源点击获取