Scrypted OpenVINO 目标检测插件:为 NVR 摄像头接入本地 AI 检测

原创2026-10-14 13:15:111,937 阅读
文章标签:音视频后端物联网计算机视觉

Scrypted OpenVINO 目标检测插件:为 NVR 摄像头接入本地 AI 检测

本指南围绕 Scrypted 仓库中的 OpenVINO Object Detection 插件展开,介绍如何利用 OpenVINO 运行时为 Scrypted 中的任意摄像头添加本地目标检测能力。读完本文,你将掌握该插件的适用场景与硬件要求、推理设备(CPU/GPU/NPU)的自动选择逻辑、模型与模式配置方法,以及插件内置的人脸识别、文字识别、CLIP 语义嵌入、图像分割和自定义模型等扩展能力的实现原理。

插件定位:专为 Scrypted NVR 用户设计的目标检测方案

OpenVINO Object Detection 插件(@scrypted/openvino)的核心作用,是为 Scrypted 中的任意摄像头添加目标检测能力。插件的官方说明明确指出两点前提:

  1. 需要较快的 GPU 和 CPU:检测推理对算力有较高要求,插件文档建议配备快速 GPU 与 CPU 以获得可用体验;
  2. 仅适用于 Scrypted NVR 用户:该插件对 HomeKit 没有任何增益,因为 HomeKit 自带独立的检测处理流程,无需也无法复用本插件的检测结果。

也就是说,这个插件面向的是使用 Scrypted 作为 NVR(网络录像机)进行录像与事件管理的用户——检测结果会融入 NVR 的录制与告警链路;如果你只是在用 HomeKit 做检测与通知,则不需要安装它。从插件清单(package.json)可以看到,它声明依赖 @scrypted/objectdetector 插件,运行环境为 Python,对外暴露 ObjectDetection、ObjectDetectionPreview、DeviceProvider、DeviceCreator、Settings、ClusterForkInterface、ScryptedSystemDevice 等接口,说明它是通过 Scrypted 标准的对象检测接口与 NVR/录像管线协作的。

硬件支持与推理设备自动选择

OpenVINO 的价值在于能够跨 CPU、集成显卡、独立显卡和 NPU(神经处理单元)执行同一份模型。插件启动时会枚举主机上所有可用推理设备(见 ov/init.py):

  • 通过 core.available_devices 获取设备列表,并打印每个设备的支持属性(dump_device_properties);
  • 逐一检查设备全名,识别 Intel Iris Xe 核显、Intel Arc 独显、NVIDIA dGPU、NPU 与通用 GPU;
  • 以 Default 模式启动时,插件根据识别到的硬件自动构造 OpenVINO 的 AUTO 设备优先级列表:
检测到的硬件 自动选择的执行设备
存在 NPU 且存在 GPU AUTO:NPU,GPU,CPU
存在 NPU 但无 GPU AUTO:NPU,CPU
存在 NVIDIA dGPU AUTO:<dgpu>,CPU
仅存在 GPU(非上述场景) GPU
其他情况 AUTO

源码注释解释了这样设计的原因:AUTO 模式在 NPU/GPU 组合下可能引发冲突或掩盖错误,因此插件尽量显式指定设备并逐级回退。若指定 GPU 编译模型失败,插件会先回退到 AUTO,再失败则清空 mode 与 model 配置并请求重启,恢复到默认行为。

模型选择:按硬件自动匹配 YOLOv9 变体

插件内置了多套针对 OpenVINO 导出优化的 YOLOv9 模型,定义在 availableModels 列表中(ov/init.py):

Default
scrypted_yolov9c_relu_test_int8
scrypted_yolov9m_relu_test_int8
scrypted_yolov9s_relu_test_int8
scrypted_yolov9t_relu_test_int8
scrypted_yolov9c_relu_int8
scrypted_yolov9m_relu_int8
scrypted_yolov9s_relu_int8
scrypted_yolov9t_relu_int8

模型名中的 c / m / s / t 对应 YOLOv9 的容量档位(从大到小),relu 表示激活函数,int8 表示量化精度。当配置为 Default 时,插件按硬件自动挑选默认模型:

  • Intel Arc / NVIDIA dGPU / NPU:scrypted_yolov9c_relu_test_int8(容量最大的一档);
  • Intel Iris Xe 核显:scrypted_yolov9s_relu_test_int8;
  • 其余(纯 CPU):scrypted_yolov9t_relu_test_int8(最轻量档)。

