Rapport

Générez un rapport d'analyse vidéo en le redirigeant vers l'un des deux backends — jamais via la méthode POST /generate sur l'agent VSS.

Si la requête est ambiguë (par exemple « rapport sur » sans plage horaire ni description d’incident), utilisez par défaut le mode A. Ne posez la question que si l’utilisateur mentionne à la fois un capteur et une plage horaire. Consultez les exemples ci-dessous pour connaître les formulations de requêtes qui orientent vers chaque mode.

Instructions

1. Choisissez le mode — Mode A pour un seul clip enregistré ou une vidéo de capteur, Mode B lorsque la requête précise une plage horaire ou des incidents/alertes (comparez avec les exemples).
2. Vérifiez le profil de déploiement correspondant à ce mode dans la section « Conditions préalables au déploiement » ; transférez la demande à /vss-deploy-profile si la vérification échoue.
3. Exécutez les étapes numérotées de ce mode — Mode A ou Mode B ci-dessous.
4. Réécrivez chaque URL de clip destinée à l’utilisateur en utilisant la chaîne $VSS_PUBLIC_HOST:$VSS_PUBLIC_PORT (URL de clip lisible dans un navigateur) avant de l’intégrer dans le rapport.
5. Renvoyer le rapport au format Markdown généré à l'utilisateur.

Spécifications pour les évaluateurs :

• Le titre principal du mode A DOIT être exactement # Rapport d’analyse vidéo.
• Le titre principal du mode B DOIT être exactement # Rapport sur la période d’incidents (jamais # Rapport d’incident ni aucune variante mentionnant le nom d’un capteur).
• Le mode B DOIT inclure la section ## Informations de base avec les lignes exactes requises du modèle (Identifiant du rapport, Plage, Portée, Nombre total d’incidents, Confirmés / Rejetés / Non vérifiés).

Exemples

• « Générer un rapport pour cette vidéo » / « rapport sur » → Mode A
• « Analyser warehouse_01.mp4 » / « Créer un rapport d'analyse sur la vidéo téléchargée » → Mode A
• « Rapport sur les incidents survenus de 12 h 31 Z à 12 h 32 Z » → Mode B
• « Rapport sur les alertes d’aujourd’hui » / « Quels incidents se sont produits au cours de dernière heure » → Mode B
• « Résumer les alertes sur entre et » → Mode B

Déclencheurs négatifs

N’ utilisez pas cette compétence lorsque la requête correspond à l’un des cas suivants :

• Questions-réponses visuelles ponctuelles sur un extrait vidéo qui ne demandent pas explicitement un rapport (« De quelle couleur est le camion ? », « Que se passe-t-il à 00:12 ? ») → utilisez /vss-ask-video.
• Recherche dans les archives ou par similarité sémantique (« trouver des chariots élévateurs », « rechercher tous les clips montrant des cas de talonnage ») → utilisez /vss-search-archive.
• Recherche en lecture seule d’incidents/de métriques sans besoin de génération de rapport → utilisez /vss-query-analytics.
• Déploiement, démantèlement ou modification de profil (« déployer des alertes », « changer de profil », « mettre en service la base ») → utilisez /vss-deploy-profile.
• Demandes de gestion des alertes et des règles en temps réel → utilisez /vss-manage-alerts.

Ne jamais acheminer les rapports via la méthode POST /generate de l’agent VSS.

Prérequis de déploiement

Le mode A nécessite le profil de base VSS (VST + VLM NIM). Le mode B nécessite le profil d’alertes VSS (VA-MCP + Elasticsearch).

Test :

# Mode A — Accessibilité VST + VLM
curl -sf --max-time 5 "http://${HOST_IP}:30888/vst/api/v1/sensor/version" >/dev/null

# Mode B — VA-MCP
curl -sf --max-time 5 "http://${HOST_IP}:9901/" >/dev/null

Si la sonde échoue, transférez la tâche à /vss-deploy-profile avec l'option -p base (mode A) ou -p alerts (mode B). Confirmez toujours au préalable le déploiement auprès de l'utilisateur.

