SentrySearch：基于Gemini视频嵌入的亚秒级语义视频搜索工具

我看看怎么个事
5 阅读1分钟

什么是SentrySearch

SentrySearch是一个视频语义搜索工具，你只需要输入文字描述想要找的内容，它就能自动从视频中找到对应的片段并剪辑出来。

它将MP4视频分割成重叠的块，使用Google Gemini Embedding API或者本地Qwen3-VL模型将每个视频块嵌入为向量，存储在本地ChromaDB数据库中。搜索时，文本查询会被嵌入到同一个向量空间，与存储的视频向量匹配，排名最高的匹配结果会自动从原视频中剪辑出来保存为片段。

安装方法

  1. 先安装uv包管理器：
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  1. 克隆项目并安装依赖：
git clone https://github.com/ssrajadh/sentrysearch.git
cd sentrysearch
uv sync
  1. 初始化配置：
sentrysearch init

这会提示你输入Gemini API密钥，写入.env文件并通过测试嵌入验证有效性。如果不想用init命令，也可以手动复制.env.example到.env，添加从aistudio.google.com/apikey获取的密钥。

基础使用

索引视频

sentrysearch index /path/to/dashcam/footage

索引选项：

  • --chunk-duration 30：每个块的秒数
  • --overlap 5：块之间的重叠秒数
  • --no-preprocess：跳过降采样/帧率降低，发送原始块
  • --target-resolution 480：预处理的目标高度（像素）
  • --target-fps 5：预处理的目标帧率
  • --no-skip-still：嵌入所有块，即使没有视觉变化

搜索视频

sentrysearch search "红色卡车闯红灯"

输出示例：

#1 [0.87] front_2024-01-15_14-30.mp4 @ 02:15-02:45
#2 [0.74] left_2024-01-15_14-30.mp4 @ 02:10-02:40
#3 [0.61] front_2024-01-20_09-15.mp4 @ 00:30-01:00

已保存剪辑：./match_front_2024-01-15_14-30_02m15s-02m45s.mp4

搜索选项：

  • --results N：返回N个结果
  • --output-dir DIR：输出目录
  • --no-trim：跳过自动剪辑
  • --threshold 0.5：调整置信度阈值（默认0.41）
  • --overlay：在剪辑上叠加速度、位置、时间等信息

特色功能

Tesla行车记录仪叠加支持

可以提取Tesla行车记录仪文件中的遥测数据（速度、GPS），渲染HUD叠加层，显示：

  • 顶部居中：速度和单位
  • 下方：日期和时间
  • 左上角：城市和道路名（通过逆地理编码）

安装Tesla叠加支持：

uv sync --extra tesla

要求：Tesla固件2025.44.25或更高版本，HW3+。

本地模型支持

可以使用本地Qwen3-VL-Embedding模型代替Gemini API，完全免费、隐私，所有运算都在本地运行：

# 安装本地模型依赖
uv sync --extra local
# 4位量化版本，更低显存占用
uv sync --extra local-quantized

使用本地模型索引和搜索：

sentrysearch index /path/to/footage --backend local
sentrysearch search "汽车闯红灯" --backend local

说明：

  • 首次运行会下载模型（2B参数约4GB，8B参数约16GB）
  • 推荐GPU运行（CUDA或Apple Metal），CPU也可以但速度很慢
  • 8B模型效果更好：--model Qwen/Qwen3-VL-Embedding-8B（需要约18GB显存）
  • Gemini和本地后端的嵌入不兼容，切换后端需要重新索引

统计信息

sentrysearch stats

输出示例：

总块数：47
源文件：12
后端：gemini

技术原理

Gemini Embedding 2和Qwen3-VL-Embedding都可以原生嵌入视频，原始视频像素直接投影到与文本查询相同的向量空间，不需要转录、帧字幕或者中间文本转换。"红灯前的红色卡车"这样的文本查询可以直接在向量级别与30秒视频剪辑比较，这是实现小时级视频亚秒级语义搜索的关键。

成本说明

使用Gemini嵌入API索引1小时视频的成本约为2.84美元（默认设置：30秒块，5秒重叠）： 1小时=3600秒视频=3600帧被模型处理 × 0.00079/帧= 0.00079/帧 = ~2.84/小时

内置优化降低成本：

  1. 预处理（默认开启）：块在上传前降采样到480p 5fps，减少上传大小和传输时间，不影响计费帧数
  2. 静态帧跳过（默认开启）：没有明显视觉变化的块（比如停着的车）会被完全跳过，直接减少API调用。Sentry Mode录制的大量闲置时间收益最大

搜索查询成本可以忽略不计（仅文本嵌入）。

系统要求

  • Python 3.11+
  • ffmpeg（PATH中，或者使用默认安装的imageio-ffmpeg捆绑版）
  • Gemini后端：Gemini API密钥（免费申请）
  • 本地后端：推荐带CUDA或Apple Metal的GPU
avatar
文章
阅读
粉丝