face-parsing on Ascend NPU

1. 简介

本文档记录 jonathandinu/face-parsing 面部解析（Face Parsing）模型在昇腾 NPU（Ascend 910B3）上的迁移适配、精度评测与性能验证结果。

该模型基于 SegFormer-B0（层级化 Transformer + MLP Decoder），在 CelebAMask-HQ 面部数据集上微调，支持 19 类面部区域的逐像素语义分割。涵盖：background、skin、nose、eye_g（眼镜）、l_eye、r_eye、l_brow、r_brow、l_ear、r_ear、mouth、u_lip、l_lip、hair、hat、ear_r（耳环）、neck_l（项链）、neck、cloth。分辨率 512×512，输出 128×128 的分割图（输入 1/4）。

SegFormer-B0 是 NVIDIA 提出的轻量级语义分割 Transformer，仅 3.7M 参数，推理极快。

相关获取地址：

• 权重下载地址（HuggingFace）：https://huggingface.co/jonathandinu/face-parsing

2. 验证环境

• NPU：8 × Ascend 910B3
• 精度对比基准：CPU（x86, PyTorch 2.8.0）
• 适配修复：preprocessor_config.json 中过时的 image_processor_type 字段名

3. 部署使用流程

3.1 环境准备

conda create -n face-parsing python=3.11 -y
conda activate face-parsing

pip install torch==2.8.0 torch_npu==2.8.0.post4 \
    -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install transformers torchvision pillow numpy \
    -i https://pypi.tuna.tsinghua.edu.cn/simple

# 修复过时的 preprocessor 配置名
sed -i 's/SegformerFeatureExtractor/SegformerImageProcessor/' \
    ./face-parsing/preprocessor_config.json

3.2 推理脚本使用

python inference.py --image face.jpg --device npu

编程接口：

from inference import SegformerSegmentor
seg = SegformerSegmentor(model_path="./face-parsing", device="npu")
pred = seg.predict(["face.jpg"])
# pred[0].shape → (128, 128)  像素级 19 类分割

4. Smoke 验证

python inference.py --image demo.png --device npu

预期输出：面部各区域的像素占比（skin, hair, nose 等），无运行时错误。模型目录含 demo.png 示例图片可用。

5. 性能参考

测试条件：6 张合成 512×512 图像（固定随机种子），batch_size=4，NPU 预热 1 轮。

SegFormer-B0 轻量架构在 NPU 上获得极高加速比（45.2×），适合实时面部解析应用。

6. 精度评测

6.1 评测方法

分别在 CPU 和 NPU 上推理 6 张合成 512×512 图像，比较逐像素 19 维分类 logits 的展平余弦相似度和像素分类匹配率。

6.2 评测结果

结论：精度误差率 0.0001%，像素级分类几乎完全一致，评测通过。

7. 迁移适配说明

7.1 模型结构

• Backbone：SegFormer-B0 Hierarchical Transformer Encoder（4 个 stage，Mix-FFN，无位置编码）
• Decoder：All-MLP Decoder 融合 4 级特征图，上采样到 1/4 分辨率
• Head：输出 19 通道逐像素 logits，经 argmax 得到分割标签
• 参数量：仅 3.7M（极轻量），适合移动端和实时场景
• 额外文件：含 ONNX 导出和 INT8 量化配置，可用于进一步优化

7.2 适配要点

1. 使用 AutoModelForSemanticSegmentation.from_pretrained() 加载
2. preprocessor 修复：preprocessor_config.json 中 image_processor_type 为过时的 SegformerFeatureExtractor，需改为 SegformerImageProcessor。不改会导致 ValueError: Unrecognized image processor
3. model.to("npu:0") 一步迁移，所有算子（Conv2d, LayerNorm, GELU, Mix-FFN）NPU 原生支持
4. AutoImageProcessor 在 CPU 完成预处理（512×512 resize + ImageNet 标准化），tensor 转移至 NPU

7.3 关键代码

import torch, torch_npu
from transformers import AutoImageProcessor, AutoModelForSemanticSegmentation

model = AutoModelForSemanticSegmentation.from_pretrained("face-parsing").to("npu:0")
processor = AutoImageProcessor.from_pretrained("face-parsing")

from PIL import Image
image = Image.open("face.jpg").convert("RGB")
inputs = processor(images=image, return_tensors="pt")
inputs = {k: v.to("npu:0") for k, v in inputs.items()}

with torch.no_grad():
    outputs = model(**inputs)
    seg_map = outputs.logits.argmax(dim=1)  # (1, 128, 128)

8. 注意事项

1. preprocessor 配置修复：下载权重后必须执行 sed -i 's/SegformerFeatureExtractor/SegformerImageProcessor/' preprocessor_config.json，否则 AutoImageProcessor 报错。这是因为模型使用的是旧版 transformers 保存的配置名。
2. 19 类标签：涵盖面部皮肤、五官（眉/眼/鼻/口/耳）、头发、配件（眼镜/帽子/耳环/项链）、衣物等。完整 19 类可在 model.config.id2label 查看。
3. 轻量级模型：SegFormer-B0 仅 3.7M 参数（14MB），加载和推理延迟极低，适合移动端和实时视频流处理。
4. ONNX 导出：模型包含 ONNX 格式导出和量化配置（quantize_config.json），可用于边缘端 INT8 推理加速。
5. 512×512 固定输入：模型在 512×512 上训练，输入自动 resize。非方形人脸需预裁剪为正方形。
6. demo.png：模型文件夹含一张示例人脸图片，可直接用于 smoke 测试验证推理管道。