Natural Language Video Search_设计多媒体 skill-PHP中文网

Natural Language Video Search

Polar Sponsor

爱发电赞助

.NET 9.0

立即下载

使用Gemini嵌入实现视频文件的语义搜索。对行车记录仪、安防摄像头或任意MP4视频进行索引，然后通过自然语言查询进行搜索，以查找...

自然语言视频搜索 : 使用自然语言查询的搜索视频文件, 由双子嵌入 2 的本地视频到视频嵌入器提供

功能概述

自然语言视频搜索 : 使用自然语言查询的搜索视频文件, 由双子嵌入 2 的本地视频到视频嵌入器提供是一项面向实际任务的技能，主要用于此技能可以让你索引。它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。

核心要点

使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。
该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。
从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。

使用与执行

实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。

结果检查与注意事项

执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。

自然语言视频搜索

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

该技能的功能

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

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

安装配置

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

克隆并安装：

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

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

uv sync --extra tesla

设置 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+。