Objectif

Déployer le service d'analytics comportementale en standalone avec le point d'entrée, la config et l'étalonnage choisis par l'utilisateur.

Instructions

Suivez les tables de routage et les workflows étape par étape ci-dessous. Chaque section qui se termine 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/.

Exemples

Les exemples end-to-end complets se trouvent sous evals/ (chaque manifest *.json contient un scénario exécutable). Exécutez une évaluation Tier-3 pour les rejouer :

nv-base validate skills/deployment/vss-setup-behavior-analytics --agent-eval

Un démarrage minimal en standalone ressemble à :

cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
docker compose -f services/analytics/behavior-analytics/compose.yml up -d vss-behavior-analytics-base

Suivez references/deploy-behavior-analytics-service.md pour le workflow complet (choix du point d'entrée, source de config, mises à jour dynamiques).

Limitations

Pas d'API HTTP. C'est un processeur de stream broker — il lit et écrit dans Kafka / Redis Streams / MQTT et n'expose aucun endpoint REST, donc il n'y a rien à curl et pas de /health à sonder. Vérifiez via les logs du conteneur et les topics de sortie.
CPU uniquement. Il ne charge aucun modèle et ne réserve aucun GPU (gpu_count: 0 dans les evals de ce skill), donc la mémoire GPU et les rate-limits NIM ne sont pas des contraintes ici.
Au moins un processeur doit être activé, et l'oubli est silencieux. Avec chaque numWorkersFor* à 0, le runner enregistre FATAL - Error in app: No processors registered, ferme ses listeners et retourne — le processus se termine avec le code 0, donc pour tout ce qui surveille les codes de sortie, cela ressemble à un arrêt propre. Seul le log le distingue.
Une destination omise dans la config est une sortie désactivée, pas une erreur. Le sink enregistre No destination configured for '<key>'; output for it is disabled une fois par clé et abandonne le reste, donc un topic manquant ressemble à un stream vide plutôt qu'à une défaillance.
Un producteur de comportement par déploiement. Deux instances produisant des comportements pour les mêmes capteurs écrivent chaque comportement deux fois, depuis des processus avec un état indépendant. Rien ne détecte cela.

Dépannage

Erreur : le conteneur redémarre en boucle immédiatement ; le log affiche FATAL - Config file ... contains invalid JSON ou ... has invalid structure. Cause : la config montée est malformée ou échoue la validation AppConfig. Solution : corrigez le JSON / schéma — l'app appelle exit(1), donc la politique de redémarrage de compose la fait cycler indéfiniment.
Erreur : le conteneur s'arrête presque immédiatement avec le statut Exited (0) et le log se termine par FATAL - Error in app: No processors registered in app .... Cause : chaque numWorkersFor* est 0 (la composite_config.json livrée l'est volontairement). Solution : définissez le nombre de workers pour les capacités que vous voulez. Notez que le code de sortie est 0, donc une politique restart: on-failure ne le cyclera pas — il reste simplement arrêté.
Erreur : le conteneur affiche Restarting (N) et le log se termine par une erreur de connexion Kafka/Redis. Cause : aucun broker accessible. Le client réessaie un nombre limité de fois, puis le worker lève et le scheduler arrête l'app entière. Solution : démarrez le broker, ou attendez-vous à la boucle de redémarrage jusqu'à ce qu'un existe.
Erreur : un topic attendu reste vide. Cause : soit la destination n'est pas définie dans la config (cherchez l'avertissement No destination configured unique), soit le processeur qui l'écrit a 0 workers. Solution : définissez le topic et réglez le nombre de workers.
Erreur : le log affiche Error reading calibration type from ...: defaulting to IMAGE. Cause : --calibration a été omis ou illisible. Solution : ce n'est pas fatal — l'app s'exécute avec étalonnage image, ce qui change silencieusement la sémantique des coordonnées. Montez un étalonnage si vous aviez l'intention d'un déploiement cartésien ou géo.

VSS Setup Behavior Analytics — Standalone

