VSS Frag — Analyse vidéo avec Enterprise RAG

Générez des rapports de synthèse vidéo en utilisant l'extension video_search_frag de VSS. Cette compétence ajoute la récupération de connaissances Enterprise RAG (Milvus) et la collecte guidée de paramètres en boucle humaine (HITL) au-dessus de l'agent VSS de base.

Exécutez toujours les commandes curl vous-même ; ne demandez jamais à l'utilisateur de les exécuter.

Déploiement de l'extension Frag

L'extension frag superpose les outils Enterprise RAG et HITL LVS à l'image de l'agent VSS de base. Le déploiement consiste en deux étapes : un build Docker suivi d'un compose up.

Variables d'environnement : Toutes les commandes utilisent les valeurs du fichier .env à deployments/developer-workflow/dev-profile-lvs/.env. Modifiez-le avant le déploiement. Variables clés : HOST_IP, VSS_AGENT_PORT (par défaut 8000), NGC_CLI_API_KEY, NVIDIA_API_KEY, ENTERPRISE_RAG_*.

Étape 1 : Configurer le fichier .env

nano deployments/developer-workflow/dev-profile-lvs/.env

Définissez au minimum :

HOST_IP — l'IP de votre machine (hostname -I | awk '{print $1}')
NGC_CLI_API_KEY — depuis https://ngc.nvidia.com/
NVIDIA_API_KEY — depuis https://build.nvidia.com/
VSS_AGENT_CONFIG_FILE=./configs/video_search_frag/config.yml
ENTERPRISE_RAG_VDB_ENDPOINT — votre endpoint Milvus (ex. tcp://127.0.0.1:19530)
ENTERPRISE_RAG_COLLECTION_NAMES — votre nom de collection Milvus

Étape 2 : Se connecter au registre NGC

echo "$NGC_CLI_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin

Étape 3 : Construire l'image de l'agent de base

cd agent
docker build -f docker/Dockerfile -t vss-agent-base .

Étape 4 : Construire l'image de l'extension frag

docker compose \
  -f app/video_search_frag/docker-compose.yml \
  --env-file ../deployments/developer-workflow/dev-profile-lvs/.env \
  build

Ceci produit vss-agent-frag:latest — l'agent de base étendu avec video_search_frag (Enterprise RAG, HITL LVS, génération de rapports PDF).

Étape 5 : Déployer avec docker compose

docker compose \
  -f app/video_search_frag/docker-compose.yml \
  -f ../deployments/agents/agent_ui/compose.yml \
  --env-file ../deployments/developer-workflow/dev-profile-lvs/.env \
  --profile bp_developer_lvs_2d \
  up -d

Deux flags -f : le compose frag définit vss-agent, le compose UI définit metropolis-vss-ui. Ils se fusionnent en un seul déploiement.

Étape 6 : Vérifier le déploiement

# Vérifier que les conteneurs tournent
docker ps --format "table {{.Names}}\t{{.Status}}"

# Vérification de santé
curl -sf --max-time 5 "http://${HOST_IP}:${VSS_AGENT_PORT:-8000}/health" >/dev/null \
  && echo "VSS frag agent is running" \
  || echo "VSS frag agent is NOT reachable"

Arrêter

docker compose \
  -f app/video_search_frag/docker-compose.yml \
  -f ../deployments/agents/agent_ui/compose.yml \
  --env-file ../deployments/developer-workflow/dev-profile-lvs/.env \
  --profile bp_developer_lvs_2d \
  down

Reconstruire après des modifications de code

Toujours faire down puis reconstruire et up — ne jamais faire up -d seul après des modifications.

docker compose \
  -f app/video_search_frag/docker-compose.yml \
  --env-file ../deployments/developer-workflow/dev-profile-lvs/.env \
  build

docker compose \
  -f app/video_search_frag/docker-compose.yml \
  -f ../deployments/agents/agent_ui/compose.yml \
  --env-file ../deployments/developer-workflow/dev-profile-lvs/.env \
  --profile bp_developer_lvs_2d \
  down

docker compose \
  -f app/video_search_frag/docker-compose.yml \
  -f ../deployments/agents/agent_ui/compose.yml \
  --env-file ../deployments/developer-workflow/dev-profile-lvs/.env \
  --profile bp_developer_lvs_2d \
  up -d

Quand utiliser

L'utilisateur souhaite générer une synthèse vidéo ou un rapport via le pipeline frag
L'utilisateur demande d'analyser une vidéo avec contexte de connaissance Enterprise RAG
L'utilisateur mentionne « frag », « enterprise RAG » ou « rapport enrichi de connaissance »

Quand ne pas utiliser

Requêtes simples de compréhension vidéo (utiliser la compétence video-understanding)
Synthèse LVS directe sans HITL (utiliser la compétence video-summarization)
Tâches de déploiement (utiliser la compétence deploy)
Alertes en temps réel (utiliser la compétence alerts)

Flux de travail : Générer un rapport LVS avec Enterprise RAG

Étape 1 : Lister les vidéos disponibles

curl -sS -X POST "http://${HOST_IP}:${VSS_AGENT_PORT:-8000}/v1/chat" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "What videos are available?"}]}' | \
  python3 -c "import json,sys; d=json.load(sys.stdin); print(d['choices'][0]['message']['content'])"

