C 也能跑 SAM3：OnnxRuntime 部署全流程实测（2026 最新，含内存泄漏排查）

C# 也能跑 SAM3：OnnxRuntime 部署全流程实测（2026 最新，含内存泄漏排查）

【免费下载链接】sam3项目地址: https://ai.gitcode.com/hf_mirrors/facebook/sam3

Meta 的 SAM 3 把"分割一切"从框选交互推进到了开放词汇概念分割（Promptable Concept Segmentation, PCS）：不需要画框，一句 "person"、"laptop screen" 甚至一个示例图，就能把图中所有匹配实例一次性全部切出来。这对工业质检、内容审核、医学影像标注意味着什么？意味着原来要养一整套检测+分割管线才能做的事，现在一个模型就能覆盖。但社区里大量讨论集中在 Python 侧，而真正做产品落地的团队，往往要面对的是 C# 技术栈——Windows 桌面应用、.NET 服务、Unity 里的实时分割……本文不讨论情怀，直接给出在 .NET 环境下用 OnnxRuntime 把 facebook/sam3 跑起来并跑稳的完整实测路径，重点拆解三个最容易翻车的点：内存泄漏、尺寸匹配与 GPU 利用率。

先说结论：SAM3 能在 C# 里跑，但跑起来容易，跑不崩很难。全部坑都藏在输入张量的规格、输出张量的后处理，以及 OnnxRuntime 的会话生命周期里。

一、先摸清这个仓库到底给了什么

动手写 C# 之前，先把仓库的配置读透。这个仓库是 facebook/sam3 的 HuggingFace Transformers 镜像，根目录下没有训练代码，只有模型权重与配置，但它们已经足够回答"C# 侧要准备哪些张量"这个核心问题。

config.json 里藏着关键规格：

配置项	取值	对 C# 侧的影响
vision_config.backbone_config.image_size	1008	图像输入必须 resize/pad 到 1008×1008
vision_config.backbone_config.patch_size	14	1008 / 14 = 72，patch 网格 72×72
vision_config.backbone_feature_sizes	288 / 144 / 72 三层	FPN 多尺度特征，导出时逐层取用
detector_config.detr_decoder_config.num_queries	200	检测头固定输出 200 个候选 query
detector_config.detr_decoder_config.use_presence_token	true	输出里带存在性 token，后处理要过滤"无目标"query
low_res_mask_size	288	掩码输出是低分辨率 288×288，必须插值回原图
score_threshold_detection/high_conf_thresh	0.5 / 0.8	官方默认置信度阈值参考
fill_hole_area	16	后处理里空洞填充的最小面积阈值
text_config.vocab_size/max_position_embeddings	49408 / 32	文本编码器是 CLIP，提示词 token 上限只有 32

processor_config.json 则把预处理参数直接摊开：image_mean = [0.5, 0.5, 0.5]、image_std = [0.5, 0.5, 0.5]（注意这不是 ImageNet 那组 mean/std，而是 0.5 归一化，对应像素值先乘rescale_factor = 1/255再(x - 0.5) / 0.5），图像目标尺寸 1008×1008，低分辨率掩码尺寸 288×288。resample = 2表示双线性插值。这些数字在 C# 侧一个都不能改，改了就是玄学级的分割质量下降。

另外注意 tokenizer_config.json：model_max_length = 32、do_lower_case = true，分词器是CLIPTokenizer。翻译成 C# 的话：文本提示要先小写化，token 数超过 32 会被截断——提示词写长句子意义不大，一个名词短语往往是最优解。

仓库还同时提供 model.safetensors（约 3.44GB）与 sam3.pt（约 3.45GB），这是同一份权重的两种序列化格式，ONNX 导出时取其一即可。

二、C# 环境与 OnnxRuntime 配置

推荐方案：.NET 8（LTS）+Microsoft.ML.OnnxRuntime（CPU）+Microsoft.ML.OnnxRuntime.Gpu（CUDA）。注意 GPU 包与 CPU 包不能共存于同一项目，需要按目标环境拆成两个 csproj 或用条件引用：

<PackageReference Include="Microsoft.ML.OnnxRuntime.Gpu" Version="1.20.1" /> <PackageReference Include="SixLabors.ImageSharp" Version="3.1.5" /> <PackageReference Include="System.Numerics.Tensors" Version="9.0.0" />

图像解码/缩放用 ImageSharp，张量搬运用System.Numerics.Tensors的TensorPrimitives（向量化归一化，比手写 for 循环快一个数量级）。

