Frigate中文文档

主题

2026-05-18
3310
11.8m

语义搜索 0.15.0 和 以上版本 ​

提示

语义搜索功能需要依赖外部下载的模型文件。相关模型托管在 HuggingFace 上。

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

Frigate 中的语义搜索功能允许你通过图片本身、用户定义的文本描述或自动生成的描述来查找回顾项目中的追踪目标。例如“红色衣服的人”或者“白色的猫”等。

该功能通过为追踪目标的图片和文本描述创建嵌入向量(数值向量表示)来实现。通过比较这些嵌入向量，Frigate 评估它们的相似度以提供相关的搜索结果。

Frigate 使用来自 Jina AI 的模型创建嵌入向量并保存到 Frigate 数据库中。所有处理都在本地运行。

语义搜索功能可通过 Frigate 网页中的 浏览 页面使用。

最低系统要求 ​

语义搜索通过在本地系统上运行大型 AI 模型实现。树莓派等小型或性能不足的系统可能无法可靠运行或完全无法运行语义搜索。

使用语义搜索至少需要 8GB 内存，且 CPU 需支持 AVX + AVX2 指令集。对于使用英语的用户，虽然 GPU 不是严格必需的，但相比仅使用 CPU 的系统，GPU 能显著提升性能。

为获得最佳性能，建议使用 16GB 或更多内存和独立 GPU。

配置 ​

语义搜索默认禁用，必须在配置文件或增强功能设置页面中启用后才能使用。语义搜索为全局配置设置。

yaml
semantic_search:
  enabled: True
  reindex: False

提示

通过添加reindex: True到semantic_search配置中，或在网页增强功能设置页面切换开关并重启 Frigate，可以从数据库中现有的追踪目标重新创建嵌入向量索引。根据追踪目标的数量，此过程可能需要较长时间，并可能在索引时使 CPU 负载非常高。确保在再次重启 Frigate 前关闭页面中的开关或将配置改回False。

如果是首次启用语义搜索，请注意 Frigate 不会自动为以前的追踪目标创建索引。你需要启用reindex功能来完成此操作。

Jina CLIP v1 0.15.0 和 以上版本 ​

Jina 的 V1 模型具有视觉模型，能够将图片和文本嵌入到相同的向量空间中，从而实现图片->图片和文本->图片的相似性搜索。Frigate 使用此模型对追踪目标进行编码，将缩略图图片存储在数据库中。当通过搜索框中的文本搜索追踪目标时，Frigate 将执行文本->图片相似性搜索。当在追踪目标详情面板中点击"查找相似"时，Frigate 将执行图片->图片相似性搜索以检索最匹配的缩略图。

警告

注意，v1的模型只能使用英文进行搜索。如果需要使用中文搜索，请使用Jina CLIP v2模型。

V1 文本模型用于嵌入追踪目标描述并对其执行搜索。描述可以在浏览页面点击追踪目标缩略图时创建、查看和修改。有关如何自动生成追踪目标描述的更多信息，请参阅生成式 AI 文档。

通过设置model_size配置选项为small或large，可以选择不同权重的 Jina 模型版本：

yaml
semantic_search:
  enabled: True
  model: "jinav1"
  model_size: small
  • 配置large模型将使用完整的 Jina 模型，如果适用会自动在 GPU 上运行。
  • 配置small模型将使用量化版本的 Jina 模型，占用更少内存并在 CPU 上运行，嵌入质量差异可以忽略不计。

Jina CLIP v2 0.16.0 和 以上版本 ​

Frigate 也支持Jina 的 V2 模型，该模型引入了多语言支持（支持 89 种语言，包括中文）。相比之下，V1 模型仅支持英语。

V2 在文本-图片和文本-文本检索任务中仅比 V1 有 3% 的性能提升，这种改进不太可能带来明显的实际好处。此外，V2对内存和 GPU 的要求有很大提高，导致推理时间和内存使用增加。如果你计划使用 V2，请确保系统有充足的内存和独立显卡。不建议在 CPU 上使用 V2 的small模型进行推理。

要使用 V2 模型，请更新配置中的model参数：

yaml
semantic_search:
  enabled: True
  model: "jinav2"
  model_size: large

若使用 AXERA 算力卡，请使用如下配置：

yaml
semantic_search:
  enabled: True
  model: ax_jinav2
  model_size: large

对于大多数用户，特别是母语为英语的人，V1 模型仍然是推荐选择。

NOTE

在 V1 和 V2 之间切换需要重新创建嵌入向量索引。为此，在语义搜索配置中设置reindex: True并重启 Frigate。V1 和 V2 的嵌入向量不兼容，如果不重新索引将导致搜索结果不正确。

GPU 加速 ​

CLIP 模型以 ONNX 格式下载，当可用时，large模型可以使用 GPU 硬件加速。这取决于使用的 Docker 构建版本。你也可以在安装了多个 GPU 的情况下指定使用特定设备。

yaml
semantic_search:
  enabled: True
  model_size: large
  # 可选, 如果你有多个GPU并且使用 large 模型
  device: 0

信息

如果使用了适合你 GPU / NPU 的正确构建版本并配置了large模型，GPU 将被自动检测并使用。

指定device选项来针对多 GPU 系统中的特定 GPU（参见onnxruntime 的提供商选项）。 如果你不指定设备，将使用第一个可用的 GPU。

更多信息请参考功能增强文档.

