OneFormer 通用图像分割推理实战——用单个模型完成实例/语义/全景分割

原创2026-10-10 19:40:362,336 阅读
文章标签:示例工程教程

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])

注意这里与全景分割的两处差异:

  1. 后处理调用 post_process_semantic_segmentation,返回的是单一掩码张量(上面例子中形状为 [200, 267]),没有 segments_info;
  2. 可视化直接取 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 推理 notebook,我们可以得到一个非常清晰的实战结论:同一份预训练权重、同一个 forward 调用,只需通过 processor 的 task_inputs 传入不同的任务词,并选用对应的后处理方法,即可分别完成全景、语义与实例分割。这一能力来自 OneFormer 在 Mask2Former 框架上引入的文本条件模块,而它在易用性上的回报(一个模型通吃三类任务)是以一定推理延迟为代价的。掌握 AutoProcessor + AutoModelForUniversalSegmentation 这套调用范式后,你便可以将 OneFormer 快速接入自己的图像分割项目。

登录后查看全文
Transformers-Tutorials