VSS Generate Video Report RAG — Analyse vidéo avec Enterprise RAG

Générez des rapports de synthèse vidéo en utilisant la configuration d'agent activée par RAG du profil LVS. Cette compétence ajoute l'ancrage documentaire Enterprise RAG et la collecte de paramètres guidée en boucle humain-machine (HITL) par-dessus l'agent VSS.

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

Activer Enterprise RAG sur le profil LVS

Le dépôt fournit la configuration d'agent LVS activée par RAG à deploy/docker/developer-profiles/dev-profile-lvs/vss-agent/configs/config_rag.yml. C'est un sur-ensemble de la configuration LVS par défaut : la récupération de sous-titres régulière reste activée, et frag_retrieval ajoute l'ancrage documentaire Enterprise RAG.

Utilisez le workflow normal /vss-deploy-profile pour le déploiement. Les fichiers source .env et overrides.env restent en lecture seule ; initialisez generated.env à partir de overrides.env et appliquez-y les remplacements non-secrets. generated.env est ignoré par le dépôt, mais c'est toujours un fichier en texte brut : ne le commitez pas, ne le collez pas dans les logs, et ne stockez pas les identifiants de longue durée là. Préférez un coffre-fort, les secrets Docker, ou les variables d'environnement shell éphémères pour les clés API.

Étape 1 : Configurer le fichier env généré

REPO=${REPO:-$(git rev-parse --show-toplevel)}
cd "$REPO"
cp deploy/docker/developer-profiles/dev-profile-lvs/overrides.env \
  deploy/docker/developer-profiles/dev-profile-lvs/generated.env

Définissez ces valeurs non-secrets dans generated.env :

• HOST_IP — IP de l'hôte (hostname -I | awk '{print $1}')
• VSS_AGENT_CONFIG_FILE=./deploy/docker/developer-profiles/dev-profile-lvs/vss-agent/configs/config_rag.yml
• RAG_SERVER_URL — endpoint HTTP du serveur Enterprise RAG (par défaut http://rag-server:8081/v1)
• KNOWLEDGE_COLLECTION — collection Enterprise RAG par défaut pour frag_retrieval

Gardez les valeurs sensibles (NGC_CLI_API_KEY, NVIDIA_API_KEY, RAG_API_KEY) en dehors de generated.env et en dehors de resolved.yml. Ne les exportez pas avant d'exécuter docker compose config > resolved.yml, car Compose développe les variables d'environnement dans ce fichier. Utilisez un gestionnaire de secrets, une session Docker authentifiée existante, ou un fichier de remplacement local qui référence une variable de shell éphémère au moment du démarrage.

Étape 2 : Se connecter au registre NGC

Préférez une session Docker authentifiée existante ou une connexion gérée par secrets. Si une connexion est requise, utilisez --password-stdin sans afficher les valeurs de jeton :

read -rsp "NGC API key: " NGC_CLI_API_KEY
printf '%s\n' "$NGC_CLI_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
unset NGC_CLI_API_KEY

Étape 3 : Déployer le profil LVS avec la configuration RAG

N'exportez pas RAG_API_KEY pour le test à sec ci-dessous. Si le serveur RAG requiert une clé API, créez ce remplacement local non suivi après la génération de resolved.yml :

cat > rag-secret.override.yml <<'EOF'
services:
  vss-agent:
    environment:
      RAG_API_KEY: ${RAG_API_KEY:?Set RAG_API_KEY only for docker compose up}
EOF

REPO=${REPO:-$(git rev-parse --show-toplevel)}
cd "$REPO/deploy/docker"
docker compose \
  --env-file developer-profiles/dev-profile-lvs/.env \
  --env-file developer-profiles/dev-profile-lvs/generated.env \
  config > resolved.yml
uv run "$REPO/skills/deployment/vss-deploy-profile/scripts/normalize_resolved_yml.py" \
  "$REPO/deploy/docker/resolved.yml"
docker compose \
  --env-file developer-profiles/dev-profile-lvs/.env \
  --env-file developer-profiles/dev-profile-lvs/generated.env \
  -f resolved.yml up -d

Quand rag-secret.override.yml est nécessaire, utilisez :

read -rsp "RAG API key: " RAG_API_KEY
RAG_API_KEY="$RAG_API_KEY" docker compose \
  --env-file developer-profiles/dev-profile-lvs/.env \
  --env-file developer-profiles/dev-profile-lvs/generated.env \
  -f resolved.yml -f rag-secret.override.yml up -d
unset RAG_API_KEY

Étape 4 : 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 LVS RAG agent is running" \
  || echo "VSS LVS RAG agent is NOT reachable"

Arrêter

REPO=${REPO:-$(git rev-parse --show-toplevel)}
cd "$REPO/deploy/docker"
docker compose -f resolved.yml down

Quand l'utiliser

• L'utilisateur souhaite générer un résumé ou un rapport vidéo en utilisant le pipeline LVS activé par RAG
• L'utilisateur demande d'analyser une vidéo avec contexte de connaissance Enterprise RAG
• L'utilisateur mentionne « frag », « enterprise RAG », ou « rapport amélioré par connaissance »

Quand NE PAS l'utiliser

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

Workflow : 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'])"

Une vidéo sélectionnée est requise avant l'étape 2. Si l'utilisateur n'en a pas déjà nommé une, renvoyez la courte liste et arrêtez-vous ; reprenez quand l'utilisateur fournit le nom de la vidéo.

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

Paramètres requis fournis par l'utilisateur :

1. Scénario — étiquette de scénario pour la vidéo. Exemple : « surveillance d'entrepôt », « surveillance du trafic », « activité en magasin de détail »
2. Événements — noms d'événements séparés par des virgules à détecter. Exemple : « accident, chariot élévateur bloqué, travailleurs sans EPI, personne entrant dans zone interdite »
3. Objets d'intérêt — objets d'intérêt, ou « skip ». Exemple : « chariots élévateurs, palettes, travailleurs »

Si une valeur requise manque, renvoyez un message concis de champs manquants et arrêtez-vous ; reprenez le workflow quand l'utilisateur fournit les valeurs manquantes.

Il n'y a pas d'invite HITL Enterprise RAG Query séparée. L'ancrage documentaire provient de la configuration d'agent activée par RAG exposant frag_retrieval ; si l'utilisateur souhaite que le contexte spécifique de POS, de politique ou de procédure soit reflété dans le rapport, capturez ce contexte dans la demande de rapport originale ou résolvez-le comme une question d'ancrage documentaire avant de démarrer le flux de rapport HITL.

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

Envoyez un 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-le, utilisé dans toutes les demandes ultérieures
• interaction_id — identifie l'invite actuelle
• prompt.text — le texte de l'invite HITL
• response_url — l'URL pour POSTer la réponse

Étape 4 : Répondre aux invites HITL

Pour chaque invite, POSTez 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 la prochaine invite :

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

Les invites HITL viennent dans cet ordre :

1. Scénario — répondez avec le scénario de l'étape 2
2. Événements — répondez avec les événements de l'étape 2
3. Objets d'intérêt — répondez avec les objets de l'étape 2, ou « skip »
4. Confirmation — répondez avec une chaîne vide « » pour confirmer et commencer 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

Définissez l'attente que le traitement prend généralement 3-5 minutes, puis interrogez tous 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é d'analyse narrative
• Contexte Enterprise RAG (si interrogé)
• Lien de téléchargement du rapport PDF (s'il est disponible)

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

Gestion d'erreurs

• Si un déploiement, une vérification de santé, ou une demande de chat échoue, signalez l'endpoint défaillant, le statut HTTP ou l'erreur de commande, et la vérification suivante la plus utile. Ne continuez pas dans HITL sans un execution_id, interaction_id, et response_url valides.
• Si une réponse HITL est rejetée ou que l'interrogation d'exécution suivante omet l'invite attendue, arrêtez et affichez le statut d'exécution plus tout charge d'erreur au lieu de deviner la prochaine invite.
• Si le statut d'exécution devient failed, cancelled, ou reste running sans progrès au-delà de la fenêtre de traitement attendue, surfacez le statut et recommandez de vérifier les logs vss-agent avant de réessayer.
• Si la réponse finale manque de texte de rapport ou de lien PDF, retournez les champs de réponse disponibles et indiquez clairement quelle sortie manquait.

Commandes rapides

Requête de chat simple (non-rapport)

Pour les questions simples qui N'IMPLIQUENT PAS de 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 ; définissez cette attente avant d'interroger
• Enterprise RAG nécessite un serveur RAG accessible avec des données déjà ingérées dans KNOWLEDGE_COLLECTION
• Si les objets ne sont pas nécessaires, répondez avec « skip »
• Le format de réponse HITL est toujours : {"response": {"type": "text", "text": "value"}}
• La configuration d'agent activée par RAG doit conserver ses modèles HITL et ses paramètres hitl_enabled: true pour que HTTP HITL fonctionne
• Voir aussi : video-summarization, video-understanding, report, vios, deploy