使用方法和最佳实践 ​

  1. 语义搜索与浏览页面上的其他过滤器结合使用效果最佳。结合传统过滤和语义搜索可获得最佳结果。
  2. 当搜索场景中的特定目标时使用缩略图搜索类型。当尝试辨别目标意图时使用描述搜索类型。
  3. 由于 Frigate 使用的 AI 模型训练方式，在多模态(缩略图和描述)搜索中，匹配描述的结果通常会先出现，即使缩略图嵌入可能是更好的匹配。尝试调整"搜索类型"设置以帮助找到所需内容。请注意，如果仅为特定目标或区域生成描述，可能导致搜索结果优先显示有描述的目标，即使没有描述的目标更相关。
  4. 使搜索语言和语气与你要查找的内容紧密匹配。如果使用缩略图搜索，将查询短语作为图片标题。搜索"红色汽车"可能不如"阳光明媚的住宅区街道上行驶的红色轿车"效果好。
  5. 缩略图的语义搜索在匹配占据大部分画面的大主体时效果更好。"猫"等小物体往往效果不佳。
  6. 多尝试！找到一个想测试的追踪目标，开始输入关键词和短语，看看什么对你有效。

触发器 ​

触发器利用语义搜索在追踪目标匹配指定图片或描述时自动执行动作。可以配置触发器，使 Frigate 在追踪目标的图片或描述基于相似度阈值匹配预定义图片或文本时执行特定动作。触发器按摄像头管理，可以通过 Frigate 用户界面在设置页面的触发器选项卡中进行配置。

NOTE

必须启用语义搜索才能使用触发器。

配置 ​

触发器在你的 Frigate 配置文件中的每个摄像头的semantic_search配置内定义，或通过用户界面定义。每个触发器包含一个friendly_name、一个type（thumbnail或description）、一个data字段（参考图片事件 ID 或文本）、用于相似度匹配的threshold，以及触发器触发时要执行的actions列表 - notification、sub_label和attribute。

最好通过 Frigate 用户界面配置触发器。

在用户界面中管理触发器 ​

  1. 导航到设置页面并选择触发器选项卡。
  2. 从下拉菜单中选择一个摄像头以查看或管理其触发器。
  3. 点击添加触发器创建新触发器或使用铅笔图标编辑现有触发器。
  4. 在创建触发器向导中：
    • 输入触发器的名称（例如，"Red Car Alert"）。
    • 输入触发器的描述性友好名称（例如，"Red car on the driveway camera"）。
    • 选择类型（Thumbnail或Description）。
    • 对于Thumbnail，选择一个图片，当基于阈值检测到相似的缩略图图片时触发此动作。
    • 对于Description，输入文本，当检测到相似的追踪目标描述时触发此动作。
    • 设置相似度匹配的阈值。
    • 选择触发器触发时要执行的动作。 如果启用了原生 webpush 通知，选中发送通知框以发送通知。 选中添加子标签框以将触发器的友好名称作为子标签添加到任何触发的追踪目标。 选中添加属性框以将触发器的内部 ID（例如，"red_car_alert"）添加到追踪目标的数据属性中，该属性可通过 API 或 MQTT 处理。
  5. 保存触发器以更新配置并将嵌入存储到数据库中。

当触发器触发时，用户界面会用蓝点高亮显示触发器 3 秒钟以便于识别。此外，用户界面将显示激活你的触发器的最后日期/时间和追踪目标 ID。最后触发的时间戳不会保存到数据库中或在 Frigate 重启后持久化。

使用方法和最佳实践 ​

  1. 缩略图触发器：从浏览页面选择与你要检测的目标密切匹配的代表性图片（事件 ID）。为获得最佳结果，选择目标突出并占据画面大部分的图片。
  2. 描述触发器：编写简洁、具体的文本描述（例如，"Person in a red jacket"），与追踪目标的描述保持一致。避免模糊术语以提高匹配准确性。
  3. 阈值调整：调整阈值以平衡敏感性和特异性。更高的阈值（例如 0.8）需要更接近的匹配，减少误报但可能错过相似目标。更低的阈值（例如 0.6）更具包容性但可能更频繁触发。
  4. 使用浏览：在浏览的网格视图中使用上下文菜单或右键/长按追踪目标，以基于追踪目标的缩略图快速添加触发器。
  5. 编辑触发器：为获得最佳体验，应通过用户界面编辑触发器。但是，Frigate 将确保在配置中编辑的触发器与在用户界面中创建和编辑的触发器同步。

注意事项 ​

  • 触发器依赖于用于语义搜索的相同 Jina AI CLIP 模型（V1 或 V2）。确保启用了semantic_search并正确配置。
  • 重新索引嵌入（通过用户界面或reindex: True）不会影响触发器配置，但可能更新用于匹配的嵌入。
  • 为获得最佳性能，请使用具有足够内存（最少 8GB，建议 16GB）和 GPU 的系统，并使用large模型配置。

常见问题 ​

为什么我不能通过某些文本（如“穿蓝衬衫的人”）创建缩略图触发器，让它在检测到穿蓝色衬衫的人时触发？ ​

简而言之：不支持文本到图片触发器，是因为 CLIP 可能混淆相似图片并给出不一致的分数，使自动化不可靠。相同的词到图片对可能给出不同的分数，且分数范围可能太接近而无法设置清晰的截止点。

由于基于 CLIP 的相似性搜索的根本限制，不支持文本到图片触发器。虽然 CLIP 在探索性、手动查询方面效果很好，但对于基于阈值的自动触发器来说是不可靠的。比如存在嵌入漂移（相同的文本-图片对可能随时间产生不同的余弦距离）、缺乏真正的语义基础（视觉相似但不正确的匹配）和不稳定的阈值设定（距离分布依赖于数据集，通常过于紧密聚集而无法区分相关和无关结果）等问题。

所以我们建议通过设置一个缩略图来设置触发器：首先使用文本搜索手动选择 3-5 个代表性参考追踪目标，然后基于该视觉相似性配置缩略图触发器。这将更加有效，并且没有文本到图片匹配的语义歧义。