Frigate 语义搜索Semantic Search与 Trigger 触发机制完全指南【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate导读Semantic Search 是 Frigate NVR 的一项本地化以图搜图 / 以文搜图能力它把 Review 中每一个被跟踪对象tracked object的缩略图与文字描述转换为数值向量embedding存放在本地数据库里从而支持通过文本、图片以及自动生成的描述快速检索历史片段。本文将以 Frigate 官方文档 semantic_search.md 为主体骨架结合仓库内配置定义与实现源码系统讲解语义搜索的启用方法、后端模型选择Jina CLIP V1/V2 与 GenAI Provider、GPU 加速配置以及基于相似度自动触发动作的 Triggers 机制。读完本文你将掌握完整可落地的配置方案与底层匹配原理。语义搜索是如何工作的Semantic Search 的核心是把非结构化数据图片、自然语言文本转换为向量再通过向量间的相似度计算实现检索。其工作流程可以归纳为被跟踪对象产生后Frigate 会为其生成缩略图并可能生成文字描述description。后端模型将缩略图与描述分别编码为 embedding——文本描述由文本模型编码缩略图由视觉vision模型编码见 frigate/embeddings/embeddings.py 中text_embedding与vision_embedding的构造逻辑。embedding 以序列化字节形式写入 Frigate 数据库中两张 SQLite 向量表vec_thumbnails缩略图向量与vec_descriptions描述向量。检索时将查询文本或查询图片编码为向量与表中存储的向量做相似度比较返回最相近的结果。具体而言embeddings.py中的embed_thumbnail()/batch_embed_thumbnail()会执行类似INSERT OR REPLACE INTO vec_thumbnails(id, thumbnail_embedding) VALUES(?, ?)的写入embed_description()/batch_embed_description()则写入vec_descriptions。缩略图在嵌入前会先经 PIL 解码并verify()校验损坏的图片会被跳过对应批量方法中的日志 Skipping corrupt thumbnail。Frigate 使用Jina AI的 CLIP 系列 ONNX 模型来创建与保存这些 embedding全部计算都在本机local完成不会把画面或文本发送到第三方。前端通过 Frigate UI 的Explore视图访问语义搜索。:::info 离线说明 语义搜索需要一次性的联网下载来获取 HuggingFace 上的 embedding 模型下载并缓存后即可完全离线工作。相关要求见 网络需求文档 中一次性模型下载一节。 :::最低系统要求语义搜索本质是在本机运行一个较大的 AI 模型因此对算力有硬性门槛项目要求内存最低 8GB RAM最佳体验建议 16GB 及以上CPU 指令集必须支持AVX AVX2指令GPU非必需但相比纯 CPU 能带来显著性能提升建议配备独立 GPURaspberry Pi 等小型或性能不足的设备将无法可靠运行语义搜索甚至完全无法运行。原因在于 CLIP 视觉/文本编码器是完整神经网络推理CPU-only 量化模型small虽然可以运行但吞吐与延迟都受限。从源码看small与large的差异主要体现在加载 ONNX 文件与运行设备上large模型默认倾向使用 GPU见下文。配置开启语义搜索语义搜索默认关闭且属于全局配置非逐摄像头配置。配置模型定义于 frigate/config/classification.py 的SemanticSearchConfigenabled默认False总开关reindex默认False置为True时在 Frigate 启动时对历史对象执行全量重建索引model默认jinav1可填jinav1、jinav2或一个具备embeddings角色的 GenAI Provider 配置键名model_size默认smallsmall量化、CPU 友好或large完整模型、GPU 加速device默认None多 GPU 环境下指定推理设备的覆盖项对应 onnxruntime 的 execution provider 选项。通过 UI 启用导航到Settings Enrichments Semantic search将Enable semantic search开关打开即可。通过配置文件启用semantic_search: enabled: True reindex: False:::tip 首次启用必须重建索引 嵌入式数据库只会索引启用之后新产生的对象。如果你第一次启用语义搜索Frigate 并不会自动索引历史上已存在的 tracked objects需要按下述方式手动执行一次重建。重建会遍历数据库中的全部 Event对每个对象提取缩略图与描述并重新计算 embedding。 :::Reindex重建索引的正确姿势两种触发方式等价在 UI 的Enrichments Settings中点击Reindex按钮在配置中加入reindex: True后重启 Frigate。从实现层面看reindex()见 frigate/embeddings/embeddings.py会依次执行删除并重建两张向量表 → 删除历史统计文件.search_stats.json→ 按Event.start_time倒序分页读取全部事件分两路分别批量嵌入缩略图与描述并通过进程间通信不断上报进度。需要提醒的是重建耗时与事件数量成正比过程中可能长时间打满 CPU批次大小与所选后端有关Jina V1 每批 32 条、V2 每批 4 条、GenAI Provider 每批 1 条文本单条处理以避免超出 token 上限start_reindex()用互斥锁保证重建不会并发执行若已有重建在运行会直接拒绝新的请求。后端模型选择Jina AI CLIP V1默认推荐V1 模型jinaai/jina-clip-v1的视觉模型能把图片与文本编码进同一个向量空间因此同时支持image - image与text - image两种检索图搜图image - image对 tracked objects 的缩略图编码并入库在 Explore 详情面板点击Find Similar时Frigate 用当前缩略图做相似度检索返回最接近的若干缩略图。文搜图text - image在搜索框中输入文字时Frigate 对该文本执行相似度检索返回匹配的缩略图。V1 的文本模型则用于对 tracked object 的文字描述编码与检索。描述可以在 Explore 页面点击对象缩略图后创建、查看和修改关于如何用 GenAI 自动生成对象描述见 对象描述object descriptions文档。V1 提供不同量化版本通过model_size切换semantic_search: enabled: True model: jinav1 model_size: smallsmall使用量化版 ONNX 模型占用内存更小、跑在 CPU 上embedding 质量差异几乎可忽略large使用完整 fp16 模型若硬件与 Docker 构建支持会自动跑在 GPU 上。源码印证embeddings.py对jinav1会分别实例化JinaV1TextEmbedding文本模型固定跑 CPU与JinaV1ImageEmbedding视觉模型默认按model_size large选 GPU否则 CPU且large下载的是jina-clip-v1-vision_model_fp16.onnxsmall下载的是jina-clip-v1-vision_model_quantized.onnx见 jina_v1_embedding.py。Jina AI CLIP V2多语言Frigate 同时支持 V2 模型jinaai/jina-clip-v2核心增量是多语言能力89 种语言——V1 仅支持英文。semantic_search: enabled: True model: jinav2 model_size: large需要注意 V2 的取舍V2 相比 V1 在 text-image 与 text-text 检索任务上仅提升约3%实际感知收益并不明显V2 对 RAM 与显存的需求显著更高推理耗时与内存占用都随之上升。若计划使用 V2请确保系统拥有充足内存与独立 GPU不推荐用 V2 small在 CPU 上推理编码器推理耗时增长明显。实现上V2 使用单一的JinaV2Embedding实例同时承担文本与视觉编码其__call__通过线程锁串行化文本/视觉调用见 jina_v2_embedding.py同样以model_size决定下载model_fp16.onnx还是model_quantized.onnx。结论对绝大多数用户尤其是英语母语用户V1 仍是首选。:::note 换模型必须重建索引 在 V1 与 V2或 Jina 与 GenAI Provider之间切换后必须重新索引。不同后端的 embedding 空间不兼容不重建会得到错误、不可用的搜索结果。 :::使用 GenAI Provider 生成 embedding当某个 GenAI Provider 具备embeddings角色时Frigate 可以借用它生成语义搜索向量。目前仅 llama.cpp支持多模态 embedding同时支持文本与图片。前提条件三条在 GenAI 配置中给 Provider 的roles加上embeddings把语义搜索的model指向该 GenAI 配置键名如default以--embeddings启动 llama.cpp 服务端并使用多模态 embedding 模型需--mmproj加载视觉投影以支持图片。genai: default: provider: llamacpp base_url: http://localhost:8080 model: your-model-name roles: - embeddings - descriptions - chat semantic_search: enabled: True model: defaultUI 操作在Settings Enrichments Semantic search中将 Semantic search model or GenAI provider name 设置为 GenAI 配置键名同时需在Settings Enrichments Generative AI中为对应 Provider 勾选embeddings角色。源码验证embeddings.py的初始化逻辑会先检查semantic_search.model是否是SemanticSearchModelEnum枚举——若不是则认定指向 GenAI Provider并通过genai_manager.embeddings_client构造GenAIEmbedding若找不到具备 embeddings 角色的客户端会抛出ValueError提示 Ensure the GenAI provider has embeddings in its roles。GenAI 后端在reindex时batch_size为 1逐条处理避免 token 溢出。GPU 加速与多 GPU 设备选择CLIP 模型以 ONNX 格式下载large模型在硬件与 Docker 构建支持的前提下可被 GPU/NPU 自动加速semantic_search: enabled: True model_size: large # 可选多 GPU 环境中指定推理设备onnxruntime provider 设备索引 device: 0只要使用了与你的 GPU/NPU 匹配的 Frigate 构建且配置了largeGPU 会被自动检测并启用device用于多 GPU 系统中锁定特定设备参考 onnxruntime 的 execution provider 选项。不指定时使用第一块可用 GPU各硬件平台的加速能力取决于所用 Docker 构建详见 硬件加速推理Enrichments文档。注意small模型始终运行在 CPU源码中device默认解析为CPUlarge才具备走 GPU 的可能。使用技巧与最佳实践关于如何最大化语义搜索效果——例如在缩略图检索与描述检索之间做选择、如何组织查询语句、以及如何与 Explore 页其他过滤器时间、区域、对象类型、事件严重度等组合——建议阅读 Explore 用法文档 中的 Usage and best practices 一节。简单几条原则缩略图 vs 描述想找看起来像的对象用缩略图检索想找具备某种语义特征的对象如由 GenAI 自动生成的文字描述用描述检索查询词句用简洁、具体、与日常描述一致的关键词比模糊的泛化词命中率更高组合过滤先用语义搜索粗筛再叠加时间范围、区域与对象类别过滤可以显著缩小候选集。Triggers基于相似度的自动触发Triggers 把语义搜索从手动检索升级为自动告警当某个 tracked object 的缩略图或描述与预设的参考图片/文本足够相似超过阈值时Frigate 自动执行预设动作。Triggers 按**逐摄像头per camera**管理通过 UI 中 Settings 页的Triggers标签页配置。:::note 前置条件 Triggers 依赖语义搜索的 embedding 管线因此必须先启用 semantic_search才能使用 Triggers。 :::Triggers 的组成与配置模型每个 trigger 由以下字段构成对应 classification.py 中TriggerConfig的字段字段说明默认值friendly_name在 UI 中展示的友好名称如 Red car on the driveway camera无enabled该 trigger 是否启用Truetypethumbnail图片匹配或description文本匹配descriptiondata参考内容thumbnail 类型填参考 Event IDdescription 类型填参考文本必填threshold相似度阈值0~1达到该值才触发0.8actions触发后执行的动作列表notification、sub_label、attribute空列表在 YAML 中 triggers 嵌套在每台摄像机的semantic_search配置下对应CameraSemanticSearchConfig.triggers一个以 trigger 名为键的字典。UI 的 Add Attribute 所写入的内部 ID即这个 trigger 名如red_car_alert它会被作为 data attribute 附加到 tracked object 上供 API/MQTT 消费。虽然 YAML 可以手写但官方建议 Triggers尽量通过 UI 配置。若确实在配置文件中编辑Frigate 会在启动/运行时通过sync_triggers()把配置文件中的 triggers 与 UI 创建的记录双向同步见 frigate/embeddings/embeddings.py同步会创建缺失的 trigger、按配置更新已变更的type/data/threshold、为 thumbnail 类型的 trigger 把参考事件的缩略图落盘到 trigger 目录webp并从数据库中删除配置中已移除的 trigger。persist 层方面trigger 在数据库中表现为frigate/models.py的Trigger模型主键为(camera, name)复合键字段包含type、data、threshold、model、embeddingBlob、triggering_event_id与last_triggered。在 UI 中管理 Triggers导航到Settings Enrichments Triggers从下拉框选择一台摄像机点击Add Trigger新建或用铅笔图标编辑已有 trigger在Create Trigger向导中Name触发器名称如 Red Car Alert同时作为 attribute 内部 ID 与 MQTT 标识Friendly Name描述性名称如 Red car on the driveway cameraTypeThumbnail或DescriptionThumbnail类型从 Explore 选择一个参考图片即某个 Event当检测到相似度超阈值的缩略图时触发Description类型输入参考文本当 tracked object 的文字描述与之相似时触发Threshold相似度匹配阈值Actions若已启用原生 webpush 通知勾选Send Notification即可推送通知勾选Add Sub Label把 trigger 的 friendly name 作为 sub label 附加到触发的 tracked object 上勾选Add Attribute把 trigger 的内部 ID如red_car_alert写入 tracked object 的 data attribute供 API 或 MQTT 消费。保存 trigger配置被更新同时参考图片/文本的 embedding 被计算并存入数据库。触发后的可视化反馈当 trigger 命中时UI 会用蓝色圆点高亮该 trigger 持续 3 秒便于识别同时显示最近一次触发的日期时间与被触发的 tracked object ID。注意最近触发时间戳不会写入数据库也不会在 Frigate 重启后保留——它只是运行时的展示信息对应Trigger.last_triggered只在进程内更新、且初始为None。底层触发逻辑Triggers 的运行时判定位于 frigate/data_processing/post/semantic_trigger.py 的SemanticTriggerProcessor这是一个后处理阶段post time processor。其核心流程是拿到事件后按process_typeimage/text从vec_thumbnails或vec_descriptions读出该事件的 embedding依次读取该摄像头所有启用的 trigger把 trigger 的 embedding 与事件 embedding 计算余弦距离frigate/util/builtin.py的cosine_distance用Z-score 归一化见 frigate/embeddings/util.py实现采用 Welford 在线算法维护 mean/M2将距离归一化后换算为相似度similarity 1 - normalized_distance当similarity threshold时触发更新该 trigger 的last_triggered与triggering_event_id总是通过进程间通信发布一条triggersMQTT 消息含 name / camera / event_id / type / score若配置了sub_label动作则发布 sub_label 元数据内容为 friendly_name similarity若配置了attribute动作则发布 attribute 元数据内容为 trigger name type similaritynotification动作由 webpush 机制单独处理。Z-score 归一化所需的分布统计来自.search_stats.json每类数据各维护一套thumb_stats/desc_stats这也是 FAQ 中 CLIP 分数不稳定、难以设定固定截断值 的技术背景之一。Triggers 使用与最佳实践Thumbnail 类触发从 Explore 页挑选一张与你目标对象高度吻合的代表性 Event 缩略图。最佳实践是选择对象主体突出、几乎占满画面的图片——对象太小或太偏会稀释特征。Description 类触发写简洁、具体的描述例如 Person in a red jacket并尽量与 tracked object 的自动生成描述措辞一致。避免模糊词汇如 something以提升匹配精度。阈值调优阈值用于平衡灵敏度与特异性。高阈值如 0.8要求非常接近才触发误报少但可能漏掉相似对象低阈值如 0.6覆盖更广但更容易频繁误触发。建议从 0.8 起步结合触发历史逐步下调。快速建触发器在 Explore 的 Grid View 中对某个 tracked object 右键或长按弹出上下文菜单可以直接基于该缩略图新建一个 thumbnail trigger无需手动复制 Event ID。编辑触发器优先在 UI 编辑若在配置文件手动编辑Frigate 会保证 config 中修改过的 trigger 与 UI 中创建的 trigger 双向同步。Notes注意事项Triggers 复用语义搜索所用的同一套 Jina CLIPV1/V2模型务必保证semantic_search已启用且配置正确通过 UI 或reindex: True重建 embedding 索引不会删除或重置trigger 配置但可能刷新匹配所用的 embedding从而改变后续相似度得分系统资源方面遵循语义搜索本身的建议内存最低 8GB、推荐 16GB 以上large模型建议搭配 GPU以保证触发判定的实时性。FAQ为什么不能用文字描述缩略图的触发器问为什么我无法创建一个基于文本如 person with a blue shirt的 trigger让它在该描述出现时自动触发答TL;DR文本到图片text-to-image的触发器不受支持。因为 CLIP 对相似图片可能给出不一致的分数同一文字-图片对在不同时刻得到的余弦距离可能漂移且不同样本的分数区间过于接近无法设定一个可靠的截断值来区分相关与不相关结果作为自动化判据不稳定。展开来说这是 CLIP 相似度检索的根本性局限而非 Frigate 的缺陷Embedding 漂移同一 text-image 对在不同时间的余弦距离存在波动离线重算也会产生偏差缺乏真正的语义锚定CLIP 可能把视觉上相似但语义上错误的内容判为匹配不具备可靠的语义一致性阈值不稳定距离分布与数据集强相关且往往过于集中难以划出稳定、普适的分界线。CLIP 这类模型适合探索性、人工判断的手动检索用户可自行判断结果好坏却不适合依赖单一阈值的自动化触发。官方推荐的替代工作流是先用文本检索手动挑出3~5 个有代表性的参考 tracked objects基于这些对象的缩略图配置thumbnail triggers。这样既绕开了 text-image 匹配的语义歧义又获得了稳定的自动化告警。延伸阅读Explore 用法与最佳实践语义搜索前端入口与检索技巧对象描述GenAI 自动生成如何自动生成被跟踪对象的文字描述作为 description 向量与文本检索的数据来源硬件加速推理EnrichmentsGPU/NPU 上运行 enrichment 模型的 Docker 构建与要求网络需求文档一次性模型下载与缓存说明。如果想深入阅读代码建议从这三个文件切入配置模型 frigate/config/classification.pySemanticSearchConfig/TriggerConfig、嵌入数据库 frigate/embeddings/embeddings.py表结构与 reindex/trigger 同步、触发判定 frigate/data_processing/post/semantic_trigger.py相似度计算与动作发布相关存储模型见 frigate/models.py 的Event与Trigger。【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考