VSL 项目原理
Video Search Local 的核心目标是：把连续、难以查找的监控视频，转换成可验证、可存储、可通过自然语言检索的结构化事件。
完整处理流程
1. 接入摄像头视频流
系统通过 FFmpeg 读取 RTSP、RTSPS、RTMP、RTMPS、HTTP-FLV、HLS、MJPEG、SRT、UDP 或 TCP 视频源。海康、大华、宇视等常见摄像头通常提供 RTSP 主码流和子码流。
2. 本地视觉模型检测
每隔指定时间抽取一帧，缩放到模型输入尺寸后交给 YOLO26s 或 D-FINE-S。推理可以使用 ONNX Runtime CPU，也可以使用 NVIDIA CUDA。输出包含类别、置信度和目标位置。
3. ByteTrack 目标跟踪
ByteTrack 根据连续帧中的目标位置和置信度关联同一个对象，为它生成稳定的短 ID。VSL 使用不同颜色显示不同 ID，并保存目标轨迹。这里的 ID 只在当前摄像头的一次运行和短时遮挡期间有效，不代表真实身份。
4. 规则判断和事件切片
用户可以按模型标签建立规则。例如“车辆”规则可以包含 car、truck 和 bus。只有同一目标连续命中规则达到设定帧数时，系统才创建固定时长的事件片段，减少无意义录像和 API 请求。
事件产物包括：
- 带边框、半透明遮罩、类别、置信度和目标 ID 的 MP4
- 事件封面 JPG
- VSS 风格逐帧轨迹元数据
*.cv.json.gz - SQLite 中的对象、规则、模型和处理状态
5. API 视觉大模型复核
事件录像完成后，系统异步调用用户配置的视觉大模型。OpenAI 兼容模式均匀抽取关键帧，DashScope 模式也可以上传原生 MP4。推荐让模型返回 JSON，字段包括摘要、活动、风险、关键词、相关规则、主要对象 ID 和时间线。
视觉 API 失败不会阻塞本地检测，任务保存在 SQLite 中并按设置重试。
6. 向量化和自然语言检索
系统把标签、规则、大模型摘要和关键词转换成向量并写入 Qdrant。用户输入自然语言描述后，系统检索相似事件，并返回录像、时间、摘要、对象 ID 和匹配度。
输入、处理与输出
| 类型 | 内容 |
|---|---|
| 输入 | 摄像头或流媒体 URL、检测模型、规则、视觉 API、Qdrant 配置 |
| 本地处理 | 解码、抽帧、检测、ByteTrack、规则判断、画框、录像 |
| 可选外部处理 | 视觉大模型 API 对事件进行语义复核 |
| 输出 | MP4、JPG、轨迹 JSON、SQLite 事件、Qdrant 向量 |
| 用户入口 | 实时监控、事件记录、智能搜索、系统设置 |
为什么采用两级推理？
本地检测模型速度快、成本稳定，适合持续处理视频，但它主要回答“画面里有什么”。视觉大模型擅长描述关系、活动和风险，却不适合把全部实时流持续上传分析。
VSL 先用本地模型和规则筛选事件，再让视觉大模型回答“发生了什么”，兼顾实时性、隐私、带宽和 API 成本。这与 NVIDIA VSS 的分层视频理解思路一致，但 VSL 是面向轻量本地部署的独立实现。
数据和隐私边界
- 原始连续视频流默认不永久保存。
- 本地检测、跟踪和规则判断不需要外部 API。
- 事件片段是否发送给视觉模型由用户配置决定。
- API Key 使用本地 AES-GCM 加密保存，读取设置时不返回明文。
- Qdrant 和 SQLite 默认都在本机或 Docker 环境内。