SAHI HuggingFace 分割模型封装指南：MaskFormer / Mask2Former / OneFormer 实例·语义·全景分割

计算机视觉人工智能【免费下载链接】sahiFramework agnostic sliced/tiled inference interactive ui error analysis plots项目地址https://gitcode.com/gh_mirrors/sa/sahi点击查看免费下载本篇技术指南围绕 SAHI 的sahi.models.huggingface_segmentation模块展开系统讲解HuggingfaceSegmentationModel如何把 HuggingFace Transformers 生态的 MaskFormer、Mask2Former、OneFormer 统一封装为 SAHI 的DetectionModel并支持实例instance、语义semantic、全景panoptic三种分割任务头。读完本文你将掌握该类所有构造参数的含义与默认值、模型/处理器配对校验规则、三种任务头的后处理差异以及通过AutoDetectionModelget_sliced_prediction进行切片推理的完整实战用法并了解底层掩码转 COCO 多边形的实现细节。模块定位与设计思想HuggingfaceSegmentationModel是 SAHI 为 HuggingFace Transformers 分割模型提供的统一封装完整实现位于 sahi/models/huggingface_segmentation.py。它继承自HuggingfaceDetectionModel定义于 sahi/models/huggingface.py因此天然复用了父类已具备的 processor 管理、num_categories计算、token 处理、依赖检查torchtransformers且强制transformers 4.42.0等能力只在分割专属的逻辑上做扩展。这种继承检测封装、扩展分割能力的设计带来了两个直接好处统一推理入口分割模型与检测模型都走perform_inference→convert_original_predictions→ObjectPrediction的同一套管线切片推理、后处理合并等 SAHI 核心能力无需任何改动即可直接作用于分割任务输出格式统一每个分割片段segment被转换为一个带多边形掩码polygon mask的ObjectPrediction与检测框的ObjectPrediction结构一致方便下游统一消费。模块 docstring 明确指出其支持的模型范围Supports MaskFormer, Mask2Former, and OneFormer for instance, semantic, and panoptic segmentation via Hugging Face Transformers.即通过 Transformers 库支持三种架构 × 三种任务头。支持矩阵与模型/处理器注册表模块通过_SUPPORTED_MODELS字典源码 第 21-25 行维护模型类名 → processor 类名前缀的映射字符串形式是为了避免在模块导入阶段就急切加载 Transformers_SUPPORTED_MODELS: dict[str, str] { Mask2FormerForUniversalSegmentation: Mask2FormerImageProcessor, MaskFormerForInstanceSegmentation: MaskFormerImageProcessor, OneFormerForUniversalSegmentation: OneFormerProcessor, }由此得到支持矩阵与 docs/guides/models.md 中 HuggingFace Segmentation 一节的能力表一致架构instancesemanticpanopticMaskFormer✅✅✅Mask2Former✅✅✅OneFormer✅✅✅需要注意实际可用的任务头取决于 checkpoint。例如facebook/mask2former-swin-tiny-coco-instance仅支持实例分割这是测试常量中的真实取值见 tests/utils/huggingface.py 的HuggingfaceConstants。而OneFormer 会在推理时选择任务头因此同一个 checkpoint如shi-labs/oneformer_ade20k_swin_tiny即可服务于三种任务——这正是 OneFormer 架构的设计特性。分割类型枚举SegmentationType模块定义了 SegmentationType 枚举用于显式指定推理时要使用哪个任务头class SegmentationType(Enum): INSTANCE_SEGMENTATION instance SEMANTIC_SEGMENTATION semantic PANOPTIC_SEGMENTATION panoptic该枚举的字符串值instance/semantic/panoptic会被直接用作 OneFormer 处理器的task_inputs这一点在后续_pre_process一节会详细展开。构造参数详解HuggingfaceSegmentationModel.__init__源码 第 52-67 行在继承父类全部参数的基础上新增了 4 个分割专属参数同时把默认置信度阈值从父类的 0.3 收紧到 0.5def __init__( self, *args: Any, overlap_mask_area_threshold: float 0.8, label_ids_to_fuse: list[int] | None None, min_segment_area: int 100, segmentation_type: SegmentationType SegmentationType.INSTANCE_SEGMENTATION, **kwargs: Any, ) - None: ... # Segmentation models default to a stricter threshold than detection (0.3). kwargs.setdefault(confidence_threshold, 0.5)参数含义与适用范围如下参数类型默认值作用segmentation_typeSegmentationTypeINSTANCE_SEGMENTATION使用哪种分割任务头INSTANCE_SEGMENTATION、SEMANTIC_SEGMENTATION或PANOPTIC_SEGMENTATION不适配当前任务头的参数会被忽略min_segment_areaint100轮廓面积低于该像素值的分割片段会被丢弃见_extract_segmentsoverlap_mask_area_thresholdfloat0.8实例掩码内部重叠区域阈值用于合并或丢弃每个二值实例掩码中细小的不连通部分该值会透传给 processor 的后处理方法label_ids_to_fuselist[int]None仅全景分割panoptic使用将这些 label id 的所有实例融合为单个 segment例如天空sky在单张图中通常应是一个整体tokenstrNoneHuggingFace 访问令牌用于门控gated/私有模型为None时回退到环境变量$HF_TOKEN父类也支持该参数默认阈值差异代码注释明确说明 Segmentation models default to a stricter threshold than detection (0.3)即分割模型默认confidence_threshold0.5通过kwargs.setdefault实现调用方显式传入时不会被覆盖。这与 tests/test_huggingface_segmentation.py 中CONFIDENCE_THRESHOLD 0.5的测试约定一致。除上述参数外该类还完整继承父类HuggingfaceDetectionModel的参数在 sahi/models/huggingface.py 中定义包括model_path、model、processor、config_path、device、mask_threshold默认 0.5、confidence_threshold、category_mapping、category_remapping、load_at_init、image_size等。其中image_size若传入会在加载 processor 时强制把输入 resize 为size{height: image_size, width: image_size}并启用do_resize。模型加载流程load_modelload_model 是模型的入口加载逻辑流程如下校验model_path必须提供源码中ValueError(model_path must be provided for HuggingFace models)解析 tokenhf_token os.getenv(HF_TOKEN, self._token)即优先读取环境变量HF_TOKEN否则使用构造时传入的token加载模型通过AutoModelForUniversalSegmentation.from_pretrained(self.model_path, tokenhf_token)加载注意选用的是Universal通用入口因为 MaskFormer、Mask2Former、OneFormer 都属于通用分割模型家族构建 processor固定使用use_fastFalse。代码注释解释了原因use_fastTrue会抛出AttributeError: SizeDict object has no attribute keys这一限制同样存在于父类 sahi/models/huggingface.py 中属于 Transformers 快速图像处理器在部分模型上的已知兼容问题若传入了image_size则追加size{height: image_size, width: image_size}与do_resizeTrue强制统一输入分辨率装配调用self.set_model(model, processor)完成校验与挂载。模型/处理器配对校验set_modelset_model 承担了关键的安全校验职责防止用户把不匹配的模型与处理器组装在一起若 processor 为空直接抛出ValueError(processor is required to be set.)取出模型类名与 processor 类名用_SUPPORTED_MODELS查表得到期望的 processor 前缀按前缀匹配而非全等匹配注释说明 Newer transformers append backend suffixes (e.g. Mask2FormerImageProcessorPil), so match by prefix——新版 Transformers 会给 processor 类名追加后端后缀如Mask2FormerImageProcessorPil因此必须用startswith判断校验失败时抛出ValueError并打印全部受支持组合fInvalid model/processor pair: {model_name} {processor_name}. Supported: {_SUPPORTED_MODELS}校验通过后挂载self.model并model.to(self.device)保存 processor同时将self.category_mapping设置为model.config.id2label类别 id → 名称的映射来自模型配置。推理单张与批量perform_inferenceperform_inference 接收单张np.ndarray或图像列表执行一次前向inputs self._pre_process(image) with torch.no_grad(): outputs self.model(**inputs) images image if isinstance(image, list) else [image] self._original_shapes [(int(img.shape[0]), int(img.shape[1])) for img in images] self._original_predictions outputs前向包裹在torch.no_grad()中不追踪梯度原始图像尺寸(height, width)被记录为_original_shapes供后处理还原目标尺寸使用。perform_batch_inferenceperform_batch_inference 直接委托给perform_inference(images)即把整个图像列表一次性喂给 HuggingFace processor 与模型做一次原生批量前向而非逐张串行推理。_pre_processOneFormer 的 task 注入_pre_process 是推理前的关键适配逻辑其特殊性在于OneFormerkwargs: dict[str, Any] {images: image, return_tensors: pt} if self._is_oneformer(): seg_value self.segmentation_type.value n len(image) if isinstance(image, list) else 1 kwargs[task_inputs] [seg_value] * n inputs self.processor(**kwargs) for key in (pixel_values, pixel_mask, task_inputs): if key in inputs: inputs[key] inputs[key].to(self.device)_is_oneformer()通过模型类名是否等于OneFormerForUniversalSegmentation判断源码 第 126-127 行OneFormer 处理器要求task_inputs指定本次推理任务这里直接复用SegmentationType的字符串值instance/semantic/panoptic并按图像数量复制成列表送入模型前pixel_values、pixel_mask、task_inputs会被迁移到self.device。后处理三种任务头的差异化路径_post_process 根据segmentation_type分派到不同的 processor 后处理方法公共参数统一传递common: dict[str, Any] { threshold: self.confidence_threshold, mask_threshold: self.mask_threshold, overlap_mask_area_threshold: self.overlap_mask_area_threshold, target_sizes: target_sizes, }各分支行为如下segmentation_typeprocessor 方法后续处理SEMANTIC_SEGMENTATIONpost_process_semantic_segmentation_convert_semantic_to_binary_masksPANOPTIC_SEGMENTATIONpost_process_panoptic_segmentation传label_ids_to_fuse_convert_panoptic_to_binary_masksINSTANCE_SEGMENTATIONOneFormerpost_process_instance_segmentation无return_binary_maps_convert_panoptic_to_binary_masksINSTANCE_SEGMENTATIONMaskFormer / Mask2Formerpost_process_instance_segmentationreturn_binary_mapsTrue直接返回二值掩码代码注释明确解释了这种分支的必要性OneFormer 的实例输出格式与 panoptic 格式一致需要走转换而 MaskFormer / Mask2Former 可以直接输出二值掩码图binary maps。两个转换辅助函数保证输出结构统一为{segmentation: [二值掩码...], segments_info: [...]}_convert_semantic_to_binary_masks语义分割的输出是逐像素的类别 id 张量此函数按torch.unique(class_mask)拆分为每个 label 一个二值掩码segments_info中score恒为1.0语义分割没有逐实例置信度_convert_panoptic_to_binary_masks把 panoptic 的 id 张量按每个 segment id 拆成独立二值掩码并通过segments_info_map关联每个 id 的元信息score、label_id同时自动丢弃背景 id没有对应segments_info的 id 不产出。片段提取掩码 → COCO 多边形 → ObjectPrediction_extract_segments 是把后处理结果变成可用预测的核心环节逐段执行从post_processed_output取出segmentation二值掩码列表与segments_info对每个 segment 的二值掩码bool_mask segment.cpu().numpy().astype(bool)面积过滤if bool_mask.sum() self.min_segment_area: continue即小于min_segment_area默认 100像素的片段被直接跳过调用 get_coco_segmentation_from_bool_mask定义于 sahi/utils/cv.py把二值掩码转为 COCO 多边形格式[[x1, y1, x2, y2, ...], ...]——该工具内部用cv2.findContours提取轮廓、cv2.CHAIN_APPROX_SIMPLE压缩点集并丢弃点数不足 3 个即边长小于 6 的扁平多边形的无效轮廓多边形为空则跳过否则记录coco_segmentation、score来自segments_info[score]、category_id来自segments_info[label_id]。随后 _create_object_prediction_list_from_original_predictions 为每个图像构造ObjectPredictionObjectPrediction( bboxNone, # 分割模型不产出框 segmentationsegment, # COCO 多边形列表 category_idcategory_id, category_nameself.category_mapping[category_id], # 来自 model.config.id2label shift_amountshift_amount, scorescore, full_shapefull_shape, )注意bboxNone分割模型的结果以掩码为主SAHI 允许ObjectPrediction无 bbox 而仅有 segmentation。shift_amount_list与full_shape_list分别经 fix_shift_amount_list / fix_full_shape_list 规范化兼容 sahi v0.8.15 及更早的接口形态用于在切片推理时把掩码从切片坐标平移回原图坐标。实战完整推理示例以下用法与 docs/guides/models.md HuggingFace Segmentation 一节的官方示例保持一致。依赖安装pip install transformers timm安装timm是因为 MaskFormer / Mask2Former / OneFormer 等模型在 Transformers 中通常依赖 timm 提供的主干网络实现。通过 AutoDetectionModel 加载并做切片推理huggingface_segmentation已注册进 AutoDetectionModel 的模型类型映射表huggingface_segmentation: HuggingfaceSegmentationModel可直接按类型加载from sahi import AutoDetectionModel from sahi.models.huggingface_segmentation import SegmentationType from sahi.predict import get_sliced_prediction detection_model AutoDetectionModel.from_pretrained( model_typehuggingface_segmentation, model_pathfacebook/mask2former-swin-tiny-coco-instance, confidence_threshold0.5, devicecuda:0, # 或 cpu segmentation_typeSegmentationType.INSTANCE_SEGMENTATION, ) result get_sliced_prediction( image.jpg, detection_model, slice_height512, slice_width512, )把segmentation_type切换为SEMANTIC_SEGMENTATION或PANOPTIC_SEGMENTATION即可使用对应的任务头。注意语义分割会把同一类别的所有实例合并进一个掩码因此每个类别只会返回一个ObjectPrediction而不是为每个实例分别返回这是 docs/guides/models.md 明确提示的行为差异。切片推理的常用参数定义于 sahi/predict.py 的get_sliced_prediction参数默认值说明slice_height/slice_widthNone每个切片tile的像素尺寸配合auto_slice_resolutionTrue时 SAHI 会根据图像分辨率自动选取overlap_height_ratio/overlap_width_ratio0.2相邻切片的重叠比例0.0~1.0保证跨切片边界的目标至少完整出现在一个切片中perform_standard_predTrue是否额外对整图做一次原生分辨率推理以捕获被切碎的大目标postprocess_typeGREEDYNMM切片结果合并策略GREEDYNMM贪心均值合并默认、NMM、NMSpostprocess_match_metricIOS匹配度量IOS交并小集更激进或IOU更保守postprocess_match_threshold0.5高于该重叠度阈值的切片预测会被合并/抑制batch_size1批量推理大小1 时利用perform_batch_inference的原生批量前向加速verbose10 静默、1 打印切片数、2 额外打印各阶段耗时由于分割模型输出的每个 segment 都是带多边形掩码的ObjectPrediction切片推理、跨切片重复预测的合并NMM/NMS 等都与检测模型走完全相同的管线无需任何额外适配——这正是本文开头所述统一抽象设计带来的实战红利。单图推理若无需切片直接用get_prediction定义于 sahi/predict.pyfrom sahi.predict import get_prediction result get_prediction( imageimage.jpg, detection_modeldetection_model, shift_amount[0, 0], full_shapeNone, postprocessNone, )shift_amount为[shift_x, shift_y]用于把预测从切片坐标平移到全图坐标full_shape为[height, width]不传时自动取输入图像尺寸。测试佐证覆盖矩阵与精度断言test_huggingface_segmentation.py 用一组参数化用例覆盖了3 架构 × 3 任务头的完整组合测试注释说明MaskFormer 与 OneFormer 各用单一 checkpoint 服务三种任务头Mask2Former 每个任务头一个 checkpointCASES [ pytest.param(C.MASK2FORMER_INSTANCE_MODEL_PATH, INSTANCE, idmask2former-instance), pytest.param(C.MASK2FORMER_SEMANTIC_MODEL_PATH, SEMANTIC, idmask2former-semantic), pytest.param(C.MASK2FORMER_PANOPTIC_MODEL_PATH, PANOPTIC, idmask2former-panoptic), pytest.param(C.MASKFORMER_MODEL_PATH, INSTANCE, idmaskformer-instance), ... pytest.param(C.ONEFORMER_MODEL_PATH, PANOPTIC, idoneformer-panoptic), ]测试中使用的真实 checkpoint 路径见 tests/utils/huggingface.pyMask2Formerfacebook/mask2former-swin-tiny-cityscapes-{instance,semantic,panoptic}MaskFormerfacebook/maskformer-swin-tiny-cocoOneFormershi-labs/oneformer_ade20k_swin_tiny测试断言assert_valid_segments校验每个ObjectPredictionscore confidence_threshold、mask is not None、mask.segmentation非空。其中最值得关注的是精度用例test_get_prediction_detects_cars通过AutoDetectionModel加载 Mask2Former 实例分割 checkpoint 后在测试图tests/data/small-vehicles1.jpeg上推理断言检测到的car类别片段数不少于 5 个从端到端验证了加载 → 推理 → 掩码提取 → 类别映射整条链路的正确性。此外test_get_sliced_prediction直接对分割模型调用切片推理切片尺寸约为原图的 2/3、batch_size4、关闭整图标准推理验证了分割模型与切片推理管线的兼容性。常见问题与注意事项use_fastFalse不可省略快速 processor 在分割模型上存在已知兼容问题SizeDict object has no attribute keys模块在加载与 image_size 重设场景下都固定使用慢速 processorprocessor 类名按前缀匹配新版 Transformers 会为 processor 追加Pil等后端后缀set_model的前缀匹配策略保证此类模型仍能通过校验OneFormer 的实例输出走 panoptic 转换路径不要因输出格式差异而困惑这是由 Transformers processor 的接口形态决定的语义分割无逐实例置信度转换后每个类别的score恒为1.0类别维度聚合到单掩码label_ids_to_fuse仅对 panoptic 生效例如把sky的 id 加入列表可将整幅图中所有天空碎片融合为一个 segment避免同一语义区域被拆成多个小段min_segment_area与overlap_mask_area_threshold协同控制掩码质量前者丢弃过小的轮廓后者在实例掩码内部合并/丢弃细小不连通区域两者默认值100 / 0.8在多数场景下可直接使用。小结HuggingfaceSegmentationModel以最小成本把 Transformers 生态最主流的三种通用分割架构接入 SAHI 的切片推理与后处理体系模型加载、processor 配对校验、OneFormer 任务注入、三路后处理分派、掩码转 COCO 多边形、ObjectPrediction统一输出全链路都在 sahi/models/huggingface_segmentation.py 这一个模块内闭环实现。借助AutoDetectionModel.from_pretrained(model_typehuggingface_segmentation, ...)一行注册即用再配合 docs/guides/models.md 中的参数表和 tests/test_huggingface_segmentation.py 的覆盖用例你可以快速把 MaskFormer / Mask2Former / OneFormer 部署到自己的实例、语义或全景分割任务中。赞分享计算机视觉人工智能【免费下载链接】sahiFramework agnostic sliced/tiled inference interactive ui error analysis plots项目地址https://gitcode.com/gh_mirrors/sa/sahi点击查看免费下载相关推荐SAHI 接入 HuggingFace 分割模型MaskFormer / Mask2Former / OneFormer 的实例、语义与全景分割实战SAHI 接入 HuggingFace 分割模型MaskFormer / Mask2Former / OneFormer 的实例、语义与全景分割实战 SAHI计算机视觉人工智能Transformers 中的 MaskFormer以掩码分类范式统一语义分割与全景分割的完整指南Transformers 中的 MaskFormer以掩码分类范式统一语义分割与全景分割的完整指南 本文是围绕 Transformers 仓库内 MaskFo人工智能大模型深度学习NLP预训练微调模型推理服务如何快速掌握多模态Transformers文本、图像、音频融合AI的完整指南如何快速掌握多模态Transformers文本、图像、音频融合AI的完整指南 在当今AI技术飞速发展的时代 多模态Transformers 已成为人工智能领人工智能大模型深度学习NLP预训练微调模型推理服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考