Objectif

Déployer le service REST video-analytics-api en standalone avec la configuration, le bind de data-log et la connectivité Elasticsearch / Kafka choisis par l'utilisateur.

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/.

Exemples

Les exemples complets travaillés 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-video-analytics-api --agent-eval

Un démarrage minimal en standalone ressemble à :

cd $REPO/deploy/docker
export VSS_APPS_DIR=$(pwd)
export VSS_DATA_DIR=${VSS_DATA_DIR:-/tmp/vss-data}
mkdir -p "$VSS_DATA_DIR/data_log/vss_video_analytics_api"
docker compose -f services/analytics/video-analytics-api/compose.yml up -d vss-video-analytics-api
curl -sf http://localhost:8081/livez

Suivez references/deploy-video-analytics-api-service.md pour le workflow complet (source de config, bind de data-log, dépendances d'infrastructure, endpoints REST). Pour la référence JSON config champ par champ, consultez references/configuration.md.

Limitations

Exige 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, 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 connection refused. Cause : microservice cible non actif. Solution : sondez /docs ou /health ; redéployez via vss-deploy-profile ou la skill vss-deploy-* correspondante.
Erreur : HTTP 401/403 lors des pulls NGC. Cause : NGC_CLI_API_KEY manquante/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 : basculez vers une variante plus petite ou libérez les GPUs via docker compose down.

VSS Setup Video Analytics API — Standalone

Déployez uniquement le conteneur vss-video-analytics-api (l'API REST Node.js du repo video-analytics-api en amont), pas comme partie de la pile blueprint warehouse complète.

Le walkthrough opérationnel complet — options de source de config, comportement du volume data-log, dépendances d'infrastructure, endpoints REST API, déploiement + vérification, dépannage — se trouve dans references/deploy-video-analytics-api-service.md. La référence JSON config champ par champ se trouve dans references/configuration.md. Ce SKILL.md ne traite que du routage et des prérequis.

Quand l'utiliser

« Déployer video analytics api » / « exécuter video-analytics-api en standalone »
« Je veux juste exécuter l'API REST, pas la pile complète »
« Utiliser ma propre config video-analytics-api »
« Pointer l'API vers un Elasticsearch / Kafka différent »
« Démarrer l'API sans Kafka » / « exécuter l'API sans broker »
« Vérifier quels endpoints REST sont disponibles »

Prérequis

Checkout du repo avec $VSS_APPS_DIR pointant sur <repo>/deploy/docker/. Requis par les binds de volume du compose du service.
Credentials NGC — $NGC_CLI_API_KEY défini pour que docker puisse tirer l'image. Voir references/ngc-api-key-registry-login.md.

Note de manipulation sécurisée pour NGC_CLI_API_KEY : cette clé est une credential de longue durée qui tire toutes les images privées NVIDIA disponibles pour votre org NGC. Ne commitez jamais la clé, ne la collez jamais dans le chat, ne la stockez pas dans /tmp. Lisez-la interactivement (read -rs NGC_CLI_API_KEY) ou chargez-la depuis votre gestionnaire de secrets (Vault, AWS Secrets Manager, sealed-secrets) au moment du déploiement. Écrivez tout fichier .env dérivé avec umask 077 + chmod 600, ajoutez-les à .gitignore, et faites pivoter la clé sur un cycle défini et après chaque décommissionnement d'hôte. Si elle a jamais été exposée (snapshot d'hôte, écran partagé, pièce jointe de ticket), faites pivoter immédiatement.
Runtime Docker — Docker Engine 28.3.3 avec le plugin Docker Compose v2.39.1+. Vérifiez avec docker --version et docker compose version.
Elasticsearch — doit être accessible à l'URL configurée dans elasticsearch.node. Le serveur ping ES au démarrage ; s'il est inaccessible, il s'arrête (et restart: always le ramène). Si vous avez besoin de démarrer aussi ES, utilisez le compose infra : docker compose -f services/infra/compose.yml up -d elasticsearch.
Broker Kafka optionnel. L'API peut s'exécuter sans Kafka. Si vous souhaitez un déploiement silencieux sans broker, utilisez la config intégrée à l'image ou une config personnalisée avec kafka.brokers: [] ; le compose livré avec le service pointe vers localhost:9092, les fonctionnalités dépendantes de Kafka (config dynamique, calibration dynamique, RTLS/AMR) échoueront jusqu'à ce qu'un broker soit accessible.
$VSS_DATA_DIR pour le compose par défaut. Le compose de base bind-monte $VSS_DATA_DIR/data_log/vss_video_analytics_api pour la gestion des uploads multipart et les assets sauvegardés comme les images de calibration. Définissez le répertoire sur un chemin hôte inscriptible et pré-créez-le, ou supprimez ce mount si les uploads d'images ne sont pas nécessaires.

Si un prérequis obligatoire échoue, surfacez l'écart avant d'aller plus loin.

Workflow

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

Choisir une config — image-baked default, service-shipped, ou personnalisée.
Décider si un volume data-log est nécessaire pour les uploads de fichiers.
Confirmer les dépendances d'infrastructure — Elasticsearch (requis), Kafka (optionnel).
Déployer + vérifier avec docker compose up et health check.

Les édits du fichier compose, les options de config, les commandes déploiement + vérification, la table d'endpoints REST API et la table de dépannage se trouvent tous dans cette référence — ne les dupliquez pas ici.

Référence Endpoint

Utilisez references/deploy-video-analytics-api-service.md pour la table d'endpoints REST et les notes de dépendances runtime.

Fonctionnalités dépendantes de Kafka (runtime, nécessite un broker)

Une fois le conteneur actif et un broker Kafka accessible, trois capacités supplémentaires sont disponibles :

Config dynamique

L'API agit comme le producteur des mises à jour de config dynamique. Quand un opérateur POSTe sur /config, l'API publie un message upsert sur le topic mdx-notification avec la clé Kafka behavior-analytics-config. Le conteneur behavior-analytics en aval consomme ceci et ACK en retour. L'API gère aussi le flux bootstrap — quand behavior-analytics démarre, il publie un message request-config, et l'API répond avec upsert-all contenant la dernière config vérifiée depuis Elasticsearch.

La validation côté consommateur, la sémantique ACK et le contrat wire complet sont documentés dans la référence dynamic-config de vss-setup-behavior-analytics.

Calibration dynamique

L'API produit des notifications de mise à jour de calibration sur mdx-notification avec la clé Kafka calibration. Supporte upsert-all (snapshot complet), upsert (fusion par capteur) et delete (suppression par capteur). Le conteneur behavior-analytics en aval consomme celles-ci et les applique à la calibration en direct.

La validation côté consommateur et la politique par action sont documentées dans la référence dynamic-calibration de vss-setup-behavior-analytics.

RTLS / AMR

L'API consomme les messages de localisation en temps réel (mdx-rtls) et AMR (mdx-amr) depuis Kafka et les expose via des endpoints REST.

Règles de routage

Si l'utilisateur veut « la pile complète » (UI / agent / perception) : transmettez à vss-deploy-profile avec profile warehouse (ou alerts). Ne lancez pas cette skill en parallèle.
Si l'utilisateur veut déployer le pipeline d'analytics (création de comportement, détection d'incident) : transmettez à vss-setup-behavior-analytics.
Si l'utilisateur veut publier une mise à jour de config / calibration runtime via l'API REST : confirmez que Kafka est accessible, puis utilisez les endpoints /config ou calibration et pointez-les vers les références de mise à jour dynamique behavior-analytics pour le contrat wire du consommateur.
Si l'utilisateur veut comprendre le contrat wire config dynamique / calibration dynamique du côté du consommateur (behavior-analytics) : pointez-les vers les références dynamic-config et dynamic-calibration de vss-setup-behavior-analytics.
Si l'utilisateur veut interroger ou interagir avec les endpoints REST API : la table d'endpoints de la référence de déploiement couvre ce qui est disponible. Pour la spécification OpenAPI complète, voir src/app/specification/openapi.json dans le repo video-analytics-api.