URL des extraits : entrée VLM vs lien vers le rapport du navigateur

VST renvoie des URL de capture en utilisant l’adresse hôte-port interne à l’agent ${HOST_IP}:30888. Conservez cette URL d’origine comme VIDEO_URL pour les récupérations de trames VLM locales ou au sein du cluster. Ne réécrivez pas l’URL d’entrée VLM uniquement pour la rendre lisible par un navigateur.

Ne créez une BROWSER_CLIP_URL que pour les URL affichées dans le rapport généré. La couche de déploiement exporte l’hôte:port destiné au navigateur sous la forme $VSS_PUBLIC_HOST / $VSS_PUBLIC_PORT (et le schéma sous la forme $VSS_PUBLIC_HTTP_PROTOCOL) dans chaque fichier .env de profil — Brev ou bare-metal —. La réécriture du lien du rapport est donc la suivante :

: "${VSS_PUBLIC_HOST:?Définissez VSS_PUBLIC_HOST avant de réécrire les URL des extraits}"
: "${VSS_PUBLIC_PORT:?Définissez VSS_PUBLIC_PORT avant de réécrire les URL des extraits}"
VSS_PUBLIC_HTTP_PROTOCOL="${VSS_PUBLIC_HTTP_PROTOCOL:-http}"
BROWSER_CLIP_URL=$(echo "$RAW_URL" | sed -E "s|^https?://[^/]+|${VSS_PUBLIC_HTTP_PROTOCOL}://${VSS_PUBLIC_HOST}:${VSS_PUBLIC_PORT}|")

Si l’une des valeurs d’hôte public requises est manquante, omettez le lien vers l’extrait destiné au rapport et indiquez qu’il n’a pas été possible de générer une URL lisible par un navigateur ; ne bloquez pas le chemin d’analyse VLM local. Appliquez la réécriture à chaque URL de clip figurant dans le rapport généré (Mode A, étape 4, ligne « URL du clip » ; Mode B, sous-puce « clip par incident »). Laissez le bloc de contenu video_url du VLM dans le Mode A, étape 3, sur l'URL interne d'origine lorsque le VLM est local ou au sein du cluster.

Mode A — Rapport sur un clip vidéo enregistré

Si le profil VSS lvs est déployé — la commande `curl -sf --max-time 5 "http://${HOST_IP}:38111/v1/ready"` renvoie un code HTTP 200 — exécutez ` /vss-summarize-video ` pour générer le résumé, puis collez sa sortie dans le modèle de rapport à l’étape 4 et ignorez les étapes 1 à 3 (le chemin direct vers le VLM). N’exécutez les étapes 1 à 3 que lorsque /v1/ready renvoie un code autre que 200.

Étape 1 — Résoudre l’URL du clip

Transférez la tâche à /vss-manage-video-io-storage pour :

1. répertorier les capteurs et vérifier que le capteur nommé (le télécharger d’abord s’il n’existe pas).

2. Récupérer les données /storage//timelines pour la plage enregistrée lorsque l’utilisateur n’a pas fourni de startTime ni d’endTime.

3. Demander l’URL du clip :

   curl -s "http://${HOST_IP}:30888/vst/api/v1/storage/file//url?startTime=&endTime=&container=mp4&disableAudio=true" | jq -r .videoUrl
   

   Cela donne une URL mp4 directe à partir de laquelle le VLM local / au sein du cluster peut extraire des images. Associez-la à VIDEO_URL (utilisée par le VLM à l’étape 3) et définissez RAW_URL="$VIDEO_URL" avant d’appliquer la réécriture du lien du rapport pour générer BROWSER_CLIP_URL à l’étape 4 — le navigateur de l’utilisateur ne peut pas accéder directement à $VIDEO_URL. Le mode A nécessite que le point de terminaison VLM sélectionné soit capable de récupérer VIDEO_URL. Les déploiements NIM/RT-VLM locaux en sont généralement capables ; les points de terminaison distants ne peuvent généralement pas récupérer localhost, une adresse HOST_IP privée ou des URL internes à VST. Si le point de terminaison VLM_ENDPOINT en direct est distant, signalez cette exigence d’accessibilité au lieu d’ effectuer une requête de chat qui échouera après la réussite de /v1/models.

