SentrySearch

Recherche sémantique sur des séquences vidéo. Tapez ce que vous cherchez, obtenez un extrait découpé.

[!IMPORTANT] Source officielle : github.com/ssrajadh/sentrysearch est le seul emplacement officiel de SentrySearch. Les autres sites qui republient ou reflètent ce projet ne sont pas affiliés ni approuvés par le mainteneur, téléchargez toujours depuis ce dépôt.

Langues : Anglais · 简体中文

Nouveau : Vidéo de présentation du code de SentrySearch

Le pipeline :

1. SentrySearch (trouver un événement dans vos séquences)
2. SentryMerge (découper automatiquement les séquences multicam en une seule vidéo qui suit le sujet à travers les caméras)
3. SentryBlur (flouter automatiquement les informations sensibles)

Table des matières

• Fonctionnement
• Pour commencer
• Utilisation
  • Init
  • Index footage
  • Search
  • Search by image
  • Highlights
  • Qwen Cloud (Alibaba DashScope)
  • Local Backend (no API key needed)
  • Pourquoi le modèle local est rapide
  • Tesla Metadata Overlay
  • Stitch with SentryMerge
  • Redact with SentryBlur
  • Gestion de l'index
    • Segments échoués et nouvelles tentatives
    • Fichiers de cache et d'état
  • Mode verbeux
• Comment est-ce possible ?
• Coût
• Avertissements connus (inoffensifs)
• Limitations et travaux futurs
• Compatibilité
• Prérequis

Fonctionnement

SentrySearch divise vos vidéos en segments qui se chevauchent, intègre chaque segment en tant que vidéo via l'API Google Gemini Embedding, Alibaba DashScope (qwen-cloud), ou un modèle local Qwen3-VL, et stocke les vecteurs dans une base de données ChromaDB locale. Lorsque vous effectuez une recherche, votre requête textuelle (ou image, voir search by image) est intégrée dans le même espace vectoriel et comparée aux vecteurs vidéo stockés. La meilleure correspondance est automatiquement découpée du fichier d'origine et sauvegardée sous forme d'extrait.

Pour commencer

