gcw_AVRCax4T/mask2former-swin-base-coco-panoptic

Mask2Former Swin-Base COCO 全景分割（昇腾 NPU）

模型介绍

本仓库是 facebook/mask2former-swin-base-coco-panoptic 的昇腾 NPU 适配版本，基于华为昇腾 Ascend910 处理器完成推理适配与性能验证。

Mask2Former 是一种统一的图像分割架构，能够处理语义分割、实例分割和全景分割任务。该模型使用 Swin Transformer 作为骨干网络，在 COCO Panoptic 数据集上训练，支持 133 个类别（80 个"thing"类别 + 53 个"stuff"类别）的全景分割。

原始模型信息

属性	值
模型架构	Mask2Former (Swin-Base backbone)
任务类型	全景分割
输入分辨率	384 × 384
参数量	~216M
类别数	133 (80 个"thing"类别 + 53 个"stuff"类别)
查询数量	100
原始框架	PyTorch / HuggingFace Transformers
数据来源	ModelScope

昇腾 NPU 适配信息

属性	值
适配平台	Ascend910 (Atlas 800 A2)
CANN 版本	CANN 8.5.1
PyTorch 版本	2.9.0
torch_npu 版本	2.9.0.post1
适配策略	零代码修改（原生 Transformers + torch_npu）
精度验证	✅ 通过（CPU 与 NPU 像素一致性 > 99.99%）
NPU 加速比	62.70 倍对比 CPU

环境要求

# 硬件要求
- Huawei Ascend910 NPU (Atlas 800 A2/A3)
- 内存: >= 16GB

# 软件要求
- CANN >= 8.5.1
- Python >= 3.10
- PyTorch >= 2.9.0
- torch_npu >= 2.9.0
- transformers >= 4.57.0
- Pillow
- numpy
- requests

快速开始

1. 安装依赖

pip install torch torch_npu transformers Pillow numpy requests

2. 下载模型

pip install modelscope
modelscope download --model facebook/mask2former-swin-base-coco-panoptic

3. 运行推理

import torch
import torch_npu
from transformers import (
    AutoImageProcessor,
    Mask2FormerForUniversalSegmentation,
)
from PIL import Image
import requests
from io import BytesIO

# 加载模型
MODEL_PATH = "~/.cache/modelscope/hub/models/facebook/mask2former-swin-base-coco-panoptic"
device = torch.device("npu:0")

processor = AutoImageProcessor.from_pretrained(MODEL_PATH, local_files_only=True)
model = Mask2FormerForUniversalSegmentation.from_pretrained(
    MODEL_PATH, local_files_only=True
).to(device).eval()

# 加载图像
url = "http://images.cocodataset.org/val2017/000000039769.jpg"
image = Image.open(BytesIO(requests.get(url).content)).convert("RGB")

# 推理
inputs = processor(images=image, return_tensors="pt")
inputs = {k: v.to(device) for k, v in inputs.items()}

with torch.no_grad():
    torch.npu.synchronize()
    outputs = model(**inputs)
    torch.npu.synchronize()

# 后处理
result = processor.post_process_panoptic_segmentation(
    outputs, threshold=0.5, mask_threshold=0.5,
    overlap_mask_area_threshold=0.8, label_ids_to_fuse=set(),
)[0]

print(f"Segmentation map shape: {result['segmentation'].shape}")
# 获取分割图中的类别信息
for segment in result["segments_info"]:
    print(f"  Class ID: {segment['id']}, Label: {segment['label_id']}")

精度验证

验证方法

在同一输入图像上分别使用 CPU 和 NPU 运行推理，比较输出结果：

张量级比对：逐元素比较 class_queries_logits 和 masks_queries_logits
分割图比对：逐像素比对后处理生成的 segmentation map
类别级 IoU：计算每个类别的 Intersection over Union

验证结果

指标	数值	阈值	状态
Pixel Agreement	99.9939%	> 99%	✅ PASS
Pixel Disagreement	0.00610%	< 1%	✅ PASS
Per-Class IoU Mean	0.99982	> 0.99	✅ PASS
差异像素数	9 / 307,200	-	可忽略

张量级精度指标（点击展开）

张量	MAE	MSE	Relative Error	Cosine Similarity
class_queries_logits	0.0820	0.0738	0.1186	0.9986
masks_queries_logits	1.6413	46.3246	0.1630	0.9703

注：张量级相对误差较高是由于掩码 logits 中存在接近零的值，导致除法操作引入噪声。分割任务的有效精度指标是最终分割图的像素一致性（99.9939%）。

性能基准

测试配置

测试图像: COCO val2017 000000039769.jpg (640×480)
处理分辨率: 384×384
迭代次数: 20 次（含 5 次预热）
batch_size: 1
数据类型: float32

延迟对比

平台	Mean (ms)	Median (ms)	Min (ms)	Max (ms)	Std (ms)	FPS
CPU	3578.81	3568.70	3542.20	3688.70	31.57	0.28
NPU	57.08	57.06	56.68	57.81	0.29	17.52

加速比

NPU vs CPU Speedup: 62.70x

CPU 单次推理: 3.74 秒
NPU 单次推理: 0.059 秒 (58.8 ms)

文件清单

mask2former_npu/
├── inference.py                      # NPU 推理与评测脚本
├── README.md                         # 本文件（模型卡片与部署文档）
└── eval/
    ├── inference.log                 # 完整运行日志
    ├── results.json                  # 结构化评测结果
    ├── test_image.jpg                # 测试输入图像
    ├── segmentation_cpu.png          # CPU 分割可视化
    ├── segmentation_npu.png          # NPU 分割可视化
    └── segmentation_diff.png         # CPU vs NPU 差异图

适配说明

适配方式

Mask2Former 模型使用标准 PyTorch 算子实现，与 torch_npu 完全兼容，无需任何代码修改即可在 Ascend NPU 上运行。适配仅需：

将模型权重从 CPU 迁移至 NPU 设备：model.to("npu:0")
将输入张量迁移至 NPU 设备：inputs.to("npu:0")
在测时场景使用 torch.npu.synchronize() 确保异步操作完成

精度说明

NPU 与 CPU 推理结果在分割图层面几乎完全一致（像素一致性 99.9939%，仅 9 个像素差异），差异来源于 NPU 上浮点运算的数值精度特性。该差异对实际应用无任何影响。

模型标签

#NPU #Ascend #Mask2Former #PanopticSegmentation #COCO #SwinTransformer #PyTorch #torch_npu #Huawei #Ascend910 #ModelScope #ImageProcessing #ComputerVision #facebook

许可

本仓库遵循原始模型的 MIT 许可证。

引用

@article{cheng2022masked,
  title={Masked-attention Mask Transformer for Universal Image Segmentation},
  author={Cheng, Bowen and Misra, Ishan and Schwing, Alexander G and Kirillov, Alexander and Girdhar, Rohit},
  journal={CVPR},
  year={2022}
}

由昇腾NPU模型适配工具链生成，2026-05-20