cv_human_68-la 68点人脸关键点检测 — 昇腾 NPU 适配部署文档

1. 模型概述

项目	说明
模型名称	cv_human_68-la (StackedHGNetV1)
来源	Damo_XR_Lab/cv_human_68-facial-landmark-detection
任务	68点人脸关键点检测
参数量	17,069,572 (17.1M)
输入	RGB图像, 256×256, 归一化到 [-1, 1]
输出	68个 (x, y) 关键点坐标
原始框架	ModelScope / PyTorch
适配设备	Ascend 910 (9362)

模型架构

主干网络: Stacked Hourglass Network (4 stacks, 4 levels)
关键模块: CoordConv, ResBlock, E2HTransform (Edge-to-Heatmap), AddCoordsTh
解码方式: Soft-argmax 从热力图解码坐标
辅助损失: 边缘图 (Edge Map) + Attention Activation Map (AAM)

2. 环境依赖

依赖	版本
Python	3.11
PyTorch	2.1.0
torch_npu	2.1.0
CANN	8.0
OpenCV	4.x
NumPy	1.x

环境检查

python3 -c "import torch; import torch_npu; print(f'PyTorch: {torch.__version__}'); print(f'torch_npu: {torch_npu.__version__}'); print(f'NPU: {torch.npu.get_device_name(0)}')"

3. 快速开始

3.1 单图推理 (NPU)

# 原图推理 (自动 resize 到 256x256, 关键点映射回原图坐标)
python inference.py --input assets/test.jpg --output result.png --device npu:0 --contour

# 256x256 裁剪人脸图推理
python inference.py --input assets/sample.jpg --output result.png --device npu:0 --cropped --contour

3.2 单图推理 (CPU)

python inference.py --input assets/test.jpg --output result.png --device cpu --contour

3.3 Python API

from inference import FaceLandmarkDetector, draw_landmarks_with_contours
import cv2

# 初始化 (自动加载权重)
detector = FaceLandmarkDetector('pytorch_model.pkl', device='npu:0')

# 方式1: 原图推理 (自动 resize, 坐标映射回原图尺寸)
image = cv2.imread('assets/test.jpg')
landmarks = detector.detect(image)  # (68, 2) 原图坐标

# 方式2: 256x256 裁剪人脸图推理
cropped = cv2.imread('assets/sample.jpg')
landmarks = detector.detect_from_cropped(cropped)  # (68, 2) 像素坐标

# 方式3: 指定人脸框
landmarks = detector.detect(image, face_bbox=(100, 50, 500, 450))

# 可视化
result = draw_landmarks_with_contours(image, landmarks)
cv2.imwrite('result.png', result)

4. 适配修改说明

4.1 模型代码适配

原始模型依赖 ModelScope 框架，涉及多层相对导入（from ..dataset import get_decoder 等），无法独立运行。适配时完成以下重写：

模块	原始实现	适配说明
`decoder_default`	`from ..dataset.decoder_default`	内联重写 soft-argmax 解码器
`E2HTransform`	`from ..dataset.augmentation`	内联重写边缘图变换矩阵
`AddCoordsTh`	`from coord_conv`	内联重写坐标通道注入
`CoordConvTh`	`from coord_conv`	内联重写 CoordConv 卷积层
`GetCropMatrix`	`from utility`	内联重写仿射变换矩阵
`EDGE_INFO_300W`	配置文件	内联定义 9 条轮廓线

4.2 NPU 适配要点

权重加载: torch.load(..., map_location='cpu') 加载后 .to(device) 上 NPU
推理模式: model.eval() + torch.no_grad()
无需任何算子替换, 原始 PyTorch 模型在 Ascend 910 上 开箱即用

4.3 权重兼容性

加载结果: 0 missing keys, 0 unexpected keys ✅
所有权重完整迁移, 无需任何权重量化/转换

4.4 推理流程说明

自动模式 (detect() 无参数): 将原图 resize 到 256×256 → 模型推理 → 坐标按原图尺寸等比缩放
裁剪人脸模式 (detect_from_cropped()): 直接对 256×256 图推理, 输出像素坐标
人脸框模式 (detect(face_bbox=...)): 从 bbox 计算 scale/center → GetCropMatrix 裁剪 → 推理 → 逆变换回原图坐标

5. 精度验证 (CPU vs NPU)

5.1 运行评测

python benchmark.py --device_npu npu:0 --device_cpu cpu --runs 100 --output benchmark_report.json

5.2 精度对比数据

