Frigate中文文档

主题

2026-02-27
1891
6.6m

目标分类 0.17.0 和 以上版本 ​

提示

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

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

目标分类功能允许你训练一个自定义的MobileNetV2分类模型，该模型可运行在被追踪的目标（如人员、车辆、动物等）后，从而为这些目标识别出更精细的类别或属性。能够在浏览中的追踪目标详细信息窗口中、frigate/tracked_object_details MQTT主题、官方 Home Assistant Frigate 集成 的 传感器中，或者通过 HTTP API 中的事件接口查看分类结果。

最低系统要求 ​

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

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

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

类别 ​

类别是指你的模型将要学会区分的不同种类。每个类别代表模型将预测的一个独特视觉类别。

对于目标分类：

  • 定义用于区分被检测目标不同类型或属性的类别。
  • 示例：对于人员（person）类的目标，类别可以是外卖员、员工等。
  • 包含一个无标签（none）类别，用于那些不属于任何特定类别的目标。
  • 保持各类别在视觉上具有明显差异，以提高准确率。

分类类型 ​

  • 子标签：

    • 应用于目标的子标签（sub_label）字段。
    • 适用于单一、更具体的身份或类型。
    • 比如：猫（cat）→ 米米、花花、无标签（None）。

  • 属性：

    • 作为元数据添加至目标中（在 /events 接口及浏览页面的追踪目标详情面板中可见），同时会以 <模型名称>: <值> 的格式，在 frigate/events MQTT 消息与 HTTP API 响应数据内。
    • 适用于多个属性可以独立共存的情况。
    • 示例：检测建筑工地上的人员（person）是否佩戴了安全帽。

NOTE

每个被追踪的目标仅能拥有单个子标签。若你同时使用了 触发器 或 人脸识别 功能，且为 person 目标配置了基于「子标签（sub label）」类型的目标分类模型，那么该子标签可能无法被正确分配。出现此问题的原因是，子标签的最终分配结果取决于哪一项识别增强任务率先完成分析流程。这种情况建议你改用「属性（attribute）」类型替代子标签类型。

分配要求 ​

只有在同时满足以下两个条件时，才会分配子标签和属性：

  1. 阈值（Threshold）：每次分类尝试的识别分数百分比必须达到或超过配置的 threshold（默认值：0.8）。
  2. 类别共识（Class Consensus）：在至少 3 次分类识别尝试后，有 60% 的识别结果一致。如果共识类别为 none，则不进行分配。

这种两步验证机制通过要求在多个帧上保持一致的预测结果，防止误报，然后再分配子标签或属性。

示例使用场景 ​

子标签 ​

  • 已知宠物与未知宠物：对于狗（dog）类的目标，可以将子标签设置为你宠物的名字（例如旺财），其他则为无标签（none）。
  • 快递车辆与普通车辆：对于车辆（car），可以分类为快递车辆和无标签（none），以便筛选快递配送车。
  • 快递员与非快递员：对于人员（person），可以根据衣服将人员分类外卖员和无标签（none）。

属性 ​

  • 背包：对于人员（person），可以添加属性背包: 有/无。
  • 安全帽：对于人员（person），可以添加属性 安全帽: 有/无
  • 牵引绳：在公园或院子的场景，可以为狗（dog）添加 牵引绳：有/无。

配置 ​

目标分类被配置为一个自定义分类模型。每个模型都有其自己的名称和设置。你必须列出需要进行分类的目标标签。

yaml
classification:
  custom: 
    狗: # 分类的名称，可以使用中文
      threshold: 0.8
      object_config: 
        objects: [dog] # 要分类的目标标签
        classification_type: sub_label # 分类类型，可输入 sub_label（子标签）或 attribute（属性）

训练模型 ​

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

步骤 1：命名和定义 ​

为你的模型输入一个名称，然后选择要分类的目标标签（例如 人员（person）、狗（dog）、车辆（car）），选择分类类型（子标签或属性），并定义你的类别。Frigate 会自动添加一个 无标签（none）类别，用于归类不符合任何特定类别的目标。

例如：若要对家中的两只猫进行分类识别，可创建一个名为 “我家猫咪”的模型，并在模型中建立两个类别，分别命名为“米米”和“花花”。系统会自动生成第三个名为 无标签（none） 的类别，用于分类不是你家的其他小猫。

步骤 2：分配训练样本 ​

系统将自动从与你所选标签匹配的被检测目标中生成示例图像。系统会逐步引导你为每个类别选择哪些图像代表该类别。在你完成最后一个类别后，任何未分配到特定类别的图像将自动分配到 无标签（none）类别。一旦所有图像都处理完毕，训练将自动开始。

在选择要分类的目标时，建议从少量视觉上具有明显差异的类别开始，并确保你的训练样本与这些目标常见的摄像头视角和距离相匹配。

提升模型性能 ​

  • 问题定义：保持类别在视觉上具有明显差异，并与所选目标类型相关。
  • 数据收集：使用模型的“最近分类”选项卡，收集一天中不同时段、不同天气和不同距离下的均衡样本。
  • 预处理：确保示例图像反映与 Frigate 检测框相似的目标裁剪；保持主体居中。
  • 标签：保持标签名称简短且一致；如果你计划忽略子标签的不确定预测，包含一个 none 类别。
  • 阈值：根据每个模型调整 threshold 以减少误分配。从 0.8 开始，并根据验证结果进行调整。

调试分类模型 ​

排查目标分类模型故障时，开启调试日志可查看分类识别过程、置信分数及一致性判定的详细信息。

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

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

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

  • 每次分类识别的置信概率值
  • 置信分数是否达到阈值要求
  • 一致性判定的计算过程及分类结果确认时机
  • 目标分类历史记录与加权分数