简介这是一套面向C#开发者的U2Net抠图完整源码基于U-Net对称编码器-解码器结构实现像素级前景分割解决在.NET环境中进行深度学习自动抠图的难题。适用于电商商品背景移除、人像分割、图像后期处理等需要精确提取前景对象的场景尤其方便已有C#基础但尚未接触深度学习工程的开发者入门。压缩包为RAR格式共81个文件总大小约338.9MB内含Visual Studio解决方案与C#工程源码、三个预训练ONNX分割模型以及ONNX Runtime、OpenCvSharp等运行依赖库还包含资源文件、配置文件、缓存与PDB调试符号等项目结构清晰便于直接编译与研究。目前已有1005人学习下载。借助这套源码开发者可完整走通模型加载、图像预处理、前向推理、结果后处理等关键环节理解U-Net在C#中的应用方式也可作为在.NET生态中集成ONNX模型的实战参考具有较高的直接复用价值。1. C# 做 U2Net 抠图的落地价值模型小事大重点在工程U2Net 在显著目标检测里算是“小而能打”的代表模型不大却靠多尺度感受野的设计边缘抓得比很多大模型还稳。把它的 PyTorch 权重导出成 ONNX再用 C# 通过 ONNX Runtime 加载推理就能在上位机、WinForms、WPF 这类 C# 工程里直接完成抠图。这套源码解决的核心问题是把 AI 抠图从一个孤立 Python 脚本变成一个能被 C# 直接调用的组件进而支持批量处理、界面集成、后台服务几种用法。它适合两类人一类是新手想完整跑通“模型转换 → C# 推理 → 合成输出”这条链路另一类是做工业视觉或桌面工具、想把背景移除塞进现有业务流的从业者。资源本身并不是什么了不起的大模型真正值钱的部分在模型落地的工程细节上。2. U2Net 模型原理与 C# 落地的技术选型先搞懂再动手2.1 RSU 结构为什么适合抠图U2Net 的定义来自 2020 年的论文《U2-Net: Going Deeper with Nested U-Structure for Salient Object Detection》核心组件是 RSUReSidual U-block。它不是普通卷积堆叠而是把一个 U 型结构嵌进残差块里内部再分成多个尺度做卷积。这样设计的效果很直接同一个卷积块既能捕捉全局语义哪个物体更突出又能保留边缘细节物体与背景的边界在哪里而且不依赖 ImageNet 预训练权重从零训练也能收敛得不错。抠图任务本质上是像素级二分类前景与背景的划分比目标检测的标注框精细得多。U2Net 输出的单通道显著性图经过 Sigmoid 之后就是 0 到 1 的概率图这个概率图可以直接当作抠图的 alpha 通道。U2Net 官方权重在 DUTS-TR 和 DUTS-TE 这类显著性数据集上做过大量训练对人物、商品、常见自然场景都有比较稳的效果。模型输入一般是 320×320 的 RGB 图输出形状是 1×1×320×320整个模型体量在 170MB 左右CPU 推理一张图只要一二百毫秒完全能接受。还有一个容易被忽略的点U2Net 的中间层有多尺度输出论文里提供了融合作图方法但默认的 CD 版本会按深度监督输出六个侧输出side output和最终融合输出。在抠图场景里我们只取最终融合输出即可没必要把全部输出都接出来否则 C# 侧后处理会多绕一层。2.2 三条落地路径对比为什么最后选 ONNX Runtime把一个 PyTorch 模型集成到 C# 里常见路径有三条。第一条是 C# 里用子进程调 Python 推理脚本优点是改模型方便缺点是每个抠图请求都要拉起 Python 进程冷启动慢不说部署时还得给客户机装 Python、PyTorch这对上位机项目基本是灾难。第二条是拿 P/Invoke 直接调 C 的推理实现性能上限最高但工作量也最高需要自己接内存和线程模型适合有专门算法能力的大团队。第三条是把 PyTorch 权重导出成 ONNX再用 ONNX Runtime 的托管接口跑推理这也是我在源码里看到的落地方式。路线集成复杂度部署体积CPU 推理性能适合场景C# 子进程调 Python低大需带 Python 环境差进程冷启动慢快速验证P/Invoke 调 C高中最强性能要求极高的产品ONNX Runtime中小一个 DLL 搞定中上上位机、桌面工具首选ONNX Runtime 本身是跨平台原生库Microsoft.ML.OnnxRuntime 这个 NuGet 包会把原生 DLL 一起带进来CPU 版本大小只有十几兆复制到目标机器就能跑。它还支持 GPU 扩展。对于大多数桌面工具场景CPU 推理已经够用320×320 的输入在普通 i5 上耗时大约 120ms 到 200ms这个延迟放在 UI 交互里不违和。2.3 源码包里典型的结构与入手顺序拆这套源码时建议按“模型 → 引擎 → 界面”的顺序看。典型的 C# U2Net 源码包布局大致如下U2NetMatting/ ├─ Models/ │ ├─ u2net.onnx # 导出的 ONNX 模型也可能未随包附带 │ └─ export_u2net.py # PyTorch 导出脚本 ├─ src/ │ ├─ U2NetEngine/ # 前处理、推理、后处理封装类 │ ├─ U2NetMatting.sln │ └─ U2NetMatting.WinForms/ # WinForms 演示工程 └─ docs/ └─ 使用说明.md先看 U2NetEngine 里的类再跑 WinForms 演示工程。如果 Models 里已经有 u2net.onnx可以跳过第 3 章的导出步骤直接看 C# 实现如果没有就必须先按第 3 章把模型转出来否则后面所有推理代码都没有东西可喂。这是一个很现实的差异不同渠道发的资源包内容不完全一样建议先打开 Models 目录确认一下再决定从哪章开始。3. 环境准备与模型转换从 PyTorch 权重到 ONNX 格式3.1 环境清单与版本组合C# 侧要跑 U2Net前提是手里有一个能用的 ONNX 模型。如果资源包里没有就得自己从 PyTorch 权重转。转换本身不难但版本组合有讲究。Python 侧我建议用 3.8 以上版本PyTorch 用 1.13 或 2.x 都行onnx 用 1.13 以上onnxruntime 用 1.15 以上。C# 侧 .NET 6 或 .NET 8 都可以NuGet 包固定用 Microsoft.ML.OnnxRuntime 1.17 左右即可。组件推荐版本说明Python3.8转换脚本不依赖高版本特性PyTorch1.13 / 2.x导出用 CPU 模式足够onnx1.13低版本对 dynamic_axes 支持不够好onnxruntime1.15用于导出后验证.NET6.0 / 8.0WinForms 用 8.0 更省心Microsoft.ML.OnnxRuntime1.17CPU 版即可GPU 版按需换这里强调一点导出 ONNX 不需要 GPUCPU 就能完成电脑上没有 CUDA 环境也不用慌。真正需要 GPU 的只在 C# 推理阶段而且是可选项没有显卡就直接走 CPUExecutionProvider。3.2 把 U2Net 的 pth 权重导出为 ONNX假设你已经拿到了u2net.pth权重和原版model.py里面定义了 U2NET 类导出脚本如下import torch import torch.onnx from model import U2NET # 原开源仓库的 model.py类名就是 U2NET checkpoint torch.load(u2net.pth, map_locationcpu) model U2NET(3, 1) model.load_state_dict(checkpoint) model.eval() dummy torch.randn(1, 3, 320, 320, devicecpu) torch.onnx.export( model, dummy, u2net.onnx, input_names[input], output_names[output], opset_version11, dynamic_axes{input: {0: batch}, output: {0: batch}} ) print(导出完成)这段代码的关键点在三个地方。第一model.eval()必须调用否则推理时会跑出训练模式特有的 Dropout 或 BatchNorm 统计预测结果会偏。第二input_names和output_names是自定义的C# 侧创建 NamedOnnxValue 时用的名字必须和这里完全一致我习惯统一用input和output后面 C# 代码也按这个名字来。第三dynamic_axes把 batch 维设成动态方便以后批量推理如果只做单张抠图不用动态轴也可以但动态轴不会带来额外损失建议保留。转换完成后检查一下生成的u2net.onnx体积。官方权重导出来的文件通常在 170MB 左右如果只有几十 MB大概率是模型结构加载不完整或者权重没写入干净。3.3 在 Python 侧先验证 ONNX 输出不要急着切到 C#先花两分钟用 onnxruntime 验证一下模型导出的结果是油是盐。这一步能省掉后面非常多排查时间import onnxruntime as ort import numpy as np from PIL import Image sess ort.InferenceSession(u2net.onnx, providers[CPUExecutionProvider]) img Image.open(test.jpg).resize((320, 320)) arr np.array(img, dtypenp.float32) / 255.0 mean np.array([0.485, 0.456, 0.406], dtypenp.float32) std np.array([0.229, 0.224, 0.225], dtypenp.float32) arr (arr - mean) / std arr arr.transpose(2, 0, 1)[None, ...].astype(np.float32) result sess.run(None, {input: arr})[0] print(result.shape, result.min(), result.max())如果输出形状是(1, 1, 320, 320)并且result.max()在 0 到几十之间不等说明模型输出的是未经过 Sigmoid 的 logits这是正常的如果输出已经全部落在 0~1 区间说明导出时模型内部已经做了 Sigmoid。这个差异会直接影响 C# 后处理是否要做归一化务必记录下 min 和 max。若 min 和 max 是 0.0 和 1.0C# 侧拿到直接乘 255 写像素即可若输出范围是负数和正数C# 侧就得先做 Sigmoid 再映射。验证通过后ONNX 文件就正式可用了。4. 核心实现加载模型、前处理、推理与后处理全流程代码4.1 创建 WinForms 项目与 NuGet 依赖用命令行初始化一个 WinForms 项目再把依赖装齐dotnet new winforms -n U2NetMatting cd U2NetMatting dotnet add package Microsoft.ML.OnnxRuntime dotnet add package System.Drawing.Common这里有个细节System.Drawing.Common 在 .NET 8 里被标记为仅支持 Windows但这套源码跑的是 WinForms/WPF本身就不跨平台这个警告可以直接忽略。如果你的目标环境是 Linux 服务器做后台抠图服务把 System.Drawing.Common 换成 ImageSharp 即可前处理逻辑不变只是像素读写 API 要改。依赖装完后把u2net.onnx拷到项目根目录下的 Models 文件夹并在 csproj 里把它设为“复制到输出目录”ItemGroup None IncludeModels\u2net.onnx CopyToOutputDirectoryPreserveNewest / /ItemGroup注意这个步骤常被忽略。很多人代码写得没问题运行时却报找不到模型文件就是因为忘了在项目文件里声明复制行为。模型文件属于 Content 或 None 类型默认不随编译输出复制。4.2 前处理缩放、归一化与 DenseTensor 填充前处理是整个 C# 端最容易出错的部分像素通道顺序、均值方差、张量布局都堆在这里。直接看代码using Microsoft.ML.OnnxRuntime.Tensors; using System.Drawing; using System.Drawing.Imaging; using System.Runtime.InteropServices; public static class U2NetPreprocess { private const int InputSize 320; private static readonly float[] Mean { 0.485f, 0.456f, 0.406f }; private static readonly float[] Std { 0.229f, 0.224f, 0.225f }; public static DenseTensorfloat Run(Bitmap src) { using var resized new Bitmap(src, InputSize, InputSize); var rect new Rectangle(0, 0, InputSize, InputSize); var data resized.LockBits(rect, ImageLockMode.ReadOnly, PixelFormat.Format24bppRgb); int stride data.Stride; int total stride * InputSize; byte[] raw new byte[total]; Marshal.Copy(data.Scan0, raw, 0, total); resized.UnlockBits(data); var tensor new DenseTensorfloat(new[] { 1, 3, InputSize, InputSize }); for (int y 0; y InputSize; y) { for (int x 0; x InputSize; x) { int pixelIdx y * stride x * 3; float b raw[pixelIdx]; float g raw[pixelIdx 1]; float r raw[pixelIdx 2]; tensor[0, 0, y, x] (r / 255f - Mean[0]) / Std[0]; tensor[0, 1, y, x] (g / 255f - Mean[1]) / Std[1]; tensor[0, 2, y, x] (b / 255f - Mean[2]) / Std[2]; } } return tensor; } }这段代码有几个地方要仔细说。LockBits 之后Bitmaps 的像素内存布局是 BGR 而不是 RGB所以先取 b再取 g最后取 r 作为蓝色分量的填充不能直接按 RGB 顺序读。归一化用 ImageNet 的 mean/std均值是 0.485、0.456、0.406方差是 0.229、0.224、0.225顺序对应 RGB 通道这也是 U2Net 官方训练时的参数。DenseTensor的维度顺序是 NCHW所以先写 batch 维 0再写通道维最后写高和宽。步长Stride不一定等于宽度乘 3因为 Bitmap 行数据会按 4 字节对齐遍历时必须用 Stride 做行跳转不能用width * 3不然图像会斜切错位。4.3 推理与原图合成把模型输出变成带透明通道的图片模型加载和推理封装在引擎类里核心代码如下using Microsoft.ML.OnnxRuntime; using Microsoft.ML.OnnxRuntime.Tensors; using System.Drawing; using System.Drawing.Imaging; public class U2NetEngine : IDisposable { private readonly InferenceSession _session; private const int InputSize 320; public U2NetEngine(string modelPath) { var options new SessionOptions(); // 有 CUDA 环境时打开下面这行没有就保持 CPU 推理 // options.AppendExecutionProvider_CUDA(0); _session new InferenceSession(modelPath, options); } public Bitmap Matting(Bitmap src) { float[,] mask RunMask(src); using var maskBmp MaskToBitmap(mask); // 320x320 灰度 using var resizedMask new Bitmap(maskBmp, src.Width, src.Height); return Composite(src, resizedMask); } private float[,] RunMask(Bitmap src) { var input U2NetPreprocess.Run(src); var feeds new ListNamedOnnxValue { NamedOnnxValue.CreateFromTensor(input, input) }; using var outputs _session.Run(feeds); var tensor outputs.First().AsTensorfloat(); var mask new float[InputSize, InputSize]; for (int y 0; y InputSize; y) for (int x 0; x InputSize; x) mask[y, x] tensor[0, 0, y, x]; return mask; } private static Bitmap MaskToBitmap(float[,] mask) { var bmp new Bitmap(InputSize, InputSize, PixelFormat.Format32bppArgb); var rect new Rectangle(0, 0, InputSize, InputSize); var data bmp.LockBits(rect, ImageLockMode.WriteOnly, PixelFormat.Format32bppArgb); byte[] pixels new byte[data.Stride * InputSize]; for (int y 0; y InputSize; y) { for (int x 0; x InputSize; x) { float v mask[y, x]; // 如果导出时未做 Sigmoid输出可能是负数或大于 1需要先压缩到 0~1 v 1f / (1f MathF.Exp(-v)); byte gray (byte)(Math.Clamp(v, 0f, 1f) * 255f); int idx y * data.Stride x * 4; pixels[idx] gray; // B pixels[idx 1] gray; // G pixels[idx 2] gray; // R pixels[idx 3] 255; // A } } Marshal.Copy(pixels, 0, data.Scan0, pixels.Length); bmp.UnlockBits(data); return bmp; } private static unsafe Bitmap Composite(Bitmap src, Bitmap mask) { int w src.Width, h src.Height; var dst new Bitmap(w, h, PixelFormat.Format32bppArgb); var rect new Rectangle(0, 0, w, h); var srcData src.LockBits(rect, ImageLockMode.ReadOnly, PixelFormat.Format24bppRgb); var maskData mask.LockBits(rect, ImageLockMode.ReadOnly, PixelFormat.Format32bppArgb); var dstData dst.LockBits(rect, ImageLockMode.WriteOnly, PixelFormat.Format32bppArgb); for (int y 0; y h; y) { byte* ps (byte*)srcData.Scan0 y * srcData.Stride; byte* pm (byte*)maskData.Scan0 y * maskData.Stride; byte* pd (byte*)dstData.Scan0 y * dstData.Stride; for (int x 0; x w; x) { byte alpha pm[x * 4]; // 灰度值同时放在 B 通道 pd[x * 4] ps[x * 3]; // B pd[x * 4 1] ps[x * 3 1]; // G pd[x * 4 2] ps[x * 3 2]; // R pd[x * 4 3] alpha; // A } } src.UnlockBits(srcData); mask.UnlockBits(maskData); dst.UnlockBits(dstData); return dst; } public void Dispose() _session.Dispose(); }这段代码的流程是先做前处理张量再调用_session.Run拿到模型输出把[1,1,320,320]的张量转成二维 mask随后把 mask 转成灰度 Bitmap放大到原图尺寸最后逐像素把灰度值填到输出图的 alpha 通道。由于用了 unsafe 指针需要在 csproj 里打开AllowUnsafeBlockstrue/AllowUnsafeBlocks否则编译不过。运行Matting后返回的是带透明通道的 Bitmap直接 Save 成 PNG 就是透明底的抠图结果。如果想把前景贴到绿幕或白色背景上在 WinForms 窗体里画一个背景色再把这张图 DrawImage 上去就行。这里对无关像素不需要额外处理透明通道会自然盖住背景。5. 避坑指南U2Net 落地时翻过最多的四个坑5.1 抠图结果全黑或全白完全看不到轮廓现象模型跑通了也不报错但保存的 PNG 要么是全黑要么是全白中间没有灰度过渡。原因有两个。第一个最常见导出 ONNX 时模型输出的是 logits不是概率图范围可能在 -3 到 3 之间。C# 侧如果直接把 float 乘以 255 再截断负数全部变 0大于 1 的变 255中间过渡细节全部丢失。第二个是导出脚本里漏了 Sigmoid 层模型接的后续结构不完整。解决在 MaskToBitmap 里对每个像素先做一次 Sigmoid再映射到 0 到 255。表达式就是上一章那段1f / (1f MathF.Exp(-v))。做完后检查最小值和最大值正常情况应该有从 0 到 255 的渐变分布而不是只有两个极值。5.2 输入图像被切斜或拉成条纹状现象抠图结果里原图内容错位边缘出现斜向条纹像隔行扫描一样。原因LockBits 返回的 Stride 和图像宽度不是简单乘 3 的关系。Bitmap 每行数据会按 4 字节对齐比如一幅 319 像素宽的 24 位图每行实际占用的字节数不是 319×3957而是向上对齐到 960。如果遍历像素时用y * width * 3而非y * stride从第二行开始每个像素偏移都是错的图像自然斜掉。解决所有行跳转都严格使用data.Stride。前处理里计算索引用y * stride x * 3后处理里用y * stride x * 4不要走捷径。这个坑初期非常隐蔽因为前几行看不出问题图像越靠下斜得越厉害。5.3 推理时报 Invalid Feed Input Name连模型都跑不起来现象_session.Run(feeds)抛出异常提示找不到某个输入名称。原因导出的 ONNX 输入名和 C# 侧NamedOnnxValue.CreateFromTensor里的名字不一致。PyTorch 导出时如果你没有显式指定input_namesONNX 会自动生成input.1、input.2之类C# 侧用input就会对不上。解决运行时先打印一次模型的输入输出元数据确认真实名字。在初始化 Session 后加一段写日志的代码foreach (var kv in _session.InputMetadata) Console.WriteLine(${kv.Key} - {string.Join(,, kv.Value.Dimensions)});如果输出的是input.1就把代码里的input改成input.1或者重新导出 ONNX 并显式指定input_names。我一般直接改导出脚本让 C# 侧代码保持稳定。5.4 C# 调用原生推理库时崩溃报 access violation c0000005现象程序跑了一段时间后突然闪退Windows 事件日志里能看到 c0000005 内存访问违规常见于批量处理多张图片时。原因ONNX Runtime 本身是原生库托管代码和它在数据竞争上的行为不完全可控。最常见的是多个线程同时调用_session.Run但同时又在多个线程里操作同一个 Bitmap前处理阶段 LockBits 还没释放另一个线程就开始改这个 Bitmap 的像素内存直接被踩坏。这和我们 C 调库崩内存的原因本质上一致只不过异常被抛到了 C# 入口。解决有两种稳妥做法。第一种InferenceSession保持单例允许并发Run但 Bitmap 的读、缩放、LockBits 全部放在方法内部局部变量里严禁外部线程共享同一张图做前处理。第二种在引擎入口加一个SemaphoreSlim(1,1)把整条“前处理 → 推理 → 后处理”链路串行化。桌面工具场景并发量不高第二种最保险。源码里我更推荐把引擎做成单例内部用信号量限定并发数既保住 session 复用又不让原生库陷入数据竞争。6. 进阶技巧把抠图封装成异步服务并自己做效果自检6.1 结合 WinForms 界面做异步处理与并发控制WinForms 里直接在主线程跑推理会卡界面尤其是大图后处理时明显。基本做法是把引擎调用丢到线程池结果回到 UI 线程再贴图private readonly U2NetEngine _engine new(Models/u2net.onnx); private readonly SemaphoreSlim _gate new(1, 1); private async void btnCutout_Click(object sender, EventArgs e) { using var src (Bitmap)pictureBox1.Image.Clone(); Bitmap result null; await _gate.WaitAsync(); try { result await Task.Run(() _engine.Matting(src)); } finally { _gate.Release(); } pictureBox2.Image result; }这里的SemaphoreSlim就是上一章第 5.4 节的保险措施。InferenceSession本身支持并发 Run但 Bitmap 操作和内存复制不保证线程安全串行化后整体吞吐对桌面工具足够。注意克隆原图时使用using避免多个实例共享同一块 GDI 资源。如果你在 WPF 里用这套代码把 System.Drawing 换成 ImageSharp只改前处理和合成两个方法即可引擎结构不用动。6.2 抠图质量自检不要只看一眼“好像还行”抠图效果判断不能靠肉眼扫一遍尤其批处理场景。我常用的简易自检方法是准备一张纯色背景的人物图抠图后分别统计透明区域和保留区域的比例。前景占比是 0.4结果却只有 0.2说明模型把大量前景裁掉了边缘如果大量像素 alpha 值集中在 127 附近说明边界模糊严重需要检查是否忘记做阈值抖动。还可以和 Python 侧结果对比。同一张测试图Python 用 onnxruntime 跑一次C# 跑一次两张 mask 做绝对差平均误差应该小于 0.02。超过这个值就说明某一侧的预处理或后处理有偏差优先检查通道顺序其次是 mean/std 是否写反最后是缩放插值方式。像素级别对不齐大多不是玄学就是这几个环节之一。整套链路我最深的体会是模型本身很成熟但 C# 落地时真正坑人的往往不是模型而是 Bitmap 的像素布局、输入输出命名、normalize 参数一致性这些细节。我最初连着做了三天换了三次图像倾斜修复方案最后发现只是 Stride 用错了。从那以后我每次在新机器上跑这套源码都强制自己先打印输入输出元数据再输出一张 mask 对比 min/max最后才进业务代码。这套流程走完U2Net 抠图基本一次点亮。希望帮到你。本文还有配套的精品资源点击获取