Réponses vidéo avec vss vlm run

Répondez à une nouvelle question visuelle sur une vidéo en exécutant vss vlm run — la commande CLI VSS qui résout le point de terminaison VLM à partir de la configuration de déploiement enregistrée, envoie la question de l'utilisateur avec la vidéo, persiste la réponse en mémoire et retourne le résultat. Cette skill n'appelle pas POST /generate sur l'agent VSS. Elle nécessite un VSS déployé avec vss configure déjà exécuté et un service rt_vlm accessible.

Règle stricte — chaque réponse provient de vss vlm run. Chaque question, y compris les questions temporelles / de timing (« à quel timestamp X s'est-il produit », « combien de temps », « quand Y commence »), est répondue par un seul appel vss vlm run. Une question de timing n'est pas une raison d'utiliser un autre outil : mettez-la dans --prompt et lisez le timing dans la réponse.

Ne remplacez jamais un appel HTTP construit à la main par la CLI. Spécifiquement, ne :

• POST à /v1/chat/completions vous-même. vss vlm run possède cet appel et envoie le paramètre d'échantillonnage de frames avec ; une requête personnalisée l'omet, le modèle voit seulement la frame d'ouverture, et les questions de timing deviennent sans réponse.
• Construisez des URLs de clip VIOS à la main (p. ex. /vst/api/v1/storage/file/<id>/url). --sensor résout le capteur, la fenêtre enregistrée et l'URL du clip en interne.
• POST à http://<host>:8000/generate (le pipeline de résumé de l'agent) ou /v1/summarize en aucune circonstance.

Si vss vlm run échoue, rapportez le code de sortie (voir Gestion des erreurs). Ne réessayez pas la question en construisant la requête à la main.

Harnais d'agent

Indépendant du harnais — quel que soit ce qui l'exécute (Claude Code, Codex, Cursor, ou l'Agent VSS NAT) appelle vss vlm run via la CLI. Un vss-agent en cours d'exécution est facultatif ; ce qui est nécessaire est vss configure ayant été exécuté une fois contre le VSS déployé afin que l'URL du service rt_vlm soit enregistrée.

Quand utiliser

• L'utilisateur demande ce qui se passe dans la vidéo, quels objets / personnes / actions apparaissent, couleurs, timing, sécurité, ou d'autres faits visuels qui nécessitent de regarder le clip.
• L'utilisateur demande des détails qui ne peuvent pas être répondus à partir des messages existants, résumés, résultats Elasticsearch/MCP, ou noms de fichiers seuls — vous avez besoin de l'inférence du modèle sur la vidéo.
• Questions de suivi sur les détails du contenu après un résumé grossier ou après la génération de rapport.
• vss-search-archive a déjà affiché uniquement des résultats unverified, l'utilisateur a explicitement confirmé la vérification visuelle, et l'appelant fournit un clip délimité exact comme VIDEO_URL. Traitez cette URL comme Chemin A ; ne relancez pas la recherche ou ne résolvez un intervalle différent.

Déclencheurs négatifs

N'utilisez pas cette skill quand la demande est l'une des suivantes :

