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

原创2026-10-12 20:42:431,863 阅读
文章标签:人工智能计算机视觉深度学习图像处理

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

本篇技术指南围绕 SAHI 的 sahi.models.huggingface_segmentation 模块展开,系统讲解 HuggingfaceSegmentationModel 如何把 HuggingFace Transformers 生态的 MaskFormer、Mask2Former、OneFormer 统一封装为 SAHI 的 DetectionModel,并支持实例(instance)、语义(semantic)、全景(panoptic)三种分割任务头。读完本文,你将掌握该类所有构造参数的含义与默认值、模型/处理器配对校验规则、三种任务头的后处理差异,以及通过 AutoDetectionModel + get_sliced_prediction 进行切片推理的完整实战用法,并了解底层掩码转 COCO 多边形的实现细节。

模块定位与设计思想

HuggingfaceSegmentationModel 是 SAHI 为 HuggingFace Transformers 分割模型提供的统一封装,完整实现位于 sahi/models/huggingface_segmentation.py。它继承自 HuggingfaceDetectionModel(定义于 sahi/models/huggingface.py),因此天然复用了父类已具备的 processor 管理、num_categories 计算、token 处理、依赖检查(torch + transformers,且强制 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" 一节的能力表一致):

架构 instance semantic panoptic
MaskFormer ✅ ✅ ✅
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.5:

def __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_type SegmentationType INSTANCE_SEGMENTATION 使用哪种分割任务头:INSTANCE_SEGMENTATION、SEMANTIC_SEGMENTATION 或 PANOPTIC_SEGMENTATION;不适配当前任务头的参数会被忽略
min_segment_area int 100 轮廓面积低于该像素值的分割片段会被丢弃(见 _extract_segments)
overlap_mask_area_threshold float 0.8 实例掩码内部重叠区域阈值,用于合并或丢弃每个二值实例掩码中细小的不连通部分,该值会透传给 processor 的后处理方法
label_ids_to_fuse list[int] None 仅全景分割(panoptic)使用:将这些 label id 的所有实例融合为单个 segment(例如天空"sky"在单张图中通常应是一个整体)
token str None HuggingFace 访问令牌,用于门控(gated)/私有模型;为 None 时回退到环境变量 $HF_TOKEN(父类也支持该参数)

默认阈值差异:代码注释明确说明 "Segmentation models default to a stricter threshold than detection (0.3)",即分割模型默认 confidence_threshold=0.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_model

load_model 是模型的入口加载逻辑,流程如下:

  1. 校验 model_path:必须提供(源码中 ValueError("model_path must be provided for HuggingFace models"));
  2. 解析 token:hf_token = os.getenv("HF_TOKEN", self._token),即优先读取环境变量 HF_TOKEN,否则使用构造时传入的 token;
  3. 加载模型:通过 AutoModelForUniversalSegmentation.from_pretrained(self.model_path, token=hf_token) 加载;注意选用的是 Universal(通用)入口,因为 MaskFormer、Mask2Former、OneFormer 都属于通用分割模型家族;
  4. 构建 processor:
    • 固定使用 use_fast=False。代码注释解释了原因:use_fast=True 会抛出 AttributeError: 'SizeDict' object has no attribute 'keys'(这一限制同样存在于父类 sahi/models/huggingface.py 中,属于 Transformers 快速图像处理器在部分模型上的已知兼容问题);
    • 若传入了 image_size,则追加 size={"height": image_size, "width": image_size} 与 do_resize=True,强制统一输入分辨率;
  5. 装配:调用 self.set_model(model, processor) 完成校验与挂载。

模型/处理器配对校验 set_model

set_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 并打印全部受支持组合:f"Invalid 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_inference

perform_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_inference

perform_batch_inference 直接委托给 perform_inference(images),即把整个图像列表一次性喂给 HuggingFace processor 与模型,做一次原生批量前向,而非逐张串行推理。

_pre_process:OneFormer 的 task 注入

_pre_process 是推理前的关键适配逻辑,其特殊性在于 OneFormer:

kwargs: 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_type processor 方法 后续处理
SEMANTIC_SEGMENTATION post_process_semantic_segmentation _convert_semantic_to_binary_masks
PANOPTIC_SEGMENTATION post_process_panoptic_segmentation(传 label_ids_to_fuse) _convert_panoptic_to_binary_masks
INSTANCE_SEGMENTATION(OneFormer) post_process_instance_segmentation(无 return_binary_maps) _convert_panoptic_to_binary_masks
INSTANCE_SEGMENTATION(MaskFormer / Mask2Former) post_process_instance_segmentation(return_binary_maps=True) 直接返回二值掩码

代码注释明确解释了这种分支的必要性: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 是"把后处理结果变成可用预测"的核心环节,逐段执行:

  1. 从 post_processed_output 取出 segmentation(二值掩码列表)与 segments_info;
  2. 对每个 segment 的二值掩码 bool_mask = segment.cpu().numpy().astype(bool);
  3. 面积过滤:if bool_mask.sum() < self.min_segment_area: continue,即小于 min_segment_area(默认 100)像素的片段被直接跳过;
  4. 调用 get_coco_segmentation_from_bool_mask(定义于 sahi/utils/cv.py)把二值掩码转为 COCO 多边形格式 [[x1, y1, x2, y2, ...], ...]——该工具内部用 cv2.findContours 提取轮廓、cv2.CHAIN_APPROX_SIMPLE 压缩点集,并丢弃点数不足 3 个(即边长小于 6 的扁平多边形)的无效轮廓;
  5. 多边形为空则跳过;否则记录 coco_segmentation、score(来自 segments_info["score"])、category_id(来自 segments_info["label_id"])。

随后 _create_object_prediction_list_from_original_predictions 为每个图像构造 ObjectPrediction:

ObjectPrediction(
    bbox=None,                    # 分割模型不产出框
    segmentation=segment,         # COCO 多边形列表
    category_id=category_id,
    category_name=self.category_mapping[category_id],  # 来自 model.config.id2label
    shift_amount=shift_amount,
    score=score,
    full_shape=full_shape,
)

注意 bbox=None:分割模型的结果以掩码为主,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_type="huggingface_segmentation",
    model_path="facebook/mask2former-swin-tiny-coco-instance",
    confidence_threshold=0.5,
    device="cuda:0",                        # 或 "cpu"
    segmentation_type=SegmentationType.INSTANCE_SEGMENTATION,
)

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
)