源码注释还记录了实测经验:relu + int8 组合在 GPU 和 NPU 上表现最优,而 silu + float 在 GPU 上比 silu + int8 更快、silu + int8 在 CPU 上更快——这些观察是模型选择逻辑的重要依据。

模型文件并非随插件打包,而是从 Hugging Face 的 scrypted/plugin-models 仓库按需下载。下载逻辑位于 predict/init.py 的 downloadHuggingFaceModelLocalFallback:优先在线下载,失败后自动降级为本地缓存(local_files_only=True)加载,缓存目录位于插件卷的 files/hf 下。下载前还会将 socket.getaddrinfo 的解析结果改为 IPv4 优先,避免在 IPv6 不通的网络环境中卡死。

插件配置项详解

插件通过 getSettings 暴露三项设置(ov/init.py):

配置键 名称 说明 取值
available_devices Available Devices 检测将使用的推理设备,只读展示 由插件自动探测,JSON 数组
model Model 用于目标检测的模型 Default 及 8 个 YOLOv9 模型,默认 Default
mode Mode 推理执行模式 Default / AUTO / CPU / GPU,支持自定义(combobox)

其中 Mode 的说明文字特别提醒:修改模式需要重载插件;如果系统 GPU 驱动不可靠,请使用 CPU 模式。任何设置的变更都会经过 putSetting 持久化到存储,并立即请求插件重启生效。

推理主模型采用 OpenVINO 的 AsyncInferQueue 异步推理队列(ov/init.py):推理结果通过回调函数取出第一个输出张量,交由 common/yolo.py 的 parse_yolov9 解析为检测框。默认检测置信度阈值为 0.2(见 common/yolo.py 的 defaultThreshold)。检测类别只有三类,定义在插件主类中:

0: person(人)
1: vehicle(车辆)
2: animal(动物)

这也是 NVR 场景下最有价值的三个告警类别。此外,检测管线的输入尺寸直接取自编译后模型的输入张量(self.compiled_model.inputs[0].shape[2]),预处理将图像从 BHWC 转置为 BCHW 并归一化到 [0, 1](np.float32 / 255.0),预处理与推理分别运行在独立的线程池(OpenVINO-Prepare 与 OpenVINO-Predict)中,避免阻塞插件事件循环。

内置扩展能力:人脸识别、文字识别、CLIP 与分割

除通用目标检测外,插件启动后还会自动注册一组附加设备(prepareRecognitionModels),每个设备均可作为独立的对象检测/嵌入设备使用:

  • OpenVINO Face Recognition:人脸检测 + 识别。检测使用 scrypted_yolov9t_relu_face 模型,识别使用 inception_resnet_v1 模型,输出 512 维人脸特征(embedding,base64 编码),供后续比对(实现见 ov/face_recognition.py 与 predict/face_recognize.py,其中包含按 IoU 大于 0.5 的人脸框 NMS 去重逻辑);
  • OpenVINO Text Recognition:文本检测与识别。检测使用 CRAFT 模型,识别使用 vgg_english_g2 模型;检测框会先做倾斜矫正分组,再识别出文字内容写入 label 字段(实现见 ov/text_recognition.py 与 predict/text_recognize.py);
  • OpenVINO CLIP Embedding:基于 openai/clip-vit-base-patch32 的文本/图像语义嵌入,分别暴露 TextEmbedding 与 ImageEmbedding 接口,vision 输入固定 reshape 为 224x224(实现见 ov/clip_embedding.py 与 predict/clip.py);
  • OpenVINO Segmentation:基于 scrypted_yolov9t_seg_relu 的实例分割,输出不仅包含检测框,还通过原型掩码上采样得到多边形轮廓(clipPaths),可用于精确裁剪目标区域(实现见 ov/segment.py 与 predict/segment.py)。

这些附加设备的模型同样从 Hugging Face 按需下载,并在推理前根据设备类型做输入张量 reshape(例如 NPU 上的文本模型 reshape 为 [1, 1, 64, 384],GPU 上则跳过以避免崩溃,见 ov/text_recognition.py)。

自定义检测模型:接入你自己的 YOLOv9 / ResNet

