Frigate 语义搜索实测：中文搜索必须上 V2，但性能只提升 3%

核心洞察

Frigate 这套语义搜索基于语义理解而非关键词匹配的搜索技术，能理解查询意图和内容含义。的思路挺聪明，用 CLIP 模型把图片和文本塞进同一个向量空间，搜"红色衣服的人"就能直接出结果。但有个坑得提前说清楚：V1 模型只认英文，想用中文搜必须上 V2，而 V2 对硬件的要求高了一大截。另外触发器基于语义搜索的自动化规则，当追踪目标的图片或描述与预设值相似度超过阈值时执行通知、添加子标签或属性等动作。那个文本到图片的限制，文档解释得挺实在，CLIP 的分数确实不够稳定，拿来做自动化容易翻车。

核心结论

1. Frigate 语义搜索基于 Jina AI 的 CLIP 模型，将图片和文本嵌入同一向量空间，所有处理均在本地完成，需至少 8GB 内存且 CPU 支持 AVX + AVX2 指令集，建议 16GB 以上内存加独立 GPU 以获得最佳性能。

2. Jina CLIP v1Jina AI 发布的视觉-文本联合嵌入模型，支持图片到图片和文本到图片的相似性搜索，仅支持英文。 模型仅支持英文搜索，如需中文搜索必须使用 v2 模型（支持 89 种语言），但 v2 对内存和 GPU 要求大幅提高，且检索性能仅比 v1 提升约 3%，官方仍推荐大多数用户使用 v1。

3. 在 v1 与 v2 之间切换必须设置 reindex: True 并重启 Frigate 重新创建嵌入向量将文本、图像或其他数据转换为固定长度的数值向量表示，用于机器学习和相似性计算。索引，因为两个版本的嵌入向量不兼容，不重新索引会导致搜索结果错误。

4. 触发器功能不支持文本到图片的自动匹配，原因是 CLIP 模型对相同文本-图片对可能给出不一致的分数，阈值设定不可靠；官方建议先用文本搜索手动选取 3-5 个代表性追踪目标，再基于视觉相似性配置缩略图触发器。

5. 语义搜索默认关闭，需在配置中设置 semantic_search.enabled: True 启用；首次启用时 Frigate 不会自动为历史追踪目标建立索引，必须通过 reindex: True 手动完成，索引过程可能耗时较长且 CPU 负载较高。

语义搜索

0.15.0 和以上版本可用。

语义搜索依赖外部下载的模型文件，模型托管在 HuggingFace 上。如果你在中国大陆地区，参考通过 Docker 安装的教程，在 environment 里配一下 HF_ENDPOINT 环境变量，不然功能可能跑不起来。

这个功能让你通过图片本身、自己写的文字描述，或者自动生成的描述，来查找回顾项目里的追踪目标。比如"红色衣服的人"、"白色的猫"这种。

原理是给追踪目标的图片和文本描述创建嵌入向量，也就是数值向量表示。比较这些向量，Frigate 就能评估相似度，给出相关搜索结果。

Frigate 用的是 Jina AI 的模型来创建嵌入向量，存到 Frigate 数据库里。所有处理都在本地跑。

在 Frigate 网页的浏览页面就能用。

最低系统要求

语义搜索要在本地跑大型 AI 模型。树莓派这类小机器或者性能不够的系统，可能跑不稳，甚至完全跑不了。

至少需要 8GB 内存，CPU 得支持 AVX + AVX2 指令集。英语用户的话，GPU 不是硬性要求，但有 GPU 比纯 CPU 快不少。

想要最佳性能，建议 16GB 以上内存加独立 GPU。

配置

语义搜索默认关闭，得在配置文件或者增强功能设置页面里启用。这是全局配置。

semantic_search:
  enabled: True
  reindex: False

在 semantic_search 配置里加上 reindex: True，或者在网页增强功能设置页面切换开关再重启 Frigate，就能从数据库里现有的追踪目标重新创建嵌入向量索引。追踪目标多的话，这个过程可能挺久，索引时 CPU 负载也会很高。记得在再次重启 Frigate 前把开关关掉，或者把配置改回 False。

首次启用语义搜索的话，Frigate 不会自动给以前的追踪目标建索引。你得开 reindex 来完成这一步。

