vss-search-archive : recherche et ingestion de vidéos VSS

Objectif

Opérer la recherche d'archive depuis l'hôte de l'appelant. Compose et Kubernetes utilisent les mêmes commandes vss configure et vss search run ; seule l'origine du déploiement diffère. L'ingestion et la suppression de sources restent gérées par l'Agent.

Limites strictes

Exécuter la CLI du projet en local sur l'hôte. Ne jamais utiliser docker exec, kubectl exec, un shell de pod, ou une vss installée globalement comme substitut.
Ne jamais appeler directement Elasticsearch, RTVI-CV, RTVI-Embed, storage-ms, ou VST pour une mutation. Télécharger et supprimer via le cycle de vie de l'Agent.
Ne jamais supprimer, élargir, ou substituer silencieusement une contrainte de source demandée.
La similarité est une preuve de récupération, non une preuve de présence visuelle.
La CLI tente par défaut une vérification critique. Ne pas inspecter séparément les captures d'écran ou appeler un autre vérificateur lors du premier tour de recherche.
Proposer une vérification déléguée uniquement quand tous les résultats affichés sont unverified, et seulement après les avoir affichés et reçu la confirmation explicite de l'utilisateur. Si un résultat est confirmed ou rejected, ne pas déléguer aucun résultat à un autre vérificateur.

Prérequis

Un profil VSS search en cours d'exécution et son origine Compose ou Ingress accessible depuis l'hôte.
Une checkout contenant services/agent, uv, curl, et jq en local.
vss vios list pour lister et inspecter les sources (même CLI, même origine enregistrée).

Résoudre et valider la checkout une fois :

VSS_REPO_ROOT="${VSS_REPO_ROOT:-$HOME/video-search-and-summarization}"
test -f "${VSS_REPO_ROOT}/services/agent/pyproject.toml" || {
  echo "VSS checkout not found at ${VSS_REPO_ROOT}; set VSS_REPO_ROOT explicitly" >&2
  exit 1
}
VSS=(uv run --project "${VSS_REPO_ROOT}/services/agent" --no-dev --extra cli vss)
cd "${VSS_REPO_ROOT}" && "${VSS[@]}" search run --help >/dev/null || exit 1

--extra cli est obligatoire car la distribution de base contient les bibliothèques principales, tandis que nvidia-vss-cli déclare l'exécutable vss.

Résoudre le déploiement via son unique origine publique/accessible depuis l'hôte :

if [ -z "${VSS_ORIGIN:-}" ]; then
  VSS_ORIGIN=$("${VSS[@]}" configure show 2>/dev/null |
    jq -er '.base_url | select(type == "string" and length > 0)') || {
      echo "Provide the Compose or Ingress origin" >&2
      exit 1
    }
fi
VSS_ORIGIN="${VSS_ORIGIN%/}"
VST_URL="${VSS_ORIGIN}"
VSS_VIOS_URL="${VSS_ORIGIN}/vst"
"${VSS[@]}" configure --base-url "${VSS_ORIGIN}" || exit 1

Dans un workflow multi-étapes persistant, réutiliser l'origine enregistrée par le déploiement préparé comme ci-dessus. Ne pas répéter la sélection d'origine publique, l'édition du routage, ou un redéploiement simplement parce que le prochain tour d'agent n'a pas hérité les variables shell.

Voir deployment resolution pour le contrat VSS_PUBLIC_URL de propriété du déploiement. Sur Kubernetes, ne jamais utiliser le port-forwarding, le DNS de Service, les NodePorts, ou une version Helm devinée. Les routes non exposées via l'Ingress sont enregistrées comme absentes et un chemin de recherche qui en a besoin sort avec le code 4.

Pour la disponibilité du déploiement, l'ingestion, le nettoyage de fixtures, les vérifications d'index, RTSP, ou la suppression, lire complètement source lifecycle avant d'agir. Réexécuter vss configure après l'ingestion car l'inventaire d'index enregistré est un snapshot.

Workflow de recherche obligatoire

Confirmer que le déploiement sélectionné est le profil search. Si les routes requises ne sont pas disponibles, demander s'il faut se reconnecter ou le déployer avec vss-deploy-profile -p search ; ne pas cibler un autre profil.
Quand l'utilisateur nomme un fichier, une caméra, ou un capteur, lister les sources enregistrées avec "${VSS[@]}" vios list avant d'invoquer la CLI de recherche — elle lit l'origine que vss configure a enregistrée, donc elle ne prend pas d'endpoint. Accepter uniquement une source exacte, un ID de flux, ou une unique correspondance de sous-chaîne normalisée sans ambiguïté.
- Aucune correspondance : signaler la source manquante, lister les noms disponibles, et demander à l'utilisateur de clarifier ou explicitement demander l'ingestion. S'arrêter sans sonder la CLI de recherche, déployer, ou ingérer. Ne jamais continuer avec une source différente. Répondre à propos de warehouse_sample quand la demande a nommé warehouse-ladder retourne une réponse confiante sur la mauvaise vidéo, et rien en aval ne peut détecte la substitution.
- Plusieurs correspondances : demander à l'utilisateur de choisir et s'arrêter.
- Ne jamais substituer une autre vidéo ou lancer une recherche sans restriction comme sondage.
Préserver à la fois le .sensorId et le .name de la source correspondante. La valeur --video-source requise dépend du chemin de recherche, pas du type de source : embed et fusion utilisent l'ID de capteur ; attribute et object utilisent le nom. La CLI fait correspondre cette valeur littéralement et ne fait pas de conversion nom↔ID. Définir --source-type video_file pour les téléchargements ou --source-type rtsp pour les flux en direct ; cela choisit la partition d'index indépendamment de l'identifiant.
Préserver l'objet/action complet, la source, les limites de temps, la limite de résultats, et les attributs visuels. Choisir un chemin :
- requête texte uniquement → run embed
- attributs visuels uniquement → run attribute
- requête texte plus attributs → run fusion
- IDs d'objet suivi explicites → run object
--attribute est pour des propriétés détectables spécifiques comme white jacket ou red hard hat, pas des noms génériques ou des actions. Garder red forklift entièrement dans --query. Pour person in a red jacket running, préserver l'action et l'attribut : run fusion --query "person in a red jacket running" --attribute "red jacket".
Construire l'invocation comme un tableau Bash et valider uniquement son exact stdout. Lire CLI usage pour tous les flags supportés.

: "${SEARCH_PATH:?set embed|attribute|fusion|object}"
: "${SOURCE_TYPE:?set video_file or rtsp}"
TOP_K="${TOP_K:-3}"
VIDEO_SOURCES=() # sensor IDs for embed/fusion; names for attribute/object
: "${SOURCE_SCOPED:?set true for a resolved scope; false only when unrestricted}"
if [ "${SOURCE_SCOPED}" = true ] && [ "${#VIDEO_SOURCES[@]}" -eq 0 ]; then
  echo "Resolved source scope is empty; refusing an unrestricted search" >&2
  exit 1
fi
SEARCH_COMMAND=(
  "${VSS[@]}" search run "${SEARCH_PATH}"
  --source-type "${SOURCE_TYPE}" --top-k "${TOP_K}" --raw
)
for source in "${VIDEO_SOURCES[@]}"; do
  SEARCH_COMMAND+=(--video-source "${source}")
done
# Append --query, repeatable --attribute, --object-id, and time bounds as needed.
if ! SEARCH_JSON=$("${SEARCH_COMMAND[@]}"); then
  echo "Search command failed" >&2
  exit 1
fi
printf '%s' "${SEARCH_JSON}" |
  jq -e 'type == "object" and (.data | type == "array")' >/dev/null || {
    echo "Search did not return a SearchOutput object with a data array" >&2
    exit 1
  }

Ne pas passer de flags endpoint, index, model, deployment, profile, ou base-URL à search run ; vss configure possède ces valeurs. Ne pas remplacer un appel CLI échoué par /api/v1/search ou un accès backend privé.

Valider chaque URL de capture d'écran exacte retournée par un hit non vide avec un GET limité pour la disponibilité uniquement. Son schéma normalisé, hôte, et port effectif correspondent toujours à l'origine enregistrée par vss configure, car la CLI tamponne cette origine dans chaque hit — une URL media localhost signifie que le déploiement a été configuré contre une origine localhost, non que l'URL est mal formée. Sur Brev, préférer l'origine de lien sécurisé HTTPS publique. Si la configuration a utilisé le fallback accessible depuis l'hôte documenté après l'échec de sa unique sonde publique limitée, accepter uniquement cette origine exacte enregistrée et labeler ses URLs media comme host-local ; ne pas redémarrer le diagnostic de routage. Rejeter les identifiants dans l'URL et ne jamais réécrire l'URL ou ajouter un header de routage streamId. Ignorer le corps de la réponse ; la disponibilité n'est pas une preuve visuelle.
Lire l'objet verification de chaque hit :
- confirmed : le critique a trouvé tous les critères visuels demandés dans ce clip.
- rejected : le critique a trouvé qu'un critère visuel n'était pas satisfait.
- unverified : aucun verdict critique utilisable n'a été produit. Ceci inclut un VLM manquant, un média inaccessible, et une sortie mal formée ou inconclusive.

La CLI est fail-open : l'échec de vérification ne doit pas écarter ou échouer la récupération. Ne jamais dériver un verdict à partir de la similarité, noms de fichiers, IDs d'objet, ou disponibilité de captures d'écran. Traiter les valeurs booléennes criteria_met comme preuve critique uniquement.

Formater les résultats non vides sans JSON brut :

## Résultats de recherche vidéo
<pour chaque hit : source exacte, début/fin, similarité, URL media complète,
résultat de vérification, et critères si présents>

Les scores de similarité sont une preuve de récupération ; le résultat de vérification séparé
enregistre si le clip limité satisfaisait la demande visuelle.

## Étape de vérification
Voulez-vous que je vérifie les résultats de recherche non vérifiés ?

Inclure ## Étape de vérification uniquement quand l'ensemble de résultats affichés non vides est entièrement unverified. Si un résultat affichée est confirmed ou rejected, l'omettre même quand d'autres hits sont unverified. Ne jamais déployer un VLM ou appeler vss-ask-video automatiquement lors de ce tour de résultats.

Si l'utilisateur confirme explicitement, lire complètement search-result verification et déléguer les hits affichés uniquement après confirmer à nouveau que chacun est toujours unverified. Préserver leurs intervalles limites exacts et l'intention visuelle originale complète. Garder au maximum trois délégations en vol. Ne jamais transmettre un ensemble de résultats partiellement vérifiés.
Si .data est vide, rapporter zéro candidats fidèlement. Ne pas prétendre que l'objet est absent ; proposer une requête spécifique ou un raffinement de seuil de similarité en préservant la source. Ne jamais élargir la recherche silencieusement.

Réponses d'Agent en langage naturel

Utiliser la CLI de l'hôte pour la recherche structurée déterministe. Si un appelant requiert explicitement que l'Agent du déploiement décompose une demande en langage naturel, sa réponse /api/v1/search est du texte conversationnel, non SearchOutput. Valider le champ texte connu et le présenter en prose ; ne jamais exécuter .data[], screenshot, ou analyse d'analyse de vérification contre cette réponse ou inventer des lignes de hits structurées.

Dépannage

CLI non disponible : conserver --extra cli, vérifier VSS_REPO_ROOT, et s'arrêter.
Exit 2 : lire la --help du chemin sélectionné ; ne pas deviner les flags.
Exit 3 : un backend enregistré est inaccessible ; réparer le routage et reconfigurer.
Exit 4 : exécuter vss configure --base-url <origin> ou choisir un chemin dont les services requis sont réellement routés.
Exit 5 : ingérer la source, attendre la disponibilité, et réexécuter vss configure.
Source manquante/ambiguë : s'arrêter pour clarification ; ne jamais substituer.
RT-VLM manquant : la récupération reste valide et les résultats restent unverified.
Authentification : utiliser la route approuvée par l'opérateur. Ne jamais placer de secrets dans les prompts, flags, fichiers générés, logs, ou sortie de skill.