1. Installez uv (si vous ne l'avez pas) :

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. Clonez et installez:```bash git clone https://github.com/ssrajadh/sentrysearch.git cd sentrysearch uv tool install .

> **Nécessite Python 3.11 ou 3.12** (les wheels PyTorch ne supportent pas encore 3.13+). Si votre Python par défaut est plus récent, installez une version gérée 3.12 et épinglez l'installation de l'outil :
> ```bash
> uv python install 3.12
> uv tool install --python 3.12 .
> ```

3. Configurez votre clé API (ou [utilisez un modèle local à la place](#local-backend-no-api-key-needed)) — **uniquement nécessaire pour le backend Gemini par défaut**; ignorez si vous utilisez `--backend local` ou `--backend qwen-cloud` avec `DASHSCOPE_API_KEY` dans `.env`.```bash
sentrysearch init

Cela demande votre clé API Gemini, l'écrit dans .env et la valide avec un test d'embedding.

4. Indexez vos séquences :```bash sentrysearch index /path/to/footage

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

ffmpeg est requis pour le découpage et le rognage vidéo. Si vous ne l'avez pas à l'échelle du système, le imageio-ffmpeg inclus est utilisé automatiquement.

Configuration manuelle : Si vous préférez ne pas utiliser sentrysearch init, vous pouvez copier .env.example vers .env et ajouter votre clé depuis aistudio.google.com/apikey manuellement.

Utilisation

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.

Si une clé est déjà configurée, il vous sera demandé si vous souhaitez la remplacer.

> **Conseil :** Définissez une limite de dépenses sur [aistudio.google.com/billing](https://aistudio.google.com/billing) pour éviter des dépenses accidentelles.

### Index des séquences```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.

Options:

• --chunk-duration 30 — secondes par segment
• --overlap 5 — chevauchement entre les segments
• --no-preprocess — ignorer la réduction de résolution/taux d'images (envoyer les segments bruts)
• --target-resolution 480 — hauteur cible en pixels pour le prétraitement
• --target-fps 5 — taux d'images cible pour le prétraitement
• --no-skip-still — intégrer tous les segments, même ceux sans changement visuel
• --backend local — utiliser un modèle local au lieu de Gemini (détails ci-dessous)

Recherche```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

Si le score de similarité du meilleur résultat est inférieur au seuil de confiance (par défaut 0.41), vous serez invité avant de rogner :```
No confident match found (best score: 0.28). Show results anyway? [y/N]:

Avec --no-trim, les résultats de faible confiance sont affichés avec une note au lieu d'une invite.

Options : --results N, --output-dir DIR, --no-trim pour ignorer le rognage automatique, --threshold 0.5 pour ajuster le seuil de confiance, --save-top N pour sauvegarder les N meilleurs extraits au lieu du seul meilleur résultat, --dedupe pour supprimer les résultats trop similaires à un choix mieux classé (empêche les morceaux quasi identiques du même événement de remplir la liste), et --rerank pour demander à un VLM de re-classer les candidats retournés avant le rognage. Le backend et le modèle sont détectés automatiquement à partir de l'index — passez --backend ou --model uniquement pour les surcharger.```bash

Save top 5 clips, dropping near-duplicates

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

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

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

La valeur `--dedupe` est un plafond de similarité cosinus (0–1). Tout résultat dont la similarité avec un résultat déjà conservé et mieux classé dépasse cette valeur est supprimé. Des valeurs plus basses sont plus strictes : `0,8` exige que les résultats soient très distincts, `0,95` ne supprime que les extraits quasi identiques. `0,9` est une bonne valeur par défaut.

`--rerank` extrait chaque clip candidat renvoyé, l'envoie à un VLM avec la requête, et classe les correspondances visuelles probables avant les résultats basés uniquement sur l'embedding. Les recherches Gemini et qwen-cloud utilisent Gemini 2.5 Flash pour le reclassement ; les recherches locales utilisent un reclassificateur local Qwen3-VL Instruct. Si le reclassement ne peut pas s'exécuter ou si un candidat ne peut pas être noté, SentrySearch conserve les résultats classés par embedding plutôt que d'échouer la recherche.

### Recherche par image

Utilisez une image de référence comme requête — utile pour trouver des clips qui ressemblent à celle-ci lorsque décrire la scène avec des mots est maladroit (une capture d'écran d'une voiture spécifique, une image de référence d'une autre vidéo, etc.).```bash
$ 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

L'image est intégrée dans le même espace vectoriel que les segments vidéo indexés et classée par similarité cosinus. La recherche d'image prend en charge --results, --threshold, --save-top, --dedupe, --overlay, --no-trim, --backend, et --model.

Formats pris en charge : JPG, PNG, WEBP, GIF, HEIC/HEIF sur le backend Gemini ; le backend local accepte en plus tout ce que PIL peut décoder (BMP, TIFF, etc.).

Remarque : La recherche d'image renvoie des correspondances visuellement similaires, pas nécessairement le même objet. Une requête de berline rouge peut remonter d'autres berlines rouges de forme similaire — ajustez vos attentes en conséquence.

Points forts

Vous ne savez pas quoi rechercher ? sentrysearch highlights classe les séquences les plus anormales de votre index — les segments dont les embeddings sont éloignés de tout le reste — et les rogne automatiquement. Idéal pour parcourir rapidement un nouveau lot de séquences.```bash $ 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 ...

Méthodes de notation (`--method`) :

- **`knn`** (défaut) — distance cosinus moyenne aux *k* plus proches voisins d'un chunk. Robuste ; révèle les clips sans quasi-jumeaux.
- **`centroid`** — distance par rapport à la moyenne de l'index. La moins coûteuse, biaisée vers ce qui est sous-représenté.
- **`lof`** — Facteur d'anomalie local. Meilleur lorsque l'index a plusieurs modes « normaux » distincts (jour vs. nuit vs. garage).

Options d'affinage :

- `--against "<query>"` — note l'anomalie *par rapport à* une requête. Avec `--against-mode within` (défaut), classe les anomalies parmi les meilleures correspondances de la requête (« les piétons étranges dans les clips de piétons »). Avec `--against-mode global`, trouve les clips qui correspondent à la requête *mais* qui sont différents du reste de l'index (« événements rares de ce type »).
- `--dedupe 0.9` — supprime les résultats trop similaires à un choix mieux classé (similarité cosinus par défaut 0,9). Empêche les images quasi identiques de remplir la liste.
- `--exclude-baseline` — supprime la moitié de l'index la plus proche du centroïde avant la notation. Utile lorsque l'index est dominé par des séquences répétitives « ennuyeuses ».
- `-k, --neighbors 10` — *k* pour `knn`/`lof`.
- `--no-trim` — affiche le classement sans écrire les clips.

> **Attention :** Statistiquement anormal ≠ intéressant. Les dysfonctionnements du capteur, les reflets de lentille, les images nocturnes dans un index principalement diurne, et le clip de garage isolé se classent tous en haut. Utilisez `--exclude-baseline` et `--dedupe` pour filtrer le bruit, ou `--against` pour contraindre par sujet.

### Qwen Cloud (Alibaba DashScope)

Utilisez le backend optionnel **qwen-cloud** pour [DashScope](https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-dashscope) / les embeddings multimodaux de Model Studio (modèle par défaut `qwen3-vl-embedding`, modifiable avec `--dashscope-model` ou `DASHSCOPE_EMBEDDING_MODEL`) :```bash
uv tool install ".[qwen-cloud]"
export DASHSCOPE_API_KEY=...
sentrysearch index /path/to/footage --backend qwen-cloud
sentrysearch search "your query" --backend qwen-cloud

Téléchargements vidéo : les fichiers de fragments locaux sont envoyés vers l'OSS temporaire géré par DashScope via le SDK Python officiel avant que l'API ne les consomme (l'API HTTP attend une URL ; le SDK gère le téléchargement pour vous).

Backend local (aucune clé API nécessaire)

Indexez et recherchez à l'aide d'un modèle Qwen3-VL-Embedding local au lieu de l'API Gemini. Gratuit, privé et fonctionne entièrement sur votre machine. Pour une qualité de recherche optimale, utilisez le backend Gemini — le modèle local 8B est une alternative solide lorsque vous avez besoin d'une recherche hors ligne/privée, et le modèle 2B est une solution de repli lorsque le matériel ne peut pas supporter le 8B.

Le modèle est autodétecté à partir de votre matériel — qwen8b pour les GPU NVIDIA et les Mac avec 24 Go+ de RAM, qwen2b pour les Mac plus petits et les systèmes sans GPU. Vous pouvez le remplacer avec --model qwen2b ou --model qwen8b. Choisissez une installation en fonction de votre matériel :

Ne fonctionnera pas bien : Les Mac Intel et les machines sans GPU dédié. Ceux-ci tombent en CPU avec float32 — trop lent et gourmand en mémoire pour une utilisation pratique. Utilisez plutôt le backend API Gemini (par défaut).

Pas sûr ? Sur Mac, utilisez ".[local]". Sur NVIDIA, utilisez ".[local-quantized]" — la quantification 4 bits fonctionne sur la plus large gamme de matériel NVIDIA avec une perte de qualité minimale. (bitsandbytes nécessite CUDA et ne fonctionne pas sur Mac/MPS.)

Version Python : Les roues PyTorch sont en retard sur les nouvelles versions de Python, donc le backend local nécessite Python 3.11 ou 3.12. Si votre Python par défaut est 3.13+, installez un 3.12 géré et épinglez l'installation de l'outil sur celui-ci :```bash uv python install 3.12 uv tool install --python 3.12 ".[local]"

**Prérequis Mac :** Installez FFmpeg système (le processeur vidéo du modèle local en a besoin — le backend Gemini utilise un ffmpeg intégré à la place) :

```bash
brew install ffmpeg
``````bash
brew install ffmpeg

Indexez avec --backend local et recherchez — aucun indicateur supplémentaire nécessaire :```bash sentrysearch index /path/to/footage --backend local sentrysearch search "car running a red light"

La commande search détecte automatiquement le backend et le modèle à partir de ce que vous avez indexé. Vous pouvez également utiliser `--model` comme raccourci — cela implique `--backend local` :```bash
sentrysearch index /path/to/footage --model qwen2b   # same as --backend local --model qwen2b
sentrysearch search "car running a red light"          # auto-detects local/qwen2b from index

Options:

• --model qwen2b — modèle plus petit, qualité inférieure mais seulement ~6 Go de mémoire (accepte aussi les identifiants HuggingFace complets)
• --quantize / --no-quantize — forcer la quantification 4 bits activée ou désactivée (par défaut : détection automatique selon que bitsandbytes est installé)

Notes:

• Le premier lancement télécharge le modèle (~16 Go pour la version 8B, ~4 Go pour la version 2B).
• L'option locale --rerank télécharge un modèle Qwen3-VL Instruct séparé (Qwen/Qwen3-VL-8B-Instruct ou Qwen/Qwen3-VL-2B-Instruct) en plus du modèle d'embedding.
• Les embeddings de différentes backends et modèles ne sont pas compatibles. Chaque combinaison backend/modèle obtient son propre index isolé, afin qu'ils ne puissent pas se mélanger accidentellement. Si vous recherchez avec un modèle qui n'a pas de données indexées, on vous indiquera quel modèle a réellement été utilisé.
• La vitesse varie en fonction du nombre de cœurs GPU — les puces de base de la série M sont plus lentes que les Pro/Max mais produisent des résultats identiques.

Pourquoi le modèle local est rapide

Le backend local reste rapide et efficace en mémoire grâce à quelques techniques qui se combinent :

• Le prétraitement réduit la taille des chunks avant qu'ils n'atteignent le modèle. Chaque chunk de 30s est réduit à 480p à 5fps via ffmpeg avant l'embedding. Un chunk de dashcam d'environ 19 Mo devient environ 1 Mo — une réduction de 95% du nombre de pixels que le modèle doit traiter. Le temps d'inférence du modèle dépend du nombre de pixels, pas de la durée de la vidéo, c'est donc le facteur d'accélération le plus important.
• Échantillonnage faible en images. Le processeur vidéo envoie au maximum 32 images par chunk au modèle (fps=1.0, max_frames=32). Un chunk de 30 secondes produit environ 30 images — pas des centaines.
• Troncature de dimension MRL. Qwen3-VL-Embedding prend en charge Matryoshka Representation Learning. Seules les 768 premières dimensions de chaque embedding sont conservées et normalisées L2, réduisant ainsi le stockage et le calcul de distance dans ChromaDB.
• Auto-quantification. Sur les GPU NVIDIA avec VRAM limitée, le modèle 8B est automatiquement chargé en 4 bits (bitsandbytes) — passant d'environ 18 Go à environ 6-8 Go avec une perte de qualité minime. Une 4090 (24 Go) fait tourner le modèle bf16 complet avec de la marge.
• Saut d'images statiques. Les chunks sans changement visuel significatif (par exemple une voiture garée) sont détectés en comparant les tailles de fichiers JPEG entre les images échantillonnées et sont entièrement ignorés — économisant un passage avant complet par chunk.

Avec tout cela, attendez-vous à environ 2-5s par chunk sur un A100 et 3-8s sur un T4. Sur une 4090, le modèle 8B en bf16 devrait être dans les faibles unités par chunk.

Superposition des métadonnées Tesla

Graver la vitesse, l'emplacement et l'heure sur les clips découpés :```bash sentrysearch search "car cutting me off" --overlay

Cette fonction extrait la télémétrie intégrée dans les fichiers dashcam Tesla (vitesse, GPS) et affiche une superposition HUD. La superposition montre :

- **Centre haut :** étiquette de vitesse et MPH sur une carte gris clair
- **Sous la carte :** date et heure (12 heures avec AM/PM)
- **Haut gauche :** nom de la ville et de la route (via géocodage inverse)

![tesla overlay](https://assets.kitploit.com/production/public/readmes/12784/6bacffb39f1503cd7f92f2326d60919b14d1bfcd6ee9b8244a9d1bfb4b26e58e.png)

Prérequis :

- Firmware Tesla 2025.44.25 ou ultérieur, HW3+
- Les métadonnées SEI ne sont présentes que dans les séquences de conduite (pas en mode stationnement/Sentry)
- Le géocodage inverse utilise l'[API Nominatim d'OpenStreetMap](https://nominatim.openstreetmap.org/) via geopy (optionnel)

Installation avec prise en charge de la superposition Tesla :```bash
uv tool install ".[tesla]"

Sans geopy, la superposition fonctionne toujours mais omet le nom de la ville/route.

Source : teslamotors/dashcam

Assembler avec SentryMerge

SentryMerge est un outil frère qui découpe automatiquement une vidéo multi-caméras d'un seul événement à partir d'un résultat SentrySearch. Chaque fois que sentrysearch search s'exécute, il met en cache la liste des résultats dans ~/.sentrysearch/last_search.json ; SentryMerge récupère cela via --last, choisit le meilleur ensemble de clips multi-caméras, demande à un VLM les plages de visibilité sous-seconde par caméra, et assemble une vidéo précise à la trame qui suit le sujet à travers les caméras :```bash sentrysearch search "" sentrymerge --last # → merge.mp4

`--last` fonctionne sans relancer la recherche ; `sentrymerge --query "..."` relance la recherche en coulisses. Consultez le [README de SentryMerge](https://github.com/ssrajadh/sentrymerge#readme) pour les instructions d'installation, les options de backend VLM (Gemini / OpenAI / Qwen local) et le système modulaire cam-config pour les dashcams non Tesla.

### Rédaction avec SentryBlur

[SentryBlur](https://github.com/ssrajadh/sentryblur) est un outil frère pour la rédaction locale de visages, de plaques d'immatriculation et de langage naturel dans les vidéos. Chaque fois que `sentrysearch search` enregistre un clip, il met en cache le chemin vers `~/.sentrysearch/last_clip.json` ; SentryBlur le récupère via `--last`, donc la recherche puis la rédaction se font en deux commandes sans passer de chemin :```bash
sentrysearch search "car cuts me off"
sentryblur prompt --last "road signs"   # → match_<...>_blurred.mp4

sentryblur faces --last et sentryblur plates --last fonctionnent de la même manière. Choisissez faces ou plates pour les détecteurs CPU rapides ; utilisez prompt "<text>" pour des objets arbitraires (écrans de téléphone, moniteurs, badges nominatifs) — prompt nécessite un GPU NVIDIA ou un Apple Silicon. Consultez le SentryBlur README pour les instructions d'installation et les notes matérielles.

Gestion de l'index```bash

Show index info (files marked [missing] no longer exist on disk)

sentrysearch stats

Remove specific files by path substring

sentrysearch remove path/to/footage

Wipe the entire index

sentrysearch reset

#### Échecs de fragments et nouvelles tentatives

Si un fragment ne peut pas être intégré après plusieurs tentatives, SentrySearch l'enregistre dans une file d'attente de lettres mortes (DLQ) à `~/.sentrysearch/dlq.json` et continue d'indexer le reste de vos séquences. Les fragments y atterrissent généralement en raison de défaillances transitoires répétées de l'API/backend, d'erreurs de décodage pour un fichier spécifique, de fichiers manquants ou d'erreurs de mémoire insuffisante. Les échecs apparemment permanents, tels que les fichiers manquants, les erreurs de décodage et les OOM, sont enregistrés immédiatement, car il est peu probable que réessayer le même fragment avec les mêmes réglages soit utile.

Inspectez les fragments échoués :```bash
sentrysearch dlq list

Réessayez-les lors de la prochaine exécution d'index :```bash sentrysearch index /path/to/footage --retry-failed

Vider la DLQ sans réessayer :```bash
sentrysearch dlq clear

Par défaut, les futures exécutions de sentrysearch index ignorent les chunks déjà dans la DLQ afin de ne pas payer ou attendre inutilement pour des échecs. Utilisez --retry-failed après avoir corrigé le problème source, modifié les paramètres de modèle/backend ou libéré de la mémoire.

Fichiers de cache et d'état

SentrySearch conserve l'état local sous ~/.sentrysearch/ :

Mode verbeux

Ajoutez --verbose à l'une ou l'autre commande pour obtenir des informations de débogage (dimensions d'embedding, temps de réponse de l'API, scores de similarité).

Comment est-ce possible ?

Gemini Embedding 2 et Qwen3-VL-Embedding peuvent intégrer nativement la vidéo — les pixels vidéo bruts sont projetés dans le même espace vectoriel que les requêtes textuelles. Il n'y a pas de transcription, de sous-titrage d'images, ni d'intermédiaire textuel. Une requête textuelle comme « camion rouge à un panneau stop » est directement comparable à un clip vidéo de 30 secondes au niveau vectoriel. C'est ce qui rend la recherche sémantique en moins d'une seconde sur des heures de séquences pratique.

Coût

Gemini

L'indexation d'une heure de séquences coûte environ 2,84 $ avec l'API d'embedding de Gemini (paramètres par défaut : chunks de 30 s, chevauchement de 5 s) :

1 heure = 3 600 secondes de vidéo = 3 600 images traitées par le modèle. 3 600 images × 0,00079 $ = ~2,84 $/h

L'API Gemini extrait et tokenize nativement exactement 1 image par seconde à partir de la vidéo téléchargée, quel que soit le taux d'images réel du fichier. L'étape de prétraitement (qui réduit les chunks à 480p à 5 ips via ffmpeg) est une optimisation locale/bande passante — elle maintient les charges utiles petites pour que les requêtes API soient rapides et ne timeoutent pas — mais ne change pas le nombre d'images traitées par l'API.

Deux optimisations intégrées aident à réduire les coûts de différentes manières :

• Prétraitement (activé par défaut) — les chunks sont réduits à 480p à 5 ips avant téléchargement. Comme l'API traite à 1 ips quoi qu'il arrive, cela réduit uniquement la taille de téléchargement et le temps de transfert, pas le nombre d'images facturées. Cela améliore principalement la vitesse et évite les timeouts de requête.
• Saut d'images fixes (activé par défaut) — les chunks sans changement visuel significatif (par exemple, une voiture garée) sont complètement ignorés. Cela économise de véritables appels API et réduit directement le coût. Les économies dépendent de vos séquences — les enregistrements du mode Sentry avec des heures d'inactivité en bénéficient le plus, tandis que les séquences de conduite dynamiques peuvent n'avoir rien à sauter.

Les requêtes de recherche sont négligeables (embedding textuel uniquement).

Qwen Cloud (DashScope, Qwen3-VL-Embedding)

DashScope facture l'embedding multimodal en CNY pour 1 000 tokens d'entrée, par modalité. Pour le modèle par défaut qwen3-vl-embedding, les tarifs publiés par Alibaba (vérifiez le document ci-dessous pour votre région et les mises à jour éventuelles) sont de l'ordre de :

• Entrée textuelle : environ 0,0007 ¥ pour 1k tokens d'entrée
• Entrée image / vidéo : environ 0,0018 ¥ pour 1k tokens d'entrée

L'indexation envoie des chunks vidéo (modalité vidéo) ; chaque requête search / img est principalement composée de tokens texte ou image, moins chers par token que la vidéo. Votre coût réel dépend des comptages de tokens renvoyés par DashScope pour chaque appel API (cela dépend de la résolution, de la durée, de l'échantillonnage tel que DASHSCOPE_VIDEO_FPS, etc.) — il n'y a pas de « $ fixe par heure de séquences » comme le taux USD par image publié par Gemini sans mesurer votre charge de travail.

Alibaba documente également une allocation de tokens gratuite (par exemple 1M de tokens dans une période limitée après activation) ; confirmez dans la page DashScope multimodal embedding metering & billing et dans la console Model Studio / facturation, car les tarifs, régions et promotions changent.

Réglage de l'indexation (les deux backends)

Ces indicateurs affectent le découpage et le prétraitement pour les deux backends Gemini et qwen-cloud :

• --chunk-duration / --overlap — des chunks plus longs avec moins de chevauchement = moins d'appels API = coût réduit
• --no-skip-still — intégrer chaque chunk même s'il ne se passe rien
• --target-resolution / --target-fps — ajuster la qualité du prétraitement
• --no-preprocess — envoyer les chunks bruts à l'API

Avertissements connus (inoffensifs)

Le backend local peut imprimer des avertissements lors de l'indexation et de la recherche. Ceux-ci sont cosmétiques et n'affectent pas les résultats :

• MPS: nonzero op is not natively supported — Une limitation connue de PyTorch sur Apple Silicon. L'opération bascule sur le CPU pour une étape ; tout le reste reste sur le GPU. Aucun impact sur la qualité de sortie.
• video_reader_backend torchcodec error, use torchvision as default — torchcodec ne trouve pas de FFmpeg compatible sur macOS. Le processeur vidéo bascule automatiquement sur torchvision. Ceci est attendu et produit des résultats identiques.
• You are sending unauthenticated requests to the HF Hub — Le modèle télécharge depuis Hugging Face sans token. Les vitesses de téléchargement peuvent être légèrement inférieures, mais le modèle se charge correctement. Définissez une variable d'environnement HF_TOKEN pour faire taire cet avertissement s'il vous dérange.

Limitations et travaux futurs

• La détection d'images fixes est heuristique — elle utilise la comparaison de taille de fichier JPEG entre images échantillonnées. Elle peut occasionnellement ignorer des chunks avec un mouvement subtil ou intégrer des chunks véritablement statiques. Désactivez avec --no-skip-still si vous avez besoin que chaque chunk soit indexé.
• La qualité de la recherche dépend des limites des chunks — si un événement s'étend sur deux chunks, la fenêtre de chevauchement aide mais n'est pas parfaite. Un découpage plus intelligent (par exemple, détection de scène) pourrait améliorer cela.
• Gemini Embedding 2 est en préversion — Le comportement de l'API et les tarifs peuvent changer.

Compatibilité

Cela fonctionne avec les séquences .mp4 et .mov, pas seulement le mode Sentry de Tesla. Le scanner de répertoire trouve récursivement les deux types de fichiers, quelle que soit la structure des dossiers.

Prérequis

• Python 3.11+
• ffmpeg dans le PATH, ou utiliser ffmpeg intégré via imageio-ffmpeg (installé par défaut)
• Backend Gemini : clé API Gemini (obtenez-en une gratuitement)
• Backend local :
  • GPU avec CUDA ou Apple Metal (voir le tableau du matériel pour les exigences VRAM/RAM)
  • macOS : brew install ffmpeg (requis par le décodeur vidéo)
  • Linux/Windows : aucune dépendance système supplémentaire