Objectif

Opérer le pipeline d'alerte VSS (détection de mode, souscriptions Alert-Bridge, notifications Slack, requêtes, intégration de caméras, personnalisation des prompts du vérificateur).

Prérequis

• Déploiement VSS actif et accessible sur $HOST_IP (voir vss-deploy-profile et references/).
• Identifiants NGC dans $NGC_CLI_API_KEY et $NVIDIA_API_KEY pour tout téléchargement d'image.
• curl, jq et Docker disponibles sur le système appelant.

Instructions

Suivez les tables de routage et les workflows étape par étape ci-dessous. Chaque section se terminant par workflow, quick start ou flow est destinée à être exécutée de haut en bas. La documentation de référence détaillée se trouve dans references/ et les scripts auxiliaires se trouvent dans scripts/ — appelez-les via run_script quand le skill pointe vers un script par son nom.

Exemples

Les exemples complets d'exécution se trouvent sous evals/ (chaque manifeste *.json contient un scénario exécutable) et en ligne dans les blocs curl par workflow ci-dessous. Exécutez une évaluation Tier-3 avec nv-base validate <this-skill-dir> --agent-eval pour les rejouer.

Limitations

• Nécessite le profil VSS correspondant / le microservice à déployer et accessible depuis le système appelant.
• Les modèles et NIMs hébergés sur NGC peuvent être soumis à des limites de débit, des exigences de mémoire GPU et des restrictions de licence.
• Les limites de concurrence, de mémoire GPU et de stockage dépendent du matériel hôte et du fichier compose du profil.

Dépannage

• Erreur : l'appel REST retourne connexion refusée. Cause : microservice cible non en cours d'exécution. Solution : sondez /docs ou /health ; redéployez via vss-deploy-profile ou le skill vss-deploy-* correspondant.
• Erreur : HTTP 401/403 lors des téléchargements NGC. Cause : NGC_CLI_API_KEY manquante/expirée. Solution : docker login nvcr.io et réexportez la clé avant de réessayer.
• Erreur : conteneur OOM ou le modèle ne peut pas se charger. Cause : mémoire GPU insuffisante pour le profil sélectionné. Solution : basculez vers une variante plus petite ou libérez les GPUs via docker compose down.

Gestion des alertes VSS

Le profil d'alertes est déployé en l'un de deux modes à la fois. Le mode est choisi à /vss-deploy-profile -p alerts -m {verification,real-time}.

• Le mode CV (vérification) exécute le pipeline CV statique (RT-CV + Behavior Analytics + vérificateur VLM alert-bridge) et le service temps réel dynamique rtvi-vlm. Les workflows A (alertes CV statiques) et B (surveillance VLM) sont disponibles ; les workflows D et E nécessitent le mode VLM temps réel.
• Le mode VLM (temps réel) exécute uniquement rtvi-vlm pour les alertes temps réel dynamiques. Le pipeline CV (RT-CV, Behavior Analytics) n'est pas en cours d'exécution, donc le workflow A n'est pas disponible.

Ce skill effectue le routage par mode déployé + intention utilisateur (surveillance vs CRUD d'abonnement vs opérations de webhook Slack).

Quand l'utiliser

• Démarrer ou arrêter une alerte temps réel sur un capteur (« Démarrer une alerte temps réel pour les boîtes tombées sur le capteur warehouse_sample »)
• Créer, lister ou arrêter des règles d'abonnement temps réel sur Alert Bridge (« Lister les règles temps réel actives sur warehouse-dock-1 »)
• Configurer ou gérer les notifications d'incident Slack (« Démarrer le webhook Slack d'alerte et envoyer une notification de test »)
• Lister ou interroger les incidents/alertes détectés
• Ajouter une nouvelle caméra au pipeline d'alertes
• Personnaliser les prompts du vérificateur VLM (mode CV)
• Vérifier les verdicts (confirmé / rejeté / non vérifié)

Prérequis de déploiement

Nécessite le profil VSS alerts sur $HOST_IP en mode verification (CV) ou real-time (VLM).

# Soit perception-alerts (mode CV) SOIT rtvi-vlm (mode VLM) doit être présent.
curl -sf --max-time 5 "http://${HOST_IP}:8000/docs" >/dev/null \
  && docker ps --format '{{.Names}}' \
     | grep -qE '^(perception-alerts|rtvi-vlm)$'

Si le sondage échoue, demandez à l'utilisateur quel mode déployer et remettez à /vss-deploy-profile -p alerts -m <mode>. Si l'utilisateur refuse, arrêtez. Si l'appelant a pré-autorisé un déploiement autonome, exécutez-le directement avec le mode verification par défaut. Si cela réussit, détectez le mode selon l'étape 1.

