SAHI HuggingFace 分割模型封装指南:MaskFormer / Mask2Former / OneFormer 实例·语义·全景分割
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 是模型的入口加载逻辑,流程如下:
- 校验
model_path:必须提供(源码中ValueError("model_path must be provided for HuggingFace models")); - 解析 token:
hf_token = os.getenv("HF_TOKEN", self._token),即优先读取环境变量HF_TOKEN,否则使用构造时传入的token; - 加载模型:通过
AutoModelForUniversalSegmentation.from_pretrained(self.model_path, token=hf_token)加载;注意选用的是 Universal(通用)入口,因为 MaskFormer、Mask2Former、OneFormer 都属于通用分割模型家族; - 构建 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,强制统一输入分辨率;
- 固定使用
- 装配:调用
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 是"把后处理结果变成可用预测"的核心环节,逐段执行:
- 从
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 为每个图像构造 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 部署到自己的实例、语义或全景分割任务中。