waylong/facebook-mask2former-swin-large-ade-semantic-NPU
模型介绍
文件和版本
Pull Requests
讨论
分析

facebook/mask2former-swin-large-ade-semantic 的 Ascend NPU 适配

1. 模型简介

  • 模型名称: facebook/mask2former-swin-large-ade-semantic
  • 模型类型: 计算机视觉 - 图像语义分割 (Image Semantic Segmentation)
  • 架构: Mask2Former，主干为 Swin-Large（Swin Transformer Large）
    • 主干：Swin-Large（embed_dim 192，depths [2,2,18,2]，hidden_size 1536）
    • 编码器：6 层，解码器：10 层，100 个查询，hidden_dim 256
    • architectures: ["Mask2FormerForUniversalSegmentation"], model_type: mask2former
  • 参数量: 215.49M
  • 权重大小: 866 MB（model.safetensors 866052064 字节 + pytorch_model.bin 866216517 字节）
  • 数据集: ADE20K (150 类语义分割)
  • 输入: RGB 图像，预处理为 384x384（size_divisor 32），归一化均值 [0.485,0.456,0.406]、标准差 [0.229,0.224,0.225]
  • 输出: class_queries_logits [B,100,151] 与 masks_queries_logits [B,100,96,96]，通过 post_process_semantic_segmentation 得到 [H,W] 语义图（0-149）
  • 用途: 通用图像语义分割，ADE20K 150 类
  • 来源: https://huggingface.co/facebook/mask2former-swin-large-ade-semantic

2. 验证环境

  • NPU: Ascend910（Ascend910_9362）2 卡，CANN 8.5.1
    • npu-smi info: 
      NPU 7 Ascend910 | Health OK | Power 168.2W | Temp 45C | HBM 3112/65536 MB (chip 0, Phy-ID 14, Bus 0000:0A:00.0)
NPU 7 Ascend910 | Health OK | Power -    | Temp 43C | HBM 2869/65536 MB (chip 1, Phy-ID 15, Bus 0000:0B:00.0)
  • torch: 2.9.0+cpu
  • torch_npu: 2.9.0.post1+gitee7ba04
  • torch.npu.is_available(): True
  • device_count: 2, device_name: Ascend910_9362, selected: npu:0
  • NPU 内存: 可用 65396822016 字节（约 60.9GB），总量 65787658240 字节（约 61.27GB）
  • transformers: 4.57.6
  • 模型目录: /tmp/mask2former-hf（通过 ModelScope 与 HuggingFace snapshot_download 获取）
  • 检验脚本: python scripts/check_npu.py --output env_check.json passed=true

3. 安装依赖

pip install -r requirements.txt
# requirements.txt:
# torch>=2.0
# torch_npu>=2.0
# transformers>=4.40
# Pillow
# numpy
# requests
# safetensors
# modelscope
# huggingface_hub
# matplotlib

4. NPU 推理

# 默认推理 (自动选择 npu:0, 若无 NPU 回退 CPU)
PYTHONPATH=/usr/local/python3.11.14/lib/python3.11/site-packages:$PYTHONPATH python inference.py

# 指定图像
PYTHONPATH=/usr/local/python3.11.14/lib/python3.11/site-packages:$PYTHONPATH python inference.py --image /path/to/image.jpg --output-vis vis.png

# CPU/NPU 一致性验证
PYTHONPATH=/usr/local/python3.11.14/lib/python3.11/site-packages:$PYTHONPATH python inference.py --mode validate

# 性能测试 (10次迭代, 含预热)
PYTHONPATH=/usr/local/python3.11.14/lib/python3.11/site-packages:$PYTHONPATH python inference.py --mode benchmark

推理流程：

  1. 使用 AutoImageProcessor.from_pretrained 加载 preprocessor_config（size 384，mean/std）
  2. 使用 Mask2FormerForUniversalSegmentation.from_pretrained 加载实际权重（215M params），并调用 .to(npu:0)
  3. 图像预处理 -> pixel_values [1,3,384,384] + pixel_mask [1,384,384]
  4. 在 torch.npu.synchronize() 前后进行计时，前向传播得到 class/mask logits
  5. 在 CPU 端调用 post_process_semantic_segmentation 生成语义分割图，并统计类别分布

5. 真实推理结果

输入：COCO val2017 000000039769.jpg（640x480，cats），下载自 https://images.cocodataset.org/val2017/000000039769.jpg，通过 https（curl -L -k）

NPU 推理 (npu:0, float32)：