Les deux modes (choix au moment du déploiement)

Changer de mode nécessite le flux de démontage et déploiement vss-deploy-profile avec l'autre drapeau -m. Passer de VLM → CV ajoute le pipeline CV statique ; passer de CV → VLM démonte le pipeline CV. rtvi-vlm est présent dans les deux modes.

Étape 1 — Détecter le mode actuellement déployé

Avant d'exécuter n'importe quel workflow d'alerte, vérifiez quel mode est actif. Utilisez les conteneurs CV uniquement comme signal — rtvi-vlm n'est plus un signal de mode fiable car il s'exécute dans les deux modes.

# Mode vérification CV (behavior analytics + perception-alerts sont CV uniquement)
docker ps --format '{{.Names}}' | grep -qx vss-behavior-analytics-alerts && echo "mode=CV"

# Mode VLM temps réel (pas de pipeline CV ; uniquement rtvi-vlm)
docker ps --format '{{.Names}}' | grep -qx vss-behavior-analytics-alerts || \
  docker ps --format '{{.Names}}' | grep -qx rtvi-vlm && echo "mode=VLM"

Si vss-behavior-analytics-alerts est présent → mode CV (qui a aussi rtvi-vlm). Si seul rtvi-vlm est présent (et aucun pipeline CV) → mode VLM. Si rien ne correspond, le profil d'alertes n'est pas déployé — dirigez l'utilisateur vers le skill vss-deploy-profile.

