C#上位机集成Unet语义分割：ONNX模型GPU推理实战与踩坑

简介面向需要将UNet语义分割模型落地到实际应用的开发者资源内含基于ONNX Runtime的GPU图片推理完整示例包括Visual Studio解决方案、Form1界面、UNetSegmentation.cs推理核心、Program.cs入口及示例图片与model1.onnx模型文件可直接运行查看分割效果。压缩包为rar格式共85个文件约287MB其中9个cs源码、2个onnx模型、20个dll运行库、3个exe等覆盖源码、配置与运行依赖便于二次开发。目前已有152人学习/下载。通过该资源可掌握C#调用ONNX模型的完整流程、图像预处理与后处理细节以及GPU推理环境配置思路适合具备基础C#和深度学习知识的开发者快速上手语义分割部署。1. C# 读 Unet 的 onnx 做 GPU 推理比你想的轻量C# 读取 Unet 语义分割转化出来的 onnx 模型再在 GPU 上做图片推理这条链路很多人一听就觉得要写 CUDA 算子、要自己管理显存实际上一个 NuGet 包就能解决。我做过一个 C# 上位机里的缺陷检测模块模型是 PyTorch 训练的 Unet转成 onnx 后交给 OnnxRuntime 跑512×512 输入在笔记本的 RTX 显卡上单次推理稳定在 10ms 以内而同一台机器用 CPU 跑要 50ms 上下。这篇笔记会把模型导出、C# 预处理、GPU 会话创建、输出 mask 解析和常见翻车点一次讲完。适合两类人一类是 C# 上位机工程师想把语义分割模型集成进现有系统另一类是算法工程师想绕过 Python 服务直接给 C# 客户端提供推理能力。2. Unet 转 onnx 的前置工作输入输出对齐与导出验证2.1 导出前先定两件事动态轴和归一化PyTorch 转 onnx 看起来是一行torch.onnx.export的事但实际决定 C# 端写起来顺不顺手的是导出时怎么处理动态轴和图像归一化。先说动态轴。Unet 的输入张量通常是[N, C, H, W]N 是 batchC 是通道数H 和 W 是图像高宽。导出时如果把四个轴全写死C# 端就得把每张图都 resize 到完全一致的尺寸跑起来很死板如果全部放开成动态C# 端要处理各种 -1 维度还容易出现 Resize 算子兼容问题。我的建议是 batch 固定为 1H 和 W 放开为动态这样既能切不同分辨率又不必处理 batch 维度的额外逻辑。归一化的位置更要提前定好。Unet 训练时通常会对输入减均值、除方差比如 ImageNet 统计量mean[0.485, 0.456, 0.406]、std[0.229, 0.224, 0.225]。这个操作放在 Python 侧、放在 onnx 模型里、放在 C# 侧效果都一样但工程成本差别很大。我一般会把归一化直接揉进模型也就是在导出前给 Unet 套一层 Normalize 预处理导出后 C# 端只做 resize 和通道转换完全不用关心 mean/std。这样做的最大好处是杜绝“训练用 RGB、推理用 BGR”或“归一化参数抄错”这类低级错误因为归一化的尺度已经被固化进模型权重了。import torch import torch.nn as nn class UnetWithNormalize(nn.Module): def __init__(self, unet): super().__init__() self.unet unet self.mean torch.tensor([0.485, 0.456, 0.406]).view(1, 3, 1, 1) self.std torch.tensor([0.229, 0.224, 0.225]).view(1, 3, 1, 1) def forward(self, x): # 假设输入 x 是 0~255 的 RGB 图像 x x / 255.0 x (x - self.mean) / self.std return self.unet(x)导出时代码要注意三点模型必须切到 eval 模式BatchNorm 才能折叠成推理用的 scale 和 bias用torch.no_grad()包住导出过程opset 至少给到 12因为 Unet 里的上采样 Resize 算子在低版本 opset 下行为差异很大C# 端同样一个模型在低 opset 下跑出来的 mask 可能整体偏移半个像素。dynamic_axes 里把高宽映射成可读的名字C# 端之后查输入输出信息时就不会只看到一串数字。model UnetWithNormalize(unet).eval() dummy torch.randn(1, 3, 512, 512, dtypetorch.float32) with torch.no_grad(): torch.onnx.export( model, dummy, unet_image.onnx, input_names[image], output_names[mask], dynamic_axes{ image: {0: batch, 2: height, 3: width}, mask: {0: batch, 2: height, 3: width}, }, opset_version12, do_constant_foldingTrue, )这段代码里input_names和output_names直接决定了 C# 端绑定时要写的字符串建议起短一点、可读性好一点的名字。do_constant_foldingTrue会把 BN、固定 shape 的卷积等子图提前折叠成常量导出的文件会更小C# 端加载也更快。如果模型里还有 Dropout导出前要记得把 Dropout 也切到 eval否则随机失活会被当成训练行为保留下来C# 端每次推理结果都不一样。2.2 尺寸策略为什么固定 512 比动态尺寸更省心Unet 的结构里包含多次下采样和上采样常见的 4 次 maxpool 会让特征图从 512 降到 32。这类模型对输入尺寸有隐性要求高和宽最好是 2 的幂退一步也必须是 16 的倍数否则在跳跃连接做 concat 时不同分支的特征图尺寸对不上导出时不会报错但推理时会在 C# 端抛出 shape mismatch 的异常。我见过有人在 C# 里喂入 500×500 的图模型前半段跑得好好的到第一次 concat 就崩原因就是 500 不能被 16 整除。如果业务场景就是固定分辨率我建议直接把 dynamic_axes 去掉H、W 写成 512。这样 C# 端的预处理不用读模型的动态 shape也不用写任何自适应逻辑代码量最小。代价是换分辨率必须重新导出模型。如果确实要支持多分辨率dynamic 模式里也尽量只使用 16 的倍数比如 512、736、960不要用任意值。另一个容易被忽略的点是 Unet 的输出尺寸和输入不一定完全一样取决于上采样层的对齐方式导出后最好在 Python 侧打一行日志确认mask.shape的高宽确实等于输入高宽。2.3 导出后先用 onnxruntime 验证一轮导出完成后不要直接跳到 C#先在 Python 环境里用 onnxruntime 跑一次推理和 PyTorch 原模型的输出做对比。这一步能过滤掉大量“看起来导出了、实际算子不兼容”的问题否则出了问题要跨语言排查定位成本翻倍。验证脚本很简单先把 onnx 模型的输入信息打出来确认名字、类型和 shape再喂一帧随机数据看输出能不能跑通。import numpy as np import onnxruntime as ort sess ort.InferenceSession( unet_image.onnx, providers[CUDAExecutionProvider, CPUExecutionProvider], ) for inp in sess.get_inputs(): print(inp.name, inp.shape, inp.type) for out in sess.get_outputs(): print(out.name, out.shape, out.type) x np.random.randn(1, 3, 512, 512).astype(np.float32) mask sess.run([mask], {image: x})[0] print(mask.shape, mask.min(), mask.max())如果这一步能跑通并且mask的 min/max 不是 NaN再拿一张真实图片分别用 PyTorch 和 onnxruntime 推理比较两张 mask 的像素级差异。语义分割模型输出的是逐像素 logits两者误差在 1e-5 量级以内是正常的如果出现整块区域不一致大概率是 Resize 对齐模式或归一化位置的问题。OnnxRuntime 的 providers 列表里把 CUDA 写在前面是为了在这一步就顺带确认 GPU 环境可用C# 端就不用再排查环境了。3. C# 侧的图像预处理缩放、归一化与 NCHW 排布3.1 用 ImageSharp 完成缩放与通道转换C# 端读图最常见的坑是选错图像库。System.Drawing.Common 在非 Windows 平台上有兼容问题而且对大批量读图的性能一般我习惯用 SixLabors.ImageSharpNuGet 直接装跨平台、API 顺手。读图时要注意默认加载的像素顺序ImageSharp 的Rgba32是 R、G、B、A 四个通道而很多 Unet 训练脚本用 OpenCV 的cv2.imread读出来是 BGR。如果训练侧没做特殊处理C# 端必须把 R 和 B 对调否则语义分割结果会把红蓝通道弄反在视觉上表现为颜色错乱、mask 边缘异常。using SixLabors.ImageSharp; using SixLabors.ImageSharp.PixelFormats; using SixLabors.ImageSharp.Processing; using var image Image.LoadRgba32(imagePath); image.Mutate(ctx { ctx.Resize(512, 512, KnownResamplers.Bilinear); }); byte[] rgbPixels new byte[512 * 512 * 3]; image.ProcessPixelRows(accessor { for (int y 0; y accessor.Height; y) { var row accessor.GetRowSpan(y); for (int x 0; x row.Length; x) { int idx (y * 512 x) * 3; rgbPixels[idx 0] row[x].R; rgbPixels[idx 1] row[x].G; rgbPixels[idx 2] row[x].B; } } });KnownResamplers.Bilinear要和训练时的 resize 方式保持一致大多数分割模型训练时用的是双线性插值如果训练用了 cubic这里也要换成KnownResamplers.Cubic。很多分割效果不如预期的案例根子不在模型而在推理时 resize 算法和训练时不一致区域边界会差一到两个像素。注意这里我保留了 RGB 顺序如果训练侧是 BGR把row[x].R和row[x].B互换即可不要同时改两处否则又是一次隐蔽的翻车。3.2 把图像数据填成模型要的 NCHW 张量onnx 模型期望的布局是 NCHW也就是先放通道、再放高、再放宽。很多第一次写 C# 推理的人直接按图像的行列扫描顺序把像素填进一维数组结果模型输出一团糟就是因为没有按通道跨度写入。对于[1, 3, 512, 512]的张量第 0 个通道的平面偏移是0 * 512 * 512第 1 个通道是1 * 512 * 512第 2 个通道是2 * 512 * 512。填数时外层循环走通道内层循环走像素位置。我在前一步已经把归一化做进模型了所以 C# 端只需要把像素从 0~255 的 byte 转成 0.0~1.0 的 float不需要再减均值。这一步用最朴素的 for 循环即可容易读也容易对。如果追求速度可以用Vectorfloat做 SIMD 批量转换但 512×512×3 的数据量在 GPU 推理链路里占比不大先把逻辑写对更重要。float[] inputTensor new float[1 * 3 * 512 * 512]; for (int c 0; c 3; c) { int channelOffset c * 512 * 512; for (int i 0; i 512 * 512; i) { inputTensor[channelOffset i] rgbPixels[i * 3 c] / 255.0f; } }这段代码把 R、G、B 三个通道分别填入三个平面。如果模型输入名是image之后绑定张量时就拿这个 float 数组去创建OrtValue。这里有个小细节如果用上一步保留的 BGR 顺序那么这里的c通道对应的颜色顺序也要同步调整不要只在读图时对调 R/B后面又按 RGB 填入。建议把通道顺序写成一个常量并在代码注释里标明当前是 RGB 还是 BGR方便三个月后的自己回来排查。3.3 输入参数从模型元数据里读而不是写死很多 C# 示例代码把输入名和 shape 直接写成字符串和常量模型稍微改动就得改代码。更稳妥的做法是在创建会话后从InferenceSession的输入元数据里读取输入名、类型和 shape然后动态分配张量。这样即使模型从 512 换成 768C# 端也不用重新编译。var inputMeta session.InputMetadata[image]; Console.WriteLine($name{inputMeta.Name}, shape{string.Join(,, inputMeta.Shape)}, type{inputMeta.ElementDataType}); int batch 1; int channels inputMeta.Shape[1]; // 通常为 3 int height inputMeta.Shape[2]; // 可能是 -1动态轴 int width inputMeta.Shape[3]; // 可能是 -1如果 shape 里出现 -1说明该维度是动态的C# 端要自己决定实际值。比如高度和宽度是 -1就以预处理后的实际尺寸为准batch 是 -1就按当前要推理的图片数填 1。我建议把channels和height、width读取出来后统一存到一个配置类里后续创建张量、后处理、打印日志都用这个配置类不要散落在各处。这样做的额外好处是换模型时只要改模型文件路径C# 端的输入输出适配逻辑基本不用动。4. OnnxRuntime GPU 会话从模型加载到第一张 mask4.1 区分 onnx 与 onnxruntime再选对 NuGet 包onnx 是一种模型文件格式onnxruntime 是微软的推理引擎这两个概念经常被混用。C# 端不直接解析 onnx 文件而是加载 onnx 模型交给 onnxruntime 去执行。NuGet 上要装的是Microsoft.ML.OnnxRuntime.Gpu不是普通的Microsoft.ML.OnnxRuntime。CPU 包和 GPU 包二选一两个都装会出现 native 库冲突运行时表现是莫名其妙的内存访问异常或 provider 加载失败。dotnet add package Microsoft.ML.OnnxRuntime.Gpu装 GPU 包不等于一定能用 GPU。onnxruntime 的 CUDA 执行提供程序依赖系统里的 CUDA runtime 和 cuDNN版本不匹配时最常见的错误是Failed to find CUDA provider。我的建议是安装前先到 NuGet 页面确认这个 OnnxRuntime 版本对应的 CUDA 主版本再去机器上检查nvidia-smi输出的 CUDA 版本和 cuDNN 版本。GPU 驱动版本可以比 CUDA runtime 新但 onnxruntime 要求的 CUDA 主版本不能错11.x 和 12.x 不能混装。4.2 创建 CUDA 会话并绑定输入输出新版 OnnxRuntime 的 C# API 里加载模型的标准流程是创建OrtEnv、配置SessionOptions、再创建InferenceSession。AppendExecutionProvider_CUDA(0)里的 0 是 GPU 设备序号多卡机器上要按实际情况改。我建议保留 CPU 执行提供程序作为 fallback这样 CUDA 初始化失败时至少能看出是环境问题还是模型问题。using Microsoft.ML.OnnxRuntime; using Microsoft.ML.OnnxRuntime.Tensors; using var env new OrtEnv(OrtLoggingLevel.ORT_LOGGING_LEVEL_WARNING); using var options new SessionOptions(); options.AppendExecutionProvider_CUDA(0); options.AppendExecutionProvider_CPU(); using var session new InferenceSession(unet_image.onnx, options, env);如果你用的 NuGet 版本里InferenceSession构造函数不接受OrtEnv参数直接去掉第三个参数即可AppendExecutionProvider_CUDA的语义不变。OrtLoggingLevel.ORT_LOGGING_LEVEL_WARNING表示只输出警告以上日志排查问题时可以临时改成ORT_LOGGING_LEVEL_VERBOSE能看到每个算子的执行设备确认模型确实跑在 CUDA 上而不是静默落到 CPU。创建输入张量时把预处理好的float[] inputTensor和 shape 一起交给OrtValue.CreateTensorValueFromMemory然后以字典形式传给session.Run。输出端拿到的ListOrtValue里只有一个元素对应导出时的mask输出。using var inputValue OrtValue.CreateTensorValueFromMemory( OrtMemoryInfo.DefaultInstance, inputTensor, new long[] { 1, 3, height, width }); var inputs new Dictionarystring, OrtValue { { image, inputValue } }; using var outputs session.Run(inputs); var mask outputs[0].GetTensorDataAsSpanfloat(); Console.WriteLine($mask length{mask.Length}, min{mask.ToArray().Min()}, max{mask.ToArray().Max()});OrtValue和Run的返回结果都要用using释放尤其是 GPU 推理场景OrtValue背后可能持有 GPU 内存不释放会在长时间运行后把显存吃满。inputs字典的 key 必须和导出时input_names完全一致差一个字母都会在运行时抛输入绑定错误。输出是一个一维的Spanfloat需要按照输出张量的 shape 重新解释成四维才能做像素级后处理。4.3 从 logits 到 mask解析输出的四种维度顺序Unet 语义分割的输出形状一般是[1, numClasses, H, W]numClasses是类别数。以一个二分类缺陷分割模型为例输出是[1, 2, 512, 512]每个像素位置有两个值分别代表背景和前景的置信度。取结果时先算通道数再对每个像素位置做 argmax取最大值所在通道作为该像素的类别。如果直接拿span[0]当第一帧图像会发现图像是花的因为你读到的其实是所有通道交织后的 logits 流。int numClasses maskShape[1]; int maskHeight maskShape[2]; int maskWidth maskShape[3]; byte[] classMask new byte[maskHeight * maskWidth]; for (int i 0; i maskHeight * maskWidth; i) { int bestClass 0; float bestScore float.MinValue; for (int c 0; c numClasses; c) { float score mask[c * maskHeight * maskWidth i]; if (score bestScore) { bestScore score; bestClass c; } } classMask[i] (byte)bestClass; }这里要特别注意 index 的计算mask[c * maskHeight * maskWidth i]对应的是 CHW 布局下第 c 个通道、第 i 个像素位置。如果模型输出的布局实际是 NHWC也就是[1, H, W, C]那么 index 要换成i * numClasses c。判断布局最简单的方法是打印输出 shape 并对照导出时的output_names和模型结构不要在 C# 里猜。语义分割和实例分割的区别也在这里体现语义分割只区分像素属于哪个类别同一个类别里的不同目标是合并的如果你需要区分两个单独的缺陷焊点那要上实例分割模型后处理逻辑完全不同。提示输出张量的 shape 可以在session.OutputMetadata里读取拿到后先打印一遍确认 numClasses、H、W 都符合预期再写死循环逻辑防止模型换版本时静默出错。5. GPU 推理的 5 个常见翻车点与排查思路5.1 会话创建报 no provider named CUDA现象程序抛异常提示找不到 CUDA execution provider或者模型加载后所有算子都跑在 CPU 上GPU 占用率为 0。原因通常有三个只装了Microsoft.ML.OnnxRuntimeCPU 包GPU 包版本和系统 CUDA/cuDNN 不匹配SessionOptions里 CUDA provider 注册失败但没有被显式抛出。解决方法是先写一小段独立代码打印当前可用的 provider 列表。foreach (var provider in OrtEnv.GetAvailableProviders()) { Console.WriteLine(provider); }如果列表里没有 CUDA就不用再排查业务逻辑了先回到环境本身。检查 NuGet 包是否确实是Microsoft.ML.OnnxRuntime.Gpu再查 CUDA 和 cuDNN 版本是否满足该包要求。有些机器装过多个 CUDA 版本PATH 环境变量指向了旧版即使nvidia-smi显示的新版本可用onnxruntime 也可能去加载旧版 cudart64_*.dll导致加载失败。这种情况可以在运行程序前打印CUDA_PATH环境变量确认指向正确版本。5.2 mask 全黑或全零现象模型跑通了输出张量长度也对但转出来的 classMask 全是 0或者只有零星几个点。最常见的原因是输入图像和训练时的预处理不一致。如果导出时没有把归一化揉进模型C# 端又忘了减均值除方差模型输入的分布完全错位logits 会整体偏向某一类argmax 之后自然全是背景。第二个常见原因是通道顺序颠倒RGB 的训练数据被以 BGR 喂入模型学到的颜色语义全部失效。排查建议是先打印原始输出的 min 和 max。如果输出值都在几十分到上百分说明模型在工作问题出在 argmax 索引或分类阈值如果输出值集中在 0 附近说明输入分布不对。拿一张训练集里的原图用 C# 预处理后导出成 npy 文件再用 Python 脚本加载并输入 onnx 模型对比结果这样能快速定位是预处理差异还是模型本身的问题。不要直接在 C# 里反复猜跨语言对比一次就能定位。5.3 显存占用只增不减现象程序跑一个晚上任务管理器显示显存占用从 1GB 涨到 6GB最后 CUDA 报 out of memory。原因几乎都是 C# 侧对象没有释放。最常见的两个错误是每次推理都新建InferenceSession以及OrtValue、Run的返回结果没用using释放。创建会话时 onnxruntime 会为模型分配权重显存和算子执行所需的 workspace这个开销很大绝不能放在循环里。正确的做法是把InferenceSession设计成单例程序启动时创建一次整个生命周期复用。每次推理的输入OrtValue和输出ListOrtValue用using包住或者手动Dispose。如果用了自己实现的张量池还要注意复用float[]数组时不要被 onnxruntime 的异步执行引用Run 返回后再还回池子。显存增长是典型的资源泄漏问题用 Nsight 或任务管理器观察是否持续增长比凭感觉判断更可靠。5.4 GPU 没跑满但 CPU 忙现象GPU 利用率在 10% 到 30% 之间波动CPU 反而多核拉满单次推理延迟没比 CPU 快多少。原因在于 onnxruntime 的 GPU 推理不是整条链路都在 GPU 上图像解码、resize、像素格式转换、NCHW 排布这些预处理仍在 CPU 执行而且每个 GPU 算子启动都有固定开销。Unet 里的卷积和 Resize 在 512×512 输入下执行时间很短kernel launch 的耗时占比反而很高小图场景尤其明显。# Linux 下可用 nvidia-smi 看进程占用Windows 下用任务管理器看 CUDA 引擎占用 nvidia-smi --querytimestamp,utilization.gpu,utilization.memory --formatcsv -l 1解决方向有三个。第一是预热程序启动后先用一张假图跑几次推理把 CUDA context 初始化和算子 autotune 的耗时吃掉。第二是加大 batch一次送多张图到 GPU摊薄 kernel launch 开销但这要求导出模型时 batch 维度是动态的。第三是把归一化揉进 onnx 模型减少一次 CPU 批量归一化的遍历。如果还要继续压延迟就得考虑在 GPU 上做 resize本质是写一个自定义 kernel 算子但工程复杂度高通常是 GPU 推理链路已经优化到极限后才考虑的方向。5.5 GPU 与 CPU 推理结果对不上现象同一张图CPU 推理出的 mask 边界很平滑GPU 推理出的边界有几像素抖动甚至个别小区域类别不同。原因不是模型坏了而是 GPU 上的 cuDNN 卷积实现会使用 TF32 或其他非确定性算法浮点累加顺序也和 CPU 不同导致 logits 存在微小差异。语义分割是逐像素分类边界像素恰好落在阈值附近时argmax 结果就可能翻转。处理方式不是追求完全一致而是设定可接受的误差范围。我一般用 Dice 系数和 mIoU 做回归验证CPU 结果作为参考标准GPU 结果和 CPU 结果的 Dice 在 0.99 以上就认为可接受。如果项目要求严格复现可以在SessionOptions里尝试关闭 TF32但要意识到这会牺牲一部分 GPU 算力。更重要的是把模型版本、CPU 基线和允许误差记录在案模型一升级就重跑一遍对比防止某个算子实现变化带来肉眼不可见的精度回退。6. 把推理封装成服务会话复用、预热与回归验证6.1 会话复用与多线程并发InferenceSession 的Run是线程安全的但OrtValue不是。多线程推理时每个任务创建自己的输入输出张量共享同一个InferenceSession不要让多个线程同时往一个OrtValue里写数据。我在 C# 上位机里的做法是把 session 包在一个单例服务类里对外暴露Taskbyte[] SegmentAsync(byte[] image)内部每个调用独立创建OrtValue用using保证释放。这样既能并发处理多路图片又不会把 GPU 资源泄漏到上层业务里。6.2 用预热把 CUDA 初始化挪到启动阶段第一次调用 GPU 推理时CUDA context 创建、cuDNN 算法选择、算子 autotune 都可能触发几百毫秒到几秒的延迟。如果这个延迟发生在用户点击“开始检测”的瞬间体验就是界面卡死。程序启动后马上用一张固定尺寸的假图跑 3 到 5 次推理预热完成后真正的业务推理就稳定在低延迟区间。预热还有一个好处显存分配、workspace 申请都在预热阶段完成运行期的显存占用曲线会更平稳。6.3 一个长期有效的验证习惯我会在模型目录里放一个baseline文件夹存 10 张典型图片和它们的标准语义分割结果任何一次模型转换、驱动升级、OnnxRuntime 版本升级后都要重新跑一遍对比 Dice。这个习惯救过我很多次有一次仅升级了显卡驱动GPU 推理结果的边界就整体偏移了半个像素如果不对比基线根本发现不了。现在我的所有 GPU 推理项目都保留了这套验证脚本每次改动前先看基线改动后立刻看差异。C# 侧读 Unet 的 onnx 做图片推理难点从来不在写第一遍代码而在后续环境变化时守住精度和延迟的底线希望这篇笔记能帮你在调试时少走几段弯路。本文还有配套的精品资源点击获取