[INFO] using model_dir /tmp/mask2former-hf
[INFO] selected device npu:0  torch_npu available True
[INFO] model_name: facebook/mask2former-swin-large-ade-semantic
[INFO] task_type: image-segmentation (semantic)
[INFO] architecture: Mask2FormerForUniversalSegmentation (Swin-Large)
[INFO] loading_backend: transformers
[INFO] device: npu:0
[INFO] requested_dtype: float32
[INFO] num_labels: 150  num_queries: 100
[INFO] loaded default image /tmp/cats3.jpg size (640, 480)
[INFO] input pixel_values shape: torch.Size([1, 3, 384, 384])
[INFO] pixel_mask shape: torch.Size([1, 384, 384])
[INFO] model params: 215.49M
[INFO] class_queries_logits shape: (1, 100, 151)  mean -3.5041
[INFO] masks_queries_logits shape: (1, 100, 96, 96)  mean -32.9512
[INFO] inference latency: 58.10 ms
[INFO] predicted semantic map shape: (480, 640) (H,W) target (480, 640)
[INFO] unique predicted classes: [0, 15, 39, 56, 98, 120, 147, 148]
[INFO] num unique classes: 8 / 150
  class   0 wall                 pixels  36075 ratio 0.1174
  class  15 table                pixels    121 ratio 0.0004
  class  39 cushion              pixels     18 ratio 0.0001
  class  56 pool table           pixels 176389 ratio 0.5742
  class  98 bottle               pixels     82 ratio 0.0003
  class 120 food                 pixels  90985 ratio 0.2962
  class 147 glass                pixels     26 ratio 0.0001
  class 148 clock                pixels   3504 ratio 0.0114
[RESULT] PASS
  • 语义图尺寸严格对应输入尺寸 (480,640)
  • 8 类预测，最大类别为 56 (pool table)，占比 57.4%；次大类别为 120 (food)，占比 29.6%；其余为 wall/clock 等
  • 直接在 npu:0 上执行前向推理，并通过 torch.npu.synchronize() 进行计时，延迟为 58.10 ms (单次)

6. CPU-NPU 一致性验证

命令: python inference.py --mode validate

结果:

[VALIDATE] CPU vs NPU consistency check
[VALIDATE] class logits max_diff 0.794116 mean_diff 0.011465
[VALIDATE] masks logits max_diff 18.635185
[VALIDATE] semantic map diff_ratio 0.000150  cpu unique [0, 15, 39, 56, 98, 120, 147, 148] npu unique [0, 15, 39, 56, 98, 120, 147, 148]
[VALIDATE] PASS
  • 相同输入（/tmp/cats3.jpg）分别在 CPU 与 npu:0 上执行前向传播，并比较 class_queries_logits 与 masks_queries_logits
  • 类别平均差异为 0.011 < 0.05；语义图仅 0.015% 的像素不一致（46 / 307200 像素，由浮点误差导致，类别集合完全一致）
  • 判定：PASS（diff_ratio < 0.01）
  • 说明：单样本一致性验证，并非完整 ADE20K 数据集的 mIoU 评测

7. 性能测试

命令：python inference.py --mode benchmark（batch 1，384x384，float32，npu:0，预热 3 次，正式 10 次，torch.npu.synchronize() 同步包裹）

结果（来自 10 次迭代）：

[BENCHMARK] repeat=10 batch=1 size=384x384 dtype=float32 device=npu:0
  iter 1: 56.29 ms
  iter 2: 55.84 ms
  iter 3: 55.90 ms
  iter 4: 55.68 ms
  iter 5: 56.02 ms
  iter 6: 56.62 ms
  iter 7: 56.56 ms
  iter 8: 56.63 ms
  iter 9: 56.56 ms
  iter 10: 56.51 ms
[BENCHMARK] avg 56.26 ms min 55.68 max 56.63 p50 56.40 p90 56.62 p95 56.63
[BENCHMARK] throughput 17.77 images/s  batch 1
[BENCHMARK] NPU memory free 59.73GB total 61.27GB used 1.54GB
[BENCHMARK] device Ascend910_9362
  • 平均延迟 56.26 ms，P50 56.40 ms，P90 56.62 ms，吞吐 17.77 张/秒
  • 峰值显存：约 1.5GB（模型 215M 参数，约 0.86GB 权重 + 激活）
  • NPU 编译缓存已包含在稳定推理计时中，首次编译不计入统计

8. 自验证截图

  • assets/agent_workflow.png：完整适配流程日志（下载、侦察、NPU 推理、验证、性能）
  • assets/npu_device_call.png：NPU 设备调用证据（npu-smi info、torch.npu.is_available()、设备名、模型参数 device）
  • assets/model_result.png：python inference.py 真实输出（任务、形状、类别分布、延迟、PASS）

9. 已知限制

  • 权重 866MB，需联网通过 ModelScope/HuggingFace 下载，未随仓库提交；无网络时需预先缓存至 /tmp/mask2former-hf
  • 使用 transformers 慢速处理器（slow）与 float32，因 NPU 与 CPU 的浮点累积差异，存在 <0.01% 的像素不一致，属于可接受误差
  • preprocessor_config.json 中 _max_size 等冗余字段警告已合并，不影响推理
  • Swin-Large 在 NPU 上偶发 allow_internel_format=False 警告，属于 torch_npu 内部格式提示，不影响正确性
  • 未在完整 ADE20K 验证集上计算 mIoU，仅做单样本 CPU-NPU 一致性验证；完整评测需额外数据集
  • 输入尺寸固定为 384x384（预处理 resize + divisor 32），不同宽高比的图像会等比缩放并填充

10. 标签

Hardware: NPU, NPU, Ascend, Ascend910, Mask2Former, Swin, Semantic-Segmentation, ADE20K, Vision