Einen Endpunkt bereitstellen und aufrufen

Gemeinsame Inferenz oder dedizierter Endpunkt#

Jedes Modell lässt sich bereits über die gemeinsame Inferenz-API von Platform aufrufen, die sich für Tests eignet. Für den Produktionseinsatz solltest du einen dedizierten Endpunkt verwenden:

Endpunkt erstellen und dimensionieren#

Öffne den Tab Deploy des Modells. Dein Browser misst die Latenz zu allen 42 Regionen (14 in Amerika, 13 in Europa, 12 im asiatisch-pazifischen Raum, 3 im Nahen Osten und in Afrika) und sortiert die Tabelle danach:

Klicke in der Zeile der Region, die deinen Aufrufern am nächsten liegt, auf Deploy, überprüfe CPU, Arbeitsspeicher, Preis und den generierten Namen (z. B. yolo26n-iowa) und klicke auf Create Deployment. Du kannst auch über New Deployment im Tab „Deployments“ deines Profils beginnen:

Dimensioniere nach dem Verkehrsmuster:

Die Tarife erlauben 3 (Free), 10 (Pro) oder unbegrenzt viele (Enterprise) Bereitstellungen; auch gestoppte Endpunkte werden mitgezählt. Der Endpunkt nimmt Traffic entgegen, sobald sein Status Ready anzeigt:

Praxisbeispiel: Ein Client, der den Produktivbetrieb übersteht#

Jeder Endpunkt hat eine URL wie https://predict-<id>-<hash>-<region>.a.run.app und stellt /predict (POST), /health sowie eine interaktive Seite /docs bereit. Er akzeptiert nur den bei der Erstellung gebundenen API-Schlüssel; Eigentümer des Arbeitsbereichs sehen diesen Schlüssel im Tab Predict der Bereitstellung unter Docs vorausgefüllt, neben Codebeispielen für Python, JavaScript und cURL. Die Codebeispiele senden jeweils eine Anfrage; Produktivcode muss auch einen Kaltstart und eine ausgelastete Instanz überstehen:

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

Wir haben den Code mit einem lokalen Stub getestet, der einmal 429 zurückgibt und danach ein echtes YOLO26n-Ergebnis für bus.jpg im Antwortformat des Endpunkts liefert:

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

Die wichtigen Entscheidungen im Einzelnen:

• timeout=90 deckt einen Kaltstart von bis zu etwa einer Minute ab; die Standard-Timeouts der meisten HTTP-Clients sind viel kürzer.
• 429- und 5xx-Fehler werden erneut versucht; dabei wird Retry-After berücksichtigt, wenn der Endpunkt diesen Wert sendet. Jeder Endpunkt verarbeitet Anfragen über eine einzelne Instanz und weist bei hoher Auslastung mit 429 Last ab.
• Bei anderen 4xx-Fehlern wird der Vorgang sofort abgebrochen: 401 bedeutet, dass der falsche Schlüssel verwendet wurde, und 413, dass der Inhalt mehr als 32 MB umfasst. Keiner dieser Fehler behebt sich von selbst.
• Die Antwort enthält in images einen Eintrag pro Bild (oder Videobild), jeweils mit results (class, name, confidence, box mit x1, y1, x2, y2) und speed in Millisekunden.

Optionale Formularfelder sind conf (Standardwert 0.25), iou (0.7), imgsz (Trainingsgröße des Modells), vid_stride für Video und normalize=true für Koordinaten im Bereich 0–1. Das entsprechende cURL-Beispiel enthält eine Zeile pro Feld:

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"

Neue Versionen bereitstellen, ohne die URL zu ändern#

Mit Replace model auf der Bereitstellungsseite wird ein anderes fertiggestelltes Modell aus demselben Arbeitsbereich eingesetzt. Das alte Modell wird weiterverwendet, bis das neue bereit ist; URL, Region und Schlüssel bleiben gleich. Schlägt die Einführung fehl, bleibt das vorherige Modell aktiv. Für ein Rollback verwendest du dieselbe Aktion mit dem vorherigen Modell. Lass es daher im Projekt. Mit Update configuration änderst du die Größe direkt, und Stop pausiert die Abrechnung und behält die URL bei.

Für manche Änderungen brauchst du einen neuen Endpunkt: Regionen sind festgelegt (für einen Wechsel musst du den Endpunkt löschen und neu erstellen, wobei eine neue URL entsteht), und benutzerdefinierte Domains werden nicht unterstützt. Schalte daher dein eigenes Gateway vor, wenn Aufrufer einen stabilen, gebrandeten Hostnamen benötigen. Um das Modell außerhalb der Platform auszuführen, exportiere das Modell (Für die Bereitstellung exportieren) oder hoste es selbst hinter dem Triton Inference Server.

Stolperfallen#