• Une base de données / MCP / sortie d'outil antérieur répond déjà à la question, sauf si l'utilisateur veut explicitement une vérification visuelle nouvelle. Le remise confirmée délimitée de vss-search-archive ci-dessus est la seule exception de résultat de recherche ; utilisez /vss-query-analytics pour la vérification de résultat d'analytique.
• Récupération de similitude / archive sémantique (« trouver des chariots élévateurs », « chercher des vidéos de tous les chariots pour le tailgating ») → utilisez /vss-search-archive. Cette skill ne peut inspecter que le clip délimité pré-résolu que la recherche remet après confirmation ; elle n'effectue jamais la récupération elle-même.
• Une demande de rapport formaté/structuré (« générer un rapport », « rapport d'analyse ») → utilisez /vss-generate-video-report.
• Résumer un enregistrement long → utilisez /vss-summarize-video.
• Modifications de déploiement/démantèlement/profil → utilisez /vss-deploy-profile.

Prérequis

Une pile VSS déployée avec le service rt_vlm accessible à travers l'origin configurée. Exécutez vss configure une fois par déploiement — tous les appels vss vlm run suivants lisent l'URL enregistrée.

Configuration

Configurez la CLI et exécutez vss configure selon AGENTS.md.

Vérifiez que rt_vlm a été découvert :

vss configure check
# Attendu : rt_vlm   ok   http://<origin>/rtvi-vlm   HTTP 200

Les détails d'amorçage, les codes de sortie et les règles qui les accompagnent se trouvent dans AGENTS.md.

Instructions

1. Exécutez les étapes numérotées — Étape 1 (obtenir la source vidéo — directement de l'utilisateur, ou éventuellement résoudre une URL de clip à partir de VST/VIOS) → Étape 2 (vss vlm run — une commande) → Étape 3 (retourner la réponse).
2. Retournez uniquement le texte de réponse final à l'utilisateur.

Pour une remise de résultat de recherche confirmée, utilisez uniquement le VIDEO_URL fourni par l'appelant et la question visuelle. Ne consommez pas les scores de similitude, les noms de fichiers, les ID d'objets, ou d'autres métadonnées de récupération comme preuve visuelle, et ne relancez pas la recherche, ne résolvez un capteur, n'élargissez le clip, ou ne choisissez un autre intervalle. L'appelant possède la validation du verdict et tout fallback après que cette skill retourne.

Vérification du capteur (uniquement lors du sourçage du clip à partir de VST/VIOS)

Cette section s'applique uniquement à l'Étape 1, Chemin B — quand vous sourcez la vidéo à partir de VST/VIOS. Si l'utilisateur a fourni la vidéo directement (un chemin de fichier ou une URL), ignorez entièrement cela et utilisez l'Étape 1, Chemin A.

Lors de l'utilisation de VST/VIOS, vous DEVEZ lister les capteurs VST avant de résoudre une URL de clip. C'est obligatoire même quand l'utilisateur nomme le capteur explicitement, même quand l'utilisateur affirme que la vidéo est déjà téléchargée, et même quand un tour précédent semblait utiliser la même vidéo. Ne sautez pas cette étape.

Exécution de la CLI. L'amorçage, vss configure, les codes de sortie et les règles de résolution de capteur se trouvent dans AGENTS.md à la racine du repo — lisez-les une fois plutôt que par skill.

1. Listez les capteurs (capturez d'abord — un simple pipe dans jq masquerait un vss échoué derrière le code de sortie de jq et se lirait comme « pas de capteurs ») :

   # Chaque bloc est son propre shell ; définissez ce qu'il utilise.
   VSS=(uv run --project "${VSS_REPO_ROOT:-$HOME/video-search-and-summarization}/services/agent" --no-dev --extra cli vss)
   set -o pipefail
   SENSORS=$("${VSS[@]}" vios list --type video) || { echo "vss vios list failed" >&2; exit 1; }
   printf '%s' "${SENSORS}" | jq -r '.sensors[].name'

2. Comparez les valeurs name retournées contre le <sensor-id> fourni par l'utilisateur (ou la racine du nom de fichier, p. ex. warehouse_safety_0001).

   Une ligne peut porter un champ error — VIOS a listé le capteur mais n'a pas pu le décrire (pas de streams, ou pas d'id). Il est toujours listé intentionnellement : le nom existe, donc le traiter comme absent et télécharger créerait un doublon et un 409.

3. Si un capteur correspondant est présent → procédez à l'Étape 1. Si sa ligne porte une error, rapportez-la plutôt que de télécharger dessus.

4. Si aucun capteur correspondant n'est présent — téléchargez d'abord la vidéo, puis relister pour confirmer que le nouveau capteur apparaît :

   # Chaque bloc est son propre shell ; définissez ce qu'il utilise.
   VSS=(uv run --project "${VSS_REPO_ROOT:-$HOME/video-search-and-summarization}/services/agent" --no-dev --extra cli vss)
   "${VSS[@]}" vios add /path/to/<filename>

   Consultez /vss-manage-video-io-storage pour les sémantiques de téléchargement au niveau REST (v1 vs v2, gestion des conflits, flux de suppression). Dans les exécutions interactives, confirmez avec l'utilisateur avant de télécharger. Ne jamais télécharger sans avoir d'abord exécuté la vérification de la liste de capteurs ci-dessus.

Étape 1 — Identifier la source vidéo

Déterminez si la vidéo provient directement de l'utilisateur (Chemin A) ou d'un capteur VST/VIOS nommé (Chemin B). Cela détermine le drapeau vss vlm run à utiliser à l'Étape 2.

Chemin A — fourni directement par l'utilisateur (par défaut ; pas VST/VIOS)

Si l'utilisateur vous fournit un chemin de fichier ou une URL, utilisez le Chemin A à l'Étape 2 :

• URL → passez comme --media-url <url>. RT-VLM récupère la vidéo directement.
• Fichier local → passez comme --file /path/to/clip.mp4. La CLI lit le fichier et l'envoie en ligne comme un URI data:video/mp4;base64,… encodé en base64.

Une remise de résultat de recherche confirmée par l'utilisateur avec un VIDEO_URL délimité pré-résolu utilise ce même chemin. Ne jetez pas cette URL et n'entrez le Chemin B simplement parce que l'appelant conserve également un ID de capteur ou des timestamps pour la création de rapport.

Passez directement à l'Étape 2 — ignorez la Vérification du capteur.

Chemin B — résoudre à partir de VST/VIOS (optionnel)

Règle stricte — une question qui nomme un capteur est Chemin B et DOIT utiliser --sensor. Quand la question fait référence à un capteur VIOS (p. ex. warehouse_safety_0001), passez --sensor <name> à vss vlm run. La CLI résout le capteur par nom, lit la plage enregistrée, crée une URL de clip normalisée et préchauffée, et l'envoie à RT-VLM — tout en un seul appel. Ne pas construire à la main un appel /storage/file/<streamId>/url ou inclure une copie locale en base64.

Une question de suivi qui ne nomme aucune vidéo reste sur le capteur déjà en jeu. Réutilisez le même --sensor <name> (et éventuellement --start-time / --end-time) du tour précédent.

Quand le clip vit sur un capteur nommé : confirmez que le capteur existe (la Vérification du capteur ci-dessus — obligatoire sur ce chemin), puis utilisez --sensor <name> à l'Étape 2.

Pour restreindre le clip à une fenêtre de temps connue, ajoutez --start-time / --end-time (ISO 8601) :

# Fenêtre optionnelle. Les deux ou aucun — pas un seul.
START_TIME='2025-01-01T00:00:00Z'
END_TIME='2025-01-01T00:00:30Z'

Étape 2 — Interrogez le VLM

Un appel, une tentative. vss vlm run lit le point de terminaison rt_vlm à partir de la configuration enregistrée, envoie le prompt avec la vidéo, et affiche le résultat en JSON.

Chemin A — URL ou fichier local :

# Chaque bloc est son propre shell ; définissez ce qu'il utilise.
VSS=(uv run --project "${VSS_REPO_ROOT:-$HOME/video-search-and-summarization}/services/agent" --no-dev --extra cli vss)
# La sortie 6 signifie que la réponse a été produite mais n'a pas pu être écrite en mémoire.
# La réponse est toujours valide, donc conservez-la ; seule la persistance doit être recommencée.
check_rc() { [ "$1" -eq 0 ] || [ "$1" -eq 6 ] || { echo "vss vlm run failed (exit $1)" >&2; exit "$1"; }; }

# URL (RT-VLM la récupère) :
RC=0
RESULT=$("${VSS[@]}" vlm run \
  --prompt "${USER_QUESTION}" \
  --media-url "${VIDEO_URL}") || RC=$?
check_rc "${RC}"

# Fichier local (inclus en base64) :
# RC=0
# RESULT=$("${VSS[@]}" vlm run \
#   --prompt "${USER_QUESTION}" \
#   --file "${VIDEO_FILE}") || RC=$?
# check_rc "${RC}"

Chemin B — capteur nommé (avec fenêtre de temps optionnelle) :

# Chaque bloc est son propre shell ; définissez ce qu'il utilise.
VSS=(uv run --project "${VSS_REPO_ROOT:-$HOME/video-search-and-summarization}/services/agent" --no-dev --extra cli vss)
# La sortie 6 signifie que la réponse a été produite mais n'a pas pu être écrite en mémoire.
# La réponse est toujours valide, donc conservez-la ; seule la persistance doit être recommencée.
check_rc() { [ "$1" -eq 0 ] || [ "$1" -eq 6 ] || { echo "vss vlm run failed (exit $1)" >&2; exit "$1"; }; }

# Sans fenêtre de temps (clip complet enregistré) :
RC=0
RESULT=$("${VSS[@]}" vlm run \
  --prompt "${USER_QUESTION}" \
  --sensor "${SENSOR_NAME}") || RC=$?
check_rc "${RC}"

# Avec une fenêtre de temps :
# RC=0
# RESULT=$("${VSS[@]}" vlm run \
#   --prompt "${USER_QUESTION}" \
#   --sensor "${SENSOR_NAME}" \
#   --start-time "${START_TIME}" \
#   --end-time "${END_TIME}") || RC=$?
# check_rc "${RC}"

Drapeaux optionnels :

Étape 3 — Retournez la réponse

Extrayez la réponse du résultat JSON et retournez-la à l'utilisateur :

# La CLI émet une ligne de corps JSON puis une ligne de marqueur de complétion JSON.
# Affichez la sortie complète pour que la trajectoire contienne le statut et la réponse.
printf '%s\n' "${RESULT}"
# Sélectionnez la ligne qui porte .answer afin que la ligne de marqueur soit silencieusement ignorée.
ANSWER=$(printf '%s' "${RESULT}" | jq -rR 'try (fromjson | objects | select(has("answer")) | .answer)')

Retournez uniquement $ANSWER à l'utilisateur — texte brut, le markdown léger va bien. Ne l'enveloppez pas dans un modèle de rapport.

Exemples

• « Que se passe-t-il dans ce clip ? /home/me/forklift.mp4 » → Chemin A (--file /home/me/forklift.mp4).
• « L'ouvrier porte-t-il un EPI ? https://example.com/clip.mp4 » → Chemin A (--media-url https://example.com/clip.mp4).
• « L'ouvrier dans warehouse_safety_0001 porte-t-il un EPI ? » → vérification du capteur → Chemin B (--sensor warehouse_safety_0001).
• « À quel timestamp l'ouvrier a-t-il grimpé l'échelle ? » → même Chemin B ; vss vlm run gère le clip.
• « Quelle couleur est le camion à 00:12 dans dock_cam ? » → Chemin B avec --start-time / --end-time.

Gestion des erreurs

• Si vss vlm run se termine avec un code non nul, arrêtez et rapportez l'erreur. Le code indique quoi faire ensuite :
  • 2 — entrée invalide : sources médias conflictuelles ou manquantes, une fenêtre de temps sans --sensor, un --file illisible, ou une URL que RT-VLM a rejetée (p. ex. bloquée par SSRF). Corrigez la requête ; ne la relancez pas inchangée.
  • 3 — backend inaccessible : rt_vlm a retourné 5xx, refusé la connexion, ou répondu avec une réponse inutilisable ou vide. Infrastructure plutôt que la requête — relancer est raisonnable.
  • 4 — service obligatoire manquant de la configuration enregistrée : rt_vlm pour chaque requête, ou vst lors de l'utilisation de --sensor. Relancez vss configure contre une origin qui expose tous les services nécessaires.
  • 5 — le nom du capteur n'est pas dans VIOS. Ne relancez pas ainsi : listez les capteurs (voir Vérification du capteur) et confirmez le nom prévu avec l'utilisateur.
  • 6 — la réponse a été produite mais n'a pas pu être écrite en mémoire. La réponse sur stdout est valide ; seule l'écriture en mémoire a échoué.
  • 7 — timeout (augmentez --timeout).
• Si aucune vidéo n'est disponible (ni URL/fichier ni capteur), arrêtez et demandez-en une à l'utilisateur.
• Si rt_vlm n'est pas listé comme ok dans vss configure check, le déploiement ne le sert pas. Arrêtez et rapportez-le ; la mise en place du service est une tâche de déploiement (voir Référence croisée).

Référence croisée

• /vss-manage-video-io-storage — optionnel (Étape 1, Chemin B) : sémantiques de téléchargement au niveau REST.
• /vss-deploy-dense-captioning — optionnel : mettre en place un RT-VLM autonome si rt_vlm n'est pas déployé. Ne relancez pas vss configure contre l'URL RT-VLM autonome si vous utilisez également le Chemin B (--sensor / vss vios) : le faire remplace la configuration de déploiement par une qui manque les routes VIOS, cassant le chemin du capteur. À la place, exposez RT-VLM à travers la même origin que VIOS et relancez vss configure contre cet origin partagé.
• /vss-generate-video-report — rapports horodatés via le même chemin VLM ; cette skill retourne une réponse ad-hoc, pas un rapport.
• /vss-query-analytics — lire les incidents/métriques déjà calculés (pas d'inférence VLM en direct).