Inferenza#

Ultralytics Platform fornisce inferenza basata su browser per testare i modelli addestrati e endpoint dedicati per l'accesso programmatico.

Scheda Predizione#

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

1. Vai al tuo modello
2. Fai clic sulla scheda Predict
3. Carica un'immagine, usa un esempio o apri la webcam
4. Esamina la sovrapposizione specifica dell'attività, il riepilogo delle predizioni, i tempi e la risposta grezza

I modelli senza pesi mostrano invece uno stato vuoto: prima addestra il modello o carica i pesi.

Metodi di input#

Il pannello Predict supporta diversi metodi di input:

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

Carica immagine#

Trascina e rilascia oppure fai clic per caricare:

• Formati supportati: JPEG, PNG, WebP, AVIF, HEIC, JP2, TIFF, BMP
• Dimensione massima: 10 MB
• Inferenza automatica: i risultati vengono visualizzati automaticamente dopo il caricamento

Immagini di esempio#

Il pannello Predict mostra fino a due immagini di esempio dal dataset collegato al tuo modello, preferendo la suddivisione val, poi test, quindi train. Se non è collegato alcun dataset, vengono usati esempi predefiniti:

Per i modelli OBB, vengono mostrate invece immagini aeree di imbarcazioni e di un aeroporto.

Webcam#

Fai clic sulla scheda della webcam per avviare un flusso video della fotocamera in tempo reale:

1. Concedi l'autorizzazione all'uso della fotocamera quando richiesto
2. Fai clic sull'anteprima video per acquisire un fotogramma
3. L'inferenza viene eseguita automaticamente sul fotogramma acquisito
4. Fai nuovamente clic per riavviare la webcam

Visualizza risultati#

I risultati dell'inferenza mostrano l'output appropriato per l'attività del modello: riquadri, maschere, punti chiave, riquadri orientati, punteggi di classificazione, copertura semantica o una mappa di profondità. Quando disponibili, i risultati degli oggetti utilizzano i colori delle classi del dataset. Il pannello mostra inoltre i tempi di pre-elaborazione, inferenza, post-elaborazione e rete.

Il pannello dei risultati mostra:

Quando sono disponibili i risultati, sull'anteprima sono presenti due controlli: fai clic sull'immagine per ingrandirla mantenendo intatte le sovrapposizioni e usa il pulsante di download per salvare un JPEG annotato del risultato corrente.

Parametri di inferenza#

Regola il comportamento dell'inferenza con i tre cursori sotto l'immagine:

Soglia di confidenza#

Filtra le predizioni in base alla confidenza:

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

Soglia IoU#

Controlla la soppressione non massima:

• Più alta (0.7+): consente un numero maggiore di riquadri sovrapposti
• Più bassa (0.3-0.5): sopprime le rilevazioni sovrapposte in modo più aggressivo
• Predefinita (0.7): comportamento NMS equilibrato per la maggior parte dei casi d'uso

Predict del deployment#

Ogni endpoint dedicato attivo include una scheda Predict direttamente nella relativa scheda di deployment. Utilizza il servizio di inferenza del deployment invece del servizio Predict condiviso, consentendoti di testare l'endpoint distribuito dal browser.

Su un endpoint a pagamento con il monitoraggio abilitato, le immagini elaborate contribuiscono anche alla Scheda Monitoraggio. I suoi esempi campionati e i grafici aggregati sono dati leggeri e temporanei conservati in memoria; l'arresto, il riavvio, il ridistribuimento, il ridimensionamento o la sostituzione del modello possono cancellarli. Salva gli esempi in un dataset per conservarli.

API dell'endpoint dedicato#

La scheda API Docs nella scheda Predict del modello contiene richieste di esempio in Python, JavaScript e cURL, precompilate con i valori di confidenza, IoU e dimensione dell'immagine attualmente impostati sui cursori. L'URL e la chiave sono segnaposto finché non esegui il deployment del modello; un pulsante Deploy accanto alle schede del codice porta alla scheda Deploy del modello. Dopo il deployment, la scheda Code della scheda del deployment compila l'URL dell'endpoint e, per i proprietari del workspace, la relativa chiave API associata, pronta per essere copiata ed eseguita.

Autenticazione#

Includi la tua chiave API nelle richieste:

Authorization: Bearer YOUR_API_KEY

Endpoint#

Gli endpoint dedicati ricevono le richieste al proprio URL:

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

L'inferenza condivisa utilizza la Platform API con il percorso completo del modello:

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

Entrambi accettano lo stesso corpo multipart/form-data e restituiscono la stessa struttura della risposta. Con l'SDK Python, usa client.models.predict(owner, project, model, body=...) per l'inferenza condivisa o client.deployments.predict(owner, deployment, body=...) per un deployment dedicato:

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

Richiesta#

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

Parametri della richiesta#

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

Campi della 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}
}

Limiti di frequenza#

L'API condivisa dei modelli è limitata a 20 richieste/minuto per ogni chiave API, utente autenticato o IP anonimo. Quando viene applicato il limite, l'API restituisce 429 con un'intestazione Retry-After. Consulta il riferimento completo sui limiti di frequenza per tutte le categorie di endpoint.

Gestione degli errori#

Risposte di errore comuni:

FAQ#