Gestion des alertes VSS

Le profil des alertes est déployé dans l'un de deux modes à la fois. Le mode est choisi à deploy -p alerts -m {verification,real-time} et reste statique jusqu'à ce que vous le démontiez et redéployiez. Le mode en cours détermine le flux à utiliser — cette compétence ne route pas par requête.

Quand utiliser

• Démarrer ou arrêter une alerte en temps réel sur un capteur (« Start real-time alert for boxes dropped on sensor warehouse_sample »)
• Lister ou interroger les incidents / alertes détectés
• Ajouter une nouvelle caméra au pipeline des alertes
• Personnaliser les prompts du vérificateur VLM (mode CV)
• Vérifier les verdicts (confirmé / rejeté / non vérifié)

Prérequis de déploiement

Cette compétence nécessite que le profil alerts de VSS soit en cours d'exécution sur l'hôte à $HOST_IP, en mode verification ou real-time. Avant toute requête :

1. Sonner la pile :

   # 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)$'

2. Si la sonde échoue, demander à l'utilisateur :

   « Le profil alerts de VSS ne s'exécute pas sur $HOST_IP. Quel mode dois-je déployer — verification (CV) ou real-time (VLM) ? »

   • Réponse → transférer à la compétence /deploy avec -p alerts -m <mode>. Revenir ici une fois que cela réussit.
   • Si l'utilisateur refuse → arrêter. Ne pas exécuter cette compétence contre une pile manquante.

   (Si votre appelant a accordé une pré-autorisation explicite pour déployer de manière autonome — par exemple la requête dit « pre-authorized to deploy prerequisites », ou vous exécutez un banc d'essai d'évaluation non interactif avec cette permission — ignorer la confirmation et invoquer /deploy directement. Par défaut, utiliser le mode verification sauf si la requête spécifie autrement.)

3. Si la sonde passe, détecter le mode selon § Étape 1 ci-dessous.

Les deux modes (choix au déploiement)

Le mode est statique. Passer d'un mode à l'autre nécessite deploy down + deploy up avec l'autre drapeau -m — voir la compétence deploy. Ne jamais supposer que les deux flux sont disponibles simultanément.

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

Avant d'exécuter un flux d'alerte, vérifier quel mode est actif. Utiliser les noms des conteneurs comme signal :

# Mode VLM real-time
docker ps --format '{{.Names}}' | grep -qx rtvi-vlm && echo "mode=VLM"

# Mode CV verification (behavior analytics est CV-only ; alert-bridge est le vérificateur VLM)
docker ps --format '{{.Names}}' | grep -qx vss-behavior-analytics-alerts && echo "mode=CV"

Exactement l'un de ces éléments devrait correspondre sur un déploiement d'alertes sain. Si aucun ne correspond, le profil des alertes n'est pas déployé — diriger l'utilisateur vers la compétence deploy.

