Distribuire e chiamare un endpoint

Inferenza condivisa o endpoint dedicato#

Ogni modello può già essere chiamato tramite l'API di inferenza condivisa di Platform, adatta ai test. Per il traffico di produzione, usa un endpoint dedicato:

Crea e dimensiona l'endpoint#

Apri la scheda Deploy del modello. Il browser misura la latenza verso tutte le 42 regioni (14 nelle Americhe, 13 in Europa, 12 nell'Asia-Pacifico, 3 in Medio Oriente e Africa) e ordina la tabella in base a questo valore:

Fai clic su Deploy nella riga più vicina ai tuoi utenti, controlla CPU, memoria, prezzo e nome generato (ad esempio yolo26n-iowa), quindi fai clic su Create Deployment. Puoi anche iniziare da New Deployment nella scheda Deployments del tuo profilo:

Scegli le dimensioni in base al tipo di traffico:

I piani consentono 3 (Free), 10 (Pro) o un numero illimitato (Enterprise) di distribuzioni; anche gli endpoint arrestati vengono conteggiati. L'endpoint accetta traffico quando il badge indica Ready:

Esempio pratico: un client pronto per la produzione#

Ogni endpoint ha un URL come https://predict-<id>-<hash>-<region>.a.run.app e serve /predict (POST), /health e una pagina interattiva /docs. Accetta solo la chiave API associata al momento della creazione; i proprietari dell'area di lavoro vedono quella chiave già compilata nella scheda Predict della distribuzione, sotto Docs, accanto agli snippet per Python, JavaScript e cURL. Gli snippet effettuano una singola richiesta; il codice di produzione deve gestire anche un avvio a freddo e un'istanza sotto carico:

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

Lo abbiamo testato con uno stub locale che risponde una volta a 429 e poi restituisce un risultato reale di YOLO26n per bus.jpg nel formato di risposta dell'endpoint:

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

Ecco, riga per riga, le decisioni importanti:

• timeout=90 copre un avvio a freddo che può durare fino a circa un minuto; i timeout predefiniti della maggior parte dei client HTTP sono molto più brevi.
• Gli errori 429 e 5xx vengono ritentati, rispettando Retry-After quando l'endpoint lo invia. Ogni endpoint serve le richieste da una singola istanza e, quando è sotto carico, rifiuta le richieste con 429.
• Gli altri errori 4xx interrompono subito l'operazione: 401 indica una chiave errata e 413 un corpo superiore a 32 MB; nessuno dei due problemi si risolve da solo.
• La risposta contiene una voce per ogni immagine (o fotogramma video) in images, ciascuna con results (class, name, confidence, box con x1, y1, x2, y2) e speed in millisecondi.

I campi facoltativi del modulo sono conf (predefinito 0.25), iou (0.7), imgsz (la dimensione di addestramento del modello), vid_stride per i video e normalize=true per le coordinate da 0 a 1. L'equivalente in cURL prevede una riga per campo:

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"

Distribuisci nuove versioni senza cambiare l'URL#

Replace model nella pagina della distribuzione sostituisce il modello con un altro modello completato della stessa area di lavoro. Il vecchio modello continua a servire le richieste finché il nuovo non è pronto; URL, regione e chiave rimangono invariati e, se il rilascio non riesce, il modello precedente resta attivo. Per ripristinare la versione precedente basta eseguire la stessa operazione selezionando il modello precedente: conservalo quindi nel progetto. Update configuration modifica le dimensioni senza ricreare l'endpoint e Stop sospende la fatturazione mantenendo l'URL.

Alcune modifiche richiedono un nuovo endpoint: le regioni sono fisse (per spostarlo, devi eliminarlo e ricrearlo ottenendo un nuovo URL) e i domini personalizzati non sono supportati; se i client hanno bisogno di un nome host stabile e personalizzato, anteponi il tuo gateway. Per eseguire il modello al di fuori della piattaforma, esportalo (Esporta per la distribuzione) oppure ospitalo autonomamente dietro Triton Inference Server.

Insidie#