SentrySearch

Busca semântica em gravações de vídeo. Digite o que você está procurando e receba um clipe recortado.

[!IMPORTANT] Fonte oficial: github.com/ssrajadh/sentrysearch é o único lar oficial do SentrySearch. Outros sites que republicam ou espelham este projeto não são afiliados nem endossados pelo mantenedor; sempre baixe a partir deste repositório.

Idiomas: English · 简体中文

Novo: Backend MLX para Apple Silicon: executa o modelo local 2B duas vezes mais rápido usando menos da metade da memória, com a mesma precisão

Como funciona

O SentrySearch divide seus vídeos em chunks sobrepostos, incorpora cada chunk como vídeo usando a API de Embedding do Gemini do Google, o Alibaba DashScope (qwen-cloud) ou um modelo Qwen3-VL local, e armazena os vetores em um banco de dados ChromaDB local. Quando você busca, sua consulta de texto (ou imagem, veja buscar por imagem) é incorporada no mesmo espaço vetorial e comparada com os embeddings de vídeo armazenados. A melhor correspondência é automaticamente recortada do arquivo original e salva como um clipe.

Primeiros passos

Instale o uv (caso não o tenha):

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

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

Clone e instale:```bash git clone https://github.com/ssrajadh/sentrysearch.git cd sentrysearch uv tool install .

> **Requer Python 3.11 ou 3.12** (os wheels do PyTorch ainda não suportam 3.13+). Se o seu Python padrão for mais recente, instale um 3.12 gerenciado e fixe a instalação da ferramenta:
> ```bash
> uv python install 3.12
> uv tool install --python 3.12 .
> ```

3. Configure a sua chave de API (ou [use um modelo local em vez disso](#local-backend-no-api-key-needed)) — **necessário apenas para o backend Gemini padrão**; ignore se usar `--backend local`, `--backend mlx`, ou `--backend qwen-cloud` com `DASHSCOPE_API_KEY` no `.env`.```bash
sentrysearch init

Isso solicita sua chave de API do Gemini, grava-a em .env e a valida com um embedding de teste.

Indexe seu material:```bash sentrysearch index /path/to/footage

5. Pesquisar:```bash
sentrysearch search "red truck running a stop sign"

ffmpeg é necessário para o chunking e o corte de vídeo. Se não o tiver instalado no sistema, o imageio-ffmpeg incluído é usado automaticamente.

Configuração manual: Se preferir não usar sentrysearch init, pode copiar .env.example para .env e adicionar a sua chave de aistudio.google.com/apikey manualmente.

Utilização

Init```bash

$ 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.

Se uma chave já estiver configurada, será perguntado se deseja substituí-la.

> **Dica:** Defina um limite de gastos em [aistudio.google.com/billing](https://aistudio.google.com/billing) para evitar gastos excessivos acidentais.

### Indexar filmagens```bash
$ 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.

Opções:

--chunk-duration 30 — segundos por chunk
--overlap 5 — sobreposição entre chunks
--no-preprocess — ignora o downscaling/redução da taxa de frames (envia chunks em bruto)
--target-resolution 480 — altura alvo em pixels para o pré-processamento
--target-fps 5 — taxa de frames alvo para o pré-processamento
--no-skip-still — incorpora todos os chunks, mesmo os que não têm alterações visuais
--rpm 10 — limita os pedidos por minuto à API na cloud (detalhes abaixo)
--backend local — usa um modelo local em vez do Gemini (detalhes abaixo)
--backend mlx — usa o modelo local através do MLX em Apple Silicon, mais rápido e mais leve que local (detalhes abaixo)

Pesquisa```bash

$ 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

Se a pontuação de similaridade do melhor resultado estiver abaixo do limite de confiança (padrão 0.41, ou 0.35 em `--backend mlx`), você será solicitado antes de aparar:```
No confident match found (best score: 0.28). Show results anyway? [y/N]:

Com --no-trim, resultados de baixa confiança são exibidos com uma nota em vez de um prompt.

Opções: --results N, --output-dir DIR, --no-trim para ignorar o auto-trimming, --threshold 0.5 para ajustar o limite de confiança, --save-top N para salvar os N melhores clipes em vez de apenas a melhor correspondência, --dedupe para definir quão semelhante um resultado pode ser a uma escolha melhor classificada antes de ser descartado (ativado por padrão, para que trechos sobrepostos do mesmo momento não preencham a lista), e --rerank para pedir a um VLM que reordene os candidatos retornados antes do trimming. O backend e o modelo são detectados automaticamente a partir do índice — passe --backend ou --model apenas para substituir.```bash

Save top 5 clips, dropping only near-identical chunks

sentrysearch search "red truck" --save-top 5 --dedupe 0.95

Re-rank the top 10 embedding matches with a VLM before trimming

sentrysearch search "pedestrian crossing behind the car" --rerank --results 10

O valor de `--dedupe` é um teto de similaridade de cosseno (0–1). Qualquer resultado cuja similaridade com um resultado de classificação superior já mantido exceda esse valor é descartado. Valores mais baixos são mais rigorosos: `0.8` exige que os resultados sejam muito distintos, `0.95` remove apenas trechos quase idênticos. O padrão é `0.9`; passe `--dedupe 1` para manter todos os resultados. A busca obtém candidatos extras ao fazer deduplicação, então você ainda obtém o número de resultados que solicitou.

sentrysearch

Mais Populares