Signal alternatif (préféré quand docker ps n'est pas accessible) : vérifiez le .env du profil :

grep -E '^MODE=' deployments/developer-workflow/dev-profile-alerts/.env
# MODE=2d_cv   → mode CV (ensemble complet)
# MODE=2d_vlm  → mode VLM temps réel (rtvi-vlm uniquement)

Étape 2 — Routage par mode déployé

Toujours confirmer avant de déclencher un redéploiement. Un changement de mode arrête toute surveillance actuellement en cours et redémarre les services.

Précédence d'intention (première correspondance gagne)

1. Workflow E (Slack) — mots-clés spécifiques à Slack (slack, webhook + slack, bot token, slack channel). notify seul n'est pas suffisant.
2. Workflow D (Abonnements) — nom du capteur plus une condition de détection, ou mots-clés de CRUD de règle (rule, subscription, ID de règle).
3. Workflow B (surveillance VLM) — démarrage/arrêt générique sur un capteur sans condition de détection.
4. Workflow C (Requête) — recherche d'incident (show/list incidents, recent alerts, requêtes de plage horaire).
5. Workflow A (CV) — gestion du déploiement CV pour tout ce qui n'est pas appareillé ci-dessus.

Désambiguïsation (B vs D) : si un capteur est nommé avec un langage de démarrage/surveillance mais que la condition de détection est floue, demandez :

« Voulez-vous que je (a) crée une règle d'alerte persistante sur Alert Bridge qui continue à s'exécuter jusqu'à ce que vous la supprimiez, ou (b) démarre une session de surveillance unique via l'agent VSS ? »

Si un prompt mélange les workflows (« démarrer la surveillance et envoyer à Slack »), posez une question de clarification pour séparer l'ordre d'exécution.

Texte de refus du mode CV pour les intentions D et E

Quand le mode déployé est vérification CV et que l'utilisateur demande une intention d'alerte-abonnement ou Slack/notification, refusez avec ce message à la lettre :

« Les abonnements aux alertes et les notifications Slack ne sont pris en charge que en mode VLM temps réel. Votre déploiement actuel est <CV verification | not deployed>. Pour utiliser ces fonctionnalités, redéployez avec /vss-deploy-profile -p alerts -m real-time (note : le changement de mode démonte la surveillance CV actuelle). »

Aucun redéploiement automatique. L'utilisateur décide s'il faut changer de mode.

Prérequis pour l'un ou l'autre mode : le capteur doit être dans VIOS

Les deux modes nécessitent que la caméra soit d'abord enregistrée dans VIOS.

• Si l'utilisateur vous donne uniquement une URL RTSP (ou une caméra IP) — remettez au skill vss-manage-video-io-storage pour l'ajouter via POST /sensor/add (voir la section 6 du skill vss-manage-video-io-storage). Enregistrez l'sensorId / le nom retourné.
• Si l'utilisateur nomme un capteur existant — confirmez qu'il est listé par GET /sensor/list via le skill vss-manage-video-io-storage avant de procéder.

Sur un déploiement CV, ajouter l'RTSP est l'intégralité de l'étape d'intégration — le pipeline récupère le flux automatiquement une fois qu'il est dans VIOS. Sur un déploiement VLM, ajouter l'RTSP est un prérequis du workflow B.

Le endpoint /generate de l'agent

Toutes les actions de flux VLM et toutes les actions de requête passent par le endpoint de langage naturel de l'agent VSS :

AGENT="http://<AGENT_ENDPOINT>"   # par défaut http://localhost:8000 sur le profil d'alertes

curl -s -X POST "$AGENT/generate" \
  -H "Content-Type: application/json" \
  -d '{"input_message": "<demande en langage naturel>"}' | jq .

Résolution du endpoint : utilisez le endpoint de l'agent du contexte de déploiement VSS actif. S'il n'est pas disponible, demandez à l'utilisateur. Ne le découvrez pas via le système de fichiers.

Vérification de disponibilité : curl -sf --connect-timeout 5 "$AGENT/docs".

Ne appelez pas directement les endpoints du microservice rtvi-vlm — passez toujours par l'agent. L'agent distribue en interne vers rtvi_vlm_alert, rtvi_prompt_gen et video_analytics_mcp.get_incidents.

Workflow A — Mode CV (-m verification / MODE=2d_cv)

Les alertes CV sont déclenchées par le déploiement, non par la requête — il n'y a pas d'appel d'agent pour en « créer » une.

1. Vérifiez si le capteur est déjà dans VIOS via GET /sensor/list du skill vss-manage-video-io-storage (idempotent — ne faites jamais aveuglément POST /sensor/add).
2. S'il manque, intégrez via POST /sensor/add du skill vss-manage-video-io-storage (voir la section 6 de ce skill). Le pipeline CV récupère le flux automatiquement une fois enregistré et en ligne.
3. Confirmez en ligne : curl -s "http://<VST_ENDPOINT>/vst/api/v1/sensor/<sensorId>/status" | jq .
4. Attendez les alertes dans Elasticsearch (Behavior Analytics → vérification VLM alert-bridge selon alert_type_config.json). Interrogez les résultats avec Workflow C.

Si l'utilisateur demande une alerte de pipeline CV statique sur un déploiement VLM uniquement, c'est une inadéquation de mode — voir la table de routage ci-dessus.

Workflow B — Surveillance VLM temps réel (mode CV ou VLM)

Intents génériques de démarrage / arrêt via l'agent VSS pour un capteur nommé sans condition de détection (si une condition est présente, routez vers le workflow D). rtvi-vlm s'exécute dans les deux modes.

# démarrer : input_message = "Start real-time alert for sensor <id>"
# arrêter : input_message = "Stop real-time alert for sensor <id>"
curl -s -X POST "$AGENT/generate" -H "Content-Type: application/json" \
  -d '{"input_message": "<start|stop> real-time alert for sensor <id>"}' | jq .

En coulisse, l'agent appelle rtvi_prompt_gen puis rtvi_vlm_alert action="start". Sémantique d'alerte : chaque chunk est sous-titré ; un chunk dont la réponse VLM contient yes / true (insensible à la casse) publie un incident dans mdx-vlm-incidents. Les prompts doivent forcer une réponse Oui/Non. Une requête de pipeline CV statique sur un déploiement VLM uniquement est une inadéquation de mode — voir la table de routage.

Workflow D — Souscriptions d'alerte (mode VLM temps réel uniquement)

Créez / listez / supprimez des règles d'alerte temps réel persistantes sur Alert Bridge. Routez ici quand le prompt a des mots-clés de règle (rule, subscription, un ID de règle) ou quand il associe un capteur spécifique à une condition de détection spécifique (p. ex. « Configurer une alerte temps réel sur warehouse-dock-1 pour les violations EPI », « Surveiller le capteur entrance-1 pour la fraude », « Arrêter la règle 496aebd1-… »).

Pas ici : démarrage/arrêt générique sans condition (→ Workflow B) ou opérations Slack (→ Workflow E).

Chargez et suivez references/alert-subscriptions.md comme playbook autoritaire pour le CRUD d'abonnement. Mode VLM temps réel uniquement ; refusez avec le texte de refus canonique sur CV.

Workflow E — Notifications Slack (mode VLM temps réel uniquement)

Utilisez quand l'utilisateur mentionne explicitement Slack ou le relais webhook (démarrage/arrêt du serveur webhook, vérification du statut/santé, envoi d'un message de test, définition du canal/token Slack). Le mot notify seul n'est pas suffisant.

alert-notify (port 9090) ≠ vss-alert-bridge (/api/v1/realtime). Ne touchez PAS à vss-alert-bridge pour les opérations Slack.