Session 初始化时，CUDA EP 的配置有几个直接影响性能的开关：

var opts = new SessionOptions(); opts.AppendExecutionProvider_CUDA(new OrtCUDAProviderOptions { DeviceId = 0, ArenaExtendStrategy = ArenaExtendStrategy.KNextPowerOfTwo, CudnnConvAlgoSearch = CudnnConvAlgoSearch.Heuristic, DoCopyInDefaultStream = true }); // 大模型建议开启内存规整，避免多次 Run 后显存碎片化 opts.EnableMemoryPattern = true; opts.ExecutionMode = ExecutionMode.ORT_SEQUENTIAL; var session = new InferenceSession(modelPath, opts);

ExecutionMode.ORT_SEQUENTIAL对单请求推理更稳，多路并发场景再考虑ORT_PARALLEL——但并行执行在多 EP 混合时会引入额外的调度开销，先别急着开。

三、模型导出：从 Transformers 到 ONNX

C# 侧没有直接吃.pt/.safetensors的路径，必须先导出 ONNX。用官方 Transformers 实现导出最省事，核心是固定动态轴：

import torch from transformers import Sam3Model, Sam3Processor model = Sam3Model.from_pretrained("facebook/sam3", torch_dtype=torch.float32) model.eval() # 构造最小输入以追踪图 processor = Sam3Processor.from_pretrained("facebook/sam3") inputs = processor(images=torch.zeros(1, 3, 1008, 1008), text="person", return_tensors="pt") dynamic_axes = { "pixel_values": {0: "batch"}, "input_ids": {0: "batch", 1: "text_len"}, "attention_mask": {0: "batch", 1: "text_len"}, "pred_masks": {0: "batch", 1: "num_queries"}, "pred_boxes": {0: "batch", 1: "num_queries"}, "scores": {0: "batch", 1: "num_queries"}, } torch.onnx.export( model, tuple(inputs.values()), "sam3.onnx", input_names=list(inputs.keys()), output_names=["pred_masks", "pred_boxes", "scores", "presence"], dynamic_axes=dynamic_axes, opset_version=17, do_constant_folding=True, )

导出时有三个必须留意的点：

1. 输出名要以model(**inputs)的返回结构为准：pred_masks是[B, num_queries, 288, 288]的 logits（未过 sigmoid），pred_boxes是归一化 xyxy，scores是实例置信度，presence token 对应每个 query "图中是否存在该概念实例" 的置信度。后处理顺序搞错任何一个，都会出现"检测到了框但掩码全空"的诡异现象。
2. 文本分支建议单独导出或固定text_len：CLIP 文本编码器接受变长输入，ONNX 导出动态轴后，C# 侧每次推理都要按实际 token 长度动态分配。SAM3 的文本路径只吃 32 个 token，实际应用里把提示词 pad 到固定 32 反而更省心——动态轴省下的那点内存，不够填你调试 shape mismatch 掉进去的坑。
3. fp16 导出要谨慎：SAM3 的 DETR 解码器对数值精度敏感，fp16 下注意力分数溢出会导致大量 query 变成 NaN，mask 全黑。要加速先用 fp32 + CUDA，稳定后再考虑convert_fp16，并且务必用真实图片做回归对比，别只看 loss。

四、模型加载、推理与后处理全流程

4.1 预处理：和 processor_config.json 严格对齐

C# 侧最容易被忽略的是：SAM3 的预处理不是"resize 到 1008"这么简单。仓库processor_config.json里default_to_square: true、do_center_crop与do_pad均为 null，意味着实际流程是等比缩放后居中 pad 成 1008×1008 正方形，同时要记录original_sizes——这个值在后处理插值回原图分辨率时是刚需。

// 1. 等比缩放 + 居中 pad 到 1008x1008，记录 scale 与 pad 偏移 var (resized, scale, offsetX, offsetY) = Letterbox(image, 1008, 1008); // 2. 归一化：/255 -> (x-0.5)/0.5，即 (x/255 - 0.5)/0.5 Span<float> pixelBuf = stackalloc float[3 * 1008 * 1008]; for (int c = 0; c < 3; c++) { var src = resized.GetPixelRowSpan(c); // 0..255 var dst = pixelBuf.Slice(c * 1008 * 1008, 1008 * 1008); TensorPrimitives.Multiply(src, 1f / 255f, dst); // rescale TensorPrimitives.Subtract(dst, 0.5f, dst); // - mean TensorPrimitives.Divide(dst, 0.5f, dst); // / std } var pixelValues = new DenseTensor<float>(pixelBuf.ToArray(), new[] { 1, 3, 1008, 1008 });

