Inferência#

A Ultralytics Platform disponibiliza inferência no browser para testar modelos treinados e endpoints dedicados para acesso programático.

Aba Previsão#

Todos os modelos com pesos incluem um separador Predict para inferência no browser:

1. Navega até ao teu modelo
2. Clica no separador Predict
3. Carrega uma imagem, usa um exemplo ou abre a webcam
4. Revê a sobreposição específica da tarefa, o resumo da previsão, os tempos e a resposta em bruto

Os modelos sem pesos apresentam um estado vazio — primeiro, treina o modelo ou carrega os pesos.

Métodos de entrada#

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

Carregar imagem#

Arrasta e larga ou clica para carregar:

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

Imagens de exemplo#

O painel de previsão apresenta até duas imagens de exemplo do conjunto de dados associado ao teu modelo, dando preferência à divisão val, depois test e, por fim, train. Se não houver nenhum conjunto de dados associado, são usados exemplos predefinidos:

Nos modelos OBB, são apresentadas imagens aéreas de barcos e de um aeroporto.

Webcam#

Seleciona Webcam acima da área da imagem para iniciar uma transmissão de vídeo em direto:

1. Concede permissão para usar a câmara quando te for pedido
2. Clica na pré-visualização do vídeo para capturar um fotograma
3. A inferência é executada automaticamente no fotograma capturado
4. Clica em Voltar à webcam para regressar à transmissão em direto

Na separador Predict da tua própria implementação, a webcam executa inferência continuamente. Consulta Inferência com câmara em direto.

Ver resultados#

Os resultados da inferência apresentam a saída adequada à tarefa do modelo: caixas, máscaras, pontos-chave, caixas orientadas, pontuações de classificação, cobertura semântica ou um mapa de profundidade. Quando disponíveis, os resultados dos objetos usam as cores das classes do conjunto de dados. O painel também apresenta os tempos de pré-processamento, inferência, pós-processamento e rede.

O painel de resultados apresenta:

Quando há resultados, aparecem dois controlos sobre a pré-visualização: clica na imagem para a ampliar sem remover as sobreposições e usa o botão de descarregamento para guardar um JPEG anotado do resultado atual.

Parâmetros de inferência#

Ajusta o comportamento da inferência com os três controles deslizantes abaixo da imagem (os modelos de profundidade mostram apenas Image Size):

Limiar de confiança#

Filtra as previsões por confiança:

• Mais alto (0.5+): menos previsões, mais confiáveis
• 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 de IoU#

Controla a supressão não máxima:

• Mais alto (0.7+): permite mais caixas sobrepostas
• Mais baixo (0.3-0.5): suprime deteções sobrepostas de forma mais agressiva
• Padrão (0.7): comportamento equilibrado da NMS para a maioria dos casos de uso

Inferência de implantação#

Cada endpoint dedicado em execução inclui uma guia Predict na respetiva página de implantação. Esta guia usa o próprio serviço de inferência da implantação, em vez do serviço de inferência partilhado, permitindo testar o endpoint implantado no navegador.

Num endpoint pronto, as imagens processadas também contribuem para a guia Monitoring. Os exemplos e gráficos agregados são dados temporários leves mantidos na memória; parar, reiniciar, reimplantar, redimensionar ou substituir o modelo pode apagá-los. Guarda os exemplos num conjunto de dados para os manter.

Inferência com câmara em direto#

No separador Predict de uma implementação que te pertence, seleciona Webcam ou Câmara IP para executar o endpoint em vídeo em direto:

A inferência em direto usa a chave API associada ao endpoint, que só o proprietário do espaço de trabalho pode carregar; para os outros membros da equipa, a webcam captura fotogramas individuais e a Câmara IP não está disponível, tal como no separador Predict de um modelo. A câmara IP tem de estar acessível a partir da Internet: o endpoint recusa endereços de rede local como 192.168.x.x. Cada resultado corresponde ao fotograma mais recente, pelo que alguns fotogramas são ignorados quando a inferência fica para trás. As alterações dos controlos deslizantes aplicam-se ao próximo fotograma da webcam e reiniciam o fluxo da câmara IP. A inferência em direto é pausada quando o separador do navegador fica oculto. Clica na pré-visualização para capturar um fotograma, ou em Desligar para deixar de ver a câmara IP.

Câmara em segundo plano#

Um endpoint com tamanho personalizado de CPU e memória pode continuar a monitorizar uma câmara IP depois de desligar ou fechar a página. Quando a câmara ligada apresentar resultados, ativa Manter em execução em segundo plano. O cabeçalho da implementação apresenta Câmara ligada, e os resultados são enviados para o separador Monitorização como exemplos temporários e estatísticas de predição.

• Definições: A câmara em segundo plano usa sempre a confiança predefinida (0.25), IoU (0.7) e o tamanho de imagem de treino do modelo; os controlos deslizantes não se aplicam a esta câmara.
• Custo: É executada na instância ativa do endpoint sem custos adicionais; a tarifa horária de disponibilidade aplica-se quer a câmara esteja ligada quer esteja desligada.
• Alterações: Ligar ou desligar a câmara, ou mudar para outra câmara, reinicia a instância do endpoint, mantendo o endpoint pronto, mas limpando os dados temporários de monitorização.
• Parar: Desativa o interruptor. Desligar ou fechar a página não para a câmara, e redimensionar o endpoint para o tamanho predefinido remove-a. Se a câmara ficar offline, o endpoint continua a tentar restabelecer a ligação.
• Ciclo de vida do endpoint: Parar o endpoint para a câmara e as cobranças; ao iniciá-lo novamente, a câmara guardada retoma a execução.

Os endpoints de tamanho predefinido permitem inferência em direto com webcam e câmara IP, sem a opção de execução em segundo plano. Para guardar uma câmara em segundo plano através da API, usa a ação camera da implementação.

Transmitir resultados da API#

Envia um URL RTSP ou RTSPS como source, com o cabeçalho Accept: text/event-stream, para um URL de endpoint dedicado para receber resultados como eventos enviados pelo servidor:

curl -N -X POST \
  "https://YOUR_DEPLOYMENT_URL.run.app/predict" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -F "source=rtsp://user:password@camera.example.com:554/stream" \
  -F "conf=0.25"

Cada evento de fotograma contém images no formato da resposta, com coordenadas normalizadas (0-1), um URL de dados JPEG preview do fotograma e metadata com a tarefa e os nomes das classes. Só se aplicam conf, iou e imgsz, e a transmissão do URL da câmara em segundo plano do endpoint usa as definições predefinidas. Os eventos que contêm apenas status não incluem um fotograma, e um evento com uma mensagem error (não foi possível ler a câmara ou o endpoint não consegue executar o modelo) termina o fluxo. O fluxo também fecha quando o endpoint é reiniciado ou o pedido atinge o limite de tempo; por isso, volta a ligar-te com um intervalo crescente quando terminar sem erro. A rota de predição de implementações e o SDK da API da Plataforma não fazem transmissão; envia os pedidos da câmara para o URL do endpoint com a chave API associada. Um pedido de câmara source sem o cabeçalho devolve 400.

API do endpoint dedicado#

O cartão API Docs na guia Predict do modelo contém exemplos de pedidos em Python, JavaScript e cURL, preenchidos previamente com os valores de confiança, IoU e tamanho da imagem definidos atualmente nos controles deslizantes. O URL e a chave são marcadores de posição até implantares o modelo — um botão Deploy junto às guias de código leva à guia Deploy do modelo. Após a implantação, a guia de resultado Docs na guia Predict da página de implantação preenche o URL desse endpoint e, para os proprietários do espaço de trabalho, a respetiva chave de API associada, pronta para copiar e executar.

Autenticação#

Inclui a tua chave de API nos pedidos:

Authorization: Bearer YOUR_API_KEY

Endpoint#

Os endpoints dedicados recebem pedidos no respetivo URL:

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

A inferência partilhada usa a API da Platform com o caminho completo do modelo:

POST https://platform.ultralytics.com/api/models/{owner}/{project}/{model}/predict

Ambos aceitam o mesmo corpo multipart/form-data e devolvem respostas com a mesma estrutura. Com o SDK de Python, usa client.models.predict(owner, project, model, body=...) para inferência partilhada ou client.deployments.predict(owner, deployment, body=...) para uma implantação dedicada. Ambos os métodos do SDK chamam a API da Platform, pelo que se aplicam os limites de taxa e o limite de tamanho dos pedidos. Para os evitar, envia o pedido diretamente para um URL de endpoint dedicado, conforme indicado em Pedido. Exemplo de inferência partilhada:

from ultralytics_platform import Platform

client = Platform()  # reads ULTRALYTICS_API_KEY
with open("image.jpg", "rb") as f:
    results = client.models.predict("acme-vision", "inspection", "v3", body={"file": f, "conf": 0.25})

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 do pedido#

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,
        "classNames": ["person", "bicycle", "car", "..."],
        "functionTimeAlive": 1284.51,
        "functionTimeCall": 0.018,
        "task": "detect",
        "version": {
            "ultralytics": "8.x.x",
            "torch": "2.6.0",
            "torchvision": "0.21.0",
            "python": "3.13.0"
        }
    }
}

Campos da resposta#

Respostas específicas por tarefa#

O formato da resposta varia consoante 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 partilhada está limitada a 20 pedidos/minuto por chave de API, utilizador com sessão iniciada ou IP anónimo. A rota de inferência da implantação da Platform (POST /api/deployments/{owner}/{deployment}/predict) tem o mesmo limite. Quando o limite é atingido, a API devolve 429 com um cabeçalho Retry-After. Consulta a referência completa dos limites de taxa para ver todas as categorias de endpoint.

Tratamento de erros#

Respostas de erro comuns:

Perguntas frequentes#