Monitore a integridade e a precisão

O que a Platform mostra#

Duas ressalvas determinam todo o resto. As métricas são coletadas somente enquanto o endpoint está Ready, e excluir uma implantação encerra o acesso ao histórico dela. As estatísticas e os exemplos da guia Monitoring são perdidos sempre que o endpoint para, reinicia, é redimensionado ou tem o modelo substituído: é uma visualização ao vivo, não um arquivo.

Exemplo prático: uma verificação agendada do endpoint#

A Platform deixa o cartão de taxa de erros vermelho quando ultrapassa 5%, e o Slack pode anunciar quando uma implantação fica pronta ou falha ao iniciar, mas não há alertas por limite. Execute esta verificação a cada 5 minutos usando cron, CI ou seu agente de monitoramento e envie um alerta se o código de saída for diferente de zero:

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

Quando executado com uma API simulada que retorna um endpoint íntegro, o código exibe uma linha e retorna 0; com P95_BUDGET_MS = 100, os mesmos dados retornam 1:

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

• health verifica o endpoint e retorna healthy, status e latencyMs. Também ativa um endpoint cuja escala chegou a zero, então uma verificação a cada 5 minutos funciona como uma chamada para mantê-lo aquecido.
• metrics(..., view="overview") retorna totalRequests, errorRate (uma porcentagem) e p95LatencyMs para o intervalo.
• logs busca os erros e avisos mais recentes, para que o alerta já chegue com uma primeira pista.

Instale o SDK com pip install -U ultralytics-platform (o SDK exige Python 3.11 ou superior). Envie alertas somente para violações persistentes, por exemplo, três verificações com falha consecutivas, e inclua em cada alerta uma entrada de runbook de uma linha.

Exemplo prático: acompanhe a precisão com um holdout#

As métricas das solicitações não mostram a precisão, mas um holdout pode: 200–500 imagens realistas de produção, rotuladas cuidadosamente em uma versão privada própria do conjunto de dados, nunca usadas no treinamento. Avalie semanalmente o checkpoint implantado e acrescente os resultados a um arquivo de histórico:

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")

A primeira execução registra a linha de base do dia da implantação. Em seguida, ensaie o alerta antes de precisar dele: este script cria uma cópia do holdout do "turno da noite", com os mesmos rótulos e imagens a 15% de brilho:

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 as solicitações durante o turno da noite ainda retornariam 200 em milissegundos, mas o modelo perdeu 5 pontos de mAP. Só o holdout detecta isso. Atualize o holdout a cada trimestre com novas imagens de produção rotuladas e redefina a linha de base sempre que implantar um novo modelo. O guia de monitoramento de modelos e a lição Observabilidade e deriva abordam testes estatísticos de deriva.

Leia a guia Monitoring para detectar deriva#

Observe o formato dos gráficos na semana da implantação e depois compare. A confiança mede a certeza, não a correção; por isso, analise estes dados junto com o holdout:

Incorpore imagens de produção ao conjunto de dados#

Na guia Monitoring, selecione exemplos e clique em Save to dataset; eles passam pelo processo normal de ingestão, junto com as previsões, e mantêm deploymentId e a região nos metadados. O modelo Collect Uncertain Detections de Agents faz o mesmo para um conjunto de dados inteiro: prevê usando sua implantação e copia as imagens com detecções dentro de um intervalo de confiança para um conjunto de dados de revisão.

Armadilhas#