Inferência#

Ultralytics Platform fornece inferência baseada no navegador para testar modelos treinados e endpoints dedicados para acesso programático.

Aba Predict#

Cada modelo inclui um separador Predict para inferência baseada no navegador:

1. Navegue até seu modelo
2. Clica no separador Predict
3. Carrega uma imagem, usa um exemplo ou abre a tua webcam
4. Revisa a sobreposição específica da tarefa, o resumo da predição, o tempo e a resposta bruta

Métodos de entrada#

O painel de previsão suporta vários métodos de entrada:

graph LR
    A[Upload Image]:::start --> D[Auto-Inference]:::proc
    B[Example Image]:::start --> D
    C[Webcam Capture]:::start --> D
    D --> E[Results + Overlays]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff

Carregar Imagem#

Arrasta e larga ou clica para carregar:

• Formatos suportados: JPEG, PNG, WebP, AVIF, HEIC, JP2, TIFF, BMP, DNG, MPO
• Tamanho máx.: 10MB
• Inferência automática: Os resultados aparecem automaticamente após o carregamento

Imagens de Exemplo#

O painel de previsão mostra imagens de exemplo do conjunto de dados ligado ao teu modelo. Se não houver nenhum conjunto de dados ligado, são usados exemplos padrão:

Para modelos OBB, são mostradas imagens aéreas de barcos e aeroportos.

Webcam#

Clica no cartão da webcam para iniciar uma transmissão de câmara ao vivo:

1. Concede permissão à câmara quando solicitado
2. Clica na pré-visualização de vídeo para capturar um fotograma
3. A inferência é executada automaticamente no fotograma capturado
4. Clica novamente para reiniciar a webcam

Ver Resultados#

Os resultados da inferência exibem a saída apropriada para a tarefa do modelo: caixas, máscaras, pontos-chave, caixas orientadas, escores de classificação, cobertura semântica ou um mapa de profundidade. Os resultados de objetos usam as cores de classe do conjunto de dados quando disponíveis. O painel também mostra o tempo de pré-processamento, inferência, pós-processamento e de rede.

O painel de resultados mostra:

Parâmetros de Inferência#

Ajusta o comportamento da inferência com os três controles deslizantes abaixo da imagem:

Limiar de Confiança#

Filtra as previsões por confiança:

• Mais alto (0.5+): Menos previsões, porém mais certas
• Mais baixo (0.1-0.25): Mais previsões, algum ruído
• Padrão (0.25): Equilibrado para a maioria dos casos de uso

Limiar IoU#

Controla a Supressão Não Máxima (NMS):

• Mais alto (0.7+): Permite mais caixas sobrepostas
• Inferior (0.3-0.5): Suprime detecções sobrepostas de forma mais agressiva
• Padrão (0.7): Comportamento de NMS equilibrado para a maioria dos casos de uso

Previsão de Implementação#

Cada endpoint dedicado em execução inclui um separador Predict diretamente no seu cartão de implementação. Isto utiliza o próprio serviço de inferência da implementação em vez do serviço de previsão partilhado, permitindo-te testar o teu endpoint implementado a partir do navegador.

API de Endpoint Dedicado#

O cartão API Docs na aba Predict do modelo contém exemplos de solicitações em Python, JavaScript e cURL. Os exemplos usam marcadores de posição até que implantar o modelo. Após a implantação, a aba Code do cartão de implantação preenche a URL do seu endpoint e a chave de API disponível para o seu workspace.

Autenticação#

Inclui a tua chave de API nos pedidos:

Authorization: Bearer YOUR_API_KEY

Endpoint#

POST https://YOUR_DEPLOYMENT_URL.run.app/predict

Pedido#

import requests

url = "https://YOUR_DEPLOYMENT_URL.run.app/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

with open("image.jpg", "rb") as image_file:
    response = requests.post(url, headers=headers, files={"file": image_file}, data=data)
print(response.json())

Parâmetros de solicitação#

Resposta#

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                },
                {
                    "class": 2,
                    "name": "car",
                    "confidence": 0.87,
                    "box": { "x1": 400, "y1": 200, "x2": 600, "y2": 350 }
                }
            ],
            "speed": {
                "preprocess": 1.2,
                "inference": 12.5,
                "postprocess": 2.3
            }
        }
    ],
    "metadata": {
        "imageCount": 1,
        "functionTimeCall": 0.018,
        "task": "detect",
        "version": {
            "ultralytics": "8.x.x",
            "torch": "2.6.0",
            "torchvision": "0.21.0",
            "python": "3.13.0"
        }
    }
}

Campos de Resposta#

Respostas específicas da tarefa#

O formato da resposta varia de acordo com a tarefa:

{
  "class": 0,
  "name": "person",
  "confidence": 0.92,
  "box": {"x1": 100, "y1": 50, "x2": 300, "y2": 400}
}

Limites de Taxa#

A API de modelo compartilhada é limitada a 20 solicitações/minuto para cada chave de API, chamador conectado ou IP anônimo. Quando limitada, a API retorna 429 com um cabeçalho Retry-After. Consulte a referência completa de limite de taxa para todas as categorias de endpoints.

Tratamento de erros#

Respostas de erro comuns:

FAQ#

Posso executar inferência em vídeo?#

Ambos os métodos de inferência aceitam arquivos de vídeo:

• Dedicated endpoints aceitam arquivos de vídeo diretamente. Formatos suportados (até 100 MB): ASF, AVI, GIF, M4V, MKV, MOV, MP4, MPEG, MPG, TS, WEBM, WMV. Cada quadro é processado individualmente e os resultados são retornados por quadro. Veja dedicated endpoints para detalhes.
• Inferência compartilhada (/api/models/{id}/predict) usa o mesmo serviço de predição e aceita os mesmos formatos de vídeo. A aba Predict do navegador seleciona apenas imagens, portanto use a API ou um endpoint dedicado para vídeos.

Como obtenho a imagem anotada?#

A API retorna previsões JSON. Para visualizar:

1. Use as previsões para desenhar caixas localmente
2. Use o método plot() da Ultralytics:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")
results = model("image.jpg")
results[0].save("annotated.jpg")

Veja a Predict mode documentation para a API completa de resultados e opções de visualização.

Qual é o tamanho máximo da imagem?#

• Limite da aba Predict: 10 MB
• Limite da API de endpoint dedicado: 100 MB
• Redimensionamento automático na aba Predict: As imagens são redimensionadas para o Image Size selecionado antes do upload

Imagens grandes são redimensionadas automaticamente mantendo a proporção.

Posso executar inferência em lote?#

A API atual processa uma imagem por solicitação. Para lote:

1. Envia solicitações separadas para cada imagem
2. Distribui solicitações entre endpoints dedicados quando apropriado
3. Usa inferência local para lotes grandes

import concurrent.futures

import requests

url = "https://predict-abc123.run.app/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
images = ["img1.jpg", "img2.jpg", "img3.jpg"]

def predict(image_path):
    with open(image_path, "rb") as f:
        return requests.post(url, headers=headers, files={"file": f}).json()

with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(predict, images))