Inferenza (Inference)

Ultralytics Platform fornisce un'API di inferenza per testare i modelli addestrati. Usa la scheda Predict basata su browser per una validazione rapida o l'REST API per l'accesso programmatico.

Scheda Predizione

Ogni modello include una scheda Predict per l'inferenza basata su browser:

1. Vai al tuo modello
2. Clicca sulla scheda Predict
3. Carica un'immagine, usa un esempio o apri la tua webcam
4. Visualizza istantaneamente le previsioni con overlay di bounding box

Metodi di input

Il pannello di previsione supporta molteplici metodi di input:

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

Carica immagine

Trascina e rilascia o clicca per caricare:

• Formati supportati: JPEG, PNG, WebP, AVIF, HEIC, JP2, TIFF, BMP, DNG, MPO
• Dimensione massima: 10MB
• Auto-inferenza: i risultati appaiono automaticamente dopo il caricamento

Immagini di esempio

Il pannello di previsione mostra immagini di esempio dal dataset collegato al tuo modello. Se nessun dataset è collegato, vengono usati esempi predefiniti:

Per i modelli OBB, vengono mostrate invece immagini aeree di barche e aeroporti.

Webcam

Clicca sulla scheda della webcam per avviare un feed video in tempo reale:

1. Concedi il permesso alla fotocamera quando richiesto
2. Clicca sull'anteprima video per acquisire un frame
3. L'inferenza viene eseguita automaticamente sul frame acquisito
4. Clicca di nuovo per riavviare la webcam

Visualizza risultati

I risultati dell'inferenza mostrano:

• Bounding boxes con etichette di classe come overlay SVG
• Punteggi di confidenza per ogni rilevamento
• Colori delle classi dalla palette colori del tuo dataset (o la palette predefinita di Ultralytics)
• Analisi della velocità: tempo di pre-elaborazione, inferenza, post-elaborazione e rete

Il pannello dei risultati mostra:

Parametri di inferenza

Regola il comportamento di rilevamento con i parametri nella sezione comprimibile Parameters:

Soglia di confidenza

Filtra le previsioni per confidenza:

• Più alta (0.5+): meno previsioni, più certe
• Più bassa (0.1-0.25): più previsioni, un po' di rumore
• Predefinita (0.25): bilanciata per la maggior parte dei casi d'uso

Soglia IoU

Controlla la Non-Maximum Suppression:

• Più alta (0.7+): permette più box sovrapposti
• Più bassa (0.3-0.5): unisce i rilevamenti vicini in modo più aggressivo
• Predefinita (0.7): comportamento NMS bilanciato per la maggior parte dei casi d'uso

Predict di Deployment

Ogni endpoint dedicato in esecuzione include una scheda Predict direttamente sulla sua scheda di deployment. Questo utilizza il servizio di inferenza del deployment invece del servizio di previsione condiviso, permettendoti di testare il tuo endpoint distribuito dal browser.

REST API

Accedi all'inferenza in modo programmatico:

Autenticazione

Includi la tua chiave API nelle richieste:

Authorization: Bearer YOUR_API_KEY

Endpoint

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

Richiesta

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())

Risposta

{
    "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"
        }
    }
}

Campi di risposta

Risposte specifiche per attività

Il formato della risposta varia in base all'attività:

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

Fatturazione

L'inferenza condivisa (la scheda Predict e l'endpoint /api/models/{id}/predict) è inclusa senza costi aggiuntivi in tutti i piani. Non ci sono addebiti per singola richiesta per l'inferenza condivisa.

Per carichi di lavoro di produzione che richiedono una maggiore velocità di elaborazione, distribuisci un endpoint dedicato.

Limiti di frequenza

L'inferenza condivisa ha un limite di 20 richieste/min per API key. Quando viene limitata, l'API restituisce 429 con un header Retry-After. Consulta il riferimento completo ai limiti di frequenza per tutte le categorie di endpoint.

Gestione degli errori

Risposte di errore comuni:

FAQ

Posso eseguire l'inferenza su un video?

Entrambi i metodi di inferenza accettano file video:

• Gli endpoint dedicati accettano file video direttamente. Formati supportati (fino a 100 MB): ASF, AVI, GIF, M4V, MKV, MOV, MP4, MPEG, MPG, TS, WEBM, WMV. Ogni fotogramma viene elaborato singolarmente e i risultati vengono restituiti per fotogramma. Vedi gli endpoint dedicati per i dettagli.
• L'inferenza condivisa (/api/models/{id}/predict) utilizza lo stesso servizio di previsione e accetta gli stessi formati video. Tuttavia, la scheda Predict del browser nell'interfaccia utente carica solo immagini: usa direttamente la REST API o un endpoint dedicato per i flussi di lavoro video. L'endpoint condiviso è anche limitato a 20 req/min, quindi gli endpoint dedicati sono la scelta migliore per carichi di lavoro video pesanti.

Come ottengo l'immagine annotata?

L'API restituisce previsioni JSON. Per visualizzarle:

1. Usa le previsioni per disegnare i riquadri localmente
2. Usa il metodo plot() di Ultralytics:

from ultralytics import YOLO

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

Consulta la documentazione della modalità Predict per l'API completa dei risultati e le opzioni di visualizzazione.

Qual è la dimensione massima dell'immagine?

• Limite di caricamento: 10MB
• Consigliato: <5MB per un'inferenza rapida
• Ridimensionamento automatico: Le immagini vengono ridimensionate in base al parametro Image Size selezionato

Le immagini di grandi dimensioni vengono ridimensionate automaticamente mantenendo le proporzioni.

Posso eseguire un'inferenza batch?

L'API corrente elabora un'immagine per richiesta. Per il batch:

1. Invia richieste simultanee
2. Usa un endpoint dedicato per una maggiore velocità di elaborazione
3. Considera l'inferenza locale per batch di grandi dimensioni

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))