Signal alternatif (si docker ps n'est pas disponible dans le contexte actuel) : vérifier le .env du profil :

grep -E '^MODE=' deployments/developer-workflow/dev-profile-alerts/.env
# MODE=2d_cv   → mode CV
# MODE=2d_vlm  → mode VLM real-time

Étape 2 — Router par mode déployé

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

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 seulement une URL RTSP (ou une caméra IP) — reporter à la compétence vios pour l'ajouter via POST /sensor/add (voir section 6 de la compétence vios). Enregistrer le sensorId / nom retourné.
• Si l'utilisateur nomme un capteur existant — confirmer qu'il figure dans la liste via GET /sensor/list de la compétence vios avant de procéder.
• Si l'utilisateur demande d'utiliser un MP4 local/exemple pour une alerte VLM real-time, ne pas charger directement le MP4 vers le stockage VIOS (PUT /storage/file/...). Les téléchargements de fichiers VIOS créent des entrées sensor_file dont l'URL du flux est un chemin de fichier local ; rtvi-vlm nécessite une URL rtsp://... en direct.
• Pour un MP4 local/exemple en mode VLM real-time, d'abord ajouter la vidéo à NVStreamer (ou un autre rétransmetteur RTSP) et obtenir son URL RTSP en direct, puis ajouter cette URL RTSP à VIOS via POST /sensor/add avec le nom de capteur souhaité. Procéder seulement une fois que GET /sensor/<sensorId>/streams affiche une URL de flux commençant par rtsp://.

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

L'endpoint /generate de l'agent

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

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

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

Résolution d'endpoint : utiliser l'endpoint de l'agent du contexte de déploiement VSS actif. Si indisponible, demander à l'utilisateur. Ne pas découvrir via le système de fichiers.

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

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

Workflow A — Mode CV (déploiement est -m verification / MODE=2d_cv)

Sur un déploiement CV, les alertes sont pilotées par le déploiement, non par la requête. Il n'y a pas d'appel à l'agent pour « créer » une alerte.

1. Intégrer la caméra — ajouter le flux RTSP à VIOS via la compétence vios (POST /sensor/add). Une fois enregistrée et en ligne, le pipeline CV la reprend automatiquement.

2. Confirmer que le capteur est en ligne :

   curl -s "http://<VST_ENDPOINT>/vst/api/v1/sensor/<sensorId>/status" | jq .

3. Attendre que les alertes arrivent dans Elasticsearch. Behavior Analytics émet des candidats qui correspondent aux règles configurées ; alert-bridge appelle le VLM pour confirmer/rejeter chaque candidat selon alert_type_config.json. Utiliser Workflow C pour interroger les résultats.

Si l'utilisateur vous demande de « démarrer une alerte en temps réel » sur un déploiement CV, c'est une incompatibilité de mode — voir le tableau de routage ci-dessus.

Workflow B — Mode VLM (déploiement est -m real-time / MODE=2d_vlm)

Sur un déploiement VLM, l'utilisateur crée des alertes via des requêtes en langage naturel à l'agent VSS. L'agent appelle rtvi_prompt_gen pour transformer la description en une question de détection Oui/Non, puis rtvi_vlm_alert avec action="start" pour enregistrer le flux auprès de rtvi-vlm et commencer la surveillance continue.

Avant d'appeler l'agent, vérifier que le capteur cible est RTSP :

curl -s "http://<VST_ENDPOINT>/vst/api/v1/sensor/<sensorId>/streams" | jq .

Au moins un flux du capteur doit avoir une URL commençant par rtsp://. Si l'URL du flux est un chemin de fichier local tel que /home/vst/.../video.mp4, le capteur a été chargé comme fichier VIOS et le démarrage d'alerte real-time échouera. Pour les vidéos d'exemple, ajouter d'abord la vidéo à NVStreamer, enregistrer l'URL RTSP retournée dans VIOS, puis démarrer l'alerte contre ce capteur VIOS supporté par RTSP.

Intégration de vidéo d'exemple pour les alertes real-time :

1. Ajouter le MP4 à NVStreamer et obtenir l'URL RTSP en direct du nouveau flux.

2. Enregistrer cette URL RTSP dans VIOS :

   curl -s -X POST "http://<VST_ENDPOINT>/vst/api/v1/sensor/add" \
     -H "Content-Type: application/json" \
     -d '{
       "sensorUrl": "rtsp://<nvstreamer-host>:<port>/<path>",
       "name": "warehouse_sample"
     }' | jq .

3. Confirmer que GET /sensor/warehouse_sample/streams retourne l'URL RTSP, puis appeler l'agent VSS comme montré ci-dessous.

Requête d'exemple canonique :

curl -s -X POST "$AGENT/generate" \
  -H "Content-Type: application/json" \
  -d '{"input_message": "Start real-time alert for boxes dropped on sensor warehouse_sample"}' | jq .

Plus d'exemples :

# Collisions de véhicules sur une caméra de rue
curl -s -X POST "$AGENT/generate" -H "Content-Type: application/json" \
  -d '{"input_message": "Start real-time alert for vehicle collisions on sensor Camera_02"}' | jq .

# Proximité chariot élévateur-piéton
curl -s -X POST "$AGENT/generate" -H "Content-Type: application/json" \
  -d '{"input_message": "Monitor Warehouse_Dock_3 for a forklift passing within 1 meter of a pedestrian"}' | jq .

# Démarrage générique (pas de cible spécifique — utilise le prompt par défaut)
curl -s -X POST "$AGENT/generate" -H "Content-Type: application/json" \
  -d '{"input_message": "Start real-time alert for sensor warehouse_sample"}' | jq .

Ce que fait l'agent en arrière-plan :

