Inferência (Inference)

A Ultralytics Platform fornece uma API de inferência para testar modelos treinados. Usa o separador Predict baseado no browser para uma validação rápida ou a REST API para acesso programático.

Aba de Prever

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

1. Navega para o teu modelo
2. Clica no separador Predict
3. Carrega uma imagem, usa um exemplo ou abre a tua webcam
4. Vê as predições instantaneamente com sobreposições de bounding box

Métodos de Entrada

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

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

    style D fill:#2196F3,color:#fff
    style E fill:#4CAF50,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áximo: 10MB
• Auto-inferência: Os resultados aparecem automaticamente após o carregamento

Imagens de Exemplo

O painel de predição mostra imagens de exemplo do dataset ligado ao teu modelo. Se não estiver nenhum dataset ligado, são usados exemplos predefinidos:

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

Webcam

Clica no cartão da webcam para iniciar um feed de câmara em direto:

1. Concede permissão de 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

Resultados da inferência exibidos:

• Bounding boxes com etiquetas de classe como sobreposições SVG
• Scores de confiança para cada deteção
• Cores da classe da paleta de cores do teu dataset (ou a paleta padrão da Ultralytics)
• Distribuição de velocidade: Pré-processamento, inferência, pós-processamento e tempo de rede

O painel de resultados mostra:

Parâmetros de Inferência

Ajusta o comportamento da deteção com parâmetros na secção expansível Parameters:

Threshold de Confiança

Filtrar predições por confiança:

• Mais alto (0.5+): Menos predições, com mais certeza
• Mais baixo (0.1-0.25): Mais predições, algum ruído
• Padrão (0.25): Equilibrado para a maioria dos casos de uso

Threshold de IoU

Controlar Non-Maximum Suppression:

• Mais alto (0.7+): Permitir mais caixas sobrepostas
• Mais baixo (0.3-0.5): Fundir deteções próximas de forma mais agressiva
• Padrão (0.7): Comportamento de NMS equilibrado para a maioria dos casos de uso

Predict de Deployment

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

REST API

Aceder à inferência programaticamente:

Autenticação

Inclui a tua chave de API nos pedidos:

Authorization: Bearer YOUR_API_KEY

Endpoint

POST https://platform.ultralytics.com/api/models/{modelId}/predict

Pedido

import requests

url = "https://platform.ultralytics.com/api/models/MODEL_ID/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
files = {"file": open("image.jpg", "rb")}
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

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,
        "model": "model.pt",
        "version": {
            "ultralytics": "8.x.x",
            "torch": "2.6.0",
            "torchvision": "0.21.0",
            "python": "3.13.0"
        }
    }
}

Campos de Resposta

Respostas Específicas por 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}
}

Faturamento

A inferência compartilhada (a aba Predict e o endpoint /api/models/{id}/predict) está incluída sem custo adicional em todos os planos. Não há cobranças por requisição para a inferência compartilhada.

Para cargas de trabalho de produção que exigem maior rendimento, implante um endpoint dedicado.

Limites de Taxa

A inferência compartilhada tem um limite de taxa de 20 requisições/min por chave de API. Quando o limite é excedido, a API retorna 429 com um cabeçalho Retry-After. Consulte a referência de limite de taxa completa 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:

• Endpoints dedicados 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. Consulte endpoints dedicados para detalhes.
• A inferência compartilhada (/api/models/{id}/predict) usa o mesmo serviço de predição e aceita os mesmos formatos de vídeo. No entanto, a aba Predict do navegador na interface só faz upload de imagens — use a REST API diretamente ou um endpoint dedicado para fluxos de trabalho de vídeo. O endpoint compartilhado também possui limite de taxa de 20 req/min, portanto, endpoints dedicados são a melhor escolha para cargas de trabalho de vídeo intensas.

Como obtenho a imagem anotada?

A API retorna predições em JSON. Para visualizar:

1. Use as prediçõ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")

Consulte a documentação do modo Predict para a API de resultados completa e opções de visualização.

Qual o tamanho máximo da imagem?

• Limite de upload: 10MB
• Recomendado: <5MB para inferência rápida
• Redimensionamento automático: As imagens são redimensionadas para o parâmetro Image Size selecionado

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

Posso executar inferência em lote?

A API atual processa uma imagem por requisição. Para processamento em lote:

1. Envie requisições concorrentes
2. Use um endpoint dedicado para maior rendimento
3. Considere 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))