Inferenza#

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

Scheda Predici#

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

1. Naviga verso il tuo modello
2. Fai clic sulla scheda Predict
3. Carica un'immagine, usa un esempio o apri la tua webcam
4. Esamina la sovrapposizione specifica per il task, il sommario delle predizioni, i tempi e la risposta grezza

Metodi di input#

Il pannello di previsione supporta molteplici 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 o fai clic 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 non è collegato alcun dataset, vengono utilizzati esempi predefiniti:

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

Webcam#

Fai clic sulla scheda della webcam per avviare un feed della telecamera dal vivo:

1. Concedi l'autorizzazione per la 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 di nuovo per riavviare la webcam

Visualizza risultati#

I risultati dell'inferenza mostrano l'output appropriato per il task del modello: box, maschere, keypoint, box orientati, punteggi di classificazione, copertura semantica o una mappa di profondità. I risultati degli oggetti utilizzano i colori delle classi del dataset quando disponibili. Il pannello mostra anche i tempi di preprocessamento, inferenza, post-processamento e rete.

Il pannello dei risultati mostra:

Parametri di inferenza#

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

Soglia di confidenza#

Filtra le previsioni in base alla confidenza:

• Più alta (0.5+): Previsioni meno numerose, ma più certe
• Più bassa (0.1-0.25): Più previsioni, presenza di rumore
• Predefinita (0.25): Bilanciata per la maggior parte dei casi d'uso

Soglia IoU#

Controlla la soppressione dei non massimi (NMS):

• Più alta (0.7+): Consenti più riquadri sovrapposti
• Inferiore (0.3-0.5): Sopprimi i rilevamenti sovrapposti in modo più aggressivo
• Predefinita (0.7): Comportamento NMS bilanciato per la maggior parte dei casi d'uso

Previsione su deployment#

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

API per endpoint dedicato#

La scheda API Docs nel tab Predict del modello contiene esempi di richieste Python, JavaScript e cURL. Gli esempi usano segnaposto finché non distribuisci il modello. Dopo la distribuzione, il tab Code della scheda di distribuzione inserisce l'URL del suo endpoint e la chiave API disponibile per il tuo workspace.

Autenticazione#

Includi la tua chiave API nelle richieste:

Authorization: Bearer YOUR_API_KEY

Endpoint#

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

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,
        "functionTimeCall": 0.018,
        "task": "detect",
        "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 a seconda dell'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/minuto per ciascuna chiave API, chiamante autenticato o IP anonimo. Quando viene limitata, l'API restituisce 429 con un header Retry-After. Consulta il riferimento sui limiti di frequenza completo per tutte le categorie di endpoint.

Gestione errori#

Risposte di errore comuni:

FAQ#

Posso eseguire l'inferenza su video?#

Entrambi i metodi di inferenza accettano file video:

• I dedicated endpoints 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 individualmente e i risultati vengono restituiti per fotogramma. Vedi dedicated endpoints per i dettagli.
• L'inferenza condivisa (/api/models/{id}/predict) utilizza lo stesso servizio di predizione e accetta gli stessi formati video. Il tab Predict del browser seleziona solo immagini, quindi usa l'API o un endpoint dedicato per i video.

Come ottengo l'immagine annotata?#

L'API restituisce previsioni JSON. Per visualizzarle:

1. Utilizza le previsioni per disegnare le box localmente
2. Utilizza 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 del tab Predict: 10 MB
• Limite dell'API per endpoint dedicato: 100 MB
• Ridimensionamento automatico nel tab Predict: Le immagini vengono ridimensionate alla Image Size selezionata prima del caricamento

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

Posso eseguire un'inferenza batch?#

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

1. Invia richieste separate per ciascuna immagine
2. Distribuisci le richieste su endpoint dedicati quando appropriato
3. Usa 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))