状态分类 0.17.0 和 以上版本

提示

状态分类功能需要依赖外部下载的模型权重文件。相关模型托管在 Google 上。

如果你在中国大陆地区，请参考通过 Docker 安装的教程，在environment中配置TF_KERAS_MOBILENET_V2_WEIGHTS_URL环境变量，否则功能可能无法正常使用。

状态分类功能允许你在摄像头画面的固定区域内训练一个自定义的 MobileNetV2 分类模型，以确定该区域的当前状态。该模型可配置为按计划运行和/或当该区域检测到画面变动时运行。能够在frigate/<camera_name>/classification/<model_name> MQTT主题、官方 Home Assistant Frigate 集成 的 传感器中查看分类结果。

最低系统要求

状态分类模型轻量级，在 CPU 上运行速度非常快。几乎任何能够运行 Frigate 的设备都能支持推理功能。

模型训练期间，每轮训练大约会短暂占用较高的系统资源，持续 1 到 3 分钟。在性能较低的设备上，训练时间可能会更长。

训练与推理过程要求 CPU 必须支持 AVX 指令集。

类别

类别是指你摄像头画面中某个区域可能处于的不同状态。每个类别代表模型将学习识别的一种独特的视觉状态。

对于状态分类：

• 定义表示互斥状态的类别
• 例如：车库门或前门的开启和关闭，灯光的开启关闭等
• 至少使用 2 个类别（通常只有两种状态效果最佳）
• 保持类别名称清晰且具有描述性

示例使用场景

• 门的状态：检测车库门或前门是开启还是关闭。
• 闸门的状态：检查车道闸门是开启还是关闭。
• 快递/外卖放在指定位置：检查指定位置是否放有物体，如外卖、快递箱。

配置

状态分类被配置为一个自定义分类模型。每个模型都有其自己的名称和设置。你必须在 state_config.cameras 下至少提供一个摄像头裁剪区域。

classification:
  custom:
    front_door:
      threshold: 0.8
      state_config:
        motion: true # 当画面变动与裁剪区域重叠时运行
        interval: 10 # 也可以每 N 秒运行一次（可选）
        cameras:
          front:
            crop: [0, 180, 220, 400]

save_attempts 为可选配置项，可作为键配置在模型名称对应的配置层级下。该参数用于定义在近期分类记录标签页中保存的分类识别尝试次数。对于状态分类模型，此参数的默认值为 100。

训练模型

创建和训练模型是在 Frigate 网页中通过“分类”页面完成的。该过程包括三个步骤：

步骤 1：命名和定义

为你的模型输入一个名称，并定义至少 2 个表示互斥状态的类别（状态）。例如，门的开启和关闭，或者灯光的开启和关闭。

步骤 2：选择裁剪区域

选择一个或多个摄像头，并在每个摄像头中对你感兴趣的区域绘制一个矩形。裁剪区域应紧密围绕你想要分类的区域，以避免引入与分类目标无关的额外信号。你可以拖动和调整矩形大小来调整裁剪区域。

步骤 3：分配训练样本

系统将自动从你的摄像头画面中生成示例图片。系统会逐步引导你为每个类别选择哪些图片代表该状态。并非严格要求你选择看到的所有图片。如果某个状态在样本中缺失，你可以稍后从“最近”选项卡中对其进行训练。

一旦分配了一些图片，训练将自动开始。

若部分类别的样本未在网格中显示，你仍可跳过这些样本继续配置模型。新的图片将陆续出现在近期分类记录视图中。当捕捉到那些缺失类别的图片时，你可以在该视图中完成分类标注，之后重新训练模型即可。

提升模型性能

• 问题定义：保持类别在视觉上具有明显差异且专注于状态（例如，开启、关闭、未知）。除非必要，避免在单个模型中将对象身份与状态混合在一起。
• 数据收集：使用模型的“最近分类”选项卡，收集一天中不同时段和不同天气条件下的均衡样本。
• 何时训练：重点关注模型完全错误或在不应切换状态时发生状态切换的情况。当模型已经能够稳定工作时，无需额外训练更多图片。
• 选择训练图片：由于新条件（例如一年中的第一场雪、季节变化）或其他变化（例如临时出现在视野中的物体、夜间的昆虫）而导致得分低于 100% 的图片，是很好的训练候选对象，因为它们代表了与默认状态不同的场景。训练这些与现有训练数据不同的低分图片有助于防止过拟合。避免训练大量看起来非常相似的图片，尤其是那些已经得分为 100% 的图片，因为这可能导致过拟合。

调试分类模型

排查状态分类模型相关故障时，开启调试日志可查看分类识别过程、置信分数及状态验证的详细信息。

在 logger 配置中添加 frigate.data_processing.real_time.custom_classification: debug，即可开启分类模型的调试日志。该日志输出内容较为详尽，仅在排查问题时开启即可。修改配置后需重启 Frigate 生效。

logger:
  default: info
  logs: 
    frigate.data_processing.real_time.custom_classification: debug

调试日志将展示以下内容：

• 每次分类识别的置信概率值
• 置信分数是否达到阈值要求
• 状态验证进度（达成验证所需的连续识别次数）
• 状态变更结果的推送时机

近期分类记录

针对状态分类功能，图片仅会在以下特定场景下被存入「近期分类记录」中：

• 首次识别：摄像机完成的第一次分类识别结果，将永久保存
• 状态变更：当识别到的状态与当前已验证的状态不一致时，对应的图片会被保存
• 待验证状态：存在待确认的状态变更时（需连续识别到3次相同状态方可完成验证），相关图片会被保存
• 低置信度识别：即便识别出的状态与当前状态一致，只要置信分数未达到100%，对应的图片仍会被保存（该机制对模型训练十分有帮助）

当监测状态处于稳定状态（识别状态与当前已验证状态一致），且本次分类的置信分数为100%时，图片不会被保存。该规则可有效避免存储大量无意义的高置信度重复分类图片，节省存储资源。