语言 / Languages: English · 简体中文
对视频素材做语义检索：输入想找的画面描述，自动得到裁剪好的片段。
[!IMPORTANT] 官方来源： github.com/ssrajadh/sentrysearch 是 SentrySearch 唯一的官方仓库。其他转载或镜像本项目的网站均与维护者无关，也未获得授权，请始终从本仓库下载。
工作流程：
新功能： sentrysearch highlights：在还不知道具体搜什么时，按与索引中其他片段的偏离程度对已建索引的切片排序，并自动裁剪导出，适合快速浏览新导入的一批素材。
SentrySearch 将视频切成有重叠的片段，再分别用 Google Gemini Embedding API、阿里云 DashScope（qwen-cloud），或本地 Qwen3-VL 模型做视频向量化，向量存入本地 ChromaDB。搜索时，你的文字（或图片，见 以图搜视频）被嵌入同一向量空间，与已存视频向量匹配；最佳匹配会从原文件中自动裁切并保存为独立片段。
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 tool install .
需要 Python 3.11 或 3.12（PyTorch 官方轮尚未支持 3.13+）。若本机默认 Python 更新，可先安装托管的 3.12 再固定版本安装：
uv python install 3.12 uv tool install --python 3.12 .
--backend local，或已在 .env 中配置 DASHSCOPE_API_KEY 并使用 --backend qwen-cloud，可跳过本节。sentrysearch init
会提示输入 Gemini API Key，写入 .env，并通过测试嵌入校验。
sentrysearch index /path/to/footage
sentrysearch search "red truck running a stop sign"
视频切片与裁剪依赖 ffmpeg。若系统未安装，会自动使用随包自带的 imageio-ffmpeg。
手动配置： 若不想用
sentrysearch init，可将.env.example复制为.env，并手动填入 aistudio.google.com/apikey 中的 Key。
$ sentrysearch init
Enter your Gemini API key (get one at https://aistudio.google.com/apikey): ****
Validating API key...
Setup complete. You're ready to go — run `sentrysearch index <directory>` to get started.
若已存在 Key，会询问是否覆盖。
建议： 在 aistudio.google.com/billing 设置消费上限，避免意外超支。
$ sentrysearch index /path/to/video/footage
Indexing file 1/3: front_2024-01-15_14-30.mp4 [chunk 1/4]
Indexing file 1/3: front_2024-01-15_14-30.mp4 [chunk 2/4]
...
Indexed 12 new chunks from 3 files. Total: 12 chunks from 3 files.
常用选项：
--chunk-duration 30 — 每段时长（秒）--overlap 5 — 段与段之间的重叠（秒）--no-preprocess — 跳过低分辨率/降帧预处理（直接送原始片段）--target-resolution 480 — 预处理目标高度（像素）--target-fps 5 — 预处理目标帧率--no-skip-still — 即使画面几乎无变化也全部嵌入--backend local — 使用本地模型而非 Gemini（见下文）$ sentrysearch search "red truck running a stop sign"
#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
Saved clip: ./match_front_2024-01-15_14-30_02m15s-02m45s.mp4
若最佳结果的相似度低于默认置信阈值（0.41），裁剪前会先询问：
No confident match found (best score: 0.28). Show results anyway? [y/N]:
使用 --no-trim 时，低置信结果仅展示说明，不再交互确认。
其他选项：--results N、--output-dir DIR、--no-trim 跳过自动裁剪、--threshold 0.5 调整置信 cutoff、--save-top N 保存前 N 个片段而不只最佳。后端与模型一般从索引自动推断；仅在需要覆盖时传 --backend 或 --model。
用参考图作为查询，适合「找和这张图很像的片段」——用文字不好描述时（例如某辆车的截图、另一段视频的参考帧等）。
$ sentrysearch img ~/Downloads/image.jpg
#1 [0.72] 2026-03-12_10-44-17-left_repeater.mp4 @ 00:00-00:30
#2 [0.69] 2026-03-12_10-44-17-left_repeater.mp4 @ 00:25-00:55
#3 [0.67] 2026-02-12_20-02-15-front.mp4 @ 00:00-00:18
Saved clip: ./match_2026-03-12_10-44-17-left_repeater_00m00s-00m30s.mp4
图片与已索引视频片段在同一向量空间中嵌入，按余弦相似度排序。search 的各标志均可用（--results、--threshold、--save-top、--overlay、--no-trim、--backend、--model）。
格式支持：Gemini 后端支持 JPG、PNG、WEBP、GIF、HEIC/HEIF；本地后端另支持 PIL 能解码的格式（BMP、TIFF 等）。
说明： 以图搜视频返回的是视觉相似的片段，不一定是同一物体。例如用红色轿车查询，可能匹配到其他形状相近的红色轿车——请按场景调整预期。
还不知道搜什么？sentrysearch highlights 会对索引里「最异常」的切片排序——即 embedding 与整体分布偏离最大的那些——并自动裁剪。适合刚导入一整批素材时先扫一遍。
$ sentrysearch highlights -n 3
#1 [0.165] 2026-02-12_20-02-15-back.mp4 @ 00:00-00:18
#2 [0.163] 2026-02-12_20-02-15-right_repeater.mp4 @ 00:00-00:18
#3 [0.149] 2026-02-12_20-02-15-front.mp4 @ 00:00-00:18
...
评分方式（--method）：
knn（默认）— 每个切片与其 k 个近邻的平均余弦距离；较稳健，能浮出「没有很像孪生」的片段。centroid — 与索引均值的距离；最省算力，偏向「整体里少见」的方向。lof — 局部离群因子（LOF）。索引里存在多种「常态」模式时（白天 / 夜间 / 车库等）更合适。细化选项：
--against "<query>" — 相对某条查询做异常度。--against-mode within（默认）在「该查询的 top 匹配」里再排异常（例如「行人片段里最怪的行人」）；--against-mode global 则找「既像该查询、又与索引其余部分都不像」的稀有事件。--dedupe 0.9 — 与更高名次结果过像（默认余弦相似度 0.9）的条目丢弃，避免列表被几乎相同的帧占满。--exclude-baseline — 先丢掉离质心最近的一半索引再打分；索引被大量重复「无聊」画面主导时有用。-k, --neighbors 10 — knn / lof 的 k。--no-trim — 只打印排名，不写裁剪文件。注意： 统计意义上的「异常」不等于「有意思」。传感器 glitch、眩光、夜间帧混在大量白天里、或唯一一段车库录像都会得高分。可配合
--exclude-baseline、--dedupe降噪，或用--against把主题收窄。
可选用 qwen-cloud 后端，对接 DashScope / 模型服务的多模态嵌入（默认模型 qwen3-vl-embedding，可用 --dashscope-model 或环境变量 DASHSCOPE_EMBEDDING_MODEL 覆盖）：
uv tool install ".[qwen-cloud]"
export DASHSCOPE_API_KEY=...
sentrysearch index /path/to/footage --backend qwen-cloud
sentrysearch search "your query" --backend qwen-cloud
视频上传： 本地切片文件会先由官方 Python SDK 上传到 DashScope 托管的临时 OSS，再由 API 消费（HTTP API 需要 URL；SDK 代为完成上传）。
使用本地 Qwen3-VL-Embedding 建索引与搜索，免费、私密、完全在本地运行。若最看重检索质量，建议用 Gemini 后端；需要离线/隐私时，本地 8B 是稳妥替代；硬件带不动 8B 时可用 2B。
模型会按硬件自动选择——NVIDIA GPU 与内存 ≥24GB 的 Mac 倾向 qwen8b；较小内存的 Mac 与纯 CPU 环境倾向 qwen2b。可用 --model qwen2b / --model qwen8b 覆盖。请按硬件选择安装方式：
| 硬件 | 安装命令 | 自动检测模型 | 说明 |
|---|---|---|---|
| Apple Silicon，内存 ≥24GB | uv tool install ".[local]" | qwen8b | MPS 上 float16 |
| Apple Silicon，16GB 内存 | uv tool install ".[local]" | qwen2b | 8B 装不下；2B 约 6GB |
| Apple Silicon，8GB 内存 | uv tool install ".[local]" | qwen2b | 较吃紧，高负载可能换页；更建议用 Gemini API |
| NVIDIA，显存 ≥18GB | uv tool install ".[local]" | qwen8b | bf16（Linux/Windows 会自动拉 CUDA 轮） |
| NVIDIA，显存 8–16GB | uv tool install ".[local-quantized]" | qwen8b | 4bit 量化（约 6–8GB） |
体验会较差： Intel Mac、无独显的机器会退回到 CPU float32——又慢又占内存，不实用。请改用默认的 Gemini API 后端。
不确定装哪个？ Mac 用
".[local]"；NVIDIA 用".[local-quantized]"——4bit 量化适配面最广、质量损失通常很小。（bitsandbytes 需要 CUDA，不能在 Mac/MPS 上使用。）
Python 版本： PyTorch 轮滞后于新 Python，本地后端需要 3.11 或 3.12。若默认已是 3.13+：
uv python install 3.12
uv tool install --python 3.12 ".[local]"
Mac 前置： 需安装系统级 FFmpeg（本地模型的视频解码依赖它；Gemini 后端可用自带 ffmpeg）：
brew install ffmpeg
建索引时加 --backend local，搜索时一般无需额外参数：
sentrysearch index /path/to/footage --backend local
sentrysearch search "car running a red light"
search 会根据索引自动推断后端与模型。也可用 --model 作为简写（隐含 --backend local）：