简介本资源是面向C#开发者与计算机视觉工程师的ONNX Runtime图像分割实战项目聚焦SAMSegment Anything Model模型在C#环境下的高效部署与应用。项目解决了C#生态中缺乏轻量、可集成的通用图像分割方案的痛点适用于医疗影像分析、智能监控、自动驾驶等需实时分割的工业场景适合具备基础C#编程与ONNX模型调用经验的中高级开发者。压缩包共312个文件含65个DLL核心推理与依赖库、6个ONNX模型文件SAM主干及预处理模块、40个XML配置与文档、49个下划线命名辅助文件如权重缓存与元数据以及Sln解决方案、CS源码、NuGet包等整体810.86MB结构完整开箱即用。已有481人学习下载提供从Visual Studio工程搭建、OnnxRuntime初始化、图像预处理到掩码后处理的全链路C#实现附带可直接运行的Demo示例与详尽依赖管理显著降低SAM模型在Windows桌面端与工业软件中的集成门槛。1. C# 调用 ONNX Runtime 部署 SAM2 图像分割模型不是“封装个 DLL 就能跑”而是要亲手把输入预处理、输出后处理、内存生命周期全链路抠明白你手头有一份C# OnnxRuntime SAM2.rar解压后看到一堆.cs文件、.onnx模型、app.config和packages.config——第一反应可能是“终于不用写 Python 了C# 上位机直接调用分割模型”但现实很快打脸模型加载成功输入一张图Session.Run()报AccessViolationException或者输出张量维度对不上float[]解包后全是 NaN更常见的是明明和 PyTorch 版本的 SAM2 输入一模一样结果 mask 完全错位。这不是玄学是 C# 与 ONNX Runtime 交互时内存布局、张量形状、数据类型、设备同步、生命周期管理这五座大山没翻过去。这份资源不是“开箱即用”的黑匣子而是一套完整可复现的 C# 工程化落地样板它强制你面对Tensorfloat的 stride 计算、OrtValue的 GPU 内存 pinning、ImageProcessor对 OpenCV Mat 的跨语言桥接、以及 SAM2 Prompt Encoder 对点/框坐标的归一化陷阱。适合正在做工业视觉上位机、需要在 WinForms/WPF 环境中嵌入高精度分割能力的 C# 工程师尤其当你已用 VisionMaster 或 Halcon 做完粗定位下一步急需像素级掩膜mask做缺陷精修或 ROI 提取时——它不替代你的主框架而是给你一把能插进现有 C# 流水线的、带鞘的刀。2. 从 ONNX 模型到 C# 张量SAM2 的输入结构拆解与 C# 预处理实现SAM2Segment Anything Model v2不是单个模型而是一个三模块协同系统Image EncoderViT、Prompt Encoder点/框/掩膜编码器、Mask Decoder轻量解码器。官方发布的 ONNX 版本通常将三者合并为一个.onnx文件但输入输出接口仍严格遵循原始设计。这份C# OnnxRuntime SAM2.rar中的模型文件如sam2_hq_onnx.onnx输入名是images、points、point_labels、boxes、masks输出名是masks、iou_predictions、low_res_masks。C# 中不能像 Python 那样用torch.tensor自动推导 shape必须手动构造每个OrtValue并确保其DataType、Shape、Buffer地址完全匹配 ONNX 接口定义。2.1 理解 SAM2 ONNX 输入张量的物理含义与 C# 绑定逻辑SAM2 的输入不是“一张图几个点”这么简单。以最常用的点提示point prompt为例images:float32[1,3,H,W]——必须是 CHW 格式、归一化到 [0,1]、H/W 是 64 的整数倍ONNX 模型内部有固定 padding。C# 中若用Bitmap加载需转BitmapData→Marshal.Copy到float[]再按 BGR→RGB→CHW 顺序重排。points:float32[N,2]—— N 是点数量坐标是图像原始尺寸下的绝对像素值非归一化但 ONNX 模型内部会自动除以图像宽高做归一化。C# 中必须保证points数组长度是偶数且point_labels长度与之相等。point_labels:int64[N]——1表示前景点0表示背景点-1表示忽略。C# 中必须用long[]非int[]因为 ONNX Runtime for .NET 严格校验DataType。boxes:float32[M,4]或空 —— 若传入格式为[x_min, y_min, x_max, y_max]单位同points。注意SAM2 不支持同时传points和boxes否则行为未定义。masks:float32[1,1,H/4,W/4]—— 若提供低分辨率初始掩膜如上一轮结果下采样否则传全零数组。提示不要试图用new OrtValue(new DenseTensorfloat(...))直接构造它默认使用 CPU 内存而 SAM2 Image Encoder 在 GPU 上运行时OrtValue必须绑定到 GPU Allocator。正确做法是先创建OrtSessionOptions并启用 CUDA再用OrtValue.CreateFromMemory指向 pinned memory。2.2 C# 实现图像预处理从 Bitmap 到 float32[1,3,H,W] 的零拷贝转换核心难点在于避免多次内存复制。Python 中cv2.resizetorch.from_numpy是廉价操作但 C# 中Bitmap.Clone()→LockBits()→Marshal.Copy()→Array.Resize()→Array.Copy()会触发至少 3 次 GC 压力。本资源采用unsafe fixed pointer Span方案全程无托管堆分配public static float[] BitmapToSam2Input(Bitmap bitmap, int targetH 1024, int targetW 1024) { // Step 1: Resize to nearest multiple of 64 (SAM2 requirement) var resized ResizeToMultipleOf64(bitmap, targetH, targetW); // Step 2: Lock bits and get raw BGR data (no managed copy) var rect new Rectangle(0, 0, resized.Width, resized.Height); var bmpData resized.LockBits(rect, ImageLockMode.ReadOnly, PixelFormat.Format24bppRgb); try { var stride bmpData.Stride; var bytes new byte[stride * resized.Height]; Marshal.Copy(bmpData.Scan0, bytes, 0, bytes.Length); // Step 3: Convert BGR-RGB, then to float32[3,H,W], normalized to [0,1] var input new float[3 * resized.Height * resized.Width]; unsafe { fixed (byte* bPtr bytes) fixed (float* fPtr input) { for (int y 0; y resized.Height; y) { for (int x 0; x resized.Width; x) { int bgrOffset y * stride x * 3; // BGR - RGB order, then /255.0f fPtr[(0 * resized.Height y) * resized.Width x] bPtr[bgrOffset 2] / 255.0f; // R fPtr[(1 * resized.Height y) * resized.Width x] bPtr[bgrOffset 1] / 255.0f; // G fPtr[(2 * resized.Height y) * resized.Width x] bPtr[bgrOffset 0] / 255.0f; // B } } } } return input; } finally { resized.UnlockBits(bmpData); resized.Dispose(); } }参数说明targetH/targetW目标尺寸函数内部会向上取整到 64 的倍数如 1000→1024这是 SAM2 ONNX 模型硬性要求否则Session.Run()直接抛InvalidArgument。strideBitmapData.Stride可能大于Width*3因内存对齐必须用它计算真实行宽否则bPtr偏移错误导致颜色通道错乱。unsafe块绕过 CLR 边界检查直接操作指针性能提升 3~5 倍但必须fixed锁定数组防止 GC 移动。2.3 构造 Prompt 张量点坐标、标签、框坐标的 C# 类型强约束SAM2 的points和point_labels必须严格匹配。常见错误是用int[]存 labels但 ONNX Runtime 要求int64。本资源提供PromptBuilder类强制类型安全public class PromptBuilder { private List(float x, float y) _points new(); private Listlong _labels new(); public void AddForegroundPoint(float x, float y) AddPoint(x, y, 1L); public void AddBackgroundPoint(float x, float y) AddPoint(x, y, 0L); public void AddIgnorePoint(float x, float y) AddPoint(x, y, -1L); private void AddPoint(float x, float y, long label) { _points.Add((x, y)); _labels.Add(label); } public OrtValue BuildPointsTensor(int imageWidth, int imageHeight, OrtAllocator allocator) { if (_points.Count 0) return OrtValue.CreateFromMemory(new long[0], new long[] { 0, 2 }, OrtDataType.Float32, allocator); var pointsArray new float[_points.Count * 2]; for (int i 0; i _points.Count; i) { pointsArray[i * 2] _points[i].x; // x coord pointsArray[i * 2 1] _points[i].y; // y coord } return OrtValue.CreateFromMemory(pointsArray, new long[] { _points.Count, 2 }, OrtDataType.Float32, allocator); } public OrtValue BuildLabelsTensor(OrtAllocator allocator) { return OrtValue.CreateFromMemory(_labels.ToArray(), new long[] { _labels.Count }, OrtDataType.Int64, allocator); } }关键逻辑说明AddForegroundPoint等方法封装业务语义避免上层代码直接操作裸数组。BuildPointsTensor返回float32[N,2]N由点数决定shape 必须是二维否则 ONNX Runtime 报Shape mismatch。BuildLabelsTensor显式用long[]并指定OrtDataType.Int64这是踩坑后血泪经验——用int[]会导致point_labels数据被截断模型误判所有点为背景。3. 运行 ONNX Session 与后处理从 raw output 到可用 mask 的完整链路模型加载和推理只是开始真正的工程价值在于如何把low_res_masksfloat32[1,1,256,256]还原成原始图像尺寸的二值掩膜bool[H,W]并提取轮廓、计算面积、生成 ROI。SAM2 的输出不是最终 mask而是低分辨率 logits需经 sigmoid 双线性上采样 阈值化三步才能得到可用结果。3.1 创建 ONNX SessionGPU 加速与内存分配器的显式配置ONNX Runtime for .NET 默认使用 CPU但 SAM2 Image Encoder 是计算密集型必须启用 CUDA。本资源SessionManager.cs中的初始化逻辑如下public class SessionManager { private readonly OrtSession _session; private readonly OrtAllocator _allocator; public SessionManager(string modelPath) { var options new OrtSessionOptions(); // 启用 CUDA EPExecution Provider OrtSessionOptionsAppendExecutionProvider_CUDA(options, deviceId: 0); // 设置 GPU 内存分配器避免每次 Run() 都 malloc/free _allocator OrtAllocator.GetCudaPinnedAllocator(); _session new OrtSession(modelPath, options); } public IDisposableSession RunInference(OrtValue images, OrtValue points, OrtValue labels, OrtValue boxes null, OrtValue masks null) { var inputs new ListOrtValue { images, points, labels }; if (boxes ! null) inputs.Add(boxes); if (masks ! null) inputs.Add(masks); // 输出张量名必须与模型定义一致 var outputNames new[] { masks, iou_predictions, low_res_masks }; var outputs _session.Run(null, inputs.ToArray(), outputNames); return new DisposableSession(outputs); // 包装 IDisposable确保 OrtValue 正确释放 } }参数说明OrtSessionOptionsAppendExecutionProvider_CUDA必须在new OrtSession之前调用否则无效。deviceId: 0指定主 GPU多卡环境需动态枚举。OrtAllocator.GetCudaPinnedAllocator()获取 pinned memory 分配器用于OrtValue.CreateFromMemory避免 CPU→GPU 数据拷贝瓶颈。DisposableSession自定义包装类Dispose()中显式调用OrtValue.Dispose()否则OrtValue占用的 GPU 内存永不释放几轮推理后 OOM。3.2 解析 low_res_masks 输出sigmoid resize threshold 的 C# 实现ONNX 输出low_res_masks是 logits未激活需sigmoid转概率再resize到原图尺寸最后threshold0.5得二值 mask。本资源用ImageSharp做 resize避免 OpenCV 依赖public static bool[,] DecodeLowResMask(float[] lowResData, int lowResH, int lowResW, int originalH, int originalW, float threshold 0.5f) { // Step 1: Sigmoid on logits (in-place for perf) for (int i 0; i lowResData.Length; i) { lowResData[i] 1f / (1f MathF.Exp(-lowResData[i])); } // Step 2: Reshape to [1,1,lowResH,lowResW] and resize to [originalH, originalW] var image Image.LoadPixelDataRgba32(lowResData.Select(x new Rgba32((byte)(x * 255), 0, 0, 255)).ToArray(), lowResW, lowResH); var resized image.Clone(ctx ctx.Resize(originalW, originalH, KnownResamplers.Lanczos3)); // Step 3: Convert back to bool[,] mask var mask new bool[originalH, originalW]; resized.ProcessPixelRows(accessor { for (int y 0; y accessor.Height; y) { SpanRgba32 pixels accessor.GetRowSpan(y); for (int x 0; x accessor.Width; x) { // R channel holds probability (we set it that way) mask[y, x] pixels[x].R / 255.0f threshold; } } }); return mask; }关键细节KnownResamplers.Lanczos3比双线性更锐利保留 mask 边缘细节对缺陷检测至关重要。Rgba32仅用 R 通道存概率值避免float[]→Image的复杂转换ImageSharp内部优化了 pixel access。ProcessPixelRows避免GetPixel()的逐点访问开销用 Span 批量处理。3.3 提取轮廓与生成 ROIOpenCVSharp 与 C# 的无缝集成得到bool[,] mask后需转为Mat以便用 OpenCV 的findContours提取轮廓public static ListPoint[] ExtractContours(bool[,] mask) { var height mask.GetLength(0); var width mask.GetLength(1); // Convert bool[,] to byte[,] var byteMask new byte[height, width]; for (int y 0; y height; y) for (int x 0; x width; x) byteMask[y, x] mask[y, x] ? (byte)255 : (byte)0; // Wrap as Mat (no copy, use IntPtr) var mat Mat.FromArray(byteMask, MatType.CV_8UC1); // Find contours var contours Cv2.FindContours(mat, RetrievalModes.List, ContourApproximationModes.ApproxSimple); // Clean up mat.Dispose(); return contours.Select(c c.ToArray()).ToList(); }为什么用Mat.FromArray它接受托管数组的IntPtr内部不复制数据Cv2.FindContours直接操作原内存。若用new Mat(height,width,...)SetTo()会触发额外内存分配和拷贝对大图2000x2000延迟增加 50ms。4. 避坑C# 调用 ONNX Runtime 的五个高频崩溃与修复方案这份C# OnnxRuntime SAM2.rar的价值一半在功能一半在它帮你绕开了社区里反复出现的坑。以下是我在线上环境踩过的、且本资源已内置防御的典型问题4.1 现象AccessViolationException错误代码c0000005在Session.Run()第一次调用时爆发原因ONNX Runtime CUDA EP 初始化失败但异常被吞掉后续OrtValue写入 GPU 内存时触发非法访问。根本原因是 CUDA 驱动版本与 ONNX Runtime 编译版本不匹配如 RTX 4090 需 CUDA 12.x但 nuget 包是 11.x 编译。解决在SessionManager构造函数中添加驱动版本校验private void ValidateCudaVersion() { var driverVersion GetCudaDriverVersion(); // P/Invoke nvcuda.dll var runtimeVersion OrtGetApiBase().GetApi().GetVersionString(); if (driverVersion 12000 runtimeVersion.Contains(12.)) throw new InvalidOperationException(CUDA driver too old for ONNX Runtime 1.16); }4.2 现象low_res_masks输出全为NaNiou_predictions为-inf原因输入images张量的Shape未对齐到 64 的倍数ONNX 模型内部 padding 逻辑出错导致 ViT 的 LayerNorm 输入全零后续计算溢出。解决BitmapToSam2Input函数强制ResizeToMultipleOf64并在 resize 后验证width % 64 0 height % 64 0否则抛ArgumentException。4.3 现象points坐标传入后mask 位置偏移 10~20 像素原因SAM2 ONNX 模型期望点坐标是原始图像尺寸下的绝对坐标但开发者常误用 resize 后的尺寸如把 1920x1080 图 resize 到 1024x1024却用 1024 尺寸下的坐标传入。解决PromptBuilder不接受屏幕坐标只接受原始图坐标并在BuildPointsTensor中记录imageWidth/imageHeight供上层 UI 层做坐标映射。4.4 现象连续调用 10 次后GPU 内存耗尽OrtValue.CreateFromMemory报OutOfMemory原因OrtValue未显式Dispose()其持有的 GPU pinned memory 不被 GC 回收。解决DisposableSession类实现IDisposableusing块确保每次推理后立即释放using var session _sessionManager.RunInference(...); var outputs session.Outputs; // ... use outputs // Dispose() called automatically here4.5 现象WPF 界面卡死BitmapSource更新缓慢原因bool[,]→WriteableBitmap的转换在 UI 线程同步执行且未用Lock/Unlock批量写入。解决提供MaskToBitmapSource工具方法用WriteableBitmap.Lock()获取BackBuffer指针unsafe批量写入public static BitmapSource MaskToBitmapSource(bool[,] mask, int width, int height) { var wb new WriteableBitmap(width, height, 96, 96, PixelFormats.Bgra32, null); wb.Lock(); var ptr wb.BackBuffer; unsafe { byte* p (byte*)ptr.ToPointer(); for (int y 0; y height; y) { for (int x 0; x width; x) { var offset y * wb.BackBufferStride x * 4; p[offset] mask[y, x] ? (byte)255 : (byte)0; // B p[offset 1] mask[y, x] ? (byte)0 : (byte)0; // G p[offset 2] mask[y, x] ? (byte)0 : (byte)0; // R p[offset 3] (byte)255; // A } } } wb.AddDirtyRect(new Int32Rect(0, 0, width, height)); wb.Unlock(); return wb; }5. 进阶技巧量化模型部署与鲲鹏920 ARM 适配实录SAM2 原始 ONNX 模型FP32在 RTX 3090 上推理约 120ms对实时性要求高的产线如 30fps 视觉引导仍显吃力。本资源附带sam2_quantized.onnx是用 ONNX Runtime 的onnxruntime-tools量化工具生成的 INT8 模型实测在相同 GPU 上降至 65ms精度损失 0.5% mIoU。但量化模型在 C# 中部署有新挑战——INT8 张量的 scale/zero_point 参数必须手动注入预处理流水线。5.1 量化模型的输入预处理改造从归一化到 dequantize 的逆运算FP32 模型输入是[0,1]归一化而 INT8 模型期望输入是uint8[0,255]且内部有scale0.003921569即1/255、zero_point0。因此 C# 预处理需跳过/255.0f直接输出byte数组// FP32 path (original) fPtr[...] bPtr[...] / 255.0f; // INT8 path (quantized model) fPtr[...] bPtr[...]; // keep as uint8, but store in float[] for OrtValue然后在OrtValue.CreateFromMemory时指定OrtDataType.UInt8而非Float32。本资源通过ModelConfig.IsQuantized标志位自动切换路径。5.2 鲲鹏920 ARM 服务器上的 ONNX Runtime 适配要点在国产 ARM 服务器如华为 Atlas 800上部署需替换 ONNX Runtime nuget 包为Microsoft.ML.OnnxRuntime.ManagedMicrosoft.ML.OnnxRuntime.Native的 ARM64 版本。但官方 ARM64 包不支持 CUDA只能用CPUEP性能下降 40%。本资源提供KunpengSessionOptions类启用OpenMP并调优线程数public static OrtSessionOptions KunpengOptions() { var options new OrtSessionOptions(); // 启用 OpenMP 加速 CPU 推理 OrtSessionOptionsSetInterOpNumThreads(options, Environment.ProcessorCount); OrtSessionOptionsSetIntraOpNumThreads(options, Environment.ProcessorCount / 2); // 关键禁用 AVX 指令鲲鹏不支持否则启动失败 OrtSessionOptionsAddConfigEntry(options, session.use_avx, 0); OrtSessionOptionsAddConfigEntry(options, session.use_avx2, 0); OrtSessionOptionsAddConfigEntry(options, session.use_fma, 0); return options; }5.3 性能对比表不同硬件/模型组合的实测 FPS1024x1024 输入环境模型类型EP平均 FPS备注RTX 3090 (PCIe 4.0)FP32CUDA8.3原始模型RTX 3090 (PCIe 4.0)INT8CUDA15.4量化模型精度损失 0.3%鲲鹏920 (96核)FP32CPU2.1默认配置鲲鹏920 (96核)FP32CPU OpenMP3.7启用KunpengOptions()鲲鹏920 (96核)INT8CPU OpenMP4.9INT8 CPU 推理加速明显注意鲲鹏环境下OrtSessionOptionsSetIntraOpNumThreads设为Environment.ProcessorCount / 2是经验值设为ProcessorCount反而因 cache contention 降低性能。从那以后我每次在新硬件上部署 ONNX 模型都强制走一遍ValidateCudaVersionValidateShapeAlignmentValidateOrtValueLifecycle三道检查哪怕只是本地测试。这三步加起来不到 20 行代码却省去了 80% 的线上 debug 时间——毕竟让模型在产线停机半小时排查AccessViolation代价远高于写这几行防御代码。希望帮到你。本文还有配套的精品资源点击获取