指标	值
测试图片数	2
总坐标点数	272 (68点 × 2坐标 × 2图)
Mean Error	0.0537 px
Max Error	0.4636 px
Std Error	0.0786 px
P95 Error	0.2034 px
P99 Error	0.3446 px
误差 < 0.5px	100.0%
误差 < 1.0px	100.0%

逐图详情

图片	分辨率	Mean Error (px)	Max Error (px)
assets/sample.jpg	256×256	0.0056	0.0421
assets/test.jpg	1024×768	0.1017	0.4636

逐点对比示例 (sample.jpg, 前5点)

点序号	CPU (x, y)	NPU (x, y)	误差 (px)
0	(33.19, 65.90)	(33.16, 65.89)	0.03
1	(23.15, 87.28)	(23.14, 87.26)	0.02
2	(29.87, 113.31)	(29.86, 113.30)	0.01
3	(34.71, 137.54)	(34.71, 137.54)	0.01
4	(40.18, 164.11)	(40.19, 164.12)	0.01

逐点对比示例 (test.jpg, 前5点)

点序号	CPU (x, y)	NPU (x, y)	误差 (px)
0	(470.45, 414.84)	(470.67, 414.67)	0.30
1	(473.34, 437.24)	(473.49, 437.07)	0.21
2	(487.78, 428.29)	(487.97, 428.15)	0.21
3	(497.37, 446.80)	(497.58, 446.65)	0.25
4	(465.64, 461.94)	(465.88, 461.86)	0.24

5.3 精度结论

✅ NPU 与 CPU 推理结果高度一致, 最大误差仅 0.46 px, 全部 272 个坐标点误差均在 0.5px 以内, 远低于1像素的视觉感知阈值。

6. 性能基准

6.1 测试条件

设备: Ascend 910_9362
输入尺寸: 1 × 3 × 256 × 256
迭代次数: NPU 100次 (warmup 10), CPU 20次 (warmup 3)
测试方式: 纯模型推理, 不含前/后处理

6.2 性能数据

指标	CPU	NPU (Ascend 910)	加速比
单次延迟	795.58 ms	26.71 ms	—
FPS	1.3	37.4	—
加速比	—	—	29.79×

6.3 性能结论

✅ NPU 推理延迟 26.7ms, 达到 37.4 FPS, 较 CPU 提速 29.8 倍, 满足实时推理需求 (>25 FPS)。

7. 交付件清单

文件	说明
`inference.py`	推理脚本 (NPU/CPU 通用, 含 CLI 和 Python API)
`benchmark.py`	精度/性能评测脚本
`pytorch_model.pkl`	模型权重 (从 ModelScope 下载)
`configuration.json`	模型配置
`README.md`	本文档 (含适配说明、精度验证、性能基准、推理日志)
`benchmark_report.json`	评测报告 (JSON 格式, 含精度统计与性能数据)
`result_test_npu.png`	NPU 推理结果图 — test.jpg (1024×768 原图, 自动模式)
`result_sample_npu.png`	NPU 推理结果图 — sample.jpg (256×256, 裁剪模式)
`result_test_cpu.png`	CPU 推理结果图 — test.jpg (对比基准)
`result_sample_cpu.png`	CPU 推理结果图 — sample.jpg (对比基准)
`benchmark_npu_sample.jpg`	评测可视化 — sample.jpg CPU/NPU 关键点叠加对比
`benchmark_npu_test.jpg`	评测可视化 — test.jpg CPU/NPU 关键点叠加对比
`assets/sample.jpg`	256×256 裁剪人脸测试图
`assets/test.jpg`	1024×768 原始人脸测试图

8. 推理日志

8.1 NPU 推理日志 — test.jpg (1024×768 原图, 自动模式)

$ python inference.py --input assets/test.jpg --output result_test_npu.png --device npu:0 --contour

[INFO] 模型已加载到 npu:0
[INFO] 参数量: 17,069,572
[INFO] 输入图像: assets/test.jpg (1024x768)
[INFO] 检测到 68 个关键点
[INFO] 关键点坐标 (前5个):
  点0: (470.7, 414.7)
  点1: (473.5, 437.1)
  点2: (488.0, 428.1)
  点3: (497.6, 446.7)
  点4: (465.9, 461.9)
[INFO] 结果已保存: result_test_npu.png

8.2 NPU 推理日志 — sample.jpg (256×256, 裁剪模式)

$ python inference.py --input assets/sample.jpg --output result_sample_npu.png --device npu:0 --cropped --contour

[INFO] 模型已加载到 npu:0
[INFO] 参数量: 17,069,572
[INFO] 输入图像: assets/sample.jpg (256x256)
[INFO] 检测到 68 个关键点
[INFO] 关键点坐标 (前5个):
  点0: (33.2, 65.9)
  点1: (23.1, 87.3)
  点2: (29.9, 113.3)
  点3: (34.7, 137.5)
  点4: (40.2, 164.1)