Jina CLIP v1

0.15.0 和以上版本可用。

Jina 的 V1 模型带视觉能力，能把图片和文本嵌入到相同的向量空间里，所以支持图片到图片、文本到图片的相似性搜索。Frigate 用这个模型给追踪目标编码，把缩略图存在数据库里。你在搜索框里输文字搜追踪目标时，Frigate 执行的是文本到图片相似性搜索。在追踪目标详情面板点"查找相似"时，执行的是图片到图片相似性搜索，找出最匹配的缩略图。

注意，v1 模型只能拿英文搜。要用中文搜，得换 Jina CLIP v2Jina AI 发布的第二代多语言 CLIP 模型，支持 89 种语言包括中文，但内存和 GPU 要求更高。 模型。

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

把 model_size 配成 small 或 large，可以选不同权重的 Jina 模型版本：

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 参数：

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

用 AXERA 算力卡的话，配置这样写：

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

大多数用户，尤其是母语是英语的，V1 模型仍然是推荐选择。

在 V1 和 V2 之间切换需要重新创建嵌入向量索引。在语义搜索配置里设 reindex: True 再重启 Frigate。V1 和 V2 的嵌入向量不兼容，不重新索引的话搜索结果会不对。

生成式 AI 提供者

生成式 AI 提供者带 embeddings 角色时，Frigate 可以用它来做语义搜索嵌入。目前只有 llama.cpp 支持多模态嵌入，也就是同时支持文本和图片。

用 llama.cpp 做语义搜索的步骤：

1. 配一个 roles 里包含 embeddings 的生成式 AI 提供者。
2. 把语义搜索模型设成生成式 AI 配置键，比如 default。
3. 用 --embeddings 和 --mmproj 启动 llama.cpp 服务器以支持图片。

llama.cpp 服务器必须带 --embeddings 启动才能启用嵌入 API，还得用多模态嵌入模型。细节看 llama.cpp 服务器文档。

GPU 加速

CLIP 模型以 ONNX 格式下载，有 GPU 时 large 模型可以用 GPU 硬件加速。这取决于你用的 Docker 构建版本。装多块 GPU 的话，也能指定用哪块。

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

用了适合你 GPU / NPU 的构建版本，又配了 large 模型，GPU 会被自动检测并使用。

device 选项用来在多 GPU 系统里指定某块 GPU，参考 onnxruntime 的提供商选项。不指定的话就用第一块可用的 GPU。

更多信息看功能增强文档。

使用方法和最佳实践

从语义搜索拿最佳结果的技巧，比如缩略图和描述搜索之间怎么选、查询怎么写更有效、搜索怎么跟其他浏览筛选器结合，看使用文档里的使用与最佳实践。

触发器

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

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

配置

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

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

在用户界面中管理触发器

1. 进设置页面，选触发器选项卡。
2. 从下拉菜单选一个摄像头，查看或管理它的触发器。
3. 点添加触发器新建，或者用铅笔图标编辑现有的。
4. 在创建触发器向导里：
   • 输入触发器名称，比如"Red Car Alert"。Frigate 会据此生成内部 ID，可以通过显示/隐藏切换按钮查看并编辑。
   • 选类型（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 个代表性参考追踪目标，然后基于那个视觉相似性配缩略图触发器。这样更有效，也没有文本到图片匹配的语义歧义。

常见问题（FAQ）

Frigate 语义搜索用中文搜不到结果怎么办？

V1 模型只支持英文搜索，想用中文必须切换到 Jina CLIP v2 模型，它覆盖包括中文在内的 89 种语言。切换后需设 reindex: True 重建索引，否则搜索结果会出错。

跑 Frigate 语义搜索最低需要什么配置？

至少 8GB 内存，CPU 需支持 AVX 和 AVX2 指令集，树莓派这类小机器可能跑不稳。想要最佳性能建议 16GB 以上内存加独立 GPU；V2 模型要求更高，不建议在 CPU 上跑。

Frigate 语义搜索的触发器能自动做什么？

触发器在追踪目标的图片或描述与预设内容相似度超过阈值时自动执行动作，可发送通知、添加子标签或写入属性。需先启用语义搜索，建议在用户界面配置。