vss-benchmark-video-summarization

Instructions

Suivez la table de routage et le flux de travail étape par étape ci-dessous. Exécutez chaque étape dans l'ordre lors d'une première exécution. Pour les exécutions répétées, allez directement à la section Repeat Runs. La documentation détaillée se trouve dans references/ et les scripts de benchmark dans scripts/.

⚠️ Systèmes GPU partagés : Sur un hôte multi-utilisateurs, plusieurs instances LVS peuvent s'exécuter sur des ports différents. Mesurez toujours les performances par rapport à l'instance QUE VOUS avez déployée. Ne supposez jamais le port 38111 — utilisez toujours l'URL d'endpoint exacte retournée par vss-build-vision-ai lors de votre déploiement de LVS. Si vous n'avez pas déployé une instance LVS dans cette session, déployez-en une d'abord avant d'exécuter les benchmarks.

Purpose

Mesurez les limites de latence et de débit d'une instance LVS (Long Video Summarization) déployée, identifiez les goulets d'étranglement du GPU et du pipeline, et suggérez des modifications de configuration qui améliorent les performances. Produit des rapports XLSX et des fichiers de résultats JSON par scénario, plus une analyse en langage naturel avec des recommandations d'amélioration.

Ne UTILISEZ PAS cette skill pour :

• Déployer LVS — utilisez la skill vss-build-vision-ai avec le profil lvs.
• La surveillance ou les alertes en production — c'est un outil de benchmark hors ligne.
• Les profils VSS non-LVS (RTVI, search-only, etc.) — l'API /files et l'endpoint /summarize sont spécifiques à LVS.

Routing

Prerequisites

Deploy LVS for Benchmarking

Avant de mesurer les performances, déployez une instance LVS fraîche en utilisant vss-build-vision-ai. Sur les systèmes partagés, utilisez toujours un COMPOSE_PROJECT_NAME unique pour que vos conteneurs et volumes soient isolés des autres utilisateurs.

# Choisissez un nom de projet unique (ex. votre nom d'utilisateur)
export COMPOSE_PROJECT_NAME="lvs-bench-$(whoami)"

cd <repo>/deploy/docker

# REQUIS POUR LE BENCHMARK : le benchmark télécharge des vidéos via la route dev /files
# de LVS, qui est protégée par VIA_DEV_API (false par défaut ; POST /files retourne 404 quand
# c'est off). Le conteneur lvs-server charge son environnement depuis
# services/video-summarization/.env (le `env_file:` de compose), donc VIA_DEV_API doit
# être défini LÀ — le mettre dans tout autre fichier env ne l'atteindra PAS le conteneur.
# Définissez-le avant le déploiement :
grep -q '^VIA_DEV_API=' services/video-summarization/.env \
  && sed -i 's/^VIA_DEV_API=.*/VIA_DEV_API=true/' services/video-summarization/.env \
  || echo 'VIA_DEV_API=true' >> services/video-summarization/.env

# Déployez LVS sur vos GPUs désignés
./scripts/dev-profile.sh up \
  --profile lvs \
  --hardware-profile RTXPRO6000BW \
  --llm-device-id <LLM_GPU> \
  --vlm-device-id <VLM_GPU>

# Si LVS s'exécutait déjà, réexécutez la commande de déploiement ci-dessus pour que compose
# recrée le conteneur avec le nouvel env (un simple `docker restart` ne
# relit PAS les modifications env_file).

Notez l'endpoint LVS (http://<HOST_IP>:38111) et le nom du conteneur : le fichier compose le définit de façon statique à vss-lvs (vérifiez avec docker ps --filter name=lvs). Définissez-les avant de continuer :

export LVS_BACKEND=http://localhost:38111
export LVS_CONTAINER_NAME=vss-lvs
export VLM_GPUS=<VLM_GPU>
export LLM_GPUS=<LLM_GPU>

Téléchargements de modèles : Le premier déploiement télécharge les poids du modèle LLM (~20 GB) et VLM (~17 GB). Cela prend 20–40 minutes selon la vitesse du réseau. Les déploiements ultérieurs réutilisent les volumes créés sous votre COMPOSE_PROJECT_NAME et démarrent en quelques minutes.

