Concepts fondamentaux

Toutes les surfaces de Gaard (application web, API, CLI) partagent le même vocabulaire. Cette page explique les concepts que vous rencontrerez partout ailleurs dans la documentation. Lisez-la une fois et le reste des guides se lira plus vite.

Tenants et isolation

Un tenant est la frontière d’isolation dans Gaard. Il possède vos caméras, classifications, labels, configuration et utilisateurs, et rien ne passe d’un tenant à un autre. Lorsque vous vous connectez à l’application web ou authentifiez un jeton API, vous opérez toujours au sein d’un seul tenant.

Un nom de tenant est aussi un identifiant de base de données, il suit donc des règles strictes :

commence par une lettre minuscule
n’utilise que a-z, 0-9, - et _
fait au plus 64 caractères
n’est jamais admin, config ou local

Parce que le tenant est la frontière d’isolation, chaque résultat de classification porte son tenant, et chaque jeton API est limité à un seul tenant. Les vues partagées (par exemple les liens partageables) ne se résolvent que pour les personnes de la même organisation.

Solutions et droits d’accès

Une solution est une ligne de produit activable (entitlement). Votre compte dispose de l’une ou des deux :

Classify : classification vidéo par IA (l’objet de ces guides).
Replay : enregistrement et relecture vidéo dans le cloud.

Les droits d’accès déterminent ce que vous voyez : les solutions détenues par votre compte décident quelles applications apparaissent dans le sélecteur d’applications de l’application web. Les droits d’accès concernent la découvrabilité et l’accès : ils décident quelles surfaces vous sont ouvertes, et non la manière dont un clip donné est évalué.

Flows

Un flow est une unité de portée et de configuration au sein d’un tenant. Là où le tenant est la frontière d’isolation stricte, un flow vous permet de partitionner le travail à l’intérieur : par exemple, un flow par client, région ou intégration.

Les flows sont utiles lorsque vous :

Limitez un jeton ou un webhook. Un jeton API ou un webhook peut être rattaché à un flow spécifique pour que son trafic et sa livraison restent séparés.
Revoyez un sous-ensemble d’alarmes. L’application web permet de changer le flow actif pour concentrer le tableau de bord et l’espace de revue sur une seule tranche d’activité.

Voir Flows pour savoir quand en créer un et comment y limiter jetons et webhooks.

Sites et caméras

Gaard organise les caméras sous des sites :

Un site est un emplacement physique. Son identifiant est le SID.
Une caméra appartient à un site. Son identifiant est le CID.

Les pipelines Classify et Replay s’appuient tous deux sur CID/SID, de sorte qu’un résultat de classification et un segment enregistré renvoient à la même caméra physique, et l’application web route et filtre sur ces identifiants.

Il existe deux types de caméra :

Type de caméra	Créée par	Porte
Caméra API	Le trafic Classify, automatiquement	Uniquement une identité dérivée des métadonnées de la requête : aucun flux ni identifiants.
Caméra managée	Configurée explicitement	Une configuration complète de flux et d’identifiants (utilisée par Replay).

Comment les métadonnées correspondent à une caméra

Lorsque vous soumettez un clip via l’API, ses métadonnées portent des identifiants externes approximatifs. Gaard les normalise en une identité stable :

la clé de site est site_id
la clé de caméra est camera_id

La première fois que Gaard voit une nouvelle clé site/caméra, il crée automatiquement une caméra API (et son site) ; les clips suivants portant les mêmes clés se résolvent vers la même caméra. Les clips sans clé de site ou de caméra exploitable sont classifiés mais non rattachés à une caméra. Voir Métadonnées pour la liste complète des champs.

Niveaux de risque

Gaard expose trois et seulement trois niveaux de risque :

safe
danger
intrusion

Le niveau de risque est dérivé exclusivement du score intrusion à l’aide de deux seuils configurables. Les autres scores sont exposés à des fins d’observabilité, mais ils ne déterminent pas le niveau de risque.

Score d’intrusion	Niveau de risque	Signification opérationnelle
`< low_threshold`	`safe`	Activité normale de fond. Peut être filtrée.
`>= low_threshold` et `< high_threshold`	`danger`	Ambigu ou suspect. Doit être revu.
`>= high_threshold`	`intrusion`	Intrusion à forte confiance. Doit être revue et escaladée.

Les seuils typiques sont low_threshold = 0.2 et high_threshold = 0.8, et ils sont configurables par tenant. Tout ce qui n’est pas safe reste visible pour les opérateurs : jamais écarté automatiquement. Pour la dérivation complète, voir Risque, labels et scores.

Labels

Là où un score est la confiance brute du modèle et le niveau de risque la décision dérivée, un label est une étiquette attachée à une classification. Il en existe trois sortes :

Labels standard : les concepts intégrés reconnus par Gaard, comme person, vehicle, animal, flag, rain et wind.
Labels personnalisés : toute étiquette que votre équipe définit pour son propre suivi.

Labels de retour (feedback) : le verdict d’un opérateur indiquant si le modèle avait raison :

Label	Signification
`TP`	Vrai positif : Gaard a correctement signalé une menace.
`FP`	Faux positif : Gaard a signalé un clip sans menace réelle.
`FN`	Faux négatif : Gaard a manqué une menace réelle.
`TN`	Vrai négatif : Gaard a correctement classifié un clip comme safe.

Les labels de retour sont le moyen par lequel le modèle s’améliore avec le temps. Voir l’API Labels pour les endpoints, et Labels et retours pour le flux de travail opérateur.

Le cycle de vie de la classification

Chaque clip que vous soumettez devient une classification, identifiée par un classify_id (l’id de chaque réponse API). Vous utilisez cet identifiant pour interroger le résultat, attacher des labels ou télécharger la vidéo annotée.

Une classification passe par un ensemble de statuts :

Statut	Signification
`accepted`	Le clip a été accepté pour analyse.
`in-progress`	L’analyse est en cours.
`done`	L’analyse est terminée ; le résultat est disponible.
`error`	Une erreur s’est produite pendant l’analyse.
`timeout`	L’analyse a expiré.

Soumettez un clip de façon asynchrone et vous récupérez un classify_id immédiatement, puis vous interrogez jusqu’à ce que le statut soit done ; soumettez-le de façon synchrone (?sync=true) et Gaard bloque jusqu’à ce que le résultat soit prêt. Dans les deux cas, le résultat final (niveau de risque, labels, scores et highlight annoté) est rattaché à ce classify_id et accessible depuis toutes les surfaces. Voir Résultat de classification pour la structure complète du résultat.

Étapes suivantes

Démarrage rapide de l’application web : voir ces concepts dans l’espace de revue.
Démarrage rapide de l’API : soumettez votre premier clip et suivez son cycle de vie.
Risque, labels et scores : la référence détaillée des seuils.