SentrySearch

Ricerca semantica su filmati video. Digita ciò che stai cercando, ricevi indietro una clip ritagliata.

[!IMPORTANT] Fonte ufficiale: github.com/ssrajadh/sentrysearch è l'unica sede ufficiale di SentrySearch. Altri siti che ripubblicano o rispecchiano questo progetto non sono affiliati né approvati dal manutentore, scarica sempre da questo repository.

Lingue: English · 简体中文

Novità: Backend MLX per Apple Silicon: esegue il modello locale 2B due volte più velocemente con meno della metà della memoria, alla stessa accuratezza

Indice

• Come funziona
• Per iniziare
• Utilizzo
  • Init
  • Indicizzare i filmati
  • Ricerca
  • Ricerca per immagine
  • Momenti salienti
  • Qwen Cloud (Alibaba DashScope)
  • LiteLLM (gateway AI)
  • Backend locale (nessuna chiave API necessaria)
  • Perché il modello locale è veloce
  • Backend MLX (Apple Silicon)
  • Overlay metadati Tesla
  • Unisci con SentryMerge
  • Oscura con SentryBlur
  • Gestione dell'indice
    • Chunk falliti e nuovo tentativo
    • File di cache e di stato
  • Modalità dettagliata
• Come è possibile?
• Costo
• Avvisi noti (innocui)
• Limitazioni e sviluppi futuri
• Compatibilità
• Requisiti

Come funziona

SentrySearch suddivide i tuoi video in chunk sovrapposti, incorpora ogni chunk come video utilizzando l'API Gemini Embedding di Google, Alibaba DashScope (qwen-cloud) o un modello locale Qwen3-VL, e memorizza i vettori in un database ChromaDB locale. Quando effettui una ricerca, la tua query testuale (o immagine, vedi ricerca per immagine) viene incorporata nello stesso spazio vettoriale e confrontata con gli embedding video memorizzati. La corrispondenza migliore viene automaticamente ritagliata dal file originale e salvata come clip.

Per iniziare

1. Installa uv (se non lo hai già):

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

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

2. Clona e installa:```bash git clone https://github.com/ssrajadh/sentrysearch.git cd sentrysearch uv tool install .

> **Richiede Python 3.11 o 3.12** (i wheel di PyTorch non supportano ancora la 3.13+). Se il tuo Python predefinito è più recente, installa una versione gestita 3.12 e fissa l'installazione dello strumento:
> ```bash
> uv python install 3.12
> uv tool install --python 3.12 .
> ```

3. Configura la tua chiave API (oppure [usa un modello locale](#local-backend-no-api-key-needed)) — **necessaria solo per il backend Gemini predefinito**; salta questo passaggio se usi `--backend local`, `--backend mlx`, o `--backend qwen-cloud` con `DASHSCOPE_API_KEY` in `.env`.```bash
sentrysearch init

Questo richiede la tua chiave API Gemini, la scrive in .env e la valida con un embedding di test.

4. Indicizza il tuo materiale:```bash sentrysearch index /path/to/footage

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

ffmpeg è necessario per il chunking e il trimming dei video. Se non è disponibile a livello di sistema, viene utilizzato automaticamente l'imageio-ffmpeg incluso.

Configurazione manuale: Se preferisci non usare sentrysearch init, puoi copiare .env.example in .env e aggiungere manualmente la tua chiave da aistudio.google.com/apikey.

Utilizzo

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 la chiave è già configurata, ti verrà chiesto se sovrascriverla.

> **Suggerimento:** Imposta un limite di spesa su [aistudio.google.com/billing](https://aistudio.google.com/billing) per evitare spese accidentali eccessive.

### Indicizzare il footage```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.

Opzioni:

• --chunk-duration 30 — secondi per chunk
• --overlap 5 — sovrapposizione tra i chunk
• --no-preprocess — salta il ridimensionamento/la riduzione della frequenza dei fotogrammi (invia i chunk grezzi)
• --target-resolution 480 — altezza target in pixel per il preprocessing
• --target-fps 5 — frequenza dei fotogrammi target per il preprocessing
• --no-skip-still — incorpora tutti i chunk, anche quelli senza variazioni visive
• --rpm 10 — limita le richieste al minuto verso l'API cloud (dettagli sotto)
• --backend local — usa un modello locale invece di Gemini (dettagli sotto)
• --backend mlx — usa il modello locale tramite MLX su Apple Silicon, più veloce e leggero di local (dettagli sotto)

Ricerca```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 il punteggio di similarità del risultato migliore è inferiore alla soglia di confidenza (predefinita 0.41, oppure 0.35 con `--backend mlx`), ti verrà chiesto prima di eseguire il trimming:```
No confident match found (best score: 0.28). Show results anyway? [y/N]:

Con --no-trim, i risultati a bassa confidenza vengono mostrati con una nota invece di un prompt.

Opzioni: --results N, --output-dir DIR, --no-trim per saltare l'auto-trimming, --threshold 0.5 per regolare la soglia di confidenza, --save-top N per salvare i migliori N clip invece del solo miglior risultato, --dedupe per impostare quanto un risultato può essere simile a una scelta con rango superiore prima di essere scartato (attivo per impostazione predefinita, così i chunk sovrapposti dello stesso momento non riempiono la lista), e --rerank per chiedere a un VLM di riordinare i candidati restituiti prima del trimming. Backend e modello vengono rilevati automaticamente dall'indice — passa --backend o --model solo per sovrascrivere.```bash

Save top 5 clips, dropping only near-identical chunks

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