如果内置模型不够用,插件还通过 DeviceCreator 提供了自定义模型入口(predict/init.py 的 getCreateDeviceSettings / createDevice):

  1. 提供 Model Name(模型名称/描述)与 Model URL;
  2. URL 可以是直接指向 config.json 的地址,也可以是 GitHub 仓库地址(插件会自动拼接为 .../models/<plugin>/config.json);
  3. 插件下载 config.json 中 files 列表指向的模型文件(含 .xml 的 OpenVINO IR 模型),创建独立的检测设备。

自定义模型在运行时根据配置分发到不同解析路径(predict/custom_detect.py):

  • yolov9:走 parse_yolov9 目标检测解析;
  • resnet:走 softmax 分类,输出置信度超过 0.5 的前 3 个类别,并支持通过 Exclude Classes 设置排除指定类别;
  • 配置中还可提供 mean / std 对输入做标准化(见 ov/custom_detection.py)。

推理链路与高并发设计

从源码结构看,整个插件遵循一条清晰的分层链路:DetectPlugin(接口层)→ PredictPlugin(通用推理基类)→ OpenVINOPlugin(OpenVINO 实现)。其中几个关键设计值得关注:

  • 批量推理:PredictPlugin 实现了 queue_batch / run_batch / flush_batch 批处理机制,可在高负载下合并帧、分摊推理开销(predict/init.py);
  • 超时保护:safe_detect_once 对单次推理设置 60 秒超时,出错时打印异常并请求插件重启,避免检测卡死拖垮整个 NVR 管线;
  • 集群分叉:通过 ClusterForkInterface 支持在 Scrypted 集群 worker 上分叉检测任务(forkInterface / startCluster),多节点可分摊负载;主插件还会每 4 小时定期重启以规避底层推理库的内存泄漏;
  • 输入尺寸自适应:get_detection_input_size 返回 (None, None),告知管线无需强制缩放,插件侧会按需 resize 甚至多遍检测,便于生成高质量缩略图。

运行时依赖与版本兼容性提醒

插件依赖集中在 requirements.txt:

  • openvino==2026.2.0
  • Pillow==10.3.0
  • opencv-python-headless==4.10.0.84
  • transformers==5.2.0

该文件头部的注释记录了 OpenVINO 各版本在真实硬件上的兼容性问题,值得部署前留意:2025.3.0 在 9700(VGG)上加载失败、2025.0.0 在 13500H 上无法识别 CPU、2024.5.0 会崩溃 NPU(该版本 NPU 不能与 AUTO 混用)、2024.4.0 崩溃老系统、2024.3.0 在 J4105 等老 CPU 上若通过 apt 安装 level-zero 会崩溃、2024.2.0 及更旧版本在 Arc dGPU 上崩溃、2024.2.0 及更新版本在 700H / 900H GPU 上崩溃。当前锁定版本 2026.2.0 在 Wyse 5070 与 Core Ultra 125H 上验证可用,但要求较新的 Scrypted 镜像以提供对应计算运行时。

使用建议与注意事项

结合插件文档与源码,实际部署时建议遵循以下几点:

  1. 确认场景:仅在 Scrypted NVR 场景下启用,HomeKit 用户无需安装;
  2. 硬件规划:优先准备快速 GPU;若驱动不稳定,可在 Mode 中显式选择 CPU 并重载插件;
  3. 按设备选模型:让 Model 保持 Default,插件会依据 Arc / NVIDIA / Iris Xe / NPU / CPU 自动挑选合适的 YOLOv9 档位;
  4. 留意模型下载:首次启动需从 Hugging Face 下载模型,离线环境依赖本地缓存(files/hf),需保证网络或预置缓存;
  5. 组合使用扩展设备:人脸识别、文字识别、CLIP 嵌入与分割设备会自动注册,可直接在自动化中调用 ObjectDetection 接口消费其结果(如通过 detectObjects / generateObjectDetections 处理图像流,见 detect/init.py)。

总结

OpenVINO Object Detection 插件将 OpenVINO 的跨设备推理能力与 Scrypted NVR 的对象检测管线深度整合:既提供了面向 person / vehicle / animal 三类告警的即用型 YOLOv9 检测,又通过人脸识别、文字识别、CLIP 嵌入、实例分割和自定义模型等能力覆盖了更复杂的安防与自动化需求。理解其设备自动选择、模型下载与批量异步推理的设计,能够帮助你在实际部署中更好地发挥硬件性能、规避驱动与版本兼容性陷阱。

登录后查看全文
scrypted