Контролируй работоспособность и точность

Что показывает Platform#

Есть два важных ограничения. Метрики собираются только тогда, когда конечная точка имеет статус Ready, а удаление развёртывания закрывает доступ к его истории. Статистика и примеры на вкладке Monitoring пропадают при каждой остановке, перезагрузке, смене размера конечной точки или замене модели: это представление в реальном времени, а не архив.

Практический пример: регулярная проверка конечной точки#

В Platform карточка частоты ошибок становится красной при превышении 5%, а Slack может сообщать о готовности развёртывания или сбое запуска, но оповещений о превышении порогов нет. Запускай эту проверку каждые 5 минут через cron, CI или агент мониторинга и отправляй оповещение при ненулевом коде завершения:

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

При запуске с заглушкой API, которая возвращает работоспособную конечную точку, скрипт выводит одну строку и завершается с кодом 0; с P95_BUDGET_MS = 100 те же данные приводят к завершению с кодом 1:

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

• health проверяет доступность конечной точки и возвращает healthy, status и latencyMs. Кроме того, он запускает конечную точку, масштабированную до нуля, поэтому проверка каждые 5 минут одновременно поддерживает её в прогретом состоянии.
• metrics(..., view="overview") возвращает totalRequests, errorRate (процентное значение) и p95LatencyMs для заданного периода.
• logs получает последние ошибки и предупреждения, поэтому оповещение содержит первую подсказку о проблеме.

Установи SDK с помощью pip install -U ultralytics-platform (для SDK требуется Python 3.11 или новее). Отправляй оповещения только о сохраняющихся нарушениях, например после трёх неудачных проверок подряд, и добавь к каждому оповещению однострочную инструкцию по устранению проблемы.

Практический пример: отслеживание точности на контрольной выборке#

Метрики запросов не показывают точность. Для этого нужна контрольная выборка: 200–500 реалистичных производственных изображений, тщательно размеченных и сохранённых в отдельной закрытой версии набора данных, на которой никогда не обучали модель. Раз в неделю оценивай развёрнутый чекпойнт и добавляй результат в файл истории:

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

Первый запуск фиксирует базовый уровень точности на день развёртывания. Затем заранее проверь оповещение: этот скрипт создаёт копию контрольной выборки «ночная смена» с теми же метками и изображениями, яркость которых снижена до 15%:

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

Каждый запрос во время ночной смены по-прежнему получал бы ответ 200 за миллисекунды, хотя модель потеряла 5 пунктов mAP. Это заметно только по контрольной выборке. Ежеквартально обновляй контрольную выборку, добавляя новые размеченные производственные изображения, и сбрасывай базовый уровень при каждом развёртывании новой модели. В руководстве по мониторингу моделей и уроке Наблюдаемость и дрейф описаны статистические тесты на дрейф.

Отслеживай дрейф на вкладке Monitoring#

Зафиксируй форму графиков в неделю развёртывания, а затем сравнивай с ней новые данные. Уверенность показывает степень уверенности модели, а не правильность предсказания, поэтому оценивай эти графики вместе с контрольной выборкой:

Возвращай производственные изображения в набор данных#

На вкладке Monitoring выбери примеры и нажми Save to dataset; они пройдут стандартную загрузку, сохранив предсказания и регион deploymentId в метаданных. Шаблон агента Collect Uncertain Detections делает то же самое для всего набора данных: он выполняет предсказания с помощью твоего развёртывания и копирует изображения с обнаружениями в заданном диапазоне уверенности в набор для проверки.

Подводные камни#