Construire un Agent Vision

build-vision-ai donne aux agents et aux développeurs des capacités de vision prêtes pour les agents via une pile applicative personnalisable et autonome construite sur le NVIDIA VSS Blueprint. Un développeur ou un agent ajoute la vision à son application en sélectionnant les capacités qu'il souhaite (intake guidée) ou en les décrivant en langage naturel, et le skill route vers un profil développeur validé — ou compose la plus petite couche delta par-dessus — et la déploie. Utilisez-le chaque fois que l'utilisateur souhaite que les capacités de vision soient composées pour lui : déployer un profil stock, étendre un déploiement en cours d'exécution, ou créer une petite combinaison personnalisée.

Deux entrées : intake guidée (énoncez une intention ouverte comme « construire un agent vision » / « ajouter des capacités de vision » et le skill vous guide à travers la sélection des capacités) ou piloté par prompt (nommez la capacité ou le profil directement). Les deux aboutissent au même flux de routage et de composition.

Références

• references/composition.md — règles de profil delta, sélection de Foundation, contrat des artefacts de build, résolution et validation.
• references/deployment.md — cycle de vie du déploiement Compose résolu.
• references/deployment_resolution.md — publication du déploiement de VSS_PUBLIC_URL, mappages de routes publiques et contrat d'endpoint consommé par les skills d'opération.
• references/teardown.md — nettoyage par défaut du volume du projet, teardown explicite préservant le cache, suppression des volumes obsolètes et nettoyage des données montées.
• references/prerequisites.md, references/credentials.md et references/ngc.md — vérifications du host, du runtime GPU, du firewall, des credentials, des droits et d'NGC.
• references/sizing.md — dimensionnement du profil développeur consolidé, placement de modèles, budgets GPU partagés, capacité de stream, ajustement d'utilisation et validation.
• references/edge.md — routage DGX Spark et Thor, budgétisation de la mémoire unifiée, gestion du cache et recettes de modèles edge.
• references/env-overrides.md, references/data-directory.md, references/readiness.md, references/troubleshooting.md et references/brev.md — vérifications de déploiement, préparation obligatoire du répertoire de données et conseils runtime spécifiques à l'environnement.
• references/profiles/ — capacités du profil développeur actuel, ensembles de services exacts, mappages de propriétaires, knobs, vérifications de readiness et sources.
• references/services/ — contrats propriétaire-capacité pour les clés de service, pairs requis, knobs d'environnement configurables et sources.

Routage

Mode Entrée (Étape 0)

Avant le routage, détectez le mode d'entrée — l'un des trois : piloté par prompt, workflow pré-construit ou build personnalisé. Les trois partagent les mêmes machines en aval (catalogue de profils, sélection de Foundation, composition delta, résolution et déploiement) ; le mode ne détermine que le point d'entrée du flux. Workflow pré-construit est un chemin rapide — il déploie l'ensemble de services autoritaire d'un profil développeur validé inchangé en mode stock (aucune delta de capacité), produisant toujours un _builds/<name>/ stock minimal pour le cycle de vie partagé valider → déployer → readiness → teardown — tandis que build personnalisé est une porte d'entrée guidée sur le mode delta.

Étape 0.0 — Détection du mode d'entrée

Classez la requête avant tout autre travail :

1. Une capacité concrète, un microservice, un profil ou un déploiement existant est nommé (par ex. « créer un profil pour le captioning dense en streaming », « ajouter une recherche agentique à mon déploiement de base », « déployer le profil alerts ») → piloté par prompt. Parsez les entrées et continuez à l'étape 1.
2. Une intention ouverte / générique / première utilisation / « quickstart » sans capacité extractible (par ex. « construire un agent vision », « ajouter des capacités de vision », « aidez-moi à démarrer », « déployez juste quelque chose »), ou aucune description de capacité du tout → ouvrez la porte d'entrée guidée (Q1 ci-dessous), qui mène au workflow pré-construit (la valeur par défaut recommandée) et offre le build personnalisé.
3. Ambigu → posez une question de désambiguïsation, ou basculez vers la porte d'entrée guidée (c'est sûr, réversible et explicite : l'utilisateur fait des sélections avant que quoi que ce soit soit généré ou déployé). Ne supposez jamais silencieusement une capacité ni ne reveniez à un profil par défaut.

