Objectif

Déployer le service REST video-analytics-api en mode standalone avec la configuration et le bind data-log de votre choix. Le service expose le port 8081 et /livez uniquement après qu'Elasticsearch, le insertion-timestamp-pipeline, et les exigences Kafka configurées soient prêts.

Instructions

Suivez les tableaux de routage et les workflows étape par étape ci-dessous. Chaque section se terminant par workflow, quick start, ou flow doit ê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 de bout en bout se trouvent dans 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-video-analytics-api --agent-eval

Un démarrage minimal en mode 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 configuration, bind data-log, dépendances d'infrastructure, endpoints REST). Pour la référence JSON de configuration champ par champ, consultez references/configuration.md.

Limitations

Nécessite que le profil VSS correspondant / le microservice 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 une connexion refusée. 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 depuis les 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 : conteneur OOM ou le modèle ne se charge pas. Cause : mémoire GPU insuffisante pour le profil sélectionné. Solution : passez à 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 upstream video-analytics-api), non pas dans le cadre de la pile de schéma complet.

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

Quand utiliser

« Déployer video analytics api » / « lancer video-analytics-api en standalone »
« Je veux juste exécuter l'API REST, pas la pile complète »
« Utiliser ma propre configuration 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.
Identifiants NGC — $NGC_CLI_API_KEY défini pour que docker puisse extraire l'image. Consultez references/ngc-api-key-registry-login.md.

Note de gestion sécurisée pour NGC_CLI_API_KEY : cette clé est un credential de longue durée qui extrait 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 jamais dans /tmp. Lisez-la de manière interactive (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 tous les fichiers .env dérivés avec umask 077 + chmod 600, ajoutez-les à .gitignore, et faites pivoter la clé selon un calendrier 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-la pivoter immédiatement.
Runtime Docker — Docker Engine 28.3.3 avec plugin Docker Compose v2.39.1+. Vérifiez avec docker --version et docker compose version.
Elasticsearch et pipeline d'ingestion — l'endpoint dans elasticsearch.node doit être accessible et contenir insertion-timestamp-pipeline. La seule disponibilité du port Elasticsearch est insuffisante : l'API attend délibérément ce pipeline avant de binder le port 8081. Lors de l'utilisation du compose infra, démarrez à la fois elasticsearch et elasticsearch-init-container.
Kafka est optionnel uniquement s'il est désactivé dans la config. Avec kafka.brokers: [] ou null, l'API ignore Kafka. Avec des brokers configurés, elle attend avant d'écouter jusqu'à ce que les topics mdx-notification, mdx-amr, et au moins un mdx-rtls* existent. La config livrée avec le service active Kafka, donc choisissez soit une config sans broker soit provisionnez ces topics.
$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 fichier comme les images d'étalonnage. Définissez le répertoire sur un chemin d'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, signalez la lacune avant de poursuivre.

Workflow

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

Choisir une configuration — par défaut intégrée à l'image, livrée avec le service, ou personnalisée.
Décider si un volume data-log est nécessaire pour les uploads de fichiers.
Confirmer la disponibilité des dépendances — Elasticsearch plus insertion-timestamp-pipeline ; et, si Kafka est configuré, les topics requis.
Déployer + vérifier avec docker compose up et contrôle de santé.

Les éditions du fichier compose, les options de config, les commandes de déploiement + vérification, le tableau d'endpoints API REST et le tableau 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 le tableau d'endpoints REST et les notes de dépendances runtime.

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

Lorsque Kafka est configuré, le conteneur ne devient actif que lorsque son broker et les topics requis sont disponibles. Une fois qu'il est actif, trois capacités supplémentaires sont disponibles :

Config dynamique

L'API agit en tant que producteur pour les mises à jour de config dynamique. Lorsqu'un opérateur POSTe sur /config, l'API publie un message upsert au topic mdx-notification avec la clé Kafka behavior-analytics-config. Le conteneur behavior-analytics en aval consomme cela et envoie un ACK. L'API gère également le flux de bootstrap — lorsque behavior-analytics démarre, il publie un message request-config, et l'API répond par upsert-all contenant la dernière config vérifiée d'Elasticsearch.

La validation côté consumer, la sémantique ACK et le contrat de câblage 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 d'étalonnage 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 à l'étalonnage actif.

La validation côté consumer 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) : remettez à vss-deploy-profile avec le profil warehouse (ou alerts). N'exécutez pas cette skill en parallèle.
Si l'utilisateur veut déployer le pipeline analytics (création de comportement, détection d'incidents) : remettez à vss-setup-behavior-analytics.
Si l'utilisateur veut publier une mise à jour de config runtime / étalonnage via l'API REST : confirmez que Kafka est accessible, puis utilisez les endpoints /config ou d'étalonnage et pointez-le vers les références de mise à jour dynamique behavior-analytics pour le contrat de câblage du consumer.
Si l'utilisateur veut comprendre le contrat de câblage config dynamique / étalonnage dynamique du côté du consumer (behavior-analytics) : pointez-le 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 API REST : le tableau d'endpoints de la référence de déploiement couvre ce qui est disponible. Pour la spécification OpenAPI complète, consultez src/app/specification/openapi.json dans le repo video-analytics-api.