Étape 2 — Résolution du point de terminaison VLM et du modèle

Le déploiement peut fournir le VLM via l’une ou l’autre de ces deux piles. Toutes deux exposent une API de chat/complétions compatible OpenAI — choisissez celle qui est opérationnelle :

Lire les valeurs en temps réel à partir du conteneur de l’agent en cours d’exécution — ne pas deviner :

docker exec vss-agent sh -lc '
for k in HOST_IP VLM_MODE VLM_MODEL_TYPE VLM_BASE_URL VLM_NAME RTVI_VLM_BASE_URL RTVI_VLM_MODEL_TO_USE; do
  v="$(printenv "$k")"
  [ -n "$v" ] && printf "%s=%s\n" "$k" "$v"
done
'

Ne pas exiger la variable d'environnement RTVI_VLM_ENDPOINT de la part de vss-agent; plusieurs profils ne l'injectent pas.

Règle de sélection :

if [ "${VLM_MODEL_TYPE:-}" = "rtvi" ]; then
  VLM_BACKEND="rtvlm"
  VLM_ENDPOINT="${RTVI_VLM_BASE_URL:+${RTVI_VLM_BASE_URL%/}/v1}"
  [ -z "${VLM_ENDPOINT}" ] && VLM_ENDPOINT="http://${HOST_IP}:8018/v1"   # alertes par défaut
  VLM_MODEL="${RTVI_VLM_MODEL_TO_USE}"
elif [ -n "${VLM_BASE_URL}" ] && [ "${VLM_MODE}" != "none" ]; then
  VLM_BACKEND="nim_cosmos"
  VLM_ENDPOINT="${VLM_BASE_URL%/}/v1"
  VLM_MODEL="${VLM_NAME}"
else
  VLM_BACKEND="rtvlm"
  VLM_ENDPOINT="${RTVI_VLM_BASE_URL:+${RTVI_VLM_BASE_URL%/}/v1}"
  [ -z "${VLM_ENDPOINT}" ] && VLM_ENDPOINT="http://${HOST_IP}:30082/v1"  # valeur par défaut
  VLM_MODEL="${RTVI_VLM_MODEL_TO_USE}"
fi

Testez /v1/models avant d'envoyer une requête de chat afin de vérifier que le point de terminaison choisi est opérationnel et que le modèle est chargé :

curl -sf --max-time 5 "${VLM_ENDPOINT}/models" | jq -r '.data[].id'

