系列编排日期为 2026 年 8 月；正文依据 2026-10-12 核对的实现整理。历史实测保留真实日期，教学数字不代表实测；本次未重新执行板端推理。
返回系列目录 · 本篇为 14 章＋4 份附录中的一篇。
正常业务与调试共用算法
GenerateTestTools 的入口为“设备控制 → AI 调试 → 口鼻遮挡（五阶段）”。级联直接复用板端 OcclusionProcessor，因此调参看到的是板端模型与后处理结果。上位机主要处理连接、参数、图像显示和样本归档。
PC 的 head_pipnet_unet/preview.py 是另外一个浮点参考入口；hi3516/preview_board.py 只读取板端结果。遇到结果不同，先确认是哪一种运行方式，再比较模型与参数。
三种测试模式
| 模式 | 图像来源 | 适合解决的问题 |
|---|---|---|
| 本地图片 | 上传指定图像到板端 | 控制输入、检查转换与规则 |
| 实时抓图 | 获取摄像头新帧，之后可固定原图重测 | 排除场景变化，只比较参数影响 |
| 分析直播 | 同一会话连续获取最新帧 | 观察跟踪、时序、热调参与断流 |
图片及抓图测试创建新样本；直播默认不逐帧落盘，点击保存当前分析帧才留样。停止后可以保存最后结果或对固定原图重测。新的参数不是自动永久写入设备配置。
一个可重复的调参过程
先读取板端参数，保存一份基线；抓取能稳定复现问题的图像并记录原图哈希。每次只调整一类参数，使用同一原图重测，比较 head/face 数量、ROI、响应、覆盖、状态及复核证据。
例如降低 face_score 后出现更多遮挡候选，原因可能只是原来未进入 PIPNet 的小脸现在被检测到了，而不是融合阈值变敏感。分阶段记录能区分“对象变了”和“同一对象判定变了”。
直播允许编辑参数，但要点击“应用参数到直播”才在后续分析轮次生效。界面区分编辑值、待生效版本与结果版本；应用配置后重置时序，防止旧规则的累计时间被继承。
调试会话如何独占 AI
板端调试连接使用 8901 端口。begin 建立 owner 与 session，返回租约时长 120000 ms；请求校验连接归属和 session，其他客户端不能夺取同一 NPU 调试会话。
客户端心跳与活动维持会话。正常结束、断开或超时走 reset，释放调试占用并恢复正常 AI 调度。独占的是 AI 推理资源，音视频业务继续运行。实际恢复仍需在设备上验证，不能只看客户端窗口关闭。
摄像头原始帧带显式 release 生命周期；失败路径也需要释放帧。否则只运行几轮就可能耗尽视频缓冲。主模型异常和 World 异常也分别通过卸载路径回收 NPU 资源。
协议传输与帧对应
cascade.defaults 返回 policy 与 models；cascade.run 接受参数和预览编码，返回 session、frame_id、报告与标注图大小；blob.get 分块获取大数据，避免多头报告超过协议单帧容量。
当前实时标注图可使用 JPEG 降低传输量；原始测试图像仍用无损 PNG，确保同图重测不会因压缩改变输入。上位机把收到的 JPEG 标注转存为 PNG，并不会恢复 JPEG 已损失的像素，所以不要拿标注图做严格数值对齐。
报告 parameters 保存实际参数，models 含路径和 FNV-1a 64 位指纹；样本文件另使用 SHA-256 校验。两种指纹用途与字段不同，不能都描述为 SHA-256。
保存配置与生效是两步
“写入板端配置”校验模型路径与参数，把 sys.npu 整组提交配置服务，再回读确认。读取之后若其他客户端修改了该组，本次保存会拒绝覆盖。超时可能发生在落盘之后，因此不能仅凭超时断定未保存，应重新读取核实。
保存仅持久化五模型路径、元数据路径、头模型类型和判定规则等相关项；电脑输出目录、抓图间隔不写入，也不自动改 AI 开关。保存后正常 Stream 仍持有启动时缓存，必须重启该进程才加载新值。
因此四个状态要分清：已编辑、已用于调试直播、已保存并回读一致、已在重启后的正常业务生效。它们没有必然同步关系。
样本目录是复现的基本单位
|
已有帧在后续失败或停止后保留。回放旧结果不需要板子；修改参数重新推理需要板子。当前普通样本不保存全部网络原始张量，不能用它离线重做全部后处理；静态文件输入首帧的 cascade_tensors 是另一个专门对齐入口。
命令行复现
已有工具时，替换下列地址和图片路径，再使用未存在的输出目录：
|
--params 可指定导出的 JSON；没有指定则读取板端当前参数。100 ms 不是实际推理周期，完整间隔还包含推理和传输。独立构建入口为 GenerateTestTools/npu/CMakeLists.txt，需要 Qt Core、Network、Gui；图形界面另有依赖。
故障排查顺序
连接失败先检查 Stream 和端口；提示忙先检查 owner 会话；模型错误检查绝对路径、SD 挂载及元数据配套；结果陈旧检查帧号与耗时；总是新轨迹检查 track_gap、IoU 与参数版本；保存后无变化检查 Stream 是否重启以及实际读取值。不要一开始就同时改变所有阈值。
依据：GenerateTestTools/npu/README.md、CASCADE.md、StreamNpuDebug.cpp。上位机旧文档中的局部描述可能滞后，具体可写参数以板端回读与代码校验为准。