Endpoint dedicati#

Ultralytics Platform consente il deployment di modelli YOLO su endpoint dedicati in 42 regioni globali. Ciascun endpoint è un servizio a singolo tenant con comportamento di scale-to-zero, un URL di endpoint univoco e monitoraggio indipendente.

Crea Endpoint#

Dalla scheda Deploy#

Esegui il deploy di un modello dalla sua scheda Deploy:

1. Naviga verso il tuo modello
2. Fai clic sulla scheda Deploy
3. Esamina la mappa del mondo e la tabella delle regioni, ordinate in base alla latenza misurata dalla tua posizione
4. Clicca su Deploy nella riga della regione che vuoi usare

Il deployment inizia immediatamente senza passaggi di denominazione: il nome viene generato dal nome del modello e dalla città della regione (ad esempio yolo26n-iowa). Il modello deve disporre di pesi, altrimenti la scheda mostra uno stato vuoto anziché la tabella delle regioni.

Dalla pagina Deployments#

Crea un deployment dalla pagina globale Deploy nella barra laterale:

1. Fai clic su New Deployment
2. Seleziona un modello dal selettore dei modelli, che elenca i tuoi modelli completati
3. Seleziona una regione dalla mini mappa o dalla tabella della latenza
4. Rivedi il nome del deployment generato automaticamente, che puoi modificare qui
5. Fai clic su Deploy Model

Ciclo di vita della distribuzione#

stateDiagram-v2
    [*] --> Creating: Deploy
    Creating --> Deploying: Service starting
    Deploying --> Ready: Service URL published
    Ready --> Stopping: Stop
    Ready --> Deploying: Replace model
    Stopping --> Stopped: Stopped
    Stopped --> Deploying: Start
    Deploying --> Stopped: Start failed
    Ready --> [*]: Delete
    Stopped --> [*]: Delete
    Creating --> Failed: Error
    Deploying --> Failed: Error
    Failed --> [*]: Delete

    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff
    class Creating,Deploying,Stopping proc
    class Ready out
    class Failed error
    class Stopped extern

Collega gli avvisi Slack per ricevere un messaggio quando un deployment diventa pronto o non riesce ad avviarsi.

Selezione Regione#

Scegli tra 42 regioni in tutto il mondo. La mappa interattiva delle regioni e la tabella mostrano:

• Pin delle regioni: codificati a colori per latenza su un gradiente da verde a rosso (le regioni più veloci sono più verdi, quelle più lente sono più rosse)
• Regioni distribuite: Evidenziate con un badge "Distributed" nella tabella
• Regioni in fase di deployment: Indicatore a impulsi animato sul pin e sulla riga della tabella
• Evidenziazione bidirezionale: passando il mouse sulla mappa viene evidenziata la riga della tabella e viceversa

La tabella delle regioni nella scheda Deploy del modello include:

La tabella è ricercabile per città, paese e zona ed è ordinata per latenza per impostazione predefinita.

Regioni disponibili#

Configurazione endpoint#

Finestra di dialogo New Deployment#

La finestra di dialogo New Deployment raccoglie tre input:

Sotto il nome, un pannello Resources di sola lettura riporta un badge Custom resources coming soon. Le risorse non sono configurabili oggi: ogni endpoint viene eseguito come singola istanza che si riduce a zero quando è inattiva.

Scheda Distribuisci (Distribuzione rapida)#

Il deployment dalla scheda Deploy del modello utilizza le stesse risorse fisse e il nome generato automaticamente, senza passaggi di finestre di dialogo. Il deployment appare immediatamente nell'elenco Active Deployments sotto la tabella delle regioni mentre viene creato.

Gestisci endpoint#

Modalità di visualizzazione#

L'elenco delle distribuzioni supporta tre modalità di visualizzazione:

Scheda distribuzione (Vista schede)#

Ogni scheda di distribuzione nella vista a schede mostra:

• Header: Nome, bandiera della regione, badge di stato e i pulsanti di azione disponibili per lo stato corrente: sostituisci e ferma quando è Ready, avvia quando è Stopped, elimina in qualsiasi momento
• Endpoint URL: URL copiabile con un link alla referenza API dell'endpoint stesso
• Metrics: Conteggio delle richieste (24h), latenza P95, tasso di errore o "Nessun traffico ancora"
• Controllo integrità: Indicatore di stato live con latenza e aggiornamento manuale
• Schede (Tabs): Logs, Code e Predict
• Footer: Il prefisso della chiave API associato al deployment e la data in cui è diventato pronto
• Status message: Il motivo del fallimento, quando un deployment è fallito

L'URL, le metriche, il controllo dello stato e le schede compaiono solo mentre il deployment è Ready. La scheda Logs mostra recenti voci di log con filtro di severità (All / Errors). La scheda Code mostra esempi di codice pronti all'uso in Python, JavaScript, e cURL con il tuo URL dell'endpoint, oltre alla chiave API associata per i proprietari dello spazio di lavoro (vedi Monitoring). La scheda Predict fornisce un pannello di predizione integrato per testare direttamente sul deployment.