Si la vérification échoue ou si les identifiants répertoriés n'incluent pas ${VLM_MODEL}, basculez vers l'autre backend (ou signalez l'erreur — ne choisissez jamais en silence un modèle qui ne se trouve pas sur le serveur).

Étape 3 — Appeler directement le VLM

Utilisez le point de terminaison « chat/completions » compatible OpenAI avec un bloc de contenu « video_url » — la même structure de charge utile et les mêmes paramètres multimodaux que ceux utilisés par « video_understanding » dans src/vss_agents/tools/video_understanding.py (_build_vlm_messages + l’appel Cosmos base_vlm.bind(...) ).

L’échantillonnage des images et le budget en jetons visuels (pixels) doivent refléter les paramètres actuels de `video_understanding ` pour le profil actif. Envoyez mm_processor_kwargs et media_io_kwargs afin que l’appel direct utilise le même échantillonnage d’images et le même budget de pixels que l’outil video_understanding intégré à l’agent — les omettre permet au VLM d’appliquer ses propres valeurs par défaut, ce qui fait que la sortie s’écarte du chemin de l’agent.

PROMPT='Décrivez en détail ce qui se passe dans la vidéo, en indiquant les horodatages (début–fin en secondes à partir du début du clip) pour chaque segment ou événement. Mentionnez les scènes, les objets, les personnes, les véhicules et les actions notables.'

# Le raisonnement est désactivé par défaut — ce qui correspond à la configuration « video_understanding » du profil de base (`reasoning: false`).
# video_understanding.py utilise config.reasoning sauf si l’appelant le remplace, donc le raisonnement est désactivé par défaut.
# Ajoutez le suffixe de raisonnement « Cosmos Reason 2 » UNIQUEMENT lorsque l’utilisateur demande explicitement un raisonnement
# (ne l’ajoutez pas pour les VLM autres que « cosmos-reason2 »). Lorsque le raisonnement est désactivé, la réponse ne comporte pas  de bloc .
if [ "${REASONING:-false}" = "true" ]; then
PROMPT="${PROMPT}

Répondez à la question en utilisant le format suivant :


Votre raisonnement.


Écrivez votre réponse finale immédiatement après la balise ."
fi

# Si l’étape 3 est exécutée de manière autonome, déduisez le backend manquant à partir de l’environnement/modèle actuel.
[ -z "${VLM_BACKEND:-}" ] && {
  if [ "${VLM_MODEL_TYPE:-}" = "rtvi" ]; then
    VLM_BACKEND="rtvlm"
  elif [[ "${VLM_MODEL:-}" == nvidia/cosmos* ]]; then
    VLM_BACKEND="nim_cosmos"
  else
    VLM_BACKEND="rtvlm"
  fi
}

# Paramètres multimodaux — à déterminer à partir du chemin d’accès au fichier de configuration de l’agent en direct, et non à partir de valeurs codées en dur.
CFG_JSON=$(
docker exec vss-agent python3 -c '
import json, os, yaml
p = os.getenv("VSS_AGENT_CONFIG_FILE")
if not p:
    raise SystemExit("VSS_AGENT_CONFIG_FILE n’est pas défini dans vss-agent")
if not os.path.isabs(p):
    p = os.path.join("/vss-agent", p.lstrip("./"))
with open(p, encoding="utf-8") as f:
    cfg = yaml.safe_load(f) or {}
vu = (cfg.get("functions", {}) or {}).get("video_understanding", {}) or {}
print(json.dumps({
    "max_fps": int(vu.get("max_fps", 2)),
    "max_frames": int(vu.get("max_frames", 30)),
    "min_pixels": int(vu.get("min_pixels", 3136)),
    "max_pixels": int(vu.get("max_pixels", 8388608)),
}))
')
)
[ -n "${CFG_JSON}" ] || { echo "Échec de la lecture de la configuration video_understanding depuis vss-agent"; exit 1; }
jq -e . >/dev/null <<< "${CFG_JSON}" || { echo "Fichier JSON de configuration invalide provenant de vss-agent" ; exit 1 ; }
MAX_FPS="$(jq -r '.max_fps' <<< "${CFG_JSON}")"
MAX_FRAMES="$(jq -r '.max_frames' <<< "${CFG_JSON}")"
MIN_PIXELS="$(jq -r '.min_pixels' <<< "${CFG_JSON}")"
MAX_PIXELS="$(jq -r '.max_pixels' <<< "${CFG_JSON}")"

# num_frames = min(int(clip_seconds) * max_fps, max_frames), min 1 — correspond à video_understanding.py.
# clip_seconds (Step 1 endTime-startTime) peut comporter une fraction ; troncature à un nombre entier de secondes — bash $((...))
# ne prend que des entiers et renvoie une erreur pour « 15,0 »/« 1,5 ». Par défaut 15 s -> plafonné à MAX_FRAMES.
CLIP_SECONDS=$(awk -v s="${CLIP_SECONDS:-15}" 'BEGIN{printf "%d", s}')
NUM_FRAMES=$(( CLIP_SECONDS * MAX_FPS ))
[ "$NUM_FRAMES" -gt "$MAX_FRAMES" ] && NUM_FRAMES=$MAX_FRAMES
[ "$NUM_FRAMES" -lt 1 ] && NUM_FRAMES=1

# N'appliquer les arguments de ligne de commande mm/media de Cosmos que sur le chemin NIM Cosmos.
# Le mode RT-VLM utilise son propre prétraitement côté serveur et ne doit pas recevoir ces arguments de ligne de commande.
MM_KWARGS=""
if [ "${VLM_BACKEND}" = "nim_cosmos" ]; then
  case "$VLM_MODEL" in
    *cosmos-reason2*) MM_KWARGS=", \"mm_processor_kwargs\": {\"size\": {\"shortest_edge\": ${MIN_PIXELS}, \"longest_edge\": ${MAX_PIXELS}}}, \"media_io_kwargs\": {\"video\": {\"num_frames\": ${NUM_FRAMES}}}" ;;
    *cosmos*)         MM_KWARGS=", \"mm_processor_kwargs\": {\"videos_kwargs\": {\"min_pixels\": ${MIN_PIXELS}, \"max_pixels\" : ${MAX_PIXELS}}}, \"media_io_kwargs\" : {\"video\" : {\"num_frames\" : ${NUM_FRAMES}}}" ;;
    *)                      MM_KWARGS="" ;;
  esac