[INFO] 结果已保存: result_sample_npu.png

8.3 CPU 推理日志 — test.jpg (1024×768 原图, 自动模式)

$ python inference.py --input assets/test.jpg --output result_test_cpu.png --device cpu --contour

[INFO] 模型已加载到 cpu
[INFO] 参数量: 17,069,572
[INFO] 输入图像: assets/test.jpg (1024x768)
[INFO] 检测到 68 个关键点
[INFO] 关键点坐标 (前5个):
  点0: (470.4, 414.8)
  点1: (473.3, 437.2)
  点2: (487.8, 428.3)
  点3: (497.4, 446.8)
  点4: (465.6, 461.9)
[INFO] 结果已保存: result_test_cpu.png

8.4 CPU 推理日志 — sample.jpg (256×256, 裁剪模式)

$ python inference.py --input assets/sample.jpg --output result_sample_cpu.png --device cpu --cropped --contour

[INFO] 模型已加载到 cpu
[INFO] 参数量: 17,069,572
[INFO] 输入图像: assets/sample.jpg (256x256)
[INFO] 检测到 68 个关键点
[INFO] 关键点坐标 (前5个):
  点0: (33.2, 65.9)
  点1: (23.2, 87.3)
  点2: (29.9, 113.3)
  点3: (34.7, 137.5)
  点4: (40.2, 164.1)
[INFO] 结果已保存: result_sample_cpu.png

8.5 精度+性能评测日志 (benchmark.py)

$ python benchmark.py --device_npu npu:0 --runs 100 --output benchmark_report.json

============================================================
  精度对比: CPU vs NPU
============================================================
[INFO] 模型已加载到 cpu
[INFO] 参数量: 17,069,572
[INFO] 模型已加载到 npu:0
[INFO] 参数量: 17,069,572

  [assets/sample.jpg]
    CPU 前3点: (33.19,65.90), (23.15,87.28), (29.87,113.31)
    NPU 前3点: (33.16,65.89), (23.14,87.26), (29.86,113.30)
    Max Error: 0.0421 px | Mean Error: 0.0056 px
    已保存: benchmark_npu_sample.jpg

  [assets/test.jpg]
    CPU 前3点: (470.45,414.84), (473.34,437.24), (487.78,428.29)
    NPU 前3点: (470.67,414.67), (473.49,437.07), (487.97,428.15)
    Max Error: 0.4636 px | Mean Error: 0.1017 px
    已保存: benchmark_npu_test.jpg

  全局统计 (272 个坐标点):
    Mean Error: 0.053669 px
    Max Error:  0.463562 px
    Std Error:  0.078598 px
    P95 Error:  0.203375 px
    P99 Error:  0.344617 px
    < 0.5px: 100.0%
    < 1.0px: 100.0%

============================================================
  性能基准 (runs=100)
============================================================
[INFO] 模型已加载到 npu:0
[INFO] 参数量: 17,069,572
[INFO] 模型已加载到 cpu
[INFO] 参数量: 17,069,572
  NPU: 26.71 ms  (37.4 FPS)
  CPU: 795.58 ms  (1.3 FPS)
  加速比: 29.79x

评测报告已保存: benchmark_report.json
============================================================

9. 自验证指南

9.1 一键验证命令

# 1. 环境检查
python3 -c "import torch; import torch_npu; print(f'PyTorch={torch.__version__}, torch_npu={torch_npu.__version__}, NPU={torch.npu.get_device_name(0)}')"

# 2. NPU 单图推理 (原图)
python inference.py --input assets/test.jpg --output result_verify.png --device npu:0 --contour

# 3. NPU 单图推理 (裁剪人脸)
python inference.py --input assets/sample.jpg --output result_verify_sample.png --device npu:0 --cropped --contour

# 4. CPU 对比推理
python inference.py --input assets/test.jpg --output result_verify_cpu.png --device cpu --contour

# 5. 精度+性能完整评测
python benchmark.py --device_npu npu:0 --runs 100 --output benchmark_report.json

# 6. 查看评测报告
cat benchmark_report.json | python3 -m json.tool

9.2 预期输出

result_verify.png: 人脸图片上绘制 68 个关键点 + 9 条轮廓线
benchmark_report.json: 包含精度误差统计和性能 FPS 数据
精度: Mean Error < 0.1 px, Max Error < 0.5 px
性能: NPU FPS > 30, 加速比 > 20x