Objectif

Déployer le service behavior-analytics en standalone avec l'entrypoint, la config et la calibration choisis par l'utilisateur.

Instructions

Suivez les tableaux 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 du haut vers le bas. La documentation de référence détaillée se trouve dans references/.

Exemples

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

nv-base validate skills/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 d'entrypoint, source de config, mises à jour dynamiques).

Limitations

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

Dépannage

Erreur : l'appel REST retourne une connexion refusée. Cause : le microservice cible n'est pas en cours d'exécution. Solution : vérifiez /docs ou /health ; redéployez via vss-deploy-profile ou la skill vss-deploy-* correspondante.
Erreur : HTTP 401/403 depuis les pulls NGC. Cause : NGC_CLI_API_KEY manquante ou expirée. Solution : docker login nvcr.io et réexportez la clé avant de réessayer.
Erreur : OOM du conteneur ou échec du chargement du modèle. Cause : mémoire GPU insuffisante pour le profil sélectionné. Solution : passez à une variante plus petite ou libérez des GPUs via docker compose down.

VSS Setup Behavior Analytics — Standalone

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

La procédure opérationnelle complète — tableau d'entrypoint, options source-config, types de calibration, contrat de fils de mise à jour dynamique, dépannage — est references/deploy-behavior-analytics-service.md. Cette 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 analytics, pas la pile complète »
« Changer l'entrypoint vers fusion_search / dev_example / analytics 3D / mv3dt »
« Utiliser ma propre config / calibration JSON behavior-analytics »
« Pointer behavior-analytics vers la config warehouse-3d (ou mv3dt) sans déployer le reste du profil warehouse »
« Config dynamique / calibration dynamique dans un behavior-analytics en cours d'exécution »

Prérequis

Checkout du repo avec $VSS_APPS_DIR pointant sur <repo>/deploy/docker/. Requis par les liaisons de volume du compose du service.
Identifiants NGC — $NGC_CLI_API_KEY défini pour que docker puisse tirer l'image. 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éessaye un nombre limité de fois, puis l'app se termine et restart: always recycle le conteneur. Le statut affichera Restarting (N) dans docker ps jusqu'à ce qu'un broker soit accessible. Avec un broker, la config dynamique / calibration dynamique sur mdx-notification deviennent disponibles.
Fichiers config / calibration optionnels sur disque si l'utilisateur apporte les siens.

Si un prérequis obligatoire échoue, mettez en avant la lacune avant de continuer.

Workflow

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

Choisir un entrypoint (analytics 2D / 3D / mv3dt, dev_example, fusion_search).
Choisir une config — fournie par le profil ou personnalisée.
Choisir une calibration — optionnelle ; fournie par le profil ou personnalisée ; sinon l'app attend une notification de calibration dynamique.
Décider si un broker est accessible ; si oui, les diriger vers les flows de mise à jour dynamique.

Les éditions de fichier compose, les diffs YAML, les commandes de déploiement + vérification et le tableau 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 opérationnel et un broker accessible, deux flows de mise à jour runtime sont disponibles — aucun ne nécessite un redéploiement :

Config dynamique

Publiez un message upsert (patch par clé) ou upsert-all (snapshot complet) sur le topic mdx-notification avec clé Kafka behavior-analytics-config et en-têtes :

event.type: upsert | upsert-all | request-config | ack
reference-id: video-analytics-api-<uuid> (originaire de web-api), behavior-analytics-<uuid> (réponse bootstrap), ou le littéral du type source (kafka / redis / mqtt) pour les upserts de publication directe.

Body : {"status": ..., "config": <patch>, "error": ...}.

L'écouteur valide chaque message au niveau de l'enveloppe (rejette les clés inconnues, config manquante, status/error malformés) et au niveau de la payload (rejette les sections interdites, mauvaises formes d'items). Les upserts réussis sont persistés sur disque, appliqués à tous les workers et ACK'd sur le topic.

Contrat de fil complet + sémantique d'ack : references/dynamic-config.md.

Calibration dynamique

Publiez sur le même topic avec clé Kafka calibration et en-têtes :

event.type: upsert-all (snapshot complet) | upsert (fusion par capteur) | delete (suppression par capteur)
timestamp: ISO-8601 UTC (YYYY-MM-DDTHH:MM:SS.fffZ).

Body : liste JSON de capteurs (et ROI / tripwires / homographies pour upsert-all).

L'écouteur valide contre le schéma AJV fourni avant persistance. Les violations de schéma enregistrent un avertissement calibration schema violation et sont supprimées — la calibration précédemment bonne reste chargée.

Contrat de fil complet + politique de validation par action : 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 manière recommandée de changer la configuration après que le conteneur soit en cours d'exécution, afin que l'opérateur n'ait pas à redéployer.

Règles de routage

Si l'utilisateur veut « la pile complète » (UI / agent / perception) : confiez-le à vss-deploy-profile avec profil warehouse (ou alerts). Ne lancez pas cette skill en parallèle.
Si l'utilisateur veut publier une mise à jour config / calibration runtime sur un conteneur déjà en cours d'exécution : guidez 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-le vers references/configuration.md, references/dynamic-config.md ou references/dynamic-calibration.md avant d'éditer le JSON.

bump:1