口鼻遮挡工程实录：12 模型转换与海思部署

系列编排日期为 2026 年 8 月；正文依据 2026-10-12 核对的实现整理。历史实测保留真实日期，教学数字不代表实测；本次未重新执行板端推理。

返回系列目录 · 本篇为 14 章＋4 份附录中的一篇。

转换链路需要四层证据

模型能够导出 ONNX、能够转换成 OM、能够在板端运行、能够保持任务所需行为，是四件不同的事。复现记录应依次保留：原始权重与来源、ONNX 图和数值对照、转换配置与日志、板端同输入输出及业务状态。

当前系列使用已有预训练权重与规则组合，没有为口鼻遮挡重新训练一个分类器。量化校准用于估计激活分布及数值范围，不等同于训练，也不产生遮挡标签。

固定输入与输出接口

模型	导出或转换入口	特别需要核对
YuNet	`SDK/Tools/Npu/YuNet/BuildOm.sh`	显式设 320；input255 图与 AIPP 必须成对
PIPNet	`SDK/Tools/Npu/PipNet/BuildOm.sh`	五输出顺序、RGB ImageNet 标准化、邻居表
YOLOv5s-P34	`head_detection_yolov5s/prepare_board.py`、`build_om.sh`	截取两层卷积输出，匹配两组 anchors
FaceOcc	`unet_occlusion/hi3516/export_model.py`、`build_om.sh`	原始权重、RGB/255、单通道 logits
World64	`yoloworld_occluder/export_board.py`、`build_board.sh`	固定词表、三尺度 DFL、元数据同步

后面四个相对路径均位于 application/Dependent/shared/。不要用相同文件名猜测模型兼容性；附录 C 记录当前文件指纹。

YuNet 的 input255 是一个容易遗漏的步骤

原始 OpenCV 路径给 YuNet 输入 BGR 浮点 0～255。本地板端 AIPP 将 UINT8 除以 255，因此 MakeInput255Onnx.py 把第一层卷积权重乘 255：

1	`Conv(x/255, W×255) + b = Conv(x, W) + b`

偏置不变，浮点上保持等价。若使用原图 W 再配除以 255 的 AIPP，或使用放大后的 W 又输入 0～255 浮点，就破坏了配对。YuNet 通道保持 BGR，不是统一转 RGB。

BuildOm.sh 的默认输入仍为 640，当前级联要求通过 NPU_INPUT_SIZE=320 显式选择。脚本存在，不表示直接无参数运行就生成当前生产模型。

AIPP 与量化设置

PIPNet AIPP 的 mean 是 [123.675,116.28,103.53]，var_reci 为 1/(std×255)，把 UINT8 转成所需标准化值。FaceOcc 与 World 使用 RGB/255。当前输出请求 FP32，避免后处理将整型输出误按 float 读取。

FaceOcc 和 World 的脚本明确使用 compile_mode=1、quant_mode=1、按通道权重量化与 output_reorder=0。这些是此项目的转换配置，不应直接理解为所有网络都适用的最佳设置。还需检查转换器对某些算子的精度回退或 CPU 执行情况。

校准图应覆盖目标部署的人脸尺寸、光照、姿态和遮挡类型，预处理必须与推理一致。本地部分初测只有一张或几张校准图，适合贯通流程，不代表生产量化精度已经达标。校准和最终独立验证样本应避免同源泄漏。

可核对的转换命令

以下命令在工程根目录运行，依赖现有 SDK 容器、权重及脚本要求的校准图片。它们是复现入口，本次文章整理没有重新执行模型转换。

mkdir -p application/.temp/yoloworld-board
python3 application/Dependent/shared/yoloworld_occluder/export_board.py \
  > application/.temp/yoloworld-board/export.log 2>&1
docker run --rm -v "$PWD:/workspace" --entrypoint bash \
  hi3516cv610-svp-model-convert:cpu \
  /workspace/application/Dependent/shared/yoloworld_occluder/build_board.sh \
  > application/.temp/yoloworld-board/container.log 2>&1

容器镜像的存在和标签不保证其版本永远不变；归档时还应记录镜像 ID、SDK 版本、Python 依赖及转换脚本哈希。本文没有取得历史容器不可变摘要，因此不补写一个虚假的摘要。

对齐应逐层缩小问题范围

固定原图，比较实际裁剪像素、输入布局和 AIPP 语义。
比较原网络与改写/导出 ONNX 的浮点输出，排除导出问题。
比较 ONNX 与 OM 的原始输出，检查量化漂移和算子语义。
将同一原始输出送入 Python 与 C++ 后处理，排除解码差异。
比较最终 ROI、状态、World 触发和时序行为。

检测可比较匹配框 IoU 和分数差；关键点比较逐点距离与峰值差；分割比较 logits 误差、mask IoU 与鼻嘴覆盖；World 还要比较类别排名和阈值附近的分数变化。平均数之外保留最大差异和困难样本。

板端串行加载的资源取舍

当前槽位为 YuNet=0、PIPNet=1、Head=2、FaceOcc=3、World=4，注册使用 cacheFile=false。板端模型直接读入 ACL 模型缓冲，执行后复制紧凑输出，随后 deinit() 释放模型、工作区和设备输入输出；runtime/context 与路径信息保留。

每轮重复加载增加延迟，尤其受到 NFS 冷读影响，但避免五个模型同时占用工作区。Linux 文件页缓存可能让后续读取更快，不等于应用常驻了五份模型。MMZ 与 RSS 属于不同统计口径，不能简单相加或相互代替。

2026-09-17 的 P34 记录：独立纯推理 20 次平均约 394.1 ms，加载约 120.3 ms；四模型单人静态整轮约 1.2 秒。采样得到整板 MMZ 峰值约 186.2 MiB，含视频已有分配。旧 YOLOv5m 链路的约 1.5～1.7 秒属于另一模型组合，不能混写成同一结果。

模型安装与设备配置

当前平台模型源目录为 application/Platform/Module/HI3516CV610_00S/。CMake 会安装到打包暂存目录 app/Module，但当前应用镜像脚本排除 Module；五阶段模型需按现有调试文档部署到 SD 卡 Module/，板端路径通常为 /tmp/mmc/Module/。

业务开关与默认配置必须核实：仓库默认 effect=0、model=aidetect，不会因为模型文件存在就自动启动五阶段。启用相关入口需 model=yunet_pipnet，实时输入需清空 inputImagePath，路径、头模型类型与配置保存后还需重启 Stream。

回退必须恢复配套的模型路径、head_model、策略与程序版本，再通过项目正常进程管理流程重启。仅把头模型文件替换回旧版而保留新解码类型，会直接产生接口错误。

上一篇：YOLO-World物体复核 · 系列目录 · 下一篇：板端运行与调试闭环