Workflows de Recherche Vidéo

Fonctionnalité Alpha — non recommandée pour la production.

Recherchez dans les archives vidéo en langage naturel en utilisant les embeddings Cosmos Embed1. Nécessite le profil search — déployez avec la skill deploy (-p search). Ces sources vidéo peuvent être des fichiers ingérés ou des flux RTSP.

Quand l'utiliser

• « Trouver toutes les instances de chariots élévateurs »
• « Quand quelqu'un a-t-il pénétré dans la zone restreinte ? »
• « Montrez-moi les personnes près du quai de chargement »
• « Rechercher des véhicules entre 8h et midi »
• Toute recherche en langage naturel sur des archives vidéo

Prérequis de déploiement

Cette skill nécessite le profil VSS search en exécution sur l'hôte à $HOST_IP. Avant toute requête :

1. Sondez la stack :

   curl -sf --max-time 5 "http://${HOST_IP}:8000/docs" >/dev/null \
     && curl -sf --max-time 5 "http://${HOST_IP}:9200/" >/dev/null

   (Le deuxième vérification confirme qu'Elasticsearch est actif — propre au profil search.)

2. Si le sondage échoue, demandez à l'utilisateur :

   « Le profil VSS search n'est pas en exécution sur $HOST_IP. Dois-je le déployer maintenant en utilisant la skill /deploy avec -p search ? »

   • Si oui → confiez à la skill /deploy. Revenez ici une fois qu'elle réussit.
   • Si non → arrêtez. N'exécutez pas cette skill sur une stack manquante ou avec le mauvais profil.

   (Si votre appelant a donné une pré-autorisation explicite de déployer autonomement — par exemple la requête dit « pré-autorisé à déployer les prérequis », ou vous s'exécutez dans un harnais d'évaluation non interactif avec cette permission — ignorez la confirmation et invoquez /deploy directement.)

3. Si le sondage passe, continuez.

Comment fonctionne la recherche

1. Ingestion — Les vidéos sont téléchargées ou diffusées via VIOS. Le service RTVI-Embed (Cosmos Embed1) génère des embeddings vectoriels pour les segments vidéo.
2. Indexation — Les embeddings sont stockés dans Elasticsearch via le pipeline Kafka.
3. Requête — Les requêtes en langage naturel sont converties en embeddings et mises en correspondance avec les vecteurs stockés par similarité.
4. Résultats — Segments vidéo horodatés classés par pertinence, avec liens de lecture de clips.

Cette recherche orchestrée par l'agent VSS peut mener à 3 comportements :

• Attribut uniquement : quand l'LLM décompose la requête et ne trouve que des attributs d'apparence sans action (p. ex. « personne portant une veste rouge »)
• Embedding uniquement : quand la requête n'a pas d'attributs extractibles (p. ex. « montrez-moi les chariots élévateurs »)
• Fusion : quand la requête a à la fois une action et des attributs (p. ex. « personne en veste rouge qui court »), elle exécute d'abord la recherche par embedding, puis reclasse en utilisant la recherche par attribut

Workflow obligatoire

Lors de l'utilisation de cette skill, SUIVEZ TOUJOURS ce workflow haut niveau :

1. Résolvez les entrées à partir des instructions utilisateur — ARRÊT OBLIGATOIRE si $HOST_IP n'est pas explicitement fourni. Voir § Résolution des entrées ci-dessous. NE PASSEZ PAS par défaut à localhost, 127.0.0.1, l'hôte sur lequel l'agent lui-même s'exécute, ou toute autre supposition. N'ÉMETTEZ PAS de requête POST http://.../generate avant que l'utilisateur n'ait fourni un endpoint. Répondez à l'utilisateur avec une seule question demandant HOST_IP / l'endpoint de l'agent VSS et attendez.
2. Exécutez la ou les recherche(s) via l'approche choisie
3. Présentez les résultats à la requête utilisateur. Formatez la réponse comme un rapport d'inspection professionnel mais nommez-le Résultats de Recherche Vidéo : — Utilisez des en-têtes de section clairs
   • Organisez les résultats individuellement avec les détails à l'appui, et terminez par un résumé
   • Utilisez des tableaux où les comparaisons aident. Écrivez comme un rapport technique, pas un message de chat.
4. CRITIQUE : Vérifiez les résultats et expliquez cela à l'utilisateur succinctement. Si la recherche échoue, ou retourne des résultats inattendus (p. ex. des vidéos qui ne semblent pas correspondre à la requête utilisateur, zéro correspondance, zéro vidéo retournée, erreur, etc.), ARRÊTEZ. Ne continuez pas sans lire troubleshooting.md pour itérer avec des boucles de retour jusqu'à ce que les résultats appropriés soient trouvés et présentés comme un rapport d'inspection professionnel.
5. Vérifications finales :
   • INFORMEZ TOUJOURS l'utilisateur que les vérifications finales et ultérieures peuvent être exécutées. Présentez ceci comme une Étape de Vérification
   • UNIQUEMENT SI l'utilisateur accepte, téléchargez les captures d'écran en utilisant screenshot_url des meilleurs candidats (scores de similarité les plus élevés) parmi les résultats de recherche (résultats JSON) vers /tmp. Lisez-les et vérifiez s'ils correspondent à la requête utilisateur

Résolution des entrées

Déduisez ces entrées uniquement de la conversation ou de la requête utilisateur (aucun autre fichier sauf s'il est fourni). Si certaines ne peuvent pas être déduites, demandez immédiatement à l'utilisateur :

• $HOST_IP: où s'exécute le backend de l'agent VSS

Pièges

• PASSEZ TOUJOURS à l'étape de troubleshooting du workflow immédiatement si quelque chose d'inattendu se produit, lisez troubleshooting.md
• Les requêtes fonctionnent mieux avec des descriptions visuelles concrètes (objets, actions, emplacements). Augmentez les requêtes utilisateur si nécessaire pour améliorer la qualité des questions, en développant les détails potentiels
• Les requêtes utilisateur pour faire une recherche vidéo supposent que les sources vidéo sont déjà ingérées. Pas besoin de les rechercher localement. Supposez ceci sauf si les résultats montrent que la source vidéo n'a pas encore été ingérée
• Utilisez la skill video-analytics pour faire référence croisée des résultats de recherche avec les données d'incident/alerte

Recherche via API REST

Privilégiez par défaut cette approche API REST, sauf si l'utilisateur en spécifie une autre.

# Considérez uniquement les sources de fichiers vidéo ingérés par défaut
curl -s -X POST http://${HOST_IP}:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"input_message": "find all instances of forklifts"}' | jq .

Plus d'exemples

# Recherche par objet
curl -s -X POST http://${HOST_IP}:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"input_message": "find vehicles in the parking lot"}' | jq .

# Recherche par action
curl -s -X POST http://${HOST_IP}:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"input_message": "show me people running"}' | jq .

# Recherche par contexte temporel
curl -s -X POST http://${HOST_IP}:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"input_message": "what happened at the entrance between 2pm and 3pm?"}' | jq .

# Considérez uniquement les sources RTSP avec le filtre `search_source_type` (p. ex. flux de caméras en direct)
curl -s -X POST http://${HOST_IP}:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"input_message": "find all instances of forklifts", "search_source_type": "rtsp"}' | jq .

Boutons de contrôle avancé

Si la requête utilisateur est ambiguë, l'utilisateur souhaite plus de conseils ou quand un contrôle fin est nécessaire, augmentez le input_message utilisateur en appelant explicitement certaines options en texte brut et en dirigeant l'agent dans la direction souhaitée. Axes de contrôle disponibles :

Choisissez et ajustez certaines de ces options de réglage. Adaptez-les selon la situation et la requête de l'utilisateur. Pour des exemples de modes de découverte exploitant ceux-ci, voir discovery_modes.md.

Recherche via Agent UI

Ouvrez http://${HOST_IP}:3000/ et tapez des requêtes en langage naturel :

find all instances of forklifts
show me people near the loading dock
when did a truck arrive at the gate?
find someone wearing a red jacket

Les résultats incluent des clips horodatés avec scores de similarité.

Interagir via Browser (agent-browser)

npx agent-browser --auto-connect open http://${HOST_IP}:3000
npx agent-browser --auto-connect wait --load networkidle
npx agent-browser --auto-connect snapshot -i

Trouvez l'entrée de chat, saisissez une requête de recherche et prenez une capture d'écran des résultats.