把 segmentation_type 切换为 SEMANTIC_SEGMENTATION 或 PANOPTIC_SEGMENTATION 即可使用对应的任务头。注意语义分割会把同一类别的所有实例合并进一个掩码,因此每个类别只会返回一个 ObjectPrediction,而不是为每个实例分别返回(这是 docs/guides/models.md 明确提示的行为差异)。

切片推理的常用参数(定义于 sahi/predict.py 的 get_sliced_prediction):

参数 默认值 说明
slice_height / slice_width None 每个切片(tile)的像素尺寸,配合 auto_slice_resolution=True 时 SAHI 会根据图像分辨率自动选取
overlap_height_ratio / overlap_width_ratio 0.2 相邻切片的重叠比例(0.0~1.0),保证跨切片边界的目标至少完整出现在一个切片中
perform_standard_pred True 是否额外对整图做一次原生分辨率推理,以捕获被切碎的大目标
postprocess_type "GREEDYNMM" 切片结果合并策略:GREEDYNMM(贪心均值合并,默认)、NMM、NMS
postprocess_match_metric "IOS" 匹配度量:IOS(交并小集,更激进)或 IOU(更保守)
postprocess_match_threshold 0.5 高于该重叠度阈值的切片预测会被合并/抑制
batch_size 1 批量推理大小,>1 时利用 perform_batch_inference 的原生批量前向加速
verbose 1 0 静默、1 打印切片数、2 额外打印各阶段耗时

由于分割模型输出的每个 segment 都是带多边形掩码的 ObjectPrediction,切片推理、跨切片重复预测的合并(NMM/NMS 等)都与检测模型走完全相同的管线,无需任何额外适配——这正是本文开头所述"统一抽象"设计带来的实战红利。

单图推理

若无需切片,直接用 get_prediction(定义于 sahi/predict.py):

from sahi.predict import get_prediction

result = get_prediction(
    image="image.jpg",
    detection_model=detection_model,
    shift_amount=[0, 0],
    full_shape=None,
    postprocess=None,
)

shift_amount 为 [shift_x, shift_y],用于把预测从切片坐标平移到全图坐标;full_shape 为 [height, width],不传时自动取输入图像尺寸。

测试佐证:覆盖矩阵与精度断言

test_huggingface_segmentation.py 用一组参数化用例覆盖了"3 架构 × 3 任务头"的完整组合(测试注释说明:MaskFormer 与 OneFormer 各用单一 checkpoint 服务三种任务头,Mask2Former 每个任务头一个 checkpoint):

CASES = [
    pytest.param(C.MASK2FORMER_INSTANCE_MODEL_PATH, INSTANCE, id="mask2former-instance"),
    pytest.param(C.MASK2FORMER_SEMANTIC_MODEL_PATH, SEMANTIC, id="mask2former-semantic"),
    pytest.param(C.MASK2FORMER_PANOPTIC_MODEL_PATH, PANOPTIC, id="mask2former-panoptic"),
    pytest.param(C.MASKFORMER_MODEL_PATH, INSTANCE, id="maskformer-instance"),
    ...
    pytest.param(C.ONEFORMER_MODEL_PATH, PANOPTIC, id="oneformer-panoptic"),
]

测试中使用的真实 checkpoint 路径(见 tests/utils/huggingface.py):

  • Mask2Former:facebook/mask2former-swin-tiny-cityscapes-{instance,semantic,panoptic}
  • MaskFormer:facebook/maskformer-swin-tiny-coco
  • OneFormer:shi-labs/oneformer_ade20k_swin_tiny

测试断言 assert_valid_segments 校验每个 ObjectPrediction:score >= 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_size=4、关闭整图标准推理),验证了分割模型与切片推理管线的兼容性。

常见问题与注意事项

  • use_fast=False 不可省略:快速 processor 在分割模型上存在已知兼容问题('SizeDict' object has no attribute 'keys'),模块在加载与 image_size 重设场景下都固定使用慢速 processor;
  • processor 类名按前缀匹配:新版 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_type="huggingface_segmentation", ...) 一行注册即用,再配合 docs/guides/models.md 中的参数表和 tests/test_huggingface_segmentation.py 的覆盖用例,你可以快速把 MaskFormer / Mask2Former / OneFormer 部署到自己的实例、语义或全景分割任务中。

登录后查看全文
sahi