Supervisar el estado y la precisión

Qué muestra Platform#

Dos salvedades condicionan todo lo demás. Solo se recopilan métricas mientras el endpoint está Ready, y al eliminar una implementación se pierde el acceso a su historial. Las estadísticas y los ejemplos de la pestaña Monitoring se pierden cada vez que se detiene o reinicia el endpoint, se cambia su tamaño o se sustituye su modelo: es una vista en directo, no un archivo.

Ejemplo práctico: una comprobación programada del endpoint#

Platform pone en rojo la tarjeta de tasa de errores cuando supera el 5 % y Slack puede avisar cuando una implementación está lista o no se inicia, pero no hay alertas por umbral. Ejecuta esta comprobación cada 5 minutos desde cron, CI o tu agente de supervisión, y envía una alerta si devuelve un código distinto de cero:

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

Al ejecutarlo con una API simulada que devuelve un endpoint saludable, muestra una línea y devuelve el código 0; con P95_BUDGET_MS = 100, los mismos datos devuelven el código 1:

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

• health comprueba el endpoint y devuelve healthy, status y latencyMs. También activa un endpoint cuya escala había llegado a cero, así que una programación cada 5 minutos sirve además como señal para mantenerlo activo.
• metrics(..., view="overview") devuelve totalRequests, errorRate (un porcentaje) y p95LatencyMs para el intervalo.
• logs obtiene los errores y advertencias más recientes, de modo que la alerta incluye una primera pista.

Instala el SDK con pip install -U ultralytics-platform (el SDK requiere Python 3.11 o posterior). Envía alertas solo si los umbrales se superan de forma sostenida; por ejemplo, tras tres comprobaciones fallidas seguidas. Añade a cada alerta una entrada de una línea en el manual de operaciones.

Ejemplo práctico: hacer seguimiento de la precisión con un conjunto de prueba#

Las métricas de solicitudes no pueden medir la precisión; un conjunto de prueba sí: entre 200 y 500 imágenes representativas de producción, etiquetadas con cuidado, en una versión privada propia de un conjunto de datos y nunca utilizadas para entrenar. Evalúa semanalmente el checkpoint implementado y añade los resultados a un archivo de historial:

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 primera ejecución registra la referencia del día de la implementación. Después, ensaya la alerta antes de necesitarla: este script crea una copia del conjunto de prueba para el «turno de noche», con las mismas etiquetas e imágenes al 15 % de brillo:

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

Todas las solicitudes durante el turno de noche seguirían devolviendo 200 en milisegundos, pero el modelo habría perdido 5 puntos de mAP. Solo el conjunto de prueba permite detectarlo. Actualiza el conjunto cada trimestre con imágenes de producción recién etiquetadas y restablece la referencia cada vez que implementes un modelo nuevo. La guía de supervisión de modelos y la lección Observabilidad y desviaciones explican las pruebas estadísticas de desviación.

Consulta la pestaña Monitoring para detectar desviaciones#

Anota la forma de los gráficos durante la semana en que implementes el modelo y compárala más adelante. La confianza mide la certeza, no la corrección, así que interpreta estos datos junto con los del conjunto de prueba:

Incorpora las imágenes de producción al flujo de trabajo#

En la pestaña Monitoring, selecciona ejemplos y haz clic en Save to dataset; se incorporan mediante el proceso de ingesta habitual, junto con sus predicciones, y conservan deploymentId y la región en sus metadatos. La plantilla Collect Uncertain Detections de Agents hace lo mismo con todo un conjunto de datos: predice mediante tu implementación y copia las imágenes con detecciones dentro de un intervalo de confianza a un conjunto de revisión.

Errores habituales#