1. rtvi_prompt_gen — convertit « boxes dropped » → prompt: "Detect for a box being dropped. Answer in Yes or No", system_prompt: "You are a helpful assistant.".
2. rtvi_vlm_alert action="start" — cherche le capteur dans les flux VIOS en direct, appelle POST /v1/streams/add et POST /v1/generate_captions_alerts (stream=true) sur rtvi-vlm. Retourne stream_id.

Sémantique des alertes : chaque segment est sous-titré ; un segment dont la réponse VLM contient "yes" ou "true" (insensible à la casse) déclenche un incident publié au sujet des incidents Kafka (mdx-vlm-incidents sur le profil des alertes). C'est pourquoi les prompts doivent forcer une réponse Oui/Non.

Arrêter la surveillance :

curl -s -X POST "$AGENT/generate" -H "Content-Type: application/json" \
  -d '{"input_message": "Stop real-time alert for sensor warehouse_sample"}' | jq .

Si l'utilisateur vous demande de signaler un scénario qui correspond à un alert_type CV (par ex. « ladder PPE violation ») sur un déploiement VLM, c'est une incompatibilité de mode — voir le tableau de routage ci-dessus.

Workflow C — Interroger / Lister les 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 :

curl -s -X POST "$AGENT/generate" -H "Content-Type: application/json" \
  -d '{"input_message": "Show me recent alerts for sensor warehouse_sample"}' | jq .

curl -s -X POST "$AGENT/generate" -H "Content-Type: application/json" \
  -d '{"input_message": "List confirmed alerts from the last hour"}' | jq .

curl -s -X POST "$AGENT/generate" -H "Content-Type: application/json" \
  -d '{"input_message": "Were there any PPE violations today on Camera_02?"}' | jq .

curl -s -X POST "$AGENT/generate" -H "Content-Type: application/json" \
  -d '{"input_message": "Show collision incidents from Camera_02 between 2026-04-23T00:00:00.000Z and 2026-04-23T23:59:59.000Z"}' | jq .

Pour un filtrage plus riche / non en langage naturel (niveau capteur, série temporelle, comptages) : utiliser la compétence video-analytics (VA-MCP sur le port 9901).

Interprétation du verdict (mode CV uniquement)

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

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

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

Les prompts du vérificateur du 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 utilisés pour la vérification :

{
  "version": "1.0",
  "alerts": [
    {
      "alert_type": "FOV Count Violation",
      "output_category": "Ladder PPE Violation",
      "prompts": {
        "system": "You are a helpful assistant.",
        "user": "Is anyone on the ladder without a hardhat and safety vest? Answer yes or no.",
        "enrichment": "Describe the PPE violation in detail..."
      }
    }
  ]
}

• alert_type doit correspondre à la category émise par Behavior Analytics.
• output_category est le nom d'affichage dans Elasticsearch / UI.
• enrichment (optionnel) 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 (vlm-as-verifier).

Les prompts VLM real-time ne sont pas configurés dans un fichier — ils sont par requête, façonnés par rtvi_prompt_gen à partir de la description de détection en langage naturel de l'utilisateur.

Liens entre compétences

Pièges

• Le mode est statique. Ne pas tenter d'exécuter le flux VLM sur un déploiement CV ou vice-versa — les services requis ne s'exécutent pas. Confirmer avec l'utilisateur, puis router vers la compétence deploy pour redéploiement.
• Un changement de mode démontre le déploiement actuel. Tous les flux de surveillance VLM en cours d'exécution et tout état d'alerte CV non déjà dans Elasticsearch seront perdus.
• Ne pas appeler directement le microservice rtvi-vlm depuis cette compétence. Toujours passer par $AGENT/generate. L'agent gère la recherche capteur→RTSP, l'enregistrement des flux, et l'arrêt.
• Le capteur doit déjà être dans VIOS pour l'un ou l'autre mode. Si l'utilisateur ne vous donne qu'une URL RTSP, utiliser d'abord la compétence vios.
• Le déclencheur d'alerte VLM est une correspondance de token "yes" / "true" sur la réponse VLM (insensible à la casse). rtvi_prompt_gen applique le pattern Oui/Non — ne pas concevoir manuellement 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 l'arrêt de l'enregistrement des flux.
• Les changements de prompt vers alert_type_config.json nécessitent un redémarrage de alert-bridge. alert_agent.enrichment.enabled: true est requis pour que le prompt enrichment se déclenche.