Implementa y llama a un endpoint

Inferencia compartida o endpoint dedicado#

Todos los modelos ya se pueden llamar mediante la API de inferencia compartida de Platform, adecuada para las pruebas. El tráfico de producción debe dirigirse a un endpoint dedicado:

Crear y dimensionar el endpoint#

Abre la pestaña Deploy del modelo. El navegador mide la latencia en las 42 regiones (14 en América, 13 en Europa, 12 en Asia-Pacífico y 3 en Oriente Medio y África) y ordena la tabla según esta:

Haz clic en Deploy en la fila más cercana a tus usuarios, revisa la CPU, la memoria, el precio y el nombre generado (como yolo26n-iowa) y haz clic en Create Deployment. También puedes empezar desde New Deployment en la pestaña Deployments de tu perfil:

Dimensiona según el patrón de tráfico:

Los planes permiten 3 implementaciones (Free), 10 (Pro) o un número ilimitado (Enterprise), y los endpoints detenidos también cuentan. El endpoint acepta tráfico cuando su indicador muestra Ready:

Ejemplo práctico: un cliente preparado para producción#

Cada endpoint tiene una URL como https://predict-<id>-<hash>-<region>.a.run.app que sirve /predict (POST), /health y una página interactiva /docs. Solo acepta la clave de API vinculada durante la creación; los propietarios del espacio de trabajo ven esa clave rellenada de antemano en la pestaña Predict de la implementación, en Docs, junto a fragmentos de código para Python, JavaScript y cURL. Los fragmentos de código realizan una solicitud; el código de producción también debe soportar un arranque en frío y una instancia ocupada:

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 probamos con un stub local que responde a 429 una vez y, después, devuelve un resultado real de YOLO26n para bus.jpg en el formato de respuesta del endpoint:

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

Estas son, línea por línea, las decisiones importantes:

• timeout=90 cubre un arranque en frío que puede tardar hasta aproximadamente un minuto; los tiempos de espera predeterminados de la mayoría de los clientes HTTP son mucho más cortos.
• Se reintenta ante errores 429 y 5xx, respetando Retry-After cuando el endpoint lo envía. Cada endpoint sirve desde una única instancia y rechaza carga con 429 cuando está ocupado.
• Los demás errores 4xx fallan enseguida: 401 significa que la clave no es correcta y 413 que el cuerpo supera los 32 MB; ninguno de los dos se soluciona por sí solo.
• La respuesta contiene una entrada por imagen (o por fotograma de vídeo) en images, cada una con results (class, name, confidence, box con x1, y1, x2, y2) y speed en milisegundos.

Los campos opcionales del formulario son conf (0,25 de forma predeterminada), iou (0,7), imgsz (el tamaño de entrenamiento del modelo), vid_stride para vídeo y normalize=true para coordenadas de 0 a 1. El equivalente en cURL es una línea por 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"

Publicar nuevas versiones sin cambiar la URL#

Replace model en la página de implementación sustituye el modelo por otro modelo completado del mismo espacio de trabajo. El modelo anterior sigue sirviendo hasta que el nuevo está listo; la URL, la región y la clave no cambian. Si el despliegue falla, el modelo anterior sigue activo. Para volver a la versión anterior, basta con realizar la misma acción y seleccionar el modelo anterior, así que consérvalo en el proyecto. Update configuration cambia el tamaño de la instancia y Stop pausa la facturación y conserva la URL.

Algunos cambios requieren un endpoint nuevo: las regiones son fijas (para cambiar de región, debes eliminar y volver a crear el endpoint, lo que genera una URL nueva) y no se admiten dominios personalizados. Por tanto, coloca tu propia pasarela delante si los clientes necesitan un nombre de host de marca estable. Para ejecutar el modelo fuera de Platform, expórtalo (Export for Deployment) o alójalo por tu cuenta detrás de Triton Inference Server.

Errores habituales#