Les exemples qui routent ici : « Configurer les notifications Slack pour les alertes », « Vérifier si alert-notify s'exécute », « Envoyer une notification d'alerte de test à Slack », « Démarrer le webhook d'alerte pour Slack ».

Les exemples qui ne routent PAS ici : « Me notifier quand quelqu'un entre dans la zone » (→ Workflow D/B), « Alerte et notification sur mon téléphone » (ambigu — demandez).

Chargez et suivez references/alert-notify.md. Le code se trouve dans scripts/alert-notify/. Mode VLM temps réel uniquement.

Workflow C — Requête / Liste des alertes (fonctionne sur l'un ou l'autre mode)

Les alertes générées par CV et VLM atterrissent dans Elasticsearch et sont interrogeables via l'outil video_analytics_mcp.get_incidents de l'agent. POSTez des requêtes en langage naturel vers $AGENT/generate — « Montrez-moi les alertes récentes pour le capteur X », « Lister les alertes confirmées de la dernière heure », « Afficher les incidents de collision de Camera_02 entre <ISO> et <ISO> ». Pour un filtrage plus riche / non langage naturel (au niveau du capteur, séries chronologiques, comptages), utilisez le skill vss-query-analytics (VA-MCP sur le port 9901).

Interprétation des verdicts (mode CV uniquement)

Les alertes vérifiées portent un bloc info étendu :

Vérifiez verification_response_code (200 = succès) et reasoning pour l'explication du VLM. Les incidents en mode VLM sont toujours « confirmés » à la source (le déclencheur lui-même est une réponse Oui/Non du VLM), donc il n'y a pas de champ verdict séparé.

Personnaliser les prompts du vérificateur CV (mode CV uniquement)

Les prompts du vérificateur de chemin CV se trouvent dans deployments/developer-workflow/dev-profile-alerts/vlm-as-verifier/configs/alert_type_config.json. Chaque entrée mappe un alert_type CV (le champ category émis par Behavior Analytics) aux prompts VLM system / user / enrichment optionnel.

Règles clés :

• alert_type doit correspondre au category émis par Behavior Analytics.
• output_category est le nom d'affichage dans Elasticsearch / UI.
• enrichment déclenche un deuxième appel VLM pour une description plus riche ; nécessite alert_agent.enrichment.enabled: true.
• Les modifications nécessitent un redémarrage du conteneur alert-bridge pour prendre effet.

Les prompts VLM temps réel ne sont pas configurés dans un fichier — ils sont par requête, formés par rtvi_prompt_gen à partir de la description de détection en langage naturel de l'utilisateur.

Liens entre skills

Pièges

• alert-notify (port 9090) ≠ vss-alert-bridge. « Webhook Slack » → Workflow E (alert-notify). Ne routez jamais les intentions Slack vers /api/v1/realtime de vss-alert-bridge.
• Portée du workflow par mode : Workflow A est CV uniquement. Les workflows B et C fonctionnent sur l'un ou l'autre mode. Les workflows D et E (abonnements et Slack) sont VLM temps réel uniquement — refusez avec le texte de refus canonique s'ils sont tentés sur CV.
• N'utilisez pas la présence du conteneur rtvi-vlm comme signal de mode. Il s'exécute dans les deux modes. Utilisez vss-behavior-analytics-alerts (CV uniquement) ou la variable d'env MODE à la place.
• Un changement de mode démonte le déploiement actuel. Tout flux de surveillance VLM actuellement en cours et tout état d'alerte CV non déjà dans Elasticsearch sera perdu.
• N'appelez pas le microservice rtvi-vlm directement depuis ce skill. Passez toujours par $AGENT/generate. L'agent gère la recherche capteur→RTSP, l'enregistrement du flux et la suppression.
• Le capteur doit déjà être dans VIOS pour l'un ou l'autre mode. Si l'utilisateur vous donne uniquement une URL RTSP, utilisez d'abord le skill vss-manage-video-io-storage.
• Le déclencheur d'alerte VLM est une correspondance de jeton "yes" / "true" sur la réponse VLM (insensible à la casse). rtvi_prompt_gen applique le modèle Oui/Non — ne craftiez pas à la main des prompts qui le cassent.
• Arrêter une alerte VLM est un appel d'agent (« Stop real-time alert… ») ; l'agent gère à la fois le flux de sous-titrage et la suppression de l'enregistrement de flux.
• Les modifications de prompt vers alert_type_config.json ont besoin d'un redémarrage alert-bridge. alert_agent.enrichment.enabled: true est requis pour que le prompt enrichment se déclenche.

bump:1