Implementar e chamar um endpoint

Inferência partilhada ou endpoint dedicado#

Já podes chamar qualquer modelo através da API de inferência partilhada da Platform, adequada para testes. O tráfego de produção deve usar um endpoint dedicado:

Criar e dimensionar o endpoint#

Abra a guia Deploy do modelo. Seu navegador mede a latência para todas as 42 regiões (14 nas Américas, 13 na Europa, 12 na Ásia-Pacífico, 3 no Oriente Médio e na África) e ordena a tabela por latência:

Clique em Deploy na linha mais próxima dos seus clientes, confira a CPU, a memória, o preço e o nome gerado (como yolo26n-iowa) e clique em Create Deployment. Você também pode começar por New Deployment na guia Deployments do seu perfil:

Dimensione de acordo com o padrão de tráfego:

Os planos permitem 3 implantações (Free), 10 (Pro) ou um número ilimitado (Enterprise), e os endpoints interrompidos ainda contam. O endpoint aceita tráfego quando o selo mostra Ready:

Exemplo prático: um cliente que resiste em produção#

Cada endpoint tem uma URL como https://predict-<id>-<hash>-<region>.a.run.app que serve /predict (POST), /health e uma página interativa /docs. Ele aceita somente a chave de API vinculada na criação; os proprietários do workspace veem essa chave preenchida previamente na guia Predict da implantação, em Docs, ao lado dos exemplos de Python, JavaScript e cURL. Os exemplos fazem uma solicitação; o código de produção também precisa lidar com uma inicialização a frio e uma instância 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")

Testamos com um stub local que responde 429 uma vez e, em seguida, retorna um resultado real do YOLO26n para bus.jpg no formato de resposta do endpoint:

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

As decisões importantes, linha por linha:

• timeout=90 cobre uma inicialização a frio de até cerca de um minuto; os tempos limite padrão da maioria dos clientes HTTP são bem mais curtos.
• Erros 429 e 5xx são repetidos, respeitando Retry-After quando o endpoint o envia. Cada endpoint atende por uma única instância e reduz a carga com 429 quando está ocupado.
• Os outros erros 4xx falham imediatamente: 401 significa que a chave está errada e 413 indica um corpo com mais de 32 MB; nenhum dos dois se corrige sozinho.
• A resposta contém uma entrada por imagem (ou por quadro de vídeo) em images, cada uma com results (class, name, confidence, box com x1, y1, x2, y2) e speed em milissegundos.

Os campos opcionais do formulário são conf (padrão 0.25), iou (0.7), imgsz (o tamanho de treinamento do modelo), vid_stride para vídeo e normalize=true para coordenadas de 0 a 1. O equivalente em cURL usa uma linha 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"

Envie novas versões sem alterar a URL#

Replace model na página da implantação substitui o modelo por outro modelo concluído do mesmo workspace. O modelo antigo continua atendendo até que o novo esteja pronto; a URL, a região e a chave permanecem iguais e, se a implantação falhar, o modelo anterior continua ativo. Para reverter, basta executar a mesma ação selecionando o modelo anterior, então mantenha-o no projeto. Update configuration redimensiona a implantação no local, e Stop pausa a cobrança e mantém a URL.

Algumas alterações exigem um novo endpoint: as regiões são fixas (para mudar, é preciso excluir e recriar, gerando uma nova URL), e domínios personalizados não são aceitos; portanto, coloque seu próprio gateway na frente se os clientes precisarem de um nome de host de marca estável. Para executar fora da Platform, exporte o modelo (Export for Deployment) ou hospede-o por conta própria usando o Triton Inference Server.

Armadilhas#