fi

curl -s --connect-timeout 5 --max-time 120 -X POST "${VLM_ENDPOINT}/chat/completions" \
  -H "Content-Type: application/json" \
  -d @- <<EOF | jq -r '.choices[0].message.content'
{
  "model": $(jq -Rs . <<< "${VLM_MODEL}"),
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": $(jq -Rs . <<< "${PROMPT}")},
        {"type": "video_url", "video_url": {"url": $(jq -Rs . <<< "${VIDEO_URL}")}}
      ]
    }
  ],
  "max_tokens" : 1024,
  "temperature" : 0,0${MM_KWARGS}
}
EOF

Le bloc kwargs tient compte du backend : sur nim_cosmos, les variantes Reason2 (nvidia/cosmos-reason2*) utilisent mm_processor_kwargs.size{shortest_edge,longest_edge} et les autres variantes NIM Cosmos (nvidia/cosmos*) utilisent mm_processor_kwargs.videos_kwargs{min_pixels,max_pixels}; les deux envoient également media_io_kwargs.video.num_frames. Sur rtvlm, aucun kwargs Cosmos n’est envoyé.

Si le VLM renvoie un … bloc (mode de raisonnement Cosmos Reason), ne conservez que le texte situé après comme corps du rapport.

Étape 4 — Remplir le modèle de rapport d’analyse vidéo

Copiez le fichier assets/video-analysis-report.md, remplissez chaque espace réservé, puis renvoyez le code Markdown généré à l’utilisateur. Ne modifiez pas le fichier source. Avant la génération, vérifiez que BROWSER_CLIP_URL est défini et non vide, puis remplacez par cette valeur exacte dans la ligne « URL du clip ». Ne laissez jamais l’espace réservé dans la sortie, n’incluez jamais les instructions du modèle dans une cellule remplie et n’utilisez jamais l’URL brute HOST_IP:30888.

Mode B — Rapport sur les incidents sur une période donnée

Étape 1 — Déterminer la plage horaire et (facultativement) les capteurs

• start_time / end_time doivent être au format ISO 8601 UTC (AAAA-MM-JJTHH:MM:SS.sssZ). Convertissez les expressions relatives (« dernière heure », « aujourd’hui ») en fonction de l’horloge actuelle de l’hôte.
• Si l’utilisateur spécifie un capteur, enregistrez-le sous la forme source + source_type=sensor. Sinon, laissez les deux champs vides pour une requête portant sur tous les capteurs.

Étape 2 — Récupérer les incidents via /vss-query-analytics