Porte d'entrée guidée — Q1

Posez via AskUserQuestion (sélection unique). Ne générez ni ne déployez rien jusqu'à ce que l'utilisateur sélectionne ET confirme en aval (le prompt de déploiement pour le workflow pré-construit ; le diagramme d'architecture de l'étape 6 pour le build personnalisé).

Q1 — Point de départ. « Comment aimeriez-vous démarrer ? »

• Déployer un workflow développeur pré-construit (recommandé pour une première utilisation / quickstart) — Choisissez parmi un profil développeur VSS validé prêt à l'emploi. Chemin le plus rapide vers un système en cours d'exécution ; aucune composition requise. Déployé tel quel ; vous pouvez le personnaliser par la suite. → Q2a
• Déployer un blueprint industriel pré-construit — Perception multi-caméra Warehouse (2D RT-DETR ou 3D Sparse4D) avec analytique comportementale. Déployé tel quel. → Q2w
• Construire une configuration personnalisée — sélectionnez les capacités de vision spécifiques dont vous avez besoin et laissez le skill composer la plus petite couche delta pour elles. → Q2b

Mode : Workflow pré-construit (quickstart)

Le chemin de première utilisation recommandé. Déploie un profil développeur validé via mode stock — il garde le COMPOSE_PROFILES autoritaire du profil inchangé (aucune delta : aucune clé de profil ajoutée ou supprimée, aucune nouvelle composition de service), puis écrit et déploie les artefacts stock standards _builds/<name>/ comme tout autre build (étapes 5-9). Posez Q2a (sélection unique) : « Quel workflow pré-construit voulez-vous déployer ? » et mappez le choix au profil développeur :

Limite de quatre options. AskUserQuestion affiche au maximum quatre options par question (sélection unique ou multiple), donc Q2a doit rester sur les quatre profils développeur ci-dessus. Les deux modes du profil alerts ne sont pas des lignes de haut niveau séparées (ce serait une cinquième option et serait silencieusement supprimé) ; ils sont choisis dans un suivi, Q2a-mode, ci-dessous. Plus généralement, toute question nécessitant plus de quatre choix ne doit pas utiliser le widget AskUserQuestion — présentez les options en ligne dans la conversation et collectez une réponse tapée à la place (voir Q2b, qui le fait pour la multi-sélection de capacité).

Q2a-mode — uniquement quand l'utilisateur choisit Alerts (sélection unique) : « Quel mode d'alerte ? » Le profil développeur alerts est livré avec deux modes, sélectionnés par son knob MODE ; chacun a son propre ensemble COMPOSE_PROFILES enregistré dans dev-profile-alerts/overrides.env, donc les deux sont toujours des déploiements stock (aucune delta) :

Ce sont des profils développeur prédéfinis — le skill garde le COMPOSE_PROFILES autoritaire du profil inchangé (mode stock, correspondance exacte de l'étape 5) et suit le cycle de vie de build partagé (étapes 5-9). Pour Alerts, définissez le MODE du profil par Q2a-mode.

Personnaliser un workflow pré-construit → Build personnalisé. Après un déploiement pré-construit (ou à la place du déploiement), offrez : « Voulez-vous personnaliser ce workflow ? J'utiliserai <profil sélectionné> comme point de départ. » En cas de oui, basculez dans le build personnalisé, en ensemençant le profil sélectionné comme Foundation et en calculant une delta de capacité par-dessus (le profil lui-même n'est jamais modifié — il est seulement la ligne de base). Le build stock devient un build delta : les mêmes machines _builds/<name>/ portent maintenant les clés de profil ajoutées/supprimées et tout knob modifié.

Mode : Blueprint industriel pré-construit (warehouse)

