SentrySearch

你是否经历过这样的痛苦：对着几个小时的行车记录仪、监控录像或会议记录，为了寻找一个只有几秒钟的关键画面（比如“那辆红色卡车闯红灯的瞬间”），不得不快进、倒退、肉眼逐帧排查？

SentrySearch 是一个基于语义向量搜索的视频片段检索工具。你只需输入自然语言描述，它就能自动理解视频内容，精准定位并裁剪出你想要的片段。无需人工标注，无需语音转文字，真正实现了“所想即所得”。

核心原理：视频与文本的“跨模态对话”

SentrySearch 不依赖传统的关键词匹配或 OCR 识别，而是利用了最前沿的多模态嵌入技术：

1. 智能分片：将长视频自动切割成带有重叠窗口的短片段（如 30 秒），确保关键动作不被切断。
2. 向量化嵌入：
   • 使用 Google Gemini Embedding API 或本地的 Qwen3-VL 模型，直接将视频片段的像素信息映射为高维向量。
   • 同时，将你的文本搜索词（如“红色卡车”）映射到同一个向量空间。
3. 语义匹配：在向量数据库中计算文本与视频片段的相似度。即使视频中没有文字说明，模型也能“看懂”画面内容并与你的描述匹配。
4. 自动裁剪：找到最佳匹配后，自动从原视频中裁剪出该片段并保存。

核心优势：这是一种原生视频理解。不需要先转录音频或生成帧描述，文本查询直接与视频像素进行语义对齐，效率极高且准确率惊人。

双引擎驱动：云端极速 vs 本地隐私

SentrySearch 提供了灵活的部署方案，满足不同用户需求：

1. 云端模式 (Gemini Embedding)

• 优势：无需本地高性能显卡，利用 Google 强大的多模态模型，识别精度极高。
• 成本：极其低廉。索引 1 小时 视频素材仅需约 $2.84。搜索查询成本几乎可忽略不计。
• 适用：快速处理大量存量视频，或对精度要求极高的场景。

2. 本地模式 (Qwen3-VL)

• 优势：完全离线，数据不出本地，隐私绝对安全。
• 要求：需要本地 GPU 支持（推荐 NVIDIA 显卡）。
• 适用：处理敏感监控数据、涉密会议记录或无网络环境。

快速上手指南

第一步：安装环境

SentrySearch 使用现代化的 uv 包管理器，安装极速：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

克隆项目并同步依赖：

git clone https://github.com/ssrajadh/sentrysearch.git
cd sentrysearch
uv sync

第二步：初始化配置

sentrysearch init

按提示输入你的 Gemini API Key（或使用本地模式则跳过此步）。

第三步：索引视频库

假设你的行车记录仪 footage 在 /videos/dashcam：

# 使用云端模式
sentrysearch index /videos/dashcam

# 使用本地模式 (需先安装 extra 依赖: uv sync --extra local)
sentrysearch index /videos/dashcam --backend local

可选优化：通过 --chunk-duration (片段时长), --target-resolution (分辨率) 等参数平衡速度与成本。

第四步：开始搜索

# 搜索特定事件
sentrysearch search "红色卡车闯停止标志"

# 搜索并叠加特斯拉元数据 (速度/位置/时间)
sentrysearch search "car cutting me off" --overlay

# 导出前 5 个结果到指定目录
sentrysearch search "person running" --results 5 --output-dir ./found_clips

杀手级应用场景

高级功能亮点

• 📊 特斯拉元数据叠加：针对特斯拉车主，支持在导出的视频片段上自动叠加当时的车速、GPS 位置和时间戳，让证据更具说服力。
• ⚙️ 灵活调优：
  • --overlap：设置片段重叠时间，防止动作被切分。
  • --no-skip-still：强制嵌入静止帧，捕捉细微变化。
  • --threshold：调整匹配阈值，控制结果的精确度与召回率。
• 📈 统计洞察：运行 sentrysearch stats 查看已索引视频的数量、时长及数据库状态。

局限与展望

• 静止帧检测：目前基于启发式算法，极细微的运动可能被忽略（可通过 --no-skip-still 解决）。
• 片段边界：虽然重叠窗口能缓解，但精准的动作起始点仍依赖片段划分的粒度。
• API 稳定性：Gemini Embedding 2 目前处于预览阶段，定价和行为可能微调。