Transférez le traitement à /vss-query-analytics (initialisation → tools/call) avec :

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "video_analytics__get_incidents",
    "arguments": {
      "source": "",
      "source_type": "sensor",
      "start_time": "",
      "end_time": "",
      "max_count": 100,
      "includes": ["objectIds", "info"]
    }
  },
  "id": 1
}

Limite en lecture seule (obligatoire) :

• Le mode B est strictement réservé à la consultation des données d’analyse en lecture seule. Il est interdit d’écrire, d’injecter, de rétroactiver ou de modifier les données Elasticsearch/VA.
• Exemples interdits : indexation d’incidents synthétiques, réinjection de charges utiles de test dans ES, appel d’API d’écriture/mise à jour/suppression pour « rendre les données disponibles » pour le rapport.
• S'il n'existe aucun incident pour la plage ou le périmètre demandé, traitez cela comme des résultats vides (voir ci-dessous) ; ne fabriquez pas de données.

Pour chaque incident, conservez : id, sensorId, timestamp, end, category, place.name, info.verdict, info.reasoning, objectIds et l’URL du clip (généralement info.clip_url, clip_url ou tout autre champ de pointeur de clip contenu dans la réponse). Appliquez la réécriture $VSS_PUBLIC_HOST:$VSS_PUBLIC_PORT (voir « URL de clip lisible par un navigateur » ci-dessus) à chaque URL de clip avant de la coller dans le rapport — la valeur brute est une URL de type HOST_IP:30888 que le navigateur de l’utilisateur ne peut pas atteindre.

Étape 3 — Remplir le modèle de rapport sur la plage d’incidents

Copiez le fichier assets/incident-range-report.md, puis regroupez les données par capteur (ou par catégorie s’il n’y a pas de périmètre de capteur), comptabilisez les verdicts et répertoriez chaque incident avec l’horodatage, la catégorie, le verdict et le raisonnement. Ne modifiez pas le fichier source. Chaque valeur de clip d’incident doit être une URL réécrite et lisible par un navigateur ; omettez la ligne de clip lorsque l’incident ne comporte pas d’URL de clip. N’incluez jamais les instructions du modèle dans une cellule remplie.

Si get_incidents renvoie zéro résultat, ARRÊTEZ-VOUS et renvoyez exactement une ligne de déclaration de plage vide indiquant la plage et la portée demandées. Ne générez pas le modèle complet de rapport de plage d’incidents, n’inventez pas d’incidents, n’ajoutez pas de données de test et ne basculez pas en mode A.

Gestion des erreurs

• Si une sonde, une requête curl, un appel VLM ou une requête /vss-query-analytics échoue, arrêtez le workflow et signalez le point de terminaison défaillant, le statut HTTP ou l’erreur de commande, ainsi que la prochaine étape de récupération utile. Ne fabriquez pas de rapport à partir de données partielles ou manquantes.
• Si la réponse VLM est vide, mal formée ou ne contient qu’un bloc de raisonnement, signalez ce problème de réponse et suggérez de vérifier l’état de préparation du modèle et les journaux avant de réessayer.
• Si l’URL d’un extrait ne peut pas être réécrite vers l’hôte/port public, omettez-la du rapport généré et indiquez que l’URL lisible par un navigateur n’a pas pu être produite.
• Pour le mode B, traitez les champs d’incident facultatifs manquants (info.reasoning, objectIds, URL du clip) comme des omissions dans le rapport, mais traitez l’absence d’identifiant, d’horodatage ou de catégorie comme une erreur de qualité des données qui doit être signalée.

Références croisées

• /vss-manage-video-io-storage — liste des capteurs, chronologies et URL de clip pour l’étape 1 du mode A.
• /vss-query-analytics — récupération d’incidents (et enrichissement du verdict / du raisonnement) pour le mode B, étape 2.
• /vss-ask-video — questions-réponses VLM ad hoc sur un clip unique (il ne s’agit pas d’un rapport structuré).
• /vss-summarize-video — utilisé par le mode A pour générer le corps du résumé lorsque le profil LVS est déployé ; le modèle de rapport (étape 4) est toujours renseigné ici.