Déployez uniquement le conteneur vss-behavior-analytics (le pipeline d'analytics spatial-AI du repo behavior-analytics upstream), non pas comme partie de la pile complète du blueprint warehouse.

La procédure opérationnelle complète — table de points d'entrée, options de source config, types d'étalonnage, contrat de fil de mise à jour dynamique, dépannage — est references/deploy-behavior-analytics-service.md. Ce SKILL.md gère uniquement le routage et les prérequis.

Quand l'utiliser

« Déployer behavior analytics » / « exécuter behavior-analytics en standalone »
« Je veux juste exécuter l'analytics, pas la pile complète »
« Changer le point d'entrée vers search_and_alerts / analytics 3D / mv3dt »
« Utiliser ma propre config behavior-analytics / JSON d'étalonnage »
« Pointer behavior-analytics vers la config warehouse-3d (ou mv3dt) sans démarrer le reste du profil warehouse »
« Config / étalonnage dynamique dans un behavior-analytics en cours d'exécution »

Quand NE PAS l'utiliser

Ce skill déploie un conteneur. Passez plutôt la main quand la demande porte sur :

La pile complète (UI, agent, perception, stockage) — vss-deploy-profile. Ne lancez pas les deux en parallèle ; elle possède behavior-analytics comme partie du profil.
Produire les frames que ce service consomme — detection/tracking est en amont : vss-deploy-detection-tracking-2d ou -3d. Ce service analyse mdx-raw ; il ne le crée pas.
Générer un fichier d'étalonnage — vss-generate-video-calibration. Ce skill ne fait que monter un fichier.
Lire la sortie — les incidents, métriques et requêtes de capteurs sont vss-query-analytics ; les workflows d'alerte et verdicts de vérification sont vss-manage-alerts.
L'API REST en face des données — c'est un service différent : vss-setup-video-analytics-api. Behavior-analytics n'expose aucun endpoint HTTP.

Prérequis

Checkout du repo avec $VSS_APPS_DIR pointant vers <repo>/deploy/docker/. Requis par les liaisons de volume de la compose du service.
Accès au registry — aucun requis pour l'image par défaut : ghcr.io/nvidia-ai-blueprints/vss/vss-behavior-analytics est publique, donc docker pull fonctionne sans authentification. Vous n'avez besoin d'identifiants que si vous remplacez VSS_CONTAINER_REGISTRY par NGC — voir references/ngc-api-key-registry-login.md.
Runtime Docker — Docker Engine 28.3.3 avec plugin Docker Compose v2.39.1+. Vérifiez avec docker --version et docker compose version.
Broker optionnel (Kafka / Redis Streams / MQTT). Le conteneur démarre correctement sans — le client Kafka réessaie un nombre limité de fois, puis l'app se termine et restart: always cycla le conteneur. Le statut affichera Restarting (N) dans docker ps jusqu'à ce qu'un broker soit accessible. Avec un broker, la config dynamique / l'étalonnage dynamique sur mdx-notification deviennent disponibles.
Fichiers config / étalonnage optionnels sur disque si l'utilisateur apporte les siens.

Si un prérequis obligatoire échoue, signalez la lacune avant d'aller plus loin.

Workflow

Remettez à l'utilisateur references/deploy-behavior-analytics-service.md et parcourez ses étapes dans l'ordre :

Choisissez un point d'entrée (analytics 2D / 3D / mv3dt, search_and_alerts).
Choisissez une config — livrée avec le profil ou personnalisée.
Choisissez un étalonnage — optionnel ; livré avec le profil ou personnalisé ; sinon l'app attend une notification d'étalonnage dynamique.
Décidez si un broker est accessible ; si oui, pointez-les vers les flows de mise à jour dynamique.

Les édits de compose-file, les diffs YAML, les commandes de déploiement + vérification, et la table de dépannage vivent tous dans cette référence — ne les dupliquez pas ici.

Mises à jour dynamiques (runtime, sans redémarrage)

Une fois le conteneur en place et un broker accessible, deux flows de mise à jour runtime sont disponibles — aucun ne nécessite un redéploiement :

Config dynamique — patcher app[] / sensors[] au runtime en publiant sur mdx-notification sous la clé Kafka behavior-analytics-config. Seules les clés de la liste blanche s'appliquent ; tout le reste est rejeté dans l'ack plutôt que silencieusement ignoré. Les upserts réussis sont persisted sur disque, appliqués à chaque worker, et ACK'd en retour. Forme du message, headers, sémantique d'ack et liste blanche : references/dynamic-config.md.

Étalonnage dynamique — remplacer les capteurs / ROIs / tripwires / homographies au runtime sous la clé Kafka calibration sur le même topic. Les payloads sont validés selon le schéma avant que quoi que ce soit ne soit persisté, et une violation est abandonnée avec un avertissement calibration schema violation, laissant l'étalonnage précédemment-bon chargé. Forme du message, politique de validation par action et la caveat no-ack : references/dynamic-calibration.md.

Les deux flows vivent entièrement sur le broker — le producteur peut être video-analytics-api, votre propre script, ou tout client Kafka qui reflète la forme du fil. C'est la façon recommandée de changer la configuration après le démarrage du conteneur, donc l'opérateur n'a pas à redéployer.

Règles de routage

Si l'utilisateur veut « la pile complète » (UI / agent / perception) : passez la main à vss-deploy-profile avec profil warehouse (ou alerts). Ne lancez pas ce skill en parallèle.
Si l'utilisateur a besoin de plier behavior-analytics dans un déploiement composé/multi-service — quels topics Kafka il consomme et émet, et comment il se connecte aux producteurs/consommateurs autour : voir le contrat d'intégration dans references/integrate-behavior-analytics-service.md.
Si l'utilisateur veut publier une mise à jour de config / étalonnage runtime vers un conteneur déjà en cours d'exécution : parcourez la section Mises à jour dynamiques. Les deux flows ont besoin d'un broker accessible.
Si l'utilisateur décrit un changement de comportement behavior-analytics qu'il veut valider (nouveau type d'incident, nouvelle règle ROI, nouveau capteur) : pointez-les vers references/configuration.md, references/dynamic-config.md, ou references/dynamic-calibration.md avant d'éditer le JSON.