Déployer et appeler un point de terminaison

Inférence partagée ou point de terminaison dédié#

Chaque modèle peut déjà être appelé via l’API d’inférence partagée de Platform, adaptée aux tests. Le trafic de production doit passer par un point de terminaison dédié :

Créer et dimensionner le point de terminaison#

Ouvre l’onglet Deploy du modèle. Ton navigateur mesure la latence vers les 42 régions (14 dans les Amériques, 13 en Europe, 12 en Asie-Pacifique, 3 au Moyen-Orient et en Afrique), puis trie le tableau en fonction de celle-ci :

Clique sur Deploy sur la ligne correspondant à la région la plus proche de tes utilisateurs, vérifie le CPU, la mémoire, le prix et le nom généré (par exemple yolo26n-iowa), puis clique sur Create Deployment. Tu peux aussi commencer avec New Deployment dans l’onglet Deployments de ton profil :

Dimensionne selon le profil de trafic :

Les forfaits autorisent 3 (Free), 10 (Pro) ou un nombre illimité (Enterprise) de déploiements, et les points de terminaison arrêtés sont aussi comptabilisés. Le point de terminaison accepte le trafic dès que son badge indique Ready :

Exemple détaillé : un client prêt pour la production#

Chaque point de terminaison dispose d’une URL comme https://predict-<id>-<hash>-<region>.a.run.app qui sert /predict (POST), /health et une page interactive /docs. Il n’accepte que la clé API associée lors de sa création ; les propriétaires de l’espace de travail voient cette clé préremplie dans l’onglet Predict du déploiement, sous Docs, à côté des extraits Python, JavaScript et cURL. Ces extraits effectuent une seule requête ; le code de production doit aussi gérer un démarrage à froid et une instance très sollicitée :

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

Nous l’avons testé avec un serveur factice local qui répond une fois à 429, puis renvoie un véritable résultat YOLO26n pour bus.jpg dans le format de réponse du point de terminaison :

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

Voici, ligne par ligne, les décisions importantes :

• timeout=90 couvre un démarrage à froid pouvant durer environ une minute ; les délais d’attente par défaut de la plupart des clients HTTP sont bien plus courts.
• Les erreurs 429 et 5xx font l’objet de nouvelles tentatives, en respectant Retry-After lorsque le point de terminaison l’envoie. Chaque point de terminaison traite les requêtes depuis une seule instance et rejette les requêtes excédentaires avec 429 lorsqu’il est surchargé.
• Les autres erreurs 4xx entraînent un échec immédiat : 401 indique une clé incorrecte et 413 un corps de requête dépassant 32 MB ; aucune de ces erreurs ne se corrige d’elle-même.
• La réponse contient une entrée par image (ou par image vidéo) dans images, chacune avec results (class, name, confidence, box avec x1, y1, x2, y2) et speed en millisecondes.

Les champs de formulaire facultatifs sont conf (valeur par défaut : 0.25), iou (0.7), imgsz (la taille utilisée pour entraîner le modèle), vid_stride pour la vidéo et normalize=true pour des coordonnées comprises entre 0 et 1. L’équivalent cURL utilise une ligne par champ :

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"

Déployer de nouvelles versions sans changer l’URL#

Replace model sur la page du déploiement remplace le modèle par un autre modèle terminé du même espace de travail. L’ancien modèle continue de répondre jusqu’à ce que le nouveau soit prêt, l’URL, la région et la clé restent identiques et, si le déploiement échoue, l’ancien modèle reste actif. Pour revenir en arrière, effectue la même action en sélectionnant le modèle précédent ; garde-le donc dans le projet. Update configuration redimensionne le déploiement sur place, et Stop suspend la facturation tout en conservant l’URL.

Certains changements nécessitent un nouveau point de terminaison : les régions sont fixes (pour en changer, supprime le point de terminaison et recrée-le avec une nouvelle URL) et les domaines personnalisés ne sont pas pris en charge. Si tes clients ont besoin d’un nom d’hôte de marque stable, place ta propre passerelle devant le point de terminaison. Pour exécuter le modèle en dehors de Platform, exporte-le (Exporter pour le déploiement) ou héberge-le toi-même derrière Triton Inference Server.

Pièges#