简介这份C# Onnx segment-anything资源以Segment Anything Model为核心提供一键抠图、分割万物的完整工程实现适合已有一定C#基础、希望将深度学习分割模型集成到桌面应用的开发者。压缩包共301个文件包含Visual Studio解决方案、C#工程源码、ONNX模型文件、onnxruntime运行库以及大量dll、xml、txt、cs等依赖与文档包体约610MB目录结构完整可直接加载调试。目前已有3346人学习下载。通过研读源码可以系统掌握ONNX模型的加载与推理流程、图像预处理与分割结果后处理、用户交互界面设计以及NuGet包与原生库的引用方式对希望迁移到其他场景的开发者也提供了完整的二次开发基础便于实现批量抠图、前景替换等扩展功能。1. 用 C# 调 ONNX 版 SAM 做一键抠图为什么这条路值得走最近在做一个桌面图像处理工具甲方提了个看似简单的要求双击一张图自动把前景主体抠出来背景换成透明。传统 GrabCut 对毛发边缘、半透明物体基本翻车语义分割模型又只能识别训练过的类别。后来换成 segment-anythingSAM加 ONNX Runtime 的组合在 C# 里跑通了开箱即用的“分割万物”推理。这张牌打出来效果确实惊艳不管图里是商品、人像还是猫狗给一个点提示就能把目标从背景里干净地摘出来C# 单进程不依赖 Python 环境。这篇就把完整落地方案写出来从模型导出、C# 工程接入到一键抠图的前后处理和踩坑记录适合要在 WinForm/WPF 或上位机里集成抠图能力、又不想背着 Python 环境走的开发者。2. 先懂 SAM 再写代码图像编码器与掩码解码器的分工2.1 SAM 不是魔改 YOLO提示词分割的推理范式很多从目标检测转过来的同学第一反应是去搜“SAM 的 YOLO 版实现”这个方向不对。YOLO 这类检测模型是单次前向直接输出边界框和类别模型内部把“找目标”这个任务固化在权重里。SAM 的思路完全不同它把视觉分割拆成两个阶段先把整张图编码成一个稠密的图像特征image embedding然后任意给定一个提示点、框、掩码乃至文本轻量级的掩码解码器基于这个特征实时生成目标掩码。这就是标题里“分割万物”的含义——不是模型认识了所有类别而是“只要有提示就能分任意对象”。这个推理范式对工程架构影响很大。图像编码器通常是一个 ViTvit_b 大约 90MB 权重vit_h 超过 300MB前向一次耗时占整个推理的九成以上掩码解码器只有几 MB一次前向在 CPU 上约 20ms 左右。所以正确的工程姿势是把图像编码器的输出image_embeddings缓存下来复用换提示词时只重跑解码器。这一点做好了批量抠图速度能上一个台阶后面第 6 章专门讲。还有一个容易忽略的细节SAM 的输入固定是 1024×1024不是 YOLO 习惯的 640×640这一步会影响后续所有坐标换算。2.2 拿到能跑的 ONNX 模型导出流程与文件清单PyTorch 训练好的 SAM 权重没法直接在 C# 里加载要先走一遍 PyTorch 转 ONNX 的流程。Meta 官方在 segment-anything 仓库里提供了scripts/export_onnx_model.py这是最稳妥的导出路线。用第三方魔改脚本前最好先对照官方输出验证一遍不然导出的模型预处理参数经常对不上C# 这边查起来极其折磨。python scripts/export_onnx_model.py \ --checkpoint sam_vit_b_01ec64.pth \ --model-type vit_b \ --output sam_onnx \ --opset 17逻辑说明--output会在sam_onnx目录下生成两个 ONNX 文件——image_encoder.onnx图像编码器和decoder.onnx提示编码器与掩码解码器的合体。--opset 17是为了用较新的算子集导出后兼容性更好如果机器上 onnxruntime 版本偏老降到 15 也可以但不要低于 14。参数说明--model-type vit_b选择最小的 SAM 主干CPU 上单张图编码约 300~500ms精度足够应付商品图和通用主体如果对边缘细节要求极高可以换vit_h速度直接慢四五倍C# 桌面工具通常没必要。--checkpoint指向官方发布的.pth权重下载时注意对应同一型号。导出的两个文件分工如下文件输入张量输出张量image_encoder.onnximage(1,3,1024,1024)image_embeddings(1,256,64,64)decoder.onnximage_embeddings、point_coords、point_labels、mask_input、has_mask_inputsmasks(1,3,256,256)、iou_predictions(1,3)、low_res_masks(1,1,256,256)导出完成后千万别直接丢给 C#先用 Python 端 onnxruntime 做一次 sanity check加载两个 ONNX喂一个中心点提示看输出掩码是否和原模型一致。这一步能过滤掉八成“C# 端跑出来全黑/全白”的隐形问题。检查时重点看输出张量名——不同版本导出的输入输出命名可能有差异比如image有时叫input记下 C# 端要用的确切张量名。3. 在 C# 工程里接入 ONNX Runtime环境配置与最小推理3.1 项目结构与 NuGet 依赖新建一个 .NET 6 或 .NET 8 的 WPF/WinForm 项目即可控制台工程也能跑通但后面做界面还得迁。核心依赖只有两个Microsoft.ML.OnnxRuntime负责推理OpenCvSharp4负责图像读写、缩放和掩码后处理。Windows 上需要再补OpenCvSharp4.runtime.win这个运行时包不然Cv2.ImRead会报找不到原生库。dotnet add package Microsoft.ML.OnnxRuntime dotnet add package OpenCvSharp4 dotnet add package OpenCvSharp4.runtime.win逻辑说明System.Drawing 在多数教程里也能做图像处理但批量抠图时 GDI 在高分屏缩放和像素格式转换上有不少坑OpenCvSharp 的 Mat 可以直接暴露内存指针配合Marshal.Copy做像素批量运算非常高效。后面第 5.5 节会重点展开这一点。如果考虑 GPU 加速可以把第一个包换成Microsoft.ML.OnnxRuntime.Gpu但 CUDA、cuDNN 版本要和模型算子兼容部署机还要装显卡驱动桌面小工具我一般先用 CPU 版跑通再决定要不要上 GPU。3.2 加载模型跑通一次推理模型加载很简单两个InferenceSession分别对应 encoder 和 decoder。注意把 session 设计成单例不要每次推理都newONNX Runtime 创建 session 的开销不算小频繁创建还会造成线程池堆积。using Microsoft.ML.OnnxRuntime; using Microsoft.ML.OnnxRuntime.Tensors; var encoderSession new InferenceSession(models/image_encoder.onnx); var decoderSession new InferenceSession(models/decoder.onnx);逻辑说明InferenceSession是线程安全的多个线程同时调用Run没问题所以 WPF/WinForm 里做一个全局静态实例即可。这里我习惯把模型文件放到输出目录下的models文件夹用相对路径加载部署时整个目录拷走就行。图像编码的前处理官方 SAM 的导出模型接收的是已经 resize 到 1024×1024、归一化到 [0,1] 再减均值除方差的 RGB 图像顺序不能反。using OpenCvSharp; using var matBgr Cv2.ImRead(input.jpg); using var matRgb new Mat(); Cv2.CvtColor(matBgr, matRgb, ColorConversionCodes.BGR2RGB); var modelInput new Mat(); Cv2.Resize(matRgb, modelInput, new Size(1024, 1024), 0, 0, InterpolationFlags.Linear); float[] means { 0.485f, 0.456f, 0.406f }; float[] stds { 0.229f, 0.224f, 0.225f }; var inputData new float[3 * 1024 * 1024]; for (int c 0; c 3; c) { for (int h 0; h 1024; h) { for (int w 0; w 1024; w) { var pixel modelInput.AtVec3b(h, w); float val c switch { 0 pixel[0], 1 pixel[1], _ pixel[2] }; inputData[c * 1024 * 1024 h * 1024 w] (val / 255f - means[c]) / stds[c]; } } } var inputTensor new DenseTensorfloat(inputData, new[] { 1, 3, 1024, 1024 }); var inputs new ListNamedOnnxValue { NamedOnnxValue.CreateFromTensor(image, inputTensor) }; using var encoderResult encoderSession.Run(inputs); var embeddings encoderResult.First(r r.Name image_embeddings).AsTensorfloat();逻辑说明这段代码把 BGR 转 RGB、缩放、归一化三步做完最终生成[1,3,1024,1024]的DenseTensor。注意Mat.AtVec3b在逐像素循环里性能一般小图单次运行可以接受但批量场景要换第 5.5 节的内存拷贝方案。归一化的 mean 和 std 取自 ImageNet 统计值凡是导出时预处理用官方默认配置就必须用这一组。然后跑解码器这里需要一个点提示。最简单可靠的提示就是图像中心点——对“主体在画面中间”的商品图和证件照非常有效。中心点的坐标要注意我们的图已经被缩放到 1024 尺度了所以中心就是(512, 512)。float[] pointCoords { 512f, 512f }; float[] pointLabels { 1f }; // 1 表示前景点 int numPoints 1; var maskInput new DenseTensorfloat(new float[1 * 1 * 256 * 256], new[] { 1, 1, 256, 256 }); var hasMaskInput new DenseTensorfloat(new[] { 0f }, new[] { 1 }); var decoderInputs new ListNamedOnnxValue { NamedOnnxValue.CreateFromTensor(image_embeddings, embeddings), NamedOnnxValue.CreateFromTensor(point_coords, new DenseTensorfloat(pointCoords, new[] { 1, numPoints, 2 })), NamedOnnxValue.CreateFromTensor(point_labels, new DenseTensorfloat(pointLabels, new[] { 1, numPoints })), NamedOnnxValue.CreateFromTensor(mask_input, maskInput), NamedOnnxValue.CreateFromTensor(has_mask_inputs, hasMaskInput) }; using var decodeResult decoderSession.Run(decoderInputs);逻辑说明point_coords的语义是“当前输入图的像素坐标”因为我们喂给编码器的是 1024×1024 的缩放图所以这里直接填(512,512)。如果你的输入来源是原图坐标比如鼠标点击屏幕上的原图位置必须先等比换算到 1024 尺度再填进来这也是第 5.2 节讲的经典坐标陷阱。参数说明mask_input用于让解码器基于上一次的掩码继续细化首次推理必须给全 0 张量同时has_mask_inputs填0f一旦填了1f解码器会强制把mask_input当作有效的低分辨率掩码来用全 0 会直接导致输出退化。首次跑通时不要动这两个参数先拿到一个正常掩码再说。4. 二值掩码怎么变成透明抠图前后处理与一键抠图实现4.1 从模型的三个候选掩码里选一个解码器的输出masks的 shape 是(1,3,256,256)C# 端看到的是三个候选掩码。SAM 在训练时采用了“整体、局部、更精细”的多掩码策略模型会为同一个提示输出三个不同粒度的掩码iou_predictions就是模型对每个掩码和真实目标重叠程度的自评分数。自动取分最高的那个掩码是最稳的策略不要贪快只取masks[0]——同一个提示下最优掩码在三个候选里的位置并不固定。var masks decodeResult.First(r r.Name masks).AsTensorfloat(); var iouScores decodeResult.First(r r.Name iou_predictions).AsTensorfloat(); int bestIndex 0; if (iouScores[0] iouScores[1]) bestIndex 1; if (iouScores[bestIndex] iouScores[2]) bestIndex 2;逻辑说明iou_predictions是模型对掩码质量的预测置信度取最大值的索引就是bestIndex。如果你想拿到一个偏“保守主体”的掩码也可以根据业务在三个候选里手动选但“一键抠图”场景下自动取最优即可。4.2 掩码后处理取 logit、放大、二值化、去噪解码器输出的masks是 logit未过 sigmoid取值理论上可以到任意实数。要变成可用的抠图掩码先过 sigmoid 压到 [0,1]再放大回原图尺寸最后按阈值二值化。// 拿到 bestIndex 对应的 256x256 logit 数据 float[] maskLogits new float[256 * 256]; for (int i 0; i 256 * 256; i) { maskLogits[i] masks[bestIndex, 0, i / 256, i % 256]; } using var maskLogitMat new Mat(256, 256, MatType.CV_32FC1); Marshal.Copy(maskLogits, 0, maskLogitMat.Data, maskLogits.Length); // logit - sigmoid - (0,1) 概率 Cv2.Threshold(maskLogitMat, maskLogitMat, 0, 0, ThresholdTypes.Otozero); Cv2.Divide(maskLogitMat, 1 Cv2.Exp(-maskLogitMat) * 0 1e-6, maskLogitMat); // 占位实际用逐元素计算这里不要照抄上面的占位写法OpenCvSharp 对逐元素 sigmoid 没有现成 API我的做法是直接轮询数组做 sigmoidfor (int i 0; i maskLogits.Length; i) { maskLogits[i] 1f / (1f MathF.Exp(-maskLogits[i])); } Marshal.Copy(maskLogits, 0, maskLogitMat.Data, maskLogits.Length); using var maskResized new Mat(); Cv2.Resize(maskLogitMat, maskResized, new Size(origW, origH), 0, 0, InterpolationFlags.Linear); Cv2.Threshold(maskResized, maskResized, 0.5, 1.0, ThresholdTypes.Binary); // 可选开闭运算去掉孤立噪点、填补小空洞 using var kernel Cv2.GetStructuringElement(MorphShapes.Ellipse, new Size(3, 3)); Cv2.MorphologyEx(maskResized, maskResized, MorphTypes.Open, kernel); Cv2.MorphologyEx(maskResized, maskResized, MorphTypes.Close, kernel);逻辑说明sigmoid 之后每个像素表示“属于前景”的概率Threshold的默认阈值 0.5 在大多数图上效果不错如果主体边缘有虚化或半透明纱质可以降到 0.3~0.4换来更宽的边缘保留代价是背景残留概率上升。开运算能去掉 3×3 以下的噪点闭运算能填掉掩码内部的小洞这两个操作用椭圆核比矩形核更不容易伤边缘。参数说明origW、origH是原图的宽高Resize用线性插值把 256×256 放大回原图尺寸。放大后的掩码边缘会有模糊过渡二值化之后变成硬边。如果后续要做发丝级抠图这里不能直接二值化而是把maskResized作为透明的 alpha 通道保留渐变这在 4.3 里会体现。4.3 一键抠图的完整流程与透明 PNG 合成“一键”的实现本质上就是自动生成一个可靠的提示点。对中心构图的主体中心点提示即可对主体偏离的画面我会退化成 3×3 网格提示每个候选跑一次解码器再用 IoU 分数选最优这个方案放到第 6 章展开。这里先把中心点版本跑完整合出透明 PNG。// maskResized 是 float 二值掩码先转成 CV_8U值域映射到 0~255 using var mask8u new Mat(); maskResized.ConvertTo(mask8u, MatType.CV_8UC1, 255.0); // 原图 BGR 转 BGRA把 alpha 通道替换成掩码 using var bgra new Mat(); Cv2.CvtColor(matBgr, bgra, ColorConversionCodes.BGR2BGRA); var bgraChannels Cv2.Split(bgra); using var alpha mask8u.Clone(); Cv2.Merge(new[] { bgraChannels[0], bgraChannels[1], bgraChannels[2], alpha }, bgra); Cv2.ImWrite(output.png, bgra);逻辑说明最终透明图 原图的 BGR 像素 掩码作为 alpha 通道。Cv2.Split把 BGRA 拆成四个单通道 Mat替换第四个通道后再Cv2.Merge合并回去比逐像素 Set 快得多避免了第 5.5 节说的Mat.At性能陷阱。需要注意的是如果想保留发丝渐变就不要把mask8u二值化直接让 alpha 保留 0~255 的过渡值边缘会自然柔和。整体流程走完后output.png就能直接拖进设计软件使用。5. 避坑与排查C# 接 SAM 最容易翻车的五个点5.1 掩码输出全黑或像雪花先查归一化别急着骂模型现象解码器跑通了输出掩码全是 0或者乱糟糟的噪声斑点。原因八成是图像预处理和导出时的配置不一致。官方导出脚本默认按 ImageNet 的 mean/std 做归一化如果你图省事只做了val / 255模型拿到的输入分布完全不在训练时的区间内ViT 的中间特征会直接崩掉。解决回到 3.2 节的归一化代码确认means和stds用的是 0.485/0.456/0.406 和 0.229/0.224/0.225同时确认Resize用了线性插值而不是最近邻最近邻在缩小时会产生明显的块状失真对掩码噪声影响很大。还有一个隐蔽点OpenCvSharp 读图默认走 BGRCvtColor到 RGB 的顺序千万别反颜色通道错位同样会让掩码变成雪花。5.2 鼠标点选的提示位置不对坐标空间没换算现象我用鼠标在原图上点了一个位置解码器给出的掩码却落在完全不相干的地方。原因point_coords期望的坐标系取决于你喂给编码器的图。如果直接传原图坐标而编码器输入是缩放后的 1024 图解码器内部拿到一个“越界”的坐标自然分不出正确目标。我在 3.2 节的示例里用(512,512)是因为输入图本身就是 1024×1024如果是原图坐标点击必须按下式换算float scaledX mouseX * (1024f / origW); float scaledY mouseY * (1024f / origH);解决统一约定一个换算入口。我一般把“原图坐标转 1024 坐标”封装成一个PointF ToModelPoint(PointF p)方法所有提示点生成、网格采样都走它不要在业务代码里散落乘除。5.3 想迭代细化掩码结果越修越乱mask_input 用法搞错了现象第一次生成的掩码不错想用mask_input带着第一次的 low_res_masks 细化一下边缘结果输出整片变黑。原因mask_input必须配合has_mask_inputs一起用。这个参数在导出模型里是一个会改变解码器行为的开关填1f表示“我已经给了上一轮掩码请基于它细化”此时mask_input如果还是全 0相当于告诉模型“上一次分割结果是空白”解码器自然会收缩成空掩码。解决需要迭代时把上一轮解码器输出的low_res_masks注意不是masks是那个 1×1×256×256 的低分辨率版本拷贝进mask_input同时has_mask_inputs置1f。不要自己把最终掩码 resize 成 256×256 再填进去那样会因为多次插值引入边缘锯齿细化效果反而变差。5.4 扣图服务跑一会儿内存暴涨InferenceSession 创建太频繁现象工具刚启动时正常连续处理二三十张图后内存稳定涨到 2GB 以上最后开始卡顿。原因每次调用都在代码里new InferenceSessionONNX Runtime 为每个 session 分配算子执行上下文和线程池不释放旧 session 就会越积越多。网上不少示例代码为了省事把 session 创建放在处理函数内部这对长时间运行的工具是致命的。解决把 encoder 和 decoder 两个 session 提升为类级别的静态字段或单例Run本身是线程安全的多线程回调共用即可。如果确实需要动态加载卸载模型记得调用session.Dispose()同时给SessionOptions设置合理的线程数避免一个进程里创建多个 session 时线程资源膨胀。5.5 同一张图 Python 里 300msC# 跑出 8 秒Mat.At 的性能陷阱现象推理模型本身不慢但整套流程跑下来奇慢无比仔细一查时间全耗在图像预处理循环里。原因Mat.AtVec3b(h,w)每次调用都会做类型检查和边界校验三层循环叠加起来开销非常大。我第一次实现时没在意直到批量测试才意识到瓶颈根本不在 ONNX Runtime而在像素复制和归一化。解决把 Mat 的整块内存用Marshal.Copy拷进字节数组再在数组上做归一化JIT 对纯数组循环的优化比Mat.At好一两个数量级。byte[] raw new byte[3 * 1024 * 1024]; Marshal.Copy(modelInput.Data, raw, 0, raw.Length); for (int i 0; i raw.Length; i 3) { byte b raw[i]; // 已经 RGB 顺序 byte g raw[i 1]; byte r raw[i 2]; int c i / (1024 * 1024); // 所在通道 ... }逻辑说明modelInput.Data返回的是 Mat 内部数据指针Marshal.Copy一次把整张图的内存拷出来之后就是标准的数组下标运算。OpenCvSharp 的官方文档也推荐这种整块拷贝的方式避免高频At调用。注意这里拿到的数据已经是CvtColor之后的 RGB 顺序按内存连续排布逐通道归一化时要按 RGB 索引取像素别按 BGR 习惯写反。6. 进阶技巧批量抠图、多候选提示与量化取舍6.1 缓存 image_embeddings让批量抠图提速一个量级把第 3 章的 encoder 推理结果embeddings单独缓存下来。处理同一张图的多组提示时解码器可以反复使用这一份特征单次解码约 20ms10 个提示也只要 200ms而 encoder 一次就要 400ms 以上。我在桌面上实现“点一下换一个候选抠图”的交互时就是靠这个缓存做到拖拽提示点实时更新的。6.2 主体偏构图时用 3×3 网格点提示替代中心点一键抠图最怕主体不在画面中心。常见做法是取 3×3 网格共 9 个点全部作为前景提示每个点跑一次解码器然后取iou_predictions最高且超过 0.8 的掩码作为结果。这样即使主体在左下角也能被网格捕获。代价是解码器要跑 9 次但有了 embedding 缓存这根本不是问题——收益远大于成本。6.3 量化 int8 要谨慎优先量化 image encoder别动 decoder网上不少 ONNX 量化教程会诱导你把两个模型都量化成 int8但 SAM 的 decoder 本身就是小张量计算量化收益几乎为零还会显著掉边缘精度。image encoder 量化后 CPU 推理能快两三倍但高频边缘毛发、镂空、栏杆会出现明显锯齿必须拿业务图实测后再决定。我的习惯是先用官方权重跑通流程再单独量化 encoder用一套包含毛发和复杂边缘的测试图对比掩码质量达标才上线。首次实战时我就是图省事直接量了 decoder结果边缘质量崩得没法看后来花了半天重新导出才算稳住。希望这些参数和思路让同样走 C# 路线的人少走这段弯路也希望帮到你。本文还有配套的精品资源点击获取