OneFormer 通用图像分割推理实战——用单个模型完成实例/语义/全景分割
OneFormer 通用图像分割推理实战——用单个模型完成实例/语义/全景分割
本篇文章基于 Transformers-Tutorials 仓库中的 OneFormer 演示内容,系统讲解如何借助 Hugging Face Transformers 加载 OneFormer 模型,在单张图片上一次完成实例分割、语义分割与全景分割三类推理任务。读完本文后,你将掌握 AutoProcessor + AutoModelForUniversalSegmentation 的标准调用链、task_inputs 文本条件机制的工作原理,以及三种任务各自的后处理与可视化方法。
什么是 OneFormer:通用图像分割模型
OneFormer 是首次以单个模型、在单个数据集上训练即可同时在实例(instance)、语义(semantic)、全景(panoptic)三种图像分割任务上取得领先结果的通用分割模型。这正是本仓库中 Inference_with_OneFormer.ipynb 所演示的核心能力。
从模型演进脉络看,OneFormer 是 Mask2Former 的后续工作。两者的关键差异在于:
- Mask2Former 为了在各类任务上取得领先结果,仍需要分别针对实例、语义、全景三种数据集分开训练;
- OneFormer 则在 Mask2Former 框架中额外引入了一个文本模块(text module),用文本提示让模型在推理时按需切换到对应子任务。
这种设计的直接收益是精度更高、使用更灵活;代价则正如原仓库文档所明确指出的:换来了更高的推理延迟(increased latency),因为模型需要在原有图像分支之外额外处理文本条件输入。
多模态的真相:图像处理器 + 分词器
OneFormer 之所以能"听懂"任务指令,是因为它本质上是一个多模态模型——同时接收图像与文本两种模态的输入。在 Hugging Face Transformers 的实现中,OneFormerProcessor 在内部由两部分组成:
- image processor:负责图像模态的预处理(缩放、归一化、padding 等);
- tokenizer:负责文本模态的处理(将 "panoptic"、"semantic"、"instance" 等任务词编码为 token)。
这一点在调用 AutoProcessor 时会自动完成,无需手动拼接两个组件。
环境准备与模型选择
安装 Transformers
由于 OneFormer 刚被加入 Transformers 时属于全新模型,仓库演示文档在环境准备阶段选择直接从源码安装:
!pip install -q git+https://github.com/huggingface/transformers.git
如今 OneFormer 已随 Transformers 正式发布,你也可以直接通过 pip install transformers 安装稳定版本后继续。无论哪种方式,关键是确保本地的 transformers 版本包含 OneFormerProcessor 与 AutoModelForUniversalSegmentation 这两个类。
选择预训练 checkpoint
本仓库演示使用的是 COCO 上预训练的 Swin-Large 主干模型:
# 通过 Auto API 根据 checkpoint 自动加载对应的 OneFormerProcessor
processor = AutoProcessor.from_pretrained("shi-labs/oneformer_coco_swin_large")
# 加载 OneFormer 通用分割模型
model = AutoModelForUniversalSegmentation.from_pretrained("shi-labs/oneformer_coco_swin_large")
从 notebook 中可以看到,Swin-Large 版本的模型权重约 879 MB,下载完成后即可直接推理。AutoModelForUniversalSegmentation 会自动识别 checkpoint 的架构并加载正确的 OneFormer 模型类。
准备输入:图像 + 任务提示
加载测试图片
演示文档使用 COCO 验证集中经典的"两只猫 + 两个遥控器"图片(val2017/000000039769.jpg),通过 PIL 与 requests 直接在线加载:
from PIL import Image
import requests
url = 'http://images.cocodataset.org/val2017/000000039769.jpg'
image = Image.open(requests.get(url, stream=True).raw)
选择这张图很有讲究:它同时包含两个同类实例(两只猫、两个遥控器),可以直观检验模型在"全景/实例分割能区分个体"与"语义分割不区分个体"之间的行为差异。
用 processor 组装模型输入
OneFormer 的 processor 与 MaskFormer / Mask2Former 最大的不同,在于调用时多了一个 task_inputs 参数,用于指定当前要执行的任务:
panoptic_inputs = processor(images=image, task_inputs=["panoptic"], return_tensors="pt")
for k, v in panoptic_inputs.items():
print(k, v.shape)
输出如下三个张量:
| 键名 | 形状 | 含义 |
|---|---|---|
pixel_values |
[1, 3, 800, 1066] |
预处理后的图像张量(batch=1,RGB 三通道) |
pixel_mask |
[1, 800, 1066] |
指示真实像素区域与 padding 区域的掩码 |
task_inputs |
[1, 77] |
任务提示的 token 序列 |
其中 task_inputs 正是 MaskFormer 与 Mask2Former 所没有的额外输入,它承载了让模型区分三种分割任务所需的文本条件。将 token 解码回文本即可看到任务指令的真实内容:
processor.tokenizer.batch_decode(panoptic_inputs.task_inputs)
输出为:
['<|startoftext|>the task is panoptic <|endoftext|>!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!']
可见文本部分为 "the task is panoptic",后续的 ! 是 padding 填充符号。当把 task_inputs 换成 ["semantic"] 或 ["instance"] 时,解码出的文本会相应变为 "the task is semantic" 与 "the task is instance",模型将据此切换到对应的解码与匹配逻辑。
三种分割任务的完整推理流程
OneFormer 的三类推理在模型前向传播环节完全一致,唯一区别是送入的 task_inputs 与使用的后处理方法不同。这既是"单模型三任务"最直观的体现,也是下文三个小节共用同一步骤的原因:
import torch
with torch.no_grad():
outputs = model(**inputs) # inputs 分别是 panoptic/semantic/instance 三种输入
全景分割:post_process_panoptic_segmentation
将图像与 task_inputs=["panoptic"] 送入模型后,使用全景分割专用后处理方法:
panoptic_segmentation = processor.post_process_panoptic_segmentation(
outputs, target_sizes=[image.size[::-1]]
)[0]
print(panoptic_segmentation.keys())
返回的字典包含两个键:
segmentation:每个像素被分配到一个全景 segment id 的掩码张量;segments_info:每个 segment 的元信息列表,其中segment['label_id']对应类别标签,可通过model.config.id2label[segment_label_id]映射回可读类别名。
运行时会输出一条提示信息:label_ids_to_fuse unset. No instance will be fused. 意思是若不显式设置 label_ids_to_fuse,模型默认不会把"东西类"实例与"材料类"区域融合,这属于预期行为。
可视化时,演示代码为每个 segment 按 id 着色,并借助 defaultdict 为同类别的多个实例编号(如 cat-0、cat-1),从而在图中清晰看到两只猫、两个遥控器被分别标注。这正是全景分割"既分类、又分个体"的特点。
语义分割:post_process_semantic_segmentation
切换到语义分割只需修改一行 task_inputs:
semantic_inputs = processor(images=image, task_inputs=["semantic"], return_tensors="pt")
with torch.no_grad():
outputs = model(**semantic_inputs)
semantic_segmentation = processor.post_process_semantic_segmentation(outputs)[0]
semantic_segmentation.shape # torch.Size([200, 267])
注意这里与全景分割的两处差异:
- 后处理调用
post_process_semantic_segmentation,返回的是单一掩码张量(上面例子中形状为[200, 267]),没有segments_info; - 可视化直接取
torch.unique(segmentation)得到出现过的类别 id,图例中每个类别只出现一次。
从结果图中可以看到,语义分割只给出"cat"类别的单一掩码,不再区分两只猫是两个实例——这正是"语义分割不区分个体"的典型表现,也是演示文档特意强调的对比点。
实例分割:post_process_instance_segmentation
同理,将任务提示改为 ["instance"]:
instance_inputs = processor(images=image, task_inputs=["instance"], return_tensors="pt")
with torch.no_grad():
outputs = model(**instance_inputs)
instance_segmentation = processor.post_process_instance_segmentation(outputs)[0]
instance_segmentation.keys() # dict_keys(['segmentation', 'segments_info'])
实例分割的返回结构与全景分割类似(segmentation + segments_info),同样会对每个实例单独编号。与全景分割的细微差别在于:全景分割还会把不可数类别(如天空、地面等 stuff 类)纳入统一的 segment 体系,而实例分割通常只关注可计数的物体实例。演示文档对该步骤复用了与全景相同的绘图函数,图例中同样能看到 cat-0、cat-1、remote-0、remote-1 等独立个体。
三个后处理方法与设计要点
从上面的完整流程可以清晰归纳出 OneFormer 推理管线的骨架:
图片 + 任务词
│
▼
AutoProcessor (图像处理器 + 分词器)
│ pixel_values / pixel_mask / task_inputs
▼
AutoModelForUniversalSegmentation
│ outputs
▼
┌─────────────┬──────────────┬──────────────┐
│ panoptic │ semantic │ instance │
│ post_process│ post_process │ post_process │
│ _panoptic_ │ _semantic_ │ _instance_ │
│ segmentation│ segmentation │ segmentation │
└─────────────┴──────────────┴──────────────┘
三个后处理入口分别对应三种输出格式,开发者无需改动模型权重,即可在同一 checkpoint 上按需产出不同粒度的分割结果。model.config.id2label 在三种可视化中都被用于把 label_id 映射为可读类别名,这也是 Hugging Face 模型配置(config)与推理代码协作的标准模式。
如果你对 OneFormer 的训练环节感兴趣,本仓库还提供了配套的微调 notebook:Fine_tune_OneFormer_for_semantic_segmentation.ipynb,可在此基础上进一步探索自定义数据集的语义分割训练。
仓库资源导航
- OneFormer/README.md:本文主题所在的文件夹说明,概述 OneFormer 及本目录 notebook 的定位;
- OneFormer/Inference_with_OneFormer.ipynb:本文核心依据,完整演示单模型三任务推理;
- OneFormer/Fine_tune_OneFormer_for_semantic_segmentation.ipynb:OneFormer 在自定义数据集上的语义分割微调示例。
小结
通过本仓库的 OneFormer 推理 notebook,我们可以得到一个非常清晰的实战结论:同一份预训练权重、同一个 forward 调用,只需通过 processor 的 task_inputs 传入不同的任务词,并选用对应的后处理方法,即可分别完成全景、语义与实例分割。这一能力来自 OneFormer 在 Mask2Former 框架上引入的文本条件模块,而它在易用性上的回报(一个模型通吃三类任务)是以一定推理延迟为代价的。掌握 AutoProcessor + AutoModelForUniversalSegmentation 这套调用范式后,你便可以将 OneFormer 快速接入自己的图像分割项目。