自然语言视频搜索

利用 Gemini Embedding 2 原生的视频到向量（video-to-vector）嵌入能力，通过自然语言查询搜索视频文件。

该技能的功能

本技能支持将视频文件（如特斯拉行车记录仪录像、安防摄像头录像、任意 mp4 文件）索引至本地向量数据库，随后可通过日常英语描述目标内容进行搜索。匹配度最高的结果会自动裁剪并保存为独立视频片段。

针对特斯拉行车记录仪录像，可选的遥测数据叠加层（telemetry overlay）可在裁剪后的片段中烧录显示车速、GPS 坐标、地理位置及转向灯状态等信息。

安装配置

需安装 uv 工具及 Python 3.11+ 环境。

1. 克隆并安装：

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

如需启用特斯拉遥测叠加支持（含逆地理编码）：

uv sync --extra tesla

2. 设置 Gemini API 密钥：

sentrysearch init

该命令将提示输入密钥，将其写入 .env 文件，并通过一次测试嵌入验证有效性。你也可直接将 GEMINI_API_KEY 设为环境变量。

命令说明

索引视频文件

sentrysearch index <目录或文件路径>

可选参数：--chunk-duration（默认 30 秒）、--overlap（默认 5 秒）、--no-preprocess、--target-resolution、--target-fps、--skip-still / --no-skip-still、--verbose

搜索已索引的录像

sentrysearch search "<自然语言查询>"

可选参数：-n / --results（默认返回 5 条结果）、-o / --output-dir、--trim / --no-trim、--threshold（默认 0.41）、--overlay / --no-overlay（启用/禁用特斯拉遥测叠加）、--verbose

应用特斯拉遥测叠加层

sentrysearch overlay <视频文件>
sentrysearch overlay <视频文件> -o output.mp4

在特斯拉行车记录仪视频上烧录 HUD 叠加层，显示车速、GPS 坐标、地点名称及转向灯状态。该功能读取嵌入于特斯拉固件 2025.44.25+ 中的 SEI NAL 单元所携带的遥测数据。此功能亦可通过 --overlay 参数在 search 命令中启用，从而对自动裁剪出的片段直接添加叠加层。

查看索引统计信息

sentrysearch stats

工作原理

视频文件被切分为带有重叠时间的片段。静帧检测（still-frame detection）可跳过视觉内容无显著变化的片段，从而避免不必要的 API 调用——这对哨兵模式（Sentry Mode）或安防摄像头等长时间处于静态的录像尤为关键，是主要的成本节省机制。各片段还会预先进行处理（降低帧率与分辨率），以减小上传体积并加快传输速度；但需注意：Gemini API 按视频时长（而非文件大小）以固定 token 速率计费，因此预处理不会降低单个片段的 token 成本。每个片段均以原始视频形式经由 Gemini Embedding 2 进行嵌入（不依赖语音转文字或图像描述）。生成的向量存储于本地 ChromaDB 数据库中。文本查询同样被嵌入至同一向量空间，并通过余弦相似度完成匹配。匹配度最高的结果将借助 ffmpeg 从原始文件中自动裁剪输出。

适用场景

• 用户提出需在视频文件或录像中执行搜索
• 用户希望根据自然语言描述定位视频中的特定时刻
• 用户要求对视频录像进行索引或结构化整理以便后续搜索
• 用户提及行车记录仪、安防摄像头或监控录像等场景
• 用户希望从长视频中查找并提取指定片段
• 用户拥有特斯拉行车记录仪录像，并希望在片段中叠加显示车速/GPS/地理位置信息
• 用户希望为某段特斯拉视频添加遥测数据叠加层

交互示例

用户：“搜索我的行车记录仪录像，查找一辆白色卡车强行加塞的画面”
操作：运行 sentrysearch search "white truck cutting me off"

用户：“索引我 Downloads 文件夹下的所有视频文件”
操作：运行 sentrysearch index ~/Downloads

用户：“搜索闯红灯画面，并为结果片段添加特斯拉叠加层”
操作：运行 sentrysearch search "running a red light" --overlay

用户：“为这段特斯拉视频添加车速和 GPS 叠加层”
操作：运行 sentrysearch overlay /path/to/tesla_video.mp4

用户：“我当前已索引了多少视频素材？”
操作：运行 sentrysearch stats

使用规则

• 执行索引或搜索前，必须先运行 sentrysearch init，或确认已正确设置 GEMINI_API_KEY 环境变量。
• 若系统 PATH 中未找到 ffmpeg，程序将自动回退使用内置的 imageio-ffmpeg。
• 在默认参数下，每小时活跃视频内容的索引成本约为 2.84 美元。费用主要取决于发送至 API 的片段数量——对于包含大量空闲时段的录像（如哨兵模式、安防摄像头），由于静帧跳过机制会完全剔除这些片段，实际成本将显著降低。在索引大型目录前，请务必提前向用户发出成本提示。
• 搜索结果附带相似度分数。若最高分低于设定阈值（默认 0.41），将在执行裁剪前提示低置信度警告。
• 特斯拉叠加层依赖固件 2025.44.25+ 中 SEI 元数据的支持。不含特斯拉元数据的视频将自动跳过叠加步骤，不报错。
• 要求 Python 版本为 3.11+。