1. 项目定位与用途
SentrySearch 是一款面向视频素材的语义搜索命令行工具，定位为通过自然语言查询快速检索视频内容的智能助手。其核心用途是让用户无需手动浏览大量视频文件，即可准确找到包含特定事件、物体或动作的视频片段。工具自动将匹配片段裁剪为独立视频文件，便于直接使用或分享。适用于需要从监控录像、行车记录、体育赛事等长视频中高效提取关键内容的各类场景。
项目档案命令行工具
ssrajadh/sentrysearch CLI 工具：安装、命令与使用场景
ssrajadh/sentrysearch：SentrySearch 是一款基于语义理解的视频检索 CLI 工具，通过自然语言查询快速定位并自动裁剪视频片段，替代人工观看，大幅提升监控、行本页整理它解决什么问题、适用场景、安装方式和使用方法。
AI 总结
SentrySearch 是一款基于语义理解的视频检索 CLI 工具，通过自然语言查询快速定位并自动裁剪视频片段，替代人工观看，大幅提升监控、行车记录仪等场景的内容检索效率。
中文项目介绍
SentrySearch 是一款专为视频素材设计的语义搜索工具，允许用户通过自然语言描述快速定位并获取相关视频片段。
项目核心解决从大量监控或行车记录仪视频中人工查找特定内容的低效问题。传统方法需要逐帧观看，而 SentrySearch 利用多模态嵌入模型将视频内容转化为向量，实现语义级匹配，自动裁剪出最相关的片段。
技术实现上，工具将视频按时间切分为重叠片段，使用 Google Gemini Embedding API 或本地 Qwen3-VL 模型生成向量表示，并存储于本地 ChromaDB 向量数据库。搜索时，查询文本被嵌入同一空间，通过相似度匹配返回最佳片段。整个过程依赖 ffmpeg 进行视频处理，支持调整分块时长、分辨率、帧率等参数以适应不同硬件和需求。
主要适用场景包括：交通监控与行车记录仪 footage 检索、安全监控视频分析、体育比赛精彩片段定位、以及任何长视频内容的快速导航。
用户通过简单的 CLI 命令即可完成初始化、索引和搜索：首先配置 API 密钥或启用本地模型，然后索引视频目录，最后用自然语言查询获取匹配片段。系统还提供置信度阈值控制、多结果保存等灵活选项。
详细信息与使用说明
2. 解决的问题
传统视频检索依赖人工观看或基于简单标签的搜索，效率低下且无法理解语义。SentrySearch 解决以下问题：1) 从数小时监控 footage 中定位特定事件（如‘红色卡车闯红灯’）的耗时问题；2) 关键词搜索的局限性——无法匹配同义描述或复杂场景；3) 视频内容结构化困难。通过多模态嵌入模型将视频片段映射到语义向量空间，系统能理解‘车辆违规’与‘汽车闯红灯’的相似性，实现智能匹配，将检索时间从小时级缩短至秒级。
3. 适用场景
该工具主要适用于以下场景：交通监控领域，如交警部门从海量行车记录仪视频中检索违章行为；安防监控，帮助安保人员快速定位异常事件；体育分析，自动剪辑比赛中的关键动作或得分片段；内容创作，从长视频素材库中查找特定镜头；以及任何需要从连续视频流中提取特定时刻的场合。需要注意的是，当前版本针对 dashcam 风格视频优化，但理论上支持任何视频格式。对于需要高度隐私的场景，可使用本地 Qwen3-VL 模型避免数据上传。
4. 安装方式
安装需通过 uv 包管理器进行：首先访问 https://docs.astral.sh/uv/ 按系统指引安装 uv；然后克隆仓库并运行 `uv tool install .` 完成工具安装。依赖 ffmpeg 用于视频处理，若系统未预装，工具会自动使用 bundled imageio-ffmpeg。对于使用本地模型的用户，需额外安装可选依赖：`uv pip install sentrysearch[local]`（标准本地模型）或 `sentrysearch[local-quantized]`（量化版以降低显存占用）。配置阶段运行 `sentrysearch init` 交互式输入 Gemini API 密钥，或手动复制 `.env.example` 为 `.env` 并填入密钥。
5. 使用方式
基本工作流分三步：1) 初始化配置：`sentrysearch init` 设置 API 密钥或选择本地后端；2) 索引视频：`sentrysearch index /path/to/footage` 将目录下视频分块嵌入并存入 ChromaDB，支持 `--chunk-duration`（分块时长）、`--overlap`（重叠）、`--target-resolution`（分辨率）等参数调整；3) 语义搜索：`sentrysearch search "自然语言查询"` 返回最匹配片段，自动裁剪保存。搜索时可使用 `--results N` 指定返回数量，`--threshold` 调整置信度，`--no-trim` 禁用自动裁剪。索引和搜索过程会显示进度和相似度分数。
6. 补充说明与实现特点
项目采用模块化架构：chunker 负责视频分块，embedder 管理多模态嵌入（支持 Gemini API 与本地 Qwen3-VL 切换），store 封装 ChromaDB 向量存储，search 实现语义匹配，trimmer 调用 ffmpeg 裁剪视频，cli 提供统一入口。后端选择根据硬件自动检测：NVIDIA GPU 或 24GB+ RAM Mac 使用 8B 模型，较小设备使用 2B 模型。向量数据库完全本地存储，保护隐私。代码包含完整测试套件，覆盖分块、嵌入、搜索等核心逻辑。注意：Gemini API 使用需自行承担费用，建议在 Google AI Studio 设置消费限额。
思维导图
SentrySearch
核心功能
语义视频搜索
自然语言查询
自动片段裁剪
技术栈
嵌入模型: Gemini / Qwen3-VL
向量存储: ChromaDB
视频处理: ffmpeg
CLI: Click
工作流程
视频分块
向量嵌入
索引存储
查询匹配
结果裁剪
部署方式
uv 包管理
本地运行
API 密钥配置
应用场景
监控检索
行车记录仪
体育分析
内容定位
常见问题
SentrySearch 是否需要网络连接？
使用 Gemini Embedding API 时需要网络连接和有效 API 密钥；若选择本地后端（--backend local），则完全离线运行，无需网络。
支持哪些视频格式？
工具依赖 ffmpeg 进行视频处理，理论上支持 ffmpeg 支持的所有格式，如 MP4、AVI、MOV 等。实际使用中建议使用常见容器格式。
本地模型对硬件有什么要求？
本地 Qwen3-VL 模型自动检测硬件：NVIDIA GPU 或 24GB+ RAM 的 Mac 使用 8B 参数模型，较小设备使用 2B 参数模型。量化版本（local-quantized）可降低显存需求。
索引视频需要多长时间？
取决于视频长度、分块设置和所选后端。Gemini API 速度较快但受网络和配额限制；本地模型速度受硬件性能影响。分块时长默认 30 秒，重叠 5 秒，可通过参数调整。
如何控制搜索结果的准确性？
可通过 `--threshold` 参数调整置信度阈值（默认 0.41），值越高要求匹配越严格。也可使用 `--save-top N` 保存多个候选片段进行人工筛选。