Разверни и вызывай конечную точку

Общий инференс или отдельная конечная точка#

Любую модель уже можно вызывать через общий API инференса Platform — он подходит для тестирования. Для производственного трафика используй отдельную конечную точку:

Создай и настрой размер конечной точки#

Открой вкладку модели Deploy. Браузер измерит задержку до всех 42 регионов (14 в Северной и Южной Америке, 13 в Европе, 12 в Азиатско-Тихоокеанском регионе, 3 на Ближнем Востоке и в Африке) и отсортирует таблицу по этому показателю:

Нажми Deploy в строке региона, ближайшего к твоим клиентам, проверь CPU, объём памяти, цену и сгенерированное имя (например, yolo26n-iowa), затем нажми Create Deployment. Также можно начать с пункта New Deployment на вкладке Deployments в своём профиле:

Выбирай размер с учётом характера трафика:

Тарифы допускают 3 (Free), 10 (Pro) или неограниченное количество (Enterprise) развёртываний; остановленные конечные точки тоже учитываются. Конечная точка принимает трафик, когда её статус становится Ready:

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

У каждой конечной точки есть URL, например https://predict-<id>-<hash>-<region>.a.run.app, который обслуживает /predict (POST), /health и интерактивную страницу /docs. Она принимает только API-ключ, привязанный при создании; владельцы рабочего пространства видят этот ключ уже заполненным на вкладке Predict в разделе Docs развёртывания, рядом с примерами для Python, JavaScript и cURL. Примеры выполняют один запрос; производственный код должен также выдерживать холодный запуск и высокую нагрузку на экземпляр:

import os
import time
from collections import Counter

import httpx

URL = "https://YOUR_DEPLOYMENT_URL.run.app/predict"
HEADERS = {"Authorization": f"Bearer {os.environ['ULTRALYTICS_API_KEY']}"}  # the deployment's bound key, server-side only

def predict(client, path, conf=0.25, attempts=4):
    """POST one image; retry timeouts, 429, and 5xx with backoff; fail fast on other errors."""
    for attempt in range(attempts):
        try:
            with open(path, "rb") as f:
                r = client.post(URL, headers=HEADERS, data={"conf": conf}, files={"file": f}, timeout=90)
            if r.status_code < 400:
                return r.json()
            if r.status_code != 429 and r.status_code < 500:
                r.raise_for_status()  # 401 wrong key, 413 too large: retrying won't help
            wait, reason = float(r.headers.get("Retry-After", 2**attempt)), r.status_code
        except httpx.TimeoutException:  # a scaled-to-zero endpoint can take up to a minute to wake
            wait, reason = 2**attempt, "timeout"
        print(f"attempt {attempt + 1}: {reason}, retrying in {wait:.0f} s")
        time.sleep(wait)
    raise RuntimeError(f"endpoint still unavailable after {attempts} attempts")

with httpx.Client() as client:
    response = predict(client, "bus.jpg")
for image in response["images"]:
    counts = Counter(d["name"] for d in image["results"])
    print(f"{sum(counts.values())} objects {dict(counts)} in {image['speed']['inference']:.1f} ms")

Мы проверили его на локальной заглушке: она один раз отвечает 429, а затем возвращает настоящий результат YOLO26n для bus.jpg в формате ответа конечной точки:

attempt 1: 429, retrying in 2 s
5 objects {'bus': 1, 'person': 4} in 34.9 ms

Разберём важные решения построчно:

• timeout=90 учитывает холодный запуск длительностью до минуты; стандартные тайм-ауты большинства HTTP-клиентов намного короче.
• Для ошибок 429 и 5xx выполняются повторные попытки с учётом Retry-After, если конечная точка его отправляет. Каждая конечная точка обслуживает запросы одним экземпляром и при перегрузке ограничивает нагрузку с помощью 429.
• При других ошибках 4xx запрос сразу завершается с ошибкой: 401 означает неверный ключ, а 413 — что размер тела запроса превышает 32 MB; ни одна из этих проблем не исчезнет сама собой.
• Ответ содержит по одной записи на изображение (или видеокадр) в images; каждая запись включает results (class, name, confidence, box с x1, y1, x2, y2) и speed в миллисекундах.

Необязательные поля формы: conf (по умолчанию 0.25), iou (0.7), imgsz (размер, на котором обучалась модель), vid_stride для видео и normalize=true для координат в диапазоне 0–1. Эквивалентный вызов cURL — по одной строке на поле:

curl -X POST "https://YOUR_DEPLOYMENT_URL.run.app/predict" \
  -H "Authorization: Bearer $ULTRALYTICS_API_KEY" \
  -F "file=@bus.jpg" -F "conf=0.25" -F "iou=0.7" -F "imgsz=640"

Выпускай новые версии, не меняя URL#

Команда Replace model на странице развёртывания заменяет модель на другую завершённую модель из того же рабочего пространства. Старая модель продолжает работать, пока не будет готова новая; URL, регион и ключ остаются прежними. Если развёртывание новой модели завершится неудачей, предыдущая модель продолжит работу. Откат выполняется той же командой для предыдущей модели, поэтому не удаляй её из проекта. Команда Update configuration меняет размер на месте, а Stop приостанавливает оплату, сохраняя URL.

Для некоторых изменений нужна новая конечная точка: регионы нельзя изменить (для переноса нужно удалить конечную точку и создать заново, получив новый URL), а пользовательские домены не поддерживаются. Если клиентам нужно постоянное брендированное доменное имя, поставь перед конечной точкой собственный шлюз. Чтобы работать вне Platform, экспортируй модель (Экспорт для развёртывания) или размести её самостоятельно за Triton Inference Server.

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