文本侧同样不能省：小写化 + CLIP BPE 分词 + pad 到 32，attention_mask标记真实 token。仓库 merges.txt 与 vocab.json 就是 CLIP 的 BPE 词表——如果不想自研 tokenizer，可以在导出时把文本分支的 tokenize 结果也一起 trace 进图，或者干脆用一次性的.NETCLIP tokenizer 移植（词表 49408 项，BPE 规则在 merges.txt 里，工作量半天）。

4.2 推理

using var inputs = new OrtValue[] // 或 Dictionary<string, OrtValue> { OrtValue.CreateTensorValueFromMemory(pixelValues, new long[] { 1, 3, 1008, 1008 }), OrtValue.CreateTensorValueFromMemory(inputIds, new long[] { 1, 32 }), OrtValue.CreateTensorValueFromMemory(attentionMask, new long[] { 1, 32 }), OrtValue.CreateTensorValueFromMemory(boxes, new long[] { 1, 1, 4 }), // 可选框提示 OrtValue.CreateTensorValueFromMemory(boxLabels, new long[] { 1, 1 }), }; using var results = session.Run(inputNames, inputs, outputNames); var masksLogits = results[0].GetTensorDataAsSpan<float>(); // [1, 200, 288, 288] var boxes = results[1].GetTensorDataAsSpan<float>(); // [1, 200, 4] 归一化 xyxy var scores = results[2].GetTensorDataAsSpan<float>(); // [1, 200] var presence = results[3].GetTensorDataAsSpan<float>(); // [1, 200]

4.3 后处理：五步一个都不能少

从[B, 200, 288, 288]的 logits 到最终贴合原图的多边形掩码，标准管线如下：

// 1. sigmoid 概率化 // 2. presence + score 双阈值过滤： // keep = presence[i] > 0.5 && scores[i] > 0.5 // 3. NMS（仓库配置 det_nms_thresh=0.1，IoU 阈值要按这个校准） // 4. 288x288 低分辨率掩码双线性插值回原图尺寸 // (原始宽高，不是 1008x1008 —— 要去掉 pad) // 5. 按 0.5 mask_threshold 二值化；面积小于 fill_hole_area=16 的空洞填掉

第 2 步是最容易被"效果玄学"背刺的地方：presence 和 score 是两套置信度。score 高不代表 query 一定有效，presence 才是"该概念是否真的出现在图中"的判断；两个都过了，才谈得上掩码质量。只按 scores 过滤的常见恶果是：满图出现一堆高分碎片框。

第 4 步的坑在"回原图"这三个字：original_sizes是[原高, 原宽]，而掩码网格是 288×288，插值目标必须是原图分辨率，不是 1008×1008——直接把 288 插到 1008 再裁掉 pad 会引入双重插值误差，边缘锯齿翻倍。正确做法是一次性从 288 插值到原图尺寸。

五、三大坑实测排雷

坑一：内存泄漏——GC 视角下的 OnnxRuntime

这是所有 .NET 部署 SAM 系模型的头号事故。症状非常典型：Process working set或 GPU 显存每推理一次涨几十 MB，跑上几千次后服务被 OOM 杀掉。排雷顺序：

1. Session 必须单例复用。InferenceSession的构建包含图优化（graph optimization）与内存规划，动辄数秒且占用大量内存。任何"每次推理 new 一个 Session"的写法都是事故源头。正确做法是static readonly或依赖注入单例。

2. 输出张量要显式释放。session.Run()返回的OrtValue持有原生内存句柄，GC 无法精确感知其大小，必须using或手动Dispose：

// 错误：结果用完就扔，OrtValue 悬在原生堆上等 GC var results = session.Run(...); var mask = results[0].GetTensorDataAsSpan<float>(); // 正确：using 包裹，或显式 Dispose using var outputs = session.Run(...); var maskSpan = outputs[0].GetTensorDataAsSpan<float>();

3. 别把GetTensorDataAsSpan的结果缓存到字段里。这个 Span 指向的是 OnnxRuntime 内部缓冲，下一次Run可能复用同一块内存——缓存下来的"历史掩码"会被静默覆盖，表现为"结果突然全变了"。要存就ToArray()拷贝一份。

