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 un ancrage de document Enterprise RAG et une collecte de paramètres guidée avec boucle humaine (HITL) au-dessus de l'agent VSS.

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

Activer Enterprise RAG sur le profil LVS

Le dépôt inclut la configuration de l'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 caption ordinaire reste activée, et frag_retrieval ajoute l'ancrage de document Enterprise RAG.

Utilisez le workflow /vss-deploy-profile normal pour le déploiement. Le fichier source .env reste en lecture seule ; appliquez les substitutions non-secrètes à deploy/docker/developer-profiles/dev-profile-lvs/generated.env. generated.env est ignoré par le dépôt, mais c'est toujours un fichier en texte clair : ne le validez pas, ne le collez pas dans les logs, et ne stockez pas d'identifiants longue durée dedans. Préférez un vault, 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/.env \
  deploy/docker/developer-profiles/dev-profile-lvs/generated.env

Définissez ces valeurs non-secrètes 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 — point de terminaison 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) hors de generated.env et hors 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 déjà authentifiée, ou un fichier de substitution local qui référence une variable shell éphémère à l'exécution.

Étape 2 : Se connecter au registre NGC

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

read -rsp "Clé API NGC : " 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 dry-run ci-dessous. Si le serveur RAG nécessite une clé API, créez cette substitution locale non-suivie après que resolved.yml soit généré :

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/generated.env \
  config > resolved.yml
uv run "$REPO/skills/vss-deploy-profile/scripts/normalize_resolved_yml.py" \
  "$REPO/deploy/docker/resolved.yml"
docker compose --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 "Clé API RAG : " RAG_API_KEY
RAG_API_KEY="$RAG_API_KEY" docker compose \
  --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 s'exécutent
docker ps --format "table {{.Names}}\t{{.Status}}"

# Contrôle 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 une synthèse vidéo ou un rapport 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 enrichi 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)

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

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

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

Paramètres requis fournis par l'utilisateur :

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

Si une valeur requise manque, retournez un message concis sur les champs manquants et arrêtez ; reprenez le flux de travail quand l'utilisateur fournit les valeurs manquantes.

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

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

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 — enregistrez-le, 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 où 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 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 pour la prochaine invite :

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 »
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 l'achèvement

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 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
Synthèse d'analyse narrative
Contexte Enterprise RAG (si interrogé)
Lien de téléchargement PDF du rapport (si disponible)

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

Gestion des erreurs

Si un déploiement, une vérification de santé, ou une requête de chat échoue, signalez le point de terminaison 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 montrez le statut d'exécution plus tout payload d'erreur à la place 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, signalez le statut et recommandez de vérifier les logs vss-agent avant de réessayer.
Si la réponse finale manque du texte de rapport ou d'un lien PDF, retournez les champs de réponse disponibles et énoncez clairement quelle sortie manquait.

Commandes rapides

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 ; 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 de l'agent activée par RAG doit conserver ses modèles HITL et les paramètres hitl_enabled: true pour que HTTP HITL fonctionne
Voir aussi : video-summarization, video-understanding, report, vios, deploy

vss-generate-video-report-rag