Montrez la liste des vidéos à l'utilisateur et demandez laquelle il souhaite analyser.

Étape 2 : Collecter les paramètres auprès de l'utilisateur

Demandez à l'utilisateur ces quatre entrées une par une :

Scénario — De quel type de scénario parle la vidéo ? Exemple : « surveillance d'entrepôt », « surveillance du trafic », « activité en magasin de détail »
Événements — Quels événements doivent être détectés ? Séparés par des virgules. Exemple : « accident, chariot élévateur bloqué, travailleurs sans équipement de protection, personne entrant dans une zone restreinte »
Objets d'intérêt — Sur quels objets l'analyse doit-elle se concentrer ? Ou « skip » pour ignorer. Exemple : « chariots élévateurs, palettes, travailleurs »
Requête Enterprise RAG — Une question optionnelle pour interroger la base de connaissances entreprise afin d'obtenir un contexte supplémentaire à inclure dans le rapport. Ou « skip » pour ignorer. Exemple : « Quels sont les principes de STCC ? »

Étape 3 : Démarrer le rapport (HTTP HITL)

Envoyez une requête POST à /v1/chat. Cela retourne HTTP 202 avec un execution_id et la première invite HITL. Remplacez VIDEO_NAME par la vidéo choisie :

curl -sS -X POST "http://${HOST_IP}:${VSS_AGENT_PORT:-8000}/v1/chat" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Generate a report for VIDEO_NAME using long video summarization"}]}'

La réponse contient :

execution_id — sauvegardez ceci, utilisé dans toutes les requêtes suivantes
interaction_id — identifie l'invite actuelle
prompt.text — le texte de l'invite HITL
response_url — l'URL pour envoyer la réponse par POST

Étape 4 : Répondre aux invites HITL

Pour chaque invite, envoyez par POST le paramètre de l'utilisateur à response_url. Remplacez EXECUTION_ID, INTERACTION_ID et la valeur de texte :

curl -sS -X POST \
  "http://${HOST_IP}:${VSS_AGENT_PORT:-8000}/executions/EXECUTION_ID/interactions/INTERACTION_ID/response" \
  -H "Content-Type: application/json" \
  -d '{"response": {"type": "text", "text": "USER_VALUE_HERE"}}'

Puis interrogez l'invite suivante :

curl -sS "http://${HOST_IP}:${VSS_AGENT_PORT:-8000}/executions/EXECUTION_ID" | python3 -m json.tool

Les invites HITL arrivent dans cet ordre :

Scénario — répondez avec le scénario de l'étape 2
Événements — répondez avec les événements de l'étape 2
Objets d'intérêt — répondez avec les objets de l'étape 2, ou « skip »
Requête Enterprise RAG — répondez avec la requête de l'étape 2, ou « skip »
Confirmation — répondez avec une chaîne vide « » pour confirmer et démarrer le traitement

Répétez le cycle POST-puis-interrogation pour chaque invite.

Étape 5 : Attendre la fin

Après l'invite de confirmation, le système traite la vidéo. Cela prend 3 à 5 minutes. Continuez à interroger jusqu'à ce que le statut passe de « running » à « completed » :

curl -sS "http://${HOST_IP}:${VSS_AGENT_PORT:-8000}/executions/EXECUTION_ID" | python3 -m json.tool

Dites à l'utilisateur d'attendre — cela prend 3 à 5 minutes. Interrogez toutes les 30 secondes.

Étape 6 : Présenter les résultats

Quand le statut est « completed », la réponse contient le rapport complet avec :

Événements détectés avec horodatages
Résumé de l'analyse narrative
Contexte Enterprise RAG (si interrogé)
Lien de téléchargement du rapport PDF (si disponible)

Présentez le contenu du rapport à l'utilisateur dans un format lisible.

Commandes rapides

Vérification de santé

curl -sS "http://${HOST_IP}:${VSS_AGENT_PORT:-8000}/health"

Requête de chat simple (non-rapport)

Pour les questions simples qui n'impliquent PAS la génération de rapport :

curl -sS -X POST "http://${HOST_IP}:${VSS_AGENT_PORT:-8000}/v1/chat" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "YOUR_QUESTION_HERE"}]}' | \
  python3 -c "import json,sys; d=json.load(sys.stdin); print(d['choices'][0]['message']['content'])"

Notes

Les rapports LVS prennent 3 à 5 minutes pour une vidéo d'environ 3,5 minutes — dites toujours à l'utilisateur d'attendre
Enterprise RAG nécessite une base de données vectorielle Milvus avec les données ingérées
Si les objets ou rag_query ne sont pas nécessaires, répondez par « skip »
Le format de réponse HITL est toujours : {"response": {"type": "text", "text": "value"}}
enable_interactive_extensions: true doit être défini dans la config frag pour que HTTP HITL fonctionne
Voir aussi : video-summarization, video-understanding, report, vios, deploy

vss-frag