4. GPU 显存不是 .NET 管得了的。CUDA EP 的显存由 arena 管理，进程内GC.Collect()对显存毫无作用。显存持续增长时先检查是否每次Run都创建了新的OrtValue输入且未释放——输入 OrtValue 的Dispose会返还显存缓冲。实测中把输入也统一用using管理后，显存曲线从"线性爬升"变成"锯齿但不再发散"。

5. 用数据说话。不要靠感觉判断"内存是不是泄漏"，写个冒烟测试：连续 1000 次推理，采样 working set 与nvidia-smi显存，绘制曲线。平台化的判定标准是：曲线收敛于某个水位线而不是无限爬升——有波动正常，发散就是泄漏。

坑二：尺寸匹配——一套张量四处不一致

SAM3 的尺寸体系比任何单阶段检测器都复杂，C# 侧没有 Python 那套original_sizes自动传递，所有维度都要手动对齐。最容易踩的四个点：

维度	期望值	写错的症状
图像输入	[1, 3, 1008, 1008]	直接 shape mismatch 或图像被拉伸失真
文本输入	[1, 32]int64	token 超过 32 被截断，概念理解降级
掩码输出	[1, 200, 288, 288]	按 1008 索引会越界或掩码偏移
框输出	归一化 xyxy[0,1]	直接当像素坐标用，框全画到左上角

框提示（box prompt）是另一个高频雷区：输入框必须归一化到 1008 图像坐标系，即先除以原图宽高再做 letterbox 补偿，而不是直接传原始像素坐标。README 里 Transformers 用法给的是[batch, num_boxes, 4]的 xyxy，C# 侧要自行完成"像素坐标 → 1008 归一化坐标"的换算，这一步错了，框提示的分割结果会整体偏移。

坑三：GPU 利用率——算力没吃满的真相

很多人第一版 C# 实现跑完发现 GPU 利用率只有 20%~40%，第一反应是模型太大。实测下来，瓶颈几乎都在数据通路而不是算子上。排查优先级：

1. CPU 预处理是最大的隐形瓶颈。1008×1008×3 的 resize + 归一化 + pad 如果用手写循环，动辄 30~80ms，而 GPU 上 SAM3 单次推理本身量级也就百毫秒级——预处理直接把吞吐砍半。解法：ImageSharp 的 resize 支持硬件加速路径，归一化用TensorPrimitives（SIMD），且预处理与推理必须异步流水：worker 线程预先准备下一帧张量，推理线程只做Run。

// 生产者-消费者流水线：预处理线程 -> 推理线程 Channel<DenseTensor<float>> pipe = Channel.CreateBounded<DenseTensor<float>>(2); Task preprocessTask = Task.Run(() => ProduceFrames(pipe.Writer)); Task inferTask = Task.Run(() => ConsumeAndInfer(pipe.Reader, session));

2.GetTensorDataAsSpan之后的 C# 后处理会拖垮整条链路。200 个 query × 288×288 的 sigmoid + 插值 + NMS 全在 CPU 上做，这部分如果不并行化，GPU 会长时间空转等待。方案：sigmoid 用TensorPrimitives.Logistic向量化；掩码插值用Parallel.For按 query 分块；NMS 本身量级很小，单线程即可。

3. 检查DoCopyInDefaultStream与内存模式。输入张量从 CPU 拷贝到 GPU 走的是默认 CUDA stream，如果每次Run都走同步拷贝，GPU 空闲窗口会显著拉大。DoCopyInDefaultStream = true配合EnableMemoryPattern能压缩这部分开销。

4. batch 才是真正吃满算力的手段。SAM3 的 1008×1008 输入在单 batch 下 GPU 利用率天然不高，多路并发场景（比如视频帧流）把batch_size提到 4~8 往往能把利用率从 40% 拉到 80% 以上。代价是显存线性增长——OrtValue输入生命周期管理（坑一）此时从"优化项"升级为"必选项"。

六、写在最后

回看整个流程：环境配置、模型加载、推理后处理加起来一天能跑通，但真正决定生产可用性的，是那个"跑一万次不崩、显存不涨、GPU 不空转"的工程收敛过程。SAM3 的能力边界——开放词汇、穷尽实例、一次文本提示全图分割——在 Python demo 里是被 notebook 的容错环境庇护着的；搬到 C# 的 OnnxRuntime 里，每一处配置容错都要靠代码自己兜住。把 config.json 里那 288、1008、200、32 四个数字刻进脑子里，把 Session 生命周期和 OrtValue 释放写进 code review 清单，这台"分割机器"才算真正在你手里跑稳了。

【免费下载链接】sam3项目地址: https://ai.gitcode.com/hf_mirrors/facebook/sam3