简介面向计算机视觉研究与工程开发者的快速目标分割FastSAM完整实现包针对图像与视频中任意目标分割的实时性与精度平衡问题适合具备一定深度学习基础、需要快速落地分割算法的中高级开发者。压缩包共53个文件约39.52MB涵盖Python源码、预训练模型配置yaml、示例图片png/jpg、说明文档md/pdf及许可证等其中推理、解码、提示模块划分清晰便于按需复用与二次开发。已有532人学习下载。资源内不仅提供FastSAM核心算法实现与Gradio交互演示还附带多场景示例图片及异常检测、显著性目标等效果展示可帮助读者快速复现分割流程理解动态阈值与轻量网络优化策略配合代码与文档能直接用于自动驾驶、视频监控、医疗影像等场景的算法选型与定制改造。1. 快速目标分割是什么不是又一个 SAM而是把 SAM 压到能跑生产的速度做视觉检测落地的人大概都有同感SAM 出来的时候效果惊艳但真拿到产线上用单张图几百毫秒到一秒多的推理速度直接让“交互式分割”变成了“演示级功能”。工业场景里我们要的是快速目标分割一张图进来几十毫秒出掩码要么接机械臂抓取要么做质检 ROI 提取没有人会对着屏幕慢慢点 prompt。FastSAM 就是冲着这个矛盾来的——它把 SAM 的 Transformer 主体换成了 YOLOv8-seg 的卷积结构用传统目标检测的流程先找框、再对每个框生成掩码在 CPU 上能做到每秒几张图GPU 上配合 TensorRT 能跑到实时。这个方案能解决什么问题简单说就是把“分割”从离线分析工具变成在线视觉系统的第一环。适合三类人一是做工业质检想快速圈出缺陷区域的二是做边缘设备视觉方案需要目标分割但不具备大显存条件的三是刚接触分割模型、想在本地快速跑通效果的。这篇文章围绕 fastsam c tensorrt 这条主线把模型原理、导出流程、C 工程化落地和调参避坑完整过一遍目标是让读者跟着做完后能自己把 FastSAM 部署到实际项目里。2. FastSAM 的模型结构与推理路径为什么它比 SAM 快这么多2.1 从 SAM 到 FastSAM把 prompt 分割改成实例分割理解 FastSAM 之前先要清楚 SAM 的完整链路。SAM 需要两个输入一张图像和一个 prompt点、框或掩码。图像先过 ViT 编码器生成 image embeddingprompt 再过 prompt encoder两者在 mask decoder 里融合输出多个掩码和对应的 confidence。这个链条中ViT 的全局注意力是大算力消耗点一张 1024x1024 的图像嵌入计算在普通 GPU 上就要几百毫秒。FastSAM 的设计思路是彻底绕开 prompt 这个交互过程。它用 YOLOv8-seg 的 C2f 卷积结构做 backbone直接输出一组候选框、每个框的类别和对应的掩码系数。推理时只需输入图像输出就包含“哪个位置有东西、是什么类别、长什么样”的完整信息。本质上FastSAM 是一个实例分割模型而不是交互式分割模型。这意味着它是为批处理、全自动管线设计的不是给人在图上点点的。这里有一个关键差异值得注意FastSAM 输出的掩码质量不如 ViT 编码器加 mask decoder 的组合精细。尤其在小目标或遮挡严重的区域FastSAM 的掩码边缘会出现锯齿或空洞。但它带来的收益是推理链路从两段式变成单段式没有 prompt 编码环节也没有迭代 refinement计算图短了工程化难度也随之下降。用在大分辨率图或视频流上这个取舍是划算的。因为实例分割输出可以直接接下游的 ROI 提取、缺陷统计、目标计数不需要人为参与。2.2 输出格式拆解不要把检测框和掩码数组搞混FastSAM 的输出其实就是 YOLOv8-seg 的典型输出一组检测结果加一组随框附带的掩码。具体结构为对于每个检测到的目标输出包含 box 坐标x1, y1, x2, y2、置信度分数、类别 ID以及一个由掩码系数和 prototype mask 线性组合得到的二进制掩码。在 Python 端使用 Ultralytics 推理时返回的结果对象包含boxes和masks两个属性。masks是二值化后的掩码每个目标的掩码大小与原始图像尺寸相同如果设置了retina_masksTrue或者是固定的 640x640默认。这里容易踩坑的是掩码数组是布尔类型不是浮点数概率图拿去存成 PNG 时要注意类型转换。C 端处理输出的逻辑要区分两个阶段。第一阶段是网络输出的原始张量形状为[1, 总候选数, 4 1 类别数 掩码系数数]这是未经过 NMS 的密集预测。第二阶段是后处理后得到的最终结果。TensorRT 推理时你拿到的是第一个阶段的原始输出需要在 C 里自己完成 NMS、掩码系数与 prototype 的矩阵乘法、以及阈值过滤。这不难但必须提前设计好内存布局否则后处理的耗时会超过网络本身。常见做法是定义两个输出张量一个用于检测头输出box、score、class、mask coefficients一个用于 prototype masks形状为[1, 32, 160, 160]后者要与掩码系数做矩阵乘法生成最终掩码。prototype 数量和掩码系数维度是网络超参默认配置下通常为 32 维。这个数字如果记错后处理时的矩阵维度就会对不上程序会直接崩溃。3. 本地跑通 FastSAM从安装到导出 ONNX 的最小实验3.1 用 Python 先验证模型效果再谈部署先把环境搭起来。我一般用一个干净的 conda 环境不跟其他项目混装依赖。Python 版本建议选 3.9 或 3.10Ultralytics 对这两个版本支持最稳。安装命令如下。conda create -n fastsam_demo python3.10 -y conda activate fastsam_demo pip install ultralytics opencv-python onnx onnxsim安装完成后写一个最小推理脚本验证模型能否正常工作。Ultralytics 库内部已经集成了 FastSAM 的支持不需要额外改装。from ultralytics import FastSAM from ultralytics.models.fastsam import FastSAMPrompt import cv2 model FastSAM(FastSAM-s.pt) img cv2.imread(demo.jpg) img cv2.cvtColor(img, cv2.COLOR_BGR2RGB) results model(img, devicecuda:0, retina_masksTrue, conf0.4, iou0.9) prompt_process FastSAMPrompt(img, results) anns prompt_process.everything_prompt()这段代码里FastSAM-s.pt是小型权重适合先验证流程。everything_prompt()的含义很直接不提供任何 prompt让模型全图输出所有检测到的目标的掩码。conf0.4是置信度阈值低于这个值的检测框会被丢弃iou0.9是 NMS 的 IoU 阈值值越大保留的重复框越多掩码覆盖会更完整但也会更杂。如果发现图上的目标被漏检先把conf调低到 0.25 试试如果发现同一物体上堆叠了多个掩码把iou调低到 0.7 或 0.5 会好一些。这一步的目的一是确认模型在你的机器上能跑二是观察不同阈值对输出的影响。记录下你在验证集上认为“可用”的那组conf和iou值后面 C 部署时要保持一致的阈值逻辑否则两边效果会对不上。3.2 导出 ONNX把 PyTorch 模型变成部署中间格式FastSAM 是 PyTorch 模型生产环境通常不会直接用 PyTorch 跑推理。常见做法是先导出 ONNX再由 ONNX 转成 TensorRT 引擎。Ultralytics 提供了导出接口命令如下。yolo export modelFastSAM-s.pt formatonnx opset12 simplifyTrue这里的opset值得注意。TensorRT 8.x 对 ONNX opset 的兼容范围一般是 11 到 17opset12 兼容性最好既不缺少新算子也不会因为版本过高导致部分老算子被错误映射。simplifyTrue会调用 onnx-simplifier 对计算图做常量折叠和冗余节点删除。这一步对后续 TensorRT 转换帮助很大能减少转换时的未支持算子数量和显存占用。导出完成后使用 onnxruntime 做一次基准验证确认导出的模型和 PyTorch 原模型输出一致。import onnxruntime as ort import numpy as np sess ort.InferenceSession(FastSAM-s.onnx, providers[CUDAExecutionProvider]) input_name sess.get_inputs()[0].name input_shape sess.get_inputs()[0].shape print(input_name, input_shape) dummy_input np.random.randn(1, 3, 640, 640).astype(np.float32) outputs sess.run(None, {input_name: dummy_input}) for i, out in enumerate(outputs): print(foutput {i}: shape {out.shape})这段代码的作用有两个。一是确认导出后的输入输出名称和形状这在后续 TensorRT 的 C 绑定中要直接使用。二是用随机张量跑一次推理验证模型在 ONNX Runtime 下不报错。注意这里输出张量会有多个取决于导出时的配置。FastSAM 的 ONNX 输出包含检测分支和掩码分支具体数量和名称可以在打印结果中确认每个引擎都不一定相同所以把这一步的打印信息保存下来后面 C 代码里需要写死这些名字和维度。3.3 导出时的常见失败opset 和动态尺寸怎么选导出过程不会总是顺利。常见一个问题导出时报Unsupported operator错误。解决办法是修改 opset 版本或者升级 ultralytics 到最新版因为新版本会使用更新版本的算子。如果升级后错误仍存在检查模型文件中是否有自定义算子。FastSAM 基于 YOLOv8-seg理论上没有自定义算子出现这个错误大概率是 opset 版本太低。另一个高频问题是动态尺寸。导出时默认的输入是[1, 3, 640, 640]固定尺寸。如果你的业务图分辨率多变可以尝试导出动态 H、W命令加dynamicTrue。但我的建议是在 TensorRT 部署阶段不要用动态尺寸除非你的业务确实需要。动态尺寸会让 TensorRT 在推理时做输入尺寸切换优化器会为多个 shape 生成多个优化方案显存占用上升推理速度下降。固定 640x640 输入预处理阶段用 letterbox 把图像等比缩放到这个尺寸是业界最稳的做法也是 FastSAM 在训练时就使用的尺寸。4. TensorRT 部署 FastSAM 的工程化路径C 推理与后处理4.1 从 ONNX 到 TensorRT 引擎trtexec 参数与显存控制在 C 工程中集成 TensorRT 前先把 ONNX 转成 TensorRT 引擎文件通常后缀.engine。命令行转换和代码转换都可行工程期我会先用trtexec把参数验证清楚再写进 C 代码。命令如下。trtexec --onnxFastSAM-s.onnx \ --saveEngineFastSAM-s.engine \ --fp16 \ --minShapesimages:1x3x640x640 \ --optShapesimages:1x3x640x640 \ --maxShapesimages:1x3x640x640这段命令里--fp16是关键。TensorRT 开启 FP16 后在多数 NVIDIA 显卡上能让推理速度翻倍以上。但注意FP16 对某些算子的精度有影响如果后处理时发现掩码质量明显下降可以去掉--fp16跑一版 FP32 引擎对比。生产环境通常的做法是两种精度都生成做一次批量测试来决定。--minShapes/--optShapes/--maxShapes三个参数用于固定输入形状。由于这里都填了1x3x640x640TensorRT 不会为动态尺寸做任何额外优化引擎体积更小加载更快。如果你的显存有限比如 4GB 以下可以考虑在转换时加上--workspace2048限制工作区大小避免转换过程显存溢出。转换过程中输出大量日志重点看最后几行的[Detected 1 inputs and 2 outputs]以及Engine generated in ...。如果转换失败基本是 ONNX 导出时的问题比如算子不兼容、opset 过旧回头重新导出即可。这个步骤的目标是得到一个固定输入、固定输出的.engine文件后续 C 推理不再需要任何 ONNX 相关的库。4.2 C 加载引擎一个能直接抄的推理类骨架TensorRT C API 读引擎并做推理核心代码量其实不大。下面是一个最小可用的类骨架包含引擎加载、输入输出绑定和单张图推理的完整流程。#include fstream #include vector #include cuda_runtime_api.h #include NvInfer.h using namespace nvinfer1; class FastSAMInferencer { public: bool loadEngine(const std::string enginePath) { std::ifstream file(enginePath, std::ios::binary); file.seekg(0, std::ios::end); size_t size file.tellg(); file.seekg(0, std::ios::beg); std::vectorchar blob(size); file.read(blob.data(), size); file.close(); runtime createInferRuntime(gLogger); engine runtime-deserializeCudaEngine(blob.data(), size, nullptr); context engine-createExecutionContext(); return engine ! nullptr; } bool inference(const float* input, size_t inputSize, std::vectorfloat* outputs, const std::vectorsize_t outputSizes) { // 分配 GPU 显存 void* buffers[3]; cudaMalloc(buffers[0], inputSize * sizeof(float)); cudaMemcpy(buffers[0], input, inputSize * sizeof(float), cudaMemcpyHostToDevice); for (int i 0; i outputs.size(); i) { cudaMalloc(buffers[i 1], outputSizes[i] * sizeof(float)); } // 推理 context-setTensorAddress(images, buffers[0]); context-setTensorAddress(output0, buffers[1]); context-setTensorAddress(output1, buffers[2]); context-enqueueV3(stream); // 拷贝回主机 cudaMemcpy(outputs[0], buffers[1], outputSizes[0] * sizeof(float), cudaMemcpyDeviceToHost); cudaMemcpy(outputs[1], buffers[2], outputSizes[1] * sizeof(float), cudaMemcpyDeviceToHost); return true; } private: IRuntime* runtime; ICudaEngine* engine; IExecutionContext* context; cudaStream_t stream; };这段代码使用的setTensorAddress是 TensorRT 8.5 之后推荐的绑定方式相比旧的enqueue加setBinding方式更直观。需要特别留意的是images、output0、output1这几个名称它们必须与引擎中实际名称完全一致。名称可以在导出 ONNX 时打印也可以用engine-getIOTensorName(i)遍历得到。代码中没有处理错误释放实际项目中 GPU 显存和 stream 都要在析构函数中释放否则长时间运行会累计显存碎片。4.3 预处理与后处理letterbox 与掩码重建是正确率的分水岭预处理阶段图像需要经过 letterbox 等比缩放后填充到 640x640然后做归一化。这一步直接影响检出率如果直接用cv::resize把非 640x640 的图拉成 640x640会让目标比例失真小目标检测率明显下降。void letterbox(const cv::Mat src, cv::Mat dst, int targetSize 640) { float scale std::min(targetSize * 1.0f / src.cols, targetSize * 1.0f / src.rows); int newW round(src.cols * scale); int newH round(src.rows * scale); cv::Mat resized; cv::resize(src, resized, cv::Size(newW, newH), 0, 0, cv::INTER_LINEAR); dst cv::Mat(targetSize, targetSize, CV_8UC3, cv::Scalar(114, 114, 114)); resized.copyTo(dst(cv::Rect((targetSize - newW) / 2, (targetSize - newH) / 2, newW, newH))); }114, 114, 114是 YOLO 系列训练时使用的填充色不要随意改。缩放插值用INTER_LINEAR即可不需要换更高级的插值。归一化方面常见做法是把像素减去 0 再除以 255或者使用 ImageNet 均值方差。FastSAM 是基于 COCO 训练的训练时用的是简单的除以 255不涉及 ImageNet 归一化。如果你用了 ImageNet 均值方差去做预处理模型输出会完全乱掉。后处理需要重建掩码。网络输出的 raw mask 不是一张可以直接用的二值图需要将检测头的掩码系数与 prototype mask 做矩阵乘法。流程为第一步对检测头的输出做置信度过滤第二步对剩余框做 NMS第三步将过滤后的框对应的掩码系数与 prototype 矩阵相乘第四步用 sigmoid 激活且阈值化并恢复到原始图像坐标。最后一步的坐标映射最容易被忽略。letterbox 在图上加了边距后处理时掩码坐标必须减去边距偏移并除以缩放系数才能对齐到原始图像。如果漏了这一步掩码位置会整体偏移看起来像检测框和分割区域错位。5. FastSAM 部署避坑与性能排查TenosrRT 场景下最容易翻车的五个问题5.1 引擎加载成功后推理结果全零先查输入 buffer 的名称和维度现象TensorRT 引擎加载无报错但推理后输出数值全部为 0 或接近 0。原因输入张量的名称绑定错误或者输入 buffer 的维度与引擎期望不一致。TensorRT 8.5 之后如果某个张量绑定地址为 null 或尺寸不匹配部分引擎会静默输出 0 而不是报错。解决在代码中遍历所有 I/O 张量名称并打印确认images的实际名称。另外打印context-getTensorShape(images).d[i]检查维度是否为[1, 3, 640, 640]。如果维度中出现了动态值如 -1说明引擎没有完全固定 shape需要回到 trtexec 阶段补全 min/opt/max shape 参数。5.2 FP16 引擎掩码明显变差不要盲目关掉 FP16现象同一模型 FP32 引擎掩码质量正常FP16 引擎掩码出现大量空洞、边缘破碎、目标丢失。原因FP16 的精度范围有限尤其是掩码分支中的 sigmoid 激活和矩阵乘法对精度敏感。某些目标的置信度恰好落在阈值附近时FP16 引擎的输出可能会波动。解决先用性能测试确认 FP16 的实际收益。有些 GPU如 Tesla T4、RTX 3090对卷积算子的 FP16 加速明显但掩码重建涉及的矩阵乘法未必快很多。我的做法是保留两版引擎视觉验证阶段用 FP32正式跑稳定流程时用 FP16 并做全量回归测试。如果回归测试的掩码质量差异在可接受范围内才最终切换 FP16。5.3 C 后处理掩码坐标偏移忘了 letterbox 的边距现象检测框位置准确但掩码区域整体向右下偏移偏移量随目标在图像中的位置变化。原因网络输入是 letterbox 后的 640x640 图网络输出的掩码坐标对应的是这张填充后的图。后处理时直接按 640 尺寸解析掩码没有把边距和缩放比例换算回原图坐标导致坐标错位。解决后处理阶段记录 letterbox 产生的参数缩放比例 scale 和填充偏移 padX、padY。掩码的每个像素坐标映射公式为origX (maskX - padX) / scaleorigY (maskY - padY) / scale。这一步不是可选项是必须做的否则下游 ROI 提取拿到的区域是错的。5.4 推理耗时远超预期先看 NMS 是不是没实现好现象GPU 利用率正常但整体耗时高单张图推理 40ms后处理却要 80ms。原因TensorRT 只负责网络推理后处理在 CPU 上完成。如果掩码重建直接用循环逐像素处理或者 NMS 用三层嵌套循环写 O(n^3) 复杂度后处理时间会轻松超过网络推理时间。解决把 NMS 改用向量化的方式或者直接用 TensorRT 的 EfficientNMS 插件在 GPU 上完成。掩码重建用矩阵乘法而不是逐像素循环。C 中可以用cv::Mat::mul配合 precomputed 系数一次性完成效率远高于遍历像素。对于 640x640 输入优化好的后处理应该控制在 5ms 以内。5.5 多线程推理时显存不足或线程崩溃现象开了 4 个线程同时跑推理程序报显存分配失败或 cudaErrorIllegalAddress最后进程崩溃。原因每个线程独立创建了IExecutionContext但没有共享ICudaEngine。TensorRT 的 engine 是线程安全的可以多线程共享execution context 是线程独立的。显存不足往往是因为每个 context 都重复分配了输入输出缓冲或者没有正确释放旧的 buffer。解决全局只加载一个 engine每个线程创建独立的IExecutionContext和对应的显存缓冲。上下文的数量需要控制在显存允许范围内。对于 640x640 输入每个 context 大约占用 200~500MB 显存根据显卡容量计算上限。线程数不要盲目跟 CPU 核数保持一致以 GPU 利用率曲线为准一般 2~4 个线程即可把消费级 GPU 跑满。6. 性能调优与验证技巧用 TensorRT 把推理推到实时之后该做什么模型跑通只是第一步把性能调到稳定可用的状态需要几轮验证。以一张 1080p 输入图为基准我的调优步骤是先量化网络耗时再量化后处理耗时最后优化整体管线。网络耗时用cudaEvent前后打点测量后处理耗时用std::chrono测量。两者分开统计不要混在一起看总帧率否则无法定位瓶颈在哪。如果网络耗时高优先看显卡型号和 FP16 是否开启。在 RTX 3060 上FP16 开启后 FastSAM-s 的网络推理时间大约能从 40ms 降到 18ms 上下。FP32 转 FP16 不掉点的情况下这一步收益最大。如果后处理耗时长优先把掩码重建改成 GPU 计算。使用 TensorRT 的 INetworkDefinition 把掩码重建部分也放进引擎里或者使用 CUDA kernel 实现 sigmoid 加阈值化降低 CPU 侧的处理压力。验证阶段建议准备三类测试图。第一类是标准场景图验证模型基准精度第二类是含大量小目标的密集场景图验证 NMS 的阈值是否合适第三类是边缘情况比如全黑图、过曝图、纯色图确保后处理不会因为候选框为 0 或候选框过多而崩溃。每类图至少 50 张统计掩码的平均 IoU 和置信度分布对比 PyTorch 原模型的输出。这里我的习惯是保存一份 Python 端的标准输出作为 goldenC 端把输出存成相同的格式后逐像素比对误差在 1% 以内就算通过。还有一个经常被忽略的环节是显存复用。输入输出的 buffer 不要在每帧推理时重新分配而是在初始化阶段一次性分配并复用。这个改动看似小但对稳定运行的影响很大。帧率图上如果出现周期性掉帧大概率是显存分配导致的延迟。最后我个人的习惯是保留一份 trtexec 转换命令的脚本和 PyTorch 推理脚本每次换显卡或换模型版本时完整跑一遍从验证到 C 集成的流程而不是只改一个路径参数。换设备后引擎必须重新生成旧设备的 engine 文件在另一张卡上并不能直接复用。FastSAM 的工程化难度相对 SAM 已经低了一个级别但它的精度上限也摆在那里。小目标、遮挡和复杂边缘场景下它仍然会出现掩码不完整的问题这一点需要在使用前就跟需求方说清楚。希望这份部署笔记能帮你少走一些弯路少踩一些我在 TensorRT 集成时踩过的坑。本文还有配套的精品资源点击获取