Sostituisci un modello#

Sostituisci il modello dietro un endpoint pronto senza modificarne l'URL:

1. Apri il deployment nella vista Schede
2. Fai clic su Sostituisci modello
3. Seleziona un altro modello completato dallo stesso workspace
4. Facoltativamente, modifica il nome del deployment
5. Fai clic su Sostituisci modello

Il modello attuale continua a servire mentre il sostituto si avvia. Una volta che il sostituto è pronto, il traffico si sposta sul nuovo modello. L'ID del deployment, l'URL, la regione e la chiave API rimangono invariati; il suo nome visualizzato cambia solo quando ne inserisci uno nuovo. Se la sostituzione fallisce, il modello e il nome precedenti rimangono attivi.

La sostituzione richiede tutto quanto segue e viene rifiutata altrimenti:

• Il deployment è Ready e non ha altre operazioni del ciclo di vita in corso
• Il modello sostitutivo ha dei pesi e appartiene allo stesso spazio di lavoro del deployment
• Il modello sostitutivo non è quello già distribuito

Stati della distribuzione#

URL endpoint#

Ogni endpoint ha un URL univoco, ad esempio:

https://predict-<deployment-id>-<hash>-<region>.a.run.app

Fai clic sul pulsante di copia per copiare l'URL. Fai clic sull'icona dei documenti per aprire la referenza API dell'endpoint stesso. L'endpoint serve questi percorsi:

Gestione del ciclo di vita#

Controlla lo stato del tuo endpoint:

graph LR
    R[Ready]:::out -->|Stop| S[Stopped]:::extern
    S -->|Start| R
    R -->|Delete| D[Deleted]:::error
    S -->|Delete| D

    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff

Arresta endpoint#

Arresta un endpoint quando non vuoi che accetti richieste:

1. Fai clic sull'icona di pausa sulla scheda di distribuzione
2. Lo stato dell'endpoint cambia in "Arresto in corso" e poi in "Arrestato"

Endpoint arrestati:

• Non accetta richieste e non riporta metriche o stato di salute
• Mantengono il loro URL, la regione e la chiave API associata, e possono essere riavviati in qualsiasi momento
• Continuano a essere conteggiati nella quota di deployment del tuo piano: elimina un endpoint per liberare il suo slot

Elimina endpoint#

Rimuovi permanentemente un endpoint:

1. Fai clic sull'icona di eliminazione (cestino) sulla scheda di distribuzione
2. Conferma l'eliminazione nella finestra di dialogo

I deployment vengono rimossi anche quando il loro modello o progetto viene eliminato permanentemente, o quando un modello o progetto nel cestino raggiunge la fine della sua finestra di conservazione.

Utilizzo degli endpoint#

Autenticazione#

Ciascun deployment è associato a una singola chiave API dello spazio di lavoro che possiede il modello. Includila nelle richieste:

Authorization: Bearer YOUR_API_KEY

L'endpoint accetta solo la chiave associata alla creazione, quindi nessun'altra chiave lo apre – nemmeno un'altra chiave attiva nello stesso spazio di lavoro. Per controllare quale chiave viene associata, effettua il deployment tramite l'API autenticata con la chiave del proprietario dello spazio di lavoro: quella specifica chiave viene associata e la possiedi già. I deployment creati in qualsiasi altro modo (l'UI della Platform o una chiamata API autenticata come membro del team) associano automaticamente una delle chiavi attive dello spazio di lavoro proprietario – identificala dal prefisso della chiave mostrato nel piè di pagina della scheda del deployment e chiedi il suo valore al proprietario dello spazio di lavoro, poiché solo il proprietario può visualizzare i valori delle chiavi (vedi API Keys). I membri del team senza la chiave associata possono comunque eseguire l'inferenza tramite il proxy di predizione della Platform nel browser.

Richieste dirette all'endpoint#

Invia richieste di produzione direttamente all'URL mostrato sulla scheda del deployment. Queste richieste non passano attraverso il limitatore di velocità dell'API della Platform, quindi il limite di predizione di 20 richieste/minuto non si applica. L'endpoint ha comunque il suo limite di capacità:

• Una singola istanza serve ogni endpoint, elaborando un numero limitato di richieste alla volta
• Le richieste che non possono essere evase tempestivamente restituiscono 429 con un'intestazione Retry-After
• Una singola richiesta può durare fino a 1 ora, il che consente il completamento dell'inferenza video
• Le risposte superiori a 1 KB sono compresse in gzip e sono consentite richieste browser cross-origin

Esempio di richiesta#

import requests

# Deployment endpoint
url = "https://YOUR_DEPLOYMENT_URL.run.app/predict"

# Headers with your deployment API key
headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Inference parameters
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

# Send image for inference
with open("image.jpg", "rb") as f:
    response = requests.post(url, headers=headers, data=data, files={"file": f})

print(response.json())

Parametri della richiesta#

Vedi Depth responses per come bits modifica la mappa di profondità restituita e come decodificarla.

Formato risposta#

Uguale all'inferenza condivisa con campi specifici per attività.

FAQ#