Atteint de Q1 → blueprint industriel, ou quand la requête nomme warehouse directement. Développez la liste de services de la variante sélectionnée verbatim — warehouse est sélection de variante, pas composition, donc il n'y a pas de chemin delta. Lisez references/profiles/warehouse.md avant de poser des questions, et appliquez ses contraintes strictes en posant les questions, pas après.

Jusqu'à trois questions de sélection unique, chacune dans la limite de quatre options. Décrivez chaque option à partir du tableau Profile Service Set de warehouse.md ; ne reformulez pas ses listes de services ici, ou ce tableau dérive de celui qui est autoritaire :

Filtrez les options restantes plutôt que de valider les réponses après. Les deux filtres ci-dessous sont ceux de warehouse.md à énoncer ; c'est la source de vérité sur le pourquoi, et cette liste dit seulement quand les appliquer :

• Omettez bp_wh de Q2w-profile quand Q2w-mode est 3d — Contraintes strictes : bp_wh est 2D uniquement. Le laisser sélectionnable transforme un déploiement impossible en échec runtime tardif.
• Ignorez Q2w-size entièrement pour bp_wh — le tableau Profile Service Set ne liste aucune variante minimale pour celui-ci.
• Définissez SAMPLE_VIDEO_DATASET et NUM_STREAMS à partir de la variante choisie, pas du Foundation par défaut ; l'appairage dataset ↔ variante est une contrainte stricte.

Les réponses sélectionnent exactement une liste COMPOSE_PROFILES_WH_*. Enregistrez son nom dans FOUNDATION_VARIANT, développez-le verbatim dans COMPOSE_PROFILES, et continuez à l'étape 2 avec FOUNDATION=warehouse. Le cycle de vie partagé s'applique de là, avec quatre divergences warehouse : ignorez l'étape 4 (la references/composition.md est le flux delta), l'ensemble de services effectif de l'étape 5 est déjà fixé ci-dessus, l'étape 7 écrit également configurator.env, et l'étape 8 résout par references/profiles/warehouse.md plutôt que le flux delta dans references/composition.md.

Mode : Build personnalisé (guidé)

Pour un utilisateur qui souhaite une composition spécifique. Atteint de Q1 → build personnalisé, ou en personnalisant un workflow pré-construit (ensemencé avec ce profil comme Foundation). Posez Q2b (multi-sélection) : « Quelles capacités de vision voulez-vous ? (sélectionnez tout ce qui s'applique) » Chaque option mappe aux clés de profil de service canoniques possédées par un propriétaire de capacité sous references/services/. Video I/O + storage (VIOS) est toujours inclus — chaque profil en a besoin — ainsi que le pair cache redis partagé qui est livré avec la Foundation ; présentez ceux-ci comme informationnels, pas comme des choix. La pile ELK + Kafka message bus / indexing n'est pas inconditionnelle : elle est ajoutée uniquement quand une capacité sélectionnée est Kafka-backed ou Elasticsearch-indexed (voir la note sous le tableau), donc un build dense-captioning uniquement garde la plus petite delta. (Quand ensemencé d'un workflow pré-construit, les capacités de ce profil sont pré-cochées.)

Offrez à l'utilisateur exactement les capacités du tableau ci-dessous. Le contrat propriétaire de chaque ligne, les clés de profil de service canoniques et le profil Foundation le plus proche sont fixés — n'inventez pas d'options ou de clés en dehors. Parce que cette liste peut dépasser quatre lignes et AskUserQuestion plafonne une question à quatre options, ne posez pas Q2b via le widget AskUserQuestion — présentez ce tableau dans la conversation et faites répondre l'utilisateur avec les capacités qu'il souhaite (par nom ou numéro ; plusieurs autorisées). Revenez à une multi-sélection AskUserQuestion uniquement quand quatre capacités ou moins restent offrisables.

Toujours inclus — ne l'offrez pas comme choix : VIOS video I/O + storage (vios.md), l'ingress HAProxy (ingress.md) — fournissant une interface stable et unifiée à la pile VSS de sorte que les agents et les skills fassent référence à un endpoint unique plutôt qu'à des ports par service — plus le pair cache redis partagé livré avec la Foundation. Ajoutés conditionnellement, jamais offerts directement : la pile ELK + Kafka broker / indexing (elk.md) est tirée uniquement pour les capacités qui sont Kafka-backed ou Elasticsearch-indexed — recherche sémantique (vss-search-analytics-2d-fusion + rtvi-embed), alerte/vérification en temps réel (alert-bridge nécessite Kafka + Elasticsearch), ou résumé vidéo quand son backend Kafka/ES event ou DB est activé ; RT-VLM ajoute Kafka uniquement quand RTVI_VLM_KAFKA_ENABLED=true. Un build dense-captioning uniquement sur base n'ajoute donc aucun ELK/Kafka, préservant le contrat plus petite-delta. Le backend de modèle LLM NIM (llm-nim.md) et VLM NIM (vlm-nim.md) sont de même activés uniquement quand une capacité sélectionnée nécessite un modèle local (RT-VLM intégré est le propriétaire rt-vlm.md, pas le backend VLM NIM).

Règles pour la multi-sélection :

• Offrez exactement les lignes du tableau dont le contrat propriétaire existe sous references/services/ (toutes les lignes sont présentes sur cette branche) ; affichez toute capacité en attente désactivée avec une courte note « pas encore disponible ». N'offrez jamais un propriétaire fondationnel ou de backend de modèle comme choix — n'offrez pas silencieusement une capacité que le skill ne peut pas résoudre.
• Nécessitez au moins une capacité — les services fondationnels seuls ne sont pas un agent vision.
• Les sélections multiples composent dans un déploiement (par ex. captioning + alerting, ou captioning + detection).

Après Q2b, les capacités sélectionnées sont l'ensemble des capacités requises. Sélectionnez le profil développeur actuel le plus proche comme Foundation, calculez la plus petite delta (ajoutez ou supprimez uniquement les clés de profil de service canoniques, modifiez uniquement les knobs demandés), et continuez à l'étape 2. C'est le mode delta (selon le tableau de routage) ; _builds/<name>/ est créé ici.

Étapes

1. Détectez le mode d'entrée (voir Mode Entrée (Étape 0) ci-dessus). Puis parsez la requête et toute spécification d'évaluation en capacités requises, capacités exclues, knobs de configuration et vérifications de succès observables. Le build personnalisé fournit l'ensemble des capacités directement via multi-sélection ; le workflow pré-construit garde l'ensemble de services autoritaire d'un profil nommé inchangé (mode stock).
2. Lisez le fichier correspondant sous references/profiles/ et references/sizing.md. En mode delta, comparez les quatre profils développeur et sélectionnez exactement une Foundation ; demandez uniquement quand deux sont également plausibles. warehouse n'entre jamais en concurrence dans cette comparaison — il est sélectionné uniquement par une requête warehouse explicite. Lisez references/edge.md pour DGX Spark ou Thor.
3. Avant la résolution ou le déploiement, exécutez les vérifications applicables de references/prerequisites.md, references/credentials.md et references/ngc.md. Lisez les références d'environnement et Brev le cas échéant.
4. Lisez references/composition.md et uniquement les fichiers de propriétaire de capacité sous references/services/ requis par la requête.
5. Déterminez l'ensemble de services effectif. Pour une correspondance stock exacte, gardez son ensemble autoritaire inchangé. Sinon, calculez la plus petite delta à partir du COMPOSE_PROFILES exact de la Foundation : ajoutez ou supprimez uniquement les clés de profil de service canoniques et modifiez uniquement les knobs d'environnement demandés. Si cette passe unique laisse un bloqueur que les règles ne peuvent pas résoudre (une capacité non mappée ou ambiguë, une Foundation en égalité, un conflit singleton ou une contradiction demandée/exclue), appliquez la clarification gate dans references/composition.md : posez une question structurée, puis résolvez sur la réponse ; ne relancez jamais la même résolution ni ne deviez le bloquer.
6. Avant d'écrire les artefacts delta ou de démarrer un déploiement stock ou delta, présentez un diagramme d'architecture compact dans la conversation. Montrez la Foundation, les propriétaires de capacité ajoutés et supprimés et les clés de service, les flux de données et topics principaux, les endpoints externes et le placement GPU/modèle. Ne sauvegardez pas le diagramme comme un artefact de build.
7. Pour tout build stock ou delta, écrivez _builds/<name>/override.env, _builds/<name>/compose.yml et _builds/<name>/resolved.yml. Mettez la Foundation, l'intégralité des COMPOSE_PROFILES effectifs, les valeurs de chemin/host requises au build local et uniquement les valeurs d'environnement qui sont personnalisées ou transitivement dérivées d'une personnalisation dans override.env ; ne copiez pas les defaults inchangés de Foundation comme les ports stock ou les knobs de modèle. Faites que compose.yml inclue le root deploy/docker/compose.yml plus uniquement les fichiers Compose de service minimales modifiés ou nouveaux, le cas échéant. Traitez <name> uniquement comme une étiquette de système de fichiers ; n'ajoutez jamais au COMPOSE_PROFILES.
8. Générez resolved.yml avec docker compose config en utilisant les couches d'environnement ordonnées dans references/composition.md — ou, pour warehouse, les couches d'environnement et le pipeline de résolution dans references/profiles/warehouse.md — normalisez les dépendances optionnelles en attente avec scripts/normalize_resolved_yml.py, puis exécutez la gate de vérification/création obligatoire dans references/data-directory.md sur chaque build, déployer ou non — elle bloque un build warehouse dont ${VSS_DATA_DIR} n'est pas le bundle app-data fourni — elle prépare le ${VSS_DATA_DIR} externe que toute future mise en place a besoin (cet agent ou une docker compose up exécutée manuellement) et ne touche jamais l'arborescence du repo. Quand l'ensemble COMPOSE_PROFILES effectif inclut une clé de perception RT-CV (perception-alerts, perception-2d-fusion), aucun staging de détecteur côté host ou agent n'est requis : le conteneur RT-CV télécharge le détecteur ONNX au premier démarrage (phase ds-start 0) de son models-download.json monté dans le ${VSS_DATA_DIR}/models accessible en écriture que la gate vient de créer. Rejetez les placeholders obsolètes et les sources bind enregistrées invalides avec scripts/validate_resolved_yml.py ; si la validation trouve une vraie interpolation Compose ${...} non résolue, ajoutez uniquement les valeurs concrètes manquantes à override.env et régénérez avant de continuer. Ne comptez pas les variables de shell conteneur échappées comme $${HOST_IP} comme une interpolation Compose non résolue. Validez les clés sélectionnées, les services, les images, les pairs requis, le placement GPU, l'utilisation et les vérifications de succès demandées contre ce fichier exact.
9. Si le déploiement a été demandé, déployez le _builds/<name>/resolved.yml exact validé à l'étape précédente, rafraîchissez ses images de registry même quand leurs tags existent déjà localement, utilisez references/readiness.md avec les vérifications de profil correspondantes, et suivez references/deployment.md pour le cycle de vie Compose résolu. Quand une source doit être provisionnée dans le build déployé (un build headless n'en enregistre aucun au bring-up), résolvez les ports consommateur et confirmez que le build est headless (pas de vss-agent) de resolved.yml, puis suivez vss-manage-video-io-storage references/provision-vios-source.md — sauf pour warehouse, qui enregistre ses propres sources automatiquement. Quand une requête de tour d'aller-retour de recherche est alors demandée contre le build déployé, exécutez vss configure --base-url <build-origin> (la http://$HOST_IP:$HAPROXY_HOST_PORT frontale) via le point d'entrée project-local (uv run --project <repo>/services/agent --no-dev vss …, per references/deployment_resolution.md) — pas un vss brut — puis déférez entièrement à vss-search-archive pour la décomposition, le mode et la requête elle-même. Pour arrêter ou nettoyer, suivez references/teardown.md : supprimez les volumes du projet par défaut et préservez les caches de modèle uniquement quand l'utilisateur le demande explicitement.