Step 0: Pre-flight Check

Sur les systèmes partagés, un autre tenant peut occuper le port 38111 — le benchmark doit donc vérifier qu'il accède à VOTRE instance et à VOS GPUs, pas à ceux de quelqu'un d'autre. preflight.sh le fait (et échoue rapidement sinon).

Définissez les valeurs de votre déploiement, puis exécutez la vérification pré-vol :

export LVS_BACKEND=http://localhost:38111                          # VOTRE endpoint LVS /summarize
export LVS_CONTAINER_NAME=vss-lvs                                   # VOTRE conteneur LVS (voir étape de déploiement)
export VLM_GPUS=<VLM_GPU>                                           # GPU(s) utilisés par votre VLM
export LLM_GPUS=<LLM_GPU>                                           # GPU(s) utilisés par votre LLM

./scripts/preflight.sh

preflight.sh quitte avec un code non-zéro sauf si tous les éléments suivants sont vrais :

• la config s'analyse et vlm_gpus/llm_gpus sont des IDs GPU valides dans la plage GPU de l'hôte ;
• LVS_BACKEND est accessible (/v1/ready → 200) et la route dev /files est activée (pas 404) ;
• votre LVS_CONTAINER_NAME possède effectivement le port backend — son serveur s'est lié avec succès (pas address already in use dans ses logs) et aucun autre conteneur ne publie ce port ;
• les VLM_GPUS/LLM_GPUS configurés sont réservés par vos conteneurs VLM/LLM de LVS — ainsi vous ne pouvez pas silencieusement mesurer des GPUs inactives ou l'instance d'un autre tenant (l'exacte défaillance que cela protège).

run_benchmark.sh exécute preflight.sh automatiquement avant chaque exécution ; vous pouvez aussi l'exécuter en tant que programme autonome (ci-dessus) à tout moment.

Si /files retourne 404, la route dev est off — activez VIA_DEV_API=true sur votre LVS (voir l'étape de déploiement) avant de continuer.

Step 1: Download Test Videos

Le benchmark utilise des vidéos de surveillance d'entrepôt du dataset d'exemples VSS, hébergées dans NGC. scripts/fetch-videos.sh télécharge le package et place un ensemble organisé — warehouse_4min.mp4, warehouse_5min.mp4, warehouse_10min.mp4 — dans <VSS_BENCHMARK_DATA_DIR>/videos/, les noms de fichiers exacts que le scripts/config.yaml par défaut référence. Elle requiert la CLI ngc et une clé API NGC, et imprime les instructions d'installation/auth si l'un d'eux manque.

export VSS_BENCHMARK_DATA_DIR=${VSS_BENCHMARK_DATA_DIR:-$HOME/vss-benchmark-data}

# Idempotente ; ajoutez FORCE=1 pour re-télécharger, ou passez une version de package (3.2.0 par défaut)
./scripts/fetch-videos.sh

# Sondez les durées des vidéos pour vérifier ce qui a été téléchargé
find "${VSS_BENCHMARK_DATA_DIR}/videos" -name "*.mp4" | while read f; do
  dur=$(ffprobe -v quiet -show_entries format=duration -of csv=p=0 "$f" 2>/dev/null | cut -d. -f1)
  echo "$(basename $f): ${dur}s"
done

Step 2: Generate Test Clips (if needed)

Normalement l'Étape 1 fournit des clips réels de 5 et 10 minutes et cette étape peut être ignorée. Utilisez-la uniquement si un clip organisé manque (ex. la disposition du package NGC a changé) ou vous avez besoin de durées personnalisées : bouclez une vidéo source disponible dans les noms de fichiers que le scripts/config.yaml par défaut référence — warehouse_5min.mp4 (300s) et warehouse_10min.mp4 (600s).

# Trouvez une vidéo source à boucler depuis
SOURCE=$(find "${VSS_BENCHMARK_DATA_DIR}" -name "*.mp4" | head -1)
echo "Using source: ${SOURCE}"

# Créez un sous-répertoire videos/ où le serveur media attend les fichiers
mkdir -p "${VSS_BENCHMARK_DATA_DIR}/videos"

for spec in warehouse_5min:300 warehouse_10min:600; do
  NAME="${spec%%:*}"; DURATION="${spec##*:}"
  OUT="${VSS_BENCHMARK_DATA_DIR}/videos/${NAME}.mp4"
  [ -f "$OUT" ] && echo "Already exists: ${OUT}" && continue
  ffmpeg -stream_loop -1 -i "${SOURCE}" -t ${DURATION} -c copy "${OUT}" -y -loglevel error
  echo "Created: ${OUT}"
done

# Vérifiez les clips
find "${VSS_BENCHMARK_DATA_DIR}/videos" -name "*.mp4" | while read f; do
  dur=$(ffprobe -v quiet -show_entries format=duration -of csv=p=0 "$f" 2>/dev/null | cut -d. -f1)
  echo "$(basename $f): ${dur}s"
done

Step 3: Start Media Server

Le serveur media sert les vidéos de test sur HTTP pour que l'endpoint /files de LVS puisse les télécharger par URL.

SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# Démarrez le serveur media (nginx:alpine)
cd "${SKILL_DIR}"
docker compose -f scripts/media-server.yaml up -d
sleep 2

# Vérifiez la santé
curl -sf "http://localhost:8888/health" && echo "Media server ready" || echo "Media server not ready"

# Listez les vidéos disponibles (listing de répertoire JSON)
curl -s "http://localhost:8888/videos/" | python3 -m json.tool 2>/dev/null || \
  find "${VSS_BENCHMARK_DATA_DIR}/videos" -name "*.mp4" -exec basename {} \; | sed 's|^|http://localhost:8888/videos/|'

Notez les noms de fichiers retournés — vous en aurez besoin à l'étape suivante pour mettre à jour config.yaml.

Step 4: Configure

Modifiez scripts/config.yaml avec les noms de fichiers vidéo réels découverts à l'Étape 3 :

1. Mettez à jour les URLs vidéo — Dans les deux sections single_file_test et file_burst_test, remplacez HOST_IP par l'IP LAN de votre hôte (hostname -I | awk '{print $1}' — PAS localhost ; LVS télécharge les vidéos depuis l'intérieur de son conteneur) et assurez-vous que les noms de fichiers correspondent à ceux servus par le serveur media (ex., http://<HOST_IP>:8888/videos/warehouse_5min.mp4).

2. Définissez les assignations GPU — Mettez à jour vlm_gpus et llm_gpus pour correspondre à votre déploiement LVS. Vérifiez VOTRE conteneur :

   docker inspect "${LVS_CONTAINER_NAME}" \
   --format '{{range .Config.Env}}{{println .}}{{end}}' | grep -E "VLM_GPUS|LLM_GPUS|CUDA_VISIBLE"

3. Ajustez les tailles de chunk — Le chunk_sizes: [10, 30] par défaut teste à la fois le chunking de 10 et 30 secondes. Les chunks plus grands réduisent la surcharge d'appel API mais augmentent la latence par chunk.

4. Ajustez les niveaux de concurrence — Le concurrency_levels: [1, 2, 4, 8] par défaut pour file_burst. Supprimez les niveaux qui dépassent la capacité mémoire de votre matériel.

Step 5: Run Benchmark

SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "${SKILL_DIR}/scripts"

# Créez un environnement virtuel Python s'il n'existe pas
[ ! -d "vss-bench-env" ] && python3 -m venv vss-bench-env

# Activez venv et installez les requirements
source vss-bench-env/bin/activate
pip install -r requirements.txt -q

# LVS_BACKEND doit déjà être défini sur l'endpoint de VOTRE déploiement
if [ -z "${LVS_BACKEND}" ]; then
  echo "ERROR: LVS_BACKEND is not set. Set it to your own LVS endpoint before running."
  exit 1
fi
export VIA_BACKEND="${LVS_BACKEND}"
export VIA_VLM_GPUS="${VLM_GPUS:?ERROR: VLM_GPUS must be set (e.g. export VLM_GPUS=6)}"
export VIA_LLM_GPUS="${LLM_GPUS:?ERROR: LLM_GPUS must be set (e.g. export LLM_GPUS=7)}"

# Exécutez le scénario single_file
python vss_perf_benchmark.py --config config.yaml --scenario single_file_test

# Exécutez le scénario file_burst (peut s'exécuter séparément ou ensemble)
python vss_perf_benchmark.py --config config.yaml --scenario file_burst_test

Le benchmark crée un répertoire de sortie (par défaut : vss-perf-report/) avec des sous-répertoires par scénario. Chaque exécution de scénario génère un rapport XLSX et execution_summary.json.

Remarque : Le répertoire de sortie ne doit pas exister ou doit être vide avant chaque exécution. Déplacez ou renommez les résultats précédents avant de réexécuter :

mv vss-perf-report vss-perf-report-$(date +%Y%m%d-%H%M%S)

Step 6: Analyze Results

SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
OUTPUT_DIR="${SKILL_DIR}/vss-perf-report"

# Affichez le résumé d'exécution de premier niveau pour single_file
echo "=== single_file_test execution summary ==="
cat "${OUTPUT_DIR}/single_file_test/execution_summary.json" | python3 -m json.tool

# Affichez les résumés par cas de test
find "${OUTPUT_DIR}" -name "test_case_summary.json" | while read f; do
  echo ""
  echo "=== $(dirname $f | xargs basename) ==="
  cat "$f" | python3 -m json.tool
done

# Listez les rapports XLSX générés
find "${OUTPUT_DIR}" -name "*.xlsx" | while read f; do
  echo "Report: $f"
done

Lisez les fichiers de résultats JSON et extrayez les métriques clés suivantes pour l'analyse :

• E2E latency (e2e_latency en secondes) : temps total de la demande à la réponse
• VLM pipeline latency (vlm_pipeline_latency) : temps passé dans le pipeline du modèle vision
• VLM pipeline % : vlm_pipeline_latency / e2e_latency * 100
• CA-RAG latency (ca_rag_latency) : temps d'inférence RAG conscient du contexte
• VLM GPU utilization mean (vlm_gpu_usage_mean) : utilisation de calcul GPU % pour VLM
• LLM GPU utilization mean (llm_gpu_usage_mean) : utilisation de calcul GPU % pour LLM
• GPU memory mean (vlm_gpu_memory_mean, llm_gpu_memory_mean) : pression mémoire %
• File burst throughput (throughput_files_per_second) : fichiers concurrents traités par seconde
• Optimal concurrency (optimal_target_concurrency.estimated_concurrency) : le niveau de concurrence qui respecte target_latency_seconds

Step 7: Suggest Improvements

Après avoir analysé les résultats, présentez un tableau de résultats et des recommandations selon les règles suivantes :

Repeat Runs

Une fois la configuration complète (Steps 1–4), utilisez run_benchmark.sh pour les exécutions ultérieures :

SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "${SKILL_DIR}"

# Exécutez le scénario single_file
./scripts/run_benchmark.sh --scenario single_file_test

# Exécutez le scénario file_burst
./scripts/run_benchmark.sh --scenario file_burst_test

# Exécutez avec un répertoire de sortie versionné
./scripts/run_benchmark.sh --scenario single_file_test --output-dir vss-perf-report-v2

# Exécutez tous les scénarios dans config.yaml
./scripts/run_benchmark.sh

# Mode debug (payloads API verbeux)
./scripts/run_benchmark.sh --scenario single_file_test --debug

run_benchmark.sh vérifie la disponibilité de LVS, démarre le serveur media si nécessaire, crée/réutilise le venv Python, et passe tous les arguments supplémentaires directement à vss_perf_benchmark.py.

Troubleshooting

Cross-reference

• vss-build-vision-ai — déployez LVS avec le profil lvs avant le benchmark
• vss-summarize-video — utilisation opérationnelle de LVS pour la synthèse vidéo (pas de benchmark)
• Benchmark modes reference — references/benchmark-modes.md
• Analyzing results reference — references/analyzing-results.md

bump:3