Inferenza#

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

Scheda Predict#

Ogni modello con 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 previsioni, i tempi e la risposta grezza

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

Metodi di input#

Il pannello di previsione 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 appaiono automaticamente dopo il caricamento

Immagini di esempio#

Il pannello di previsione mostra fino a due immagini di esempio dal dataset collegato al modello, dando la precedenza alla suddivisione val, poi a test e infine a train. Se non è collegato alcun dataset, vengono usati gli esempi predefiniti:

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

Webcam#

Seleziona Webcam sopra l'area dell'immagine per avviare un flusso video in diretta:

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 clic su Torna alla webcam per riprendere il flusso in diretta

Nella scheda Predict della tua distribuzione, la webcam esegue invece l'inferenza in modo continuo. Consulta Inferenza da telecamera in diretta.

Visualizza i 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 usano i colori delle classi del dataset. Il pannello mostra anche i tempi di preelaborazione, inferenza, postelaborazione e rete.

Il pannello dei risultati mostra:

Quando i risultati sono disponibili, sopra l'anteprima compaiono due controlli: fai clic sull'immagine per ingrandirla mantenendo 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 (i modelli di profondità mostrano solo Dimensione immagine):

Soglia di confidenza#

Filtra le previsioni in base alla confidenza:

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

Soglia IoU#

Controlla la soppressione non massima (NMS):

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

Inferenza di deployment#

Ogni endpoint dedicato in esecuzione include una scheda Predict nella relativa pagina di deployment. Questa scheda usa il servizio di inferenza del deployment anziché il servizio di inferenza condiviso, così puoi testare l'endpoint di cui hai eseguito il deployment dal browser.

Su un endpoint pronto, anche le immagini elaborate contribuiscono alla scheda Monitoring. Gli esempi e i grafici aggregati sono dati temporanei e leggeri conservati in memoria; arrestare, riavviare, ridistribuire, ridimensionare o sostituire il modello può cancellarli. Salva gli esempi in un dataset per conservarli.

Inferenza da telecamera in diretta#

Nella scheda Predict di una distribuzione di tua proprietà, seleziona Webcam o Telecamera IP per eseguire l'endpoint su un video in diretta:

L'inferenza in diretta usa la chiave API associata all'endpoint, che solo il proprietario dell'area di lavoro può caricare; per gli altri membri del team la webcam acquisisce singoli fotogrammi e la Telecamera IP non è disponibile, come nella scheda Predict di un modello. La telecamera IP deve essere raggiungibile da Internet: l'endpoint rifiuta indirizzi di rete locale come 192.168.x.x. Ogni risultato riguarda il fotogramma più recente, quindi i fotogrammi vengono saltati se l'inferenza è in ritardo. Le modifiche ai cursori si applicano al fotogramma successivo della webcam e riavviano il flusso della telecamera IP. L'inferenza in diretta si interrompe quando la scheda del browser è nascosta. Fai clic sull'anteprima per acquisire un fotogramma oppure su Disconnetti per interrompere la visualizzazione della telecamera IP.

Telecamera in background#

Un endpoint con dimensioni personalizzate per CPU e memoria può continuare a monitorare una telecamera IP dopo che ti disconnetti o chiudi la pagina. Quando la telecamera connessa mostra i risultati, attiva Continua a funzionare in background. Nell'intestazione della distribuzione compare Telecamera attiva e i risultati vengono inviati alla scheda Monitoraggio come esempi temporanei e statistiche delle predizioni.

• Impostazioni: la telecamera in background usa sempre la confidenza predefinita (0.25), IoU (0.7) e la dimensione immagine di addestramento del modello; i cursori non si applicano.
• Costo: funziona sull'istanza attiva dell'endpoint senza costi aggiuntivi; la tariffa oraria di attività si applica sia che la telecamera sia attiva, sia che sia spenta.
• Modifiche: attivare o disattivare la telecamera oppure passare a un'altra telecamera riavvia l'istanza dell'endpoint. In questo modo l'endpoint resta pronto, ma i dati temporanei di monitoraggio vengono cancellati.
• Arresto: disattiva l'interruttore. Disconnetterti o chiudere la pagina non interrompe il funzionamento; ridimensionando l'endpoint alle dimensioni predefinite, invece, la telecamera viene rimossa. Se la telecamera si disconnette, l'endpoint continua a tentare la riconnessione.
• Ciclo di vita dell'endpoint: arrestando l'endpoint si fermano la telecamera e gli addebiti; riavviandolo, la telecamera salvata riprende a funzionare.

Gli endpoint con dimensioni predefinite supportano l'inferenza in diretta da webcam e telecamera IP senza l'opzione in background. Per salvare una telecamera in background tramite API, usa l'azione camera della distribuzione.

Trasmettere i risultati in streaming dall'API#

Invia un URL RTSP o RTSPS come source con l'intestazione Accept: text/event-stream a un URL di endpoint dedicato per ricevere i risultati come eventi inviati dal server:

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"

Ogni evento di fotogramma contiene images nel formato della risposta, con coordinate normalizzate (0-1), un URL dati JPEG preview del fotogramma e metadata con l'attività e i nomi delle classi. Si applicano solo conf, iou e imgsz, e lo streaming dell'URL della telecamera in background dell'endpoint usa le impostazioni predefinite. Gli eventi che contengono solo status non includono fotogrammi, e un evento con un messaggio error (impossibilità di leggere la telecamera o di eseguire il modello sull'endpoint) termina lo streaming. Lo streaming si chiude anche quando l'endpoint si riavvia o la richiesta raggiunge il limite di tempo; se termina senza errori, riconnettiti con un intervallo di attesa crescente. La route di predizione delle distribuzioni della Platform API e l'SDK non supportano lo streaming; invia le richieste della telecamera all'URL dell'endpoint con la chiave API associata. Una richiesta source della telecamera senza l'intestazione restituisce 400.

API dell'endpoint dedicato#

La scheda Predict del modello contiene la scheda API Docs con esempi di richieste Python, JavaScript e cURL, precompilati con i valori di confidenza, IoU e dimensione dell'immagine impostati correntemente tramite i cursori. L'URL e la chiave sono segnaposto finché non esegui il deployment del modello: un pulsante Deploy accanto alle schede del codice apre la scheda Deploy del modello. Dopo il deployment, la scheda dei risultati Docs nella scheda Predict della pagina di deployment inserisce l'URL dell'endpoint e, per i proprietari dell'area di lavoro, la chiave API associata, pronti per essere copiati ed eseguiti.

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 usa l'API Platform 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 risposte con la stessa struttura. Con l'SDK Python, usa client.models.predict(owner, project, model, body=...) per l'inferenza condivisa oppure client.deployments.predict(owner, deployment, body=...) per un deployment dedicato. Entrambi i metodi SDK chiamano l'API Platform, quindi si applicano i limiti di frequenza e il limite di dimensione delle richieste. Per evitarli, invia una richiesta direttamente all'URL di un endpoint dedicato, come mostrato in Richiesta. Esempio di inferenza condivisa:

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

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 del modello condiviso è limitata a 20 richieste al minuto per ogni chiave API, utente autenticato o IP anonimo. Anche la route di inferenza predict dei deployment di Platform (POST /api/deployments/{owner}/{deployment}/predict) ha lo stesso limite. Quando vengono applicati limiti, l'API restituisce 429 con un'intestazione Retry-After. Consulta la guida completa ai limiti di frequenza per tutte le categorie di endpoint.

Gestione degli errori#

Risposte di errore comuni:

Domande frequenti#