Surveiller l’état de santé et la précision

Ce que Platform affiche#

Deux réserves conditionnent tout le reste. Les métriques sont collectées uniquement lorsque le point de terminaison est Ready, et la suppression d’un déploiement met fin à l’accès à son historique. Les statistiques et les exemples de l’onglet Monitoring sont perdus dès que le point de terminaison s’arrête, redémarre ou change de taille, ou que son modèle est remplacé : il s’agit d’une vue en direct, pas d’une archive.

Exemple détaillé : une vérification planifiée du point de terminaison#

Platform affiche en rouge la carte du taux d’erreur au-dessus de 5 %, et Slack peut signaler qu’un déploiement est prêt ou qu’il n’a pas démarré, mais il n’existe pas d’alertes de seuil. Exécute cette vérification toutes les 5 minutes depuis cron, CI ou ton agent de surveillance, et déclenche une alerte en cas de code de sortie non nul :

from ultralytics_platform import Platform

OWNER, DEPLOYMENT = "your-username", "yolo26n-iowa"  # from the deployment page URL
P95_BUDGET_MS, MAX_ERROR_RATE = 300, 1.0  # errorRate is a percentage

with Platform() as client:  # reads ULTRALYTICS_API_KEY
    health = client.deployments.health(OWNER, DEPLOYMENT)
    summary = client.deployments.metrics(OWNER, DEPLOYMENT, range="1h", view="overview")["summary"]
    print(
        f"healthy={health['healthy']} requests={summary['totalRequests']} "
        f"p95={summary['p95LatencyMs']:.0f} ms errors={summary['errorRate']:.2f}%"
    )
    if not health["healthy"] or summary["p95LatencyMs"] > P95_BUDGET_MS or summary["errorRate"] > MAX_ERROR_RATE:
        for entry in client.deployments.logs(OWNER, DEPLOYMENT, severity="ERROR,WARNING", limit=5)["entries"]:
            print(entry["timestamp"], entry["severity"], entry["message"][:120])
        raise SystemExit(1)  # non-zero exit lets cron, CI, or your pager treat it as an alert

Exécuté contre une API factice qui renvoie un point de terminaison en bonne santé, le script affiche une ligne et renvoie le code de sortie 0 ; avec P95_BUDGET_MS = 100, les mêmes données renvoient le code de sortie 1 :

healthy=True requests=1200 p95=180 ms errors=0.40%

• health vérifie le point de terminaison et renvoie healthy, status et latencyMs. Il réveille aussi un point de terminaison dont la mise à l’échelle est descendue à zéro ; une vérification toutes les 5 minutes sert donc également de signal pour le maintenir actif.
• metrics(..., view="overview") renvoie totalRequests, errorRate (un pourcentage) et p95LatencyMs pour la période.
• logs récupère les dernières erreurs et les derniers avertissements, afin que l’alerte fournisse un premier indice.

Installe le SDK avec pip install -U ultralytics-platform (le SDK nécessite Python 3.11 ou une version ultérieure). Ne déclenche une alerte qu’en cas de dépassement prolongé, par exemple après trois vérifications consécutives en échec, et associe à chaque alerte une procédure d’intervention d’une ligne.

Exemple détaillé : suivre la précision avec un jeu de validation#

Les métriques des requêtes ne mesurent pas la précision. Un jeu de validation le permet : 200 à 500 images représentatives de la production, soigneusement annotées, dans leur propre version privée d’un jeu de données, et jamais utilisées pour l’entraînement. Évalue chaque semaine le point de contrôle déployé et ajoute les résultats à un fichier historique :

import json
import sys
from datetime import date
from pathlib import Path

from ultralytics import YOLO

DEPLOYED = "pills-v1.pt"  # the exact best.pt behind the endpoint
HOLDOUT = sys.argv[1] if len(sys.argv) > 1 else "medical-pills.yaml"  # labeled, never trained on

metrics = YOLO(DEPLOYED).val(data=HOLDOUT, split="val", plots=False, verbose=False)
history = Path("holdout_history.jsonl")
rows = [json.loads(line) for line in history.read_text().splitlines()] if history.exists() else []
row = {"date": date.today().isoformat(), "data": HOLDOUT, "map50_95": round(float(metrics.box.map), 4)}
history.write_text("".join(json.dumps(r) + "\n" for r in [*rows, row]))

baseline = rows[0]["map50_95"] if rows else row["map50_95"]
drop = baseline - row["map50_95"]
print(f"holdout mAP50-95 {row['map50_95']:.3f} (baseline {baseline:.3f}, drop {drop:+.3f})")
if drop > 0.01:  # more than 1 mAP point below the deployment-day baseline
    raise SystemExit("ALERT: holdout accuracy regressed - open the retraining runbook")

La première exécution consigne la référence du jour du déploiement. Simule ensuite l’alerte avant d’en avoir besoin : ce script crée une copie du jeu de validation « équipe de nuit », avec les mêmes annotations et les mêmes images à 15 % de luminosité :

import shutil
from pathlib import Path

import cv2

from ultralytics.data.utils import check_det_dataset

src = Path(check_det_dataset("medical-pills.yaml")["path"])
dst = Path("pills-night")
(dst / "images/val").mkdir(parents=True, exist_ok=True)
for img in (src / "images/val").glob("*.jpg"):  # darken every holdout image to mimic a dim night shift
    cv2.imwrite(str(dst / "images/val" / img.name), (cv2.imread(str(img)) * 0.15).astype("uint8"))
shutil.copytree(src / "labels/val", dst / "labels/val", dirs_exist_ok=True)  # same labels, darker pixels
Path("pills-night.yaml").write_text(f"path: {dst.resolve()}\ntrain: images/val\nval: images/val\nnames:\n  0: pill\n")
print("wrote pills-night.yaml")

$ python holdout_check.py
holdout mAP50-95 0.659 (baseline 0.659, drop +0.000)
$ python simulate_night_shift.py
wrote pills-night.yaml
$ python holdout_check.py pills-night.yaml
holdout mAP50-95 0.609 (baseline 0.659, drop +0.050)
ALERT: holdout accuracy regressed - open the retraining runbook

Toutes les requêtes pendant l’équipe de nuit renverraient toujours 200 en quelques millisecondes, alors que la précision du modèle a chuté de 5 points de mAP. Seul le jeu de validation permet de le détecter. Actualise le jeu de validation chaque trimestre avec de nouvelles images de production annotées, et réinitialise la référence à chaque déploiement d’un nouveau modèle. Le guide de surveillance des modèles et la leçon Observabilité et dérive présentent les tests statistiques de dérive.

Détecter la dérive dans l’onglet Monitoring#

Observe la forme des graphiques pendant la semaine du déploiement, puis compare-la à celle des semaines suivantes. La confiance mesure le degré de certitude, pas l’exactitude ; interprète donc ces données en parallèle avec celles du jeu de validation :

Réinjecter les images de production#

Dans l’onglet Monitoring, sélectionne des exemples et clique sur Save to dataset ; ils sont soumis au processus d’ingestion habituel avec leurs prédictions, et deploymentId ainsi que la région sont conservés dans leurs métadonnées. Le modèle Collect Uncertain Detections d’Agents fait de même pour un jeu de données entier : il effectue les prédictions avec ton déploiement et copie dans un jeu de données de révision les images contenant des détections dont la confiance se situe dans une plage donnée.

Pièges#