Ultralytics YOLO27:

Chiavi API#

Le chiavi API della Ultralytics Platform consentono un accesso programmatico sicuro per l'addestramento remoto, l'inferenza e l'automazione. Crea chiavi con nome e crittografia AES-256-GCM per diversi casi d'uso.

Scheda Chiavi API delle impostazioni della Ultralytics Platform, elenco delle chiavi

Solo proprietario

Solo il proprietario del workspace può creare, visualizzare o revocare le Ultralytics API keys di un workspace, poiché queste chiavi si autenticano come il proprietario del workspace. Gli altri membri non possono visualizzare quell'elenco di chiavi. Possono vedere lo stato della connessione del provider esterno, ma non possono visualizzare le chiavi complete del provider o modificare tali connessioni. Le API keys stesse non possono creare o revocare altre API keys. L'unica eccezione è costituita dalle On Premise worker keys, che vengono revocate scollegando l'host dall'integrazione On Premise.

Crea una chiave API#

Crea una nuova chiave API:

  1. Vai a Impostazioni > Chiavi API
  2. Fai clic su Add Key e seleziona Ultralytics come provider
  3. Inserisci un nome per la chiave (ad es. "Server di addestramento")
  4. Fai clic su Crea chiave

Finestra di dialogo per la creazione di una chiave API nella scheda Chiavi API delle impostazioni della Ultralytics Platform

Nome della chiave#

Assegna alla chiave un nome descrittivo:

  • training-server - Per macchine di addestramento remoto
  • ci-pipeline - Per l'integrazione CI/CD
  • local-dev - Per lo sviluppo locale

Visualizzazione della chiave#

Dopo la creazione, la chiave viene visualizzata in una finestra di dialogo di conferma:

Finestra di dialogo per copiare la chiave API creata nella scheda Chiavi API delle impostazioni della Ultralytics Platform

Copia la chiave

Copia la tua chiave dopo la creazione per un facile riferimento. Puoi anche usare il pulsante di copia nell'elenco delle chiavi in qualsiasi momento; l'elenco mostra solo il prefisso di ciascuna chiave.

Provider Keys per Agents#

La stessa scheda Settings > API Keys memorizza anche le chiavi per i provider di modelli esterni utilizzati da Agents. Solo il proprietario del workspace può aggiungere, sostituire o rimuovere queste chiavi; i membri del team possono vedere quali provider sono collegati. Chiedi al proprietario di collegare un provider mancante. Per collegare un provider come proprietario:

  1. Fai clic su Add Key.
  2. Seleziona il provider corrispondente al linguaggio o al modello di visione-linguaggio del tuo flusso di lavoro.
  3. Incolla la chiave API di quel provider in API Key, quindi fai clic su Save Key. Il link Get an API key della finestra di dialogo apre la pagina delle chiavi del provider.

Una chiave Ultralytics non autentica i provider di modelli esterni. L'utilizzo del provider viene fatturato tramite l'account del provider associato alla chiave salvata. Usa il controllo di modifica della riga della chiave per sostituire una chiave del provider.

Finestra di dialogo Aggiungi chiave API della piattaforma Ultralytics con Google Gemini selezionato come provider

Formato della chiave#

Le chiavi API seguono questo formato:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4
  • Prefisso: ul_ identifica le chiavi Ultralytics
  • Corpo: 40 caratteri esadecimali casuali
  • Totale: 43 caratteri

Sicurezza delle chiavi#

  • Le chiavi vengono archiviate con crittografia AES-256-GCM, mai in testo non crittografato
  • I primi 11 caratteri (ul_ più 8 caratteri esadecimali) fungono da prefisso visualizzato, così puoi identificare una chiave senza esporla

Utilizzo delle chiavi API#

Variabile d'ambiente#

Imposta la chiave come variabile d'ambiente:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Convalida e salva la chiave usando la CLI di YOLO su Python>=3.11:

yolo login YOUR_API_KEY

Rimuovi la chiave salvata con yolo logout.

Intestazioni HTTP#

Includi la chiave nelle richieste API:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/...

Oppure passala all'SDK Python (pip install "ultralytics-platform>=0.1.32"), che legge ULTRALYTICS_API_KEY o la chiave salvata da yolo login quando api_key viene omesso:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

Consulta il riferimento REST API per tutti gli endpoint disponibili.

Addestramento remoto#

Abilita lo streaming delle metriche con la tua chiave.

Installa o aggiorna il pacchetto Ultralytics su Python>=3.11 prima di iniziare:

pip install -U ultralytics
export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

Consulta Addestramento cloud per la guida completa all'addestramento remoto.

Gestisci le chiavi#

Visualizza le chiavi#

Tutte le chiavi sono elencate nella scheda Settings > API Keys:

Ogni scheda della chiave mostra il nome della chiave, il valore copiabile della chiave, il tempo relativo dalla creazione e un pulsante per revocarla.

Revoca la chiave#

Revoca una chiave compromessa o non più necessaria:

  1. Trova la chiave nella sezione Chiavi API
  2. Fai clic sul pulsante Revoca (cestino)
  3. Conferma la revoca
Effetto immediato

La revoca è immediata e permanente: il record della chiave viene eliminato, non disabilitato. Le applicazioni che utilizzano la chiave smetteranno di funzionare.

Rigenera la chiave#

Se una chiave è compromessa:

  1. Crea una nuova chiave con lo stesso nome
  2. Aggiorna le applicazioni
  3. Revoca la vecchia chiave

Chiavi API del workspace#

Le chiavi API sono associate al workspace attualmente attivo:

  • Workspace personale: le chiavi eseguono l'autenticazione come il tuo account personale
  • Workspace del team: le chiavi eseguono l'autenticazione come il proprietario del workspace del team, con autorizzazioni complete di proprietario in quel workspace

Quando cambi workspace nella barra laterale, la sezione Chiavi API mostra le chiavi di quel workspace. Poiché una chiave del workspace include le autorizzazioni del proprietario, solo il proprietario del workspace può crearla, visualizzarla o revocarla. Consulta Team per i dettagli sui ruoli.

Chiavi dei worker On Premise#

La connessione di un host On Premise genera una chiave separata per il worker. Le chiavi dei worker vengono gestite dall'integrazione On Premise anziché da questa scheda, non vengono mai elencate insieme alle tue chiavi API e vengono revocate disconnettendo l'host, annullando anche i job in coda e in esecuzione di quell'host.

Best practice di sicurezza#

Da fare#

  • Archivia le chiavi nelle variabili d'ambiente
  • Usa chiavi separate per ambienti diversi
  • Revoca tempestivamente le chiavi inutilizzate
  • Ruota periodicamente le chiavi
  • Usa nomi descrittivi per identificare lo scopo delle chiavi

Da non fare#

  • Inserire le chiavi nel controllo versione
  • Condividere le chiavi tra le applicazioni
  • Registrare le chiavi nell'output dell'applicazione
  • Incorporare le chiavi nel codice lato client

Rotazione delle chiavi#

Ruota periodicamente le chiavi per motivi di sicurezza:

  1. Crea una nuova chiave con lo stesso nome
  2. Aggiorna le applicazioni affinché utilizzino la nuova chiave
  3. Verifica che le applicazioni funzionino correttamente
  4. Revoca la vecchia chiave
Pianificazione della rotazione

Per le applicazioni sensibili, valuta la possibilità di ruotare le chiavi ogni 90 giorni.

Risoluzione dei problemi#

Errore: chiave non valida#

Error: Invalid API key

Soluzioni:

  1. Verifica che la chiave sia stata copiata correttamente (incluso il prefisso ul_)
  2. Verifica che la chiave non sia stata revocata
  3. Conferma che la variabile d'ambiente sia impostata
  4. Assicurati di usare Python>=3.11 e ultralytics>=8.4.120

Autorizzazione negata#

Error: Permission denied for this operation

Soluzioni:

  1. Verifica di essere il proprietario della risorsa o di disporre dell'accesso appropriato al workspace
  2. Verifica che la chiave appartenga al workspace corretto
  3. Se gestisci le chiavi in un workspace del team, conferma di essere il proprietario del workspace: gli altri ruoli ricevono Workspace owner access required
  4. Crea una nuova chiave se necessario

Limite di frequenza raggiunto#

Error: Rate limit exceeded

Soluzioni:

  1. Riduci la frequenza delle richieste: consulta la tabella dei limiti di frequenza per i limiti per categoria
  2. Implementa un backoff esponenziale usando l'intestazione Retry-After
  3. Usa un endpoint dedicato quando hai bisogno di capacità di inferenza isolata

FAQ#

  • Non esiste un limite rigido al numero di chiavi API. Creane quante ne servono per applicazioni e ambienti diversi.

  • Le chiavi non scadono automaticamente. Rimangono valide finché non vengono revocate. Per maggiore sicurezza, valuta l'implementazione della rotazione delle chiavi.

  • Sì, i valori completi delle chiavi sono visibili nell'elenco delle chiavi su Settings > API Keys. La piattaforma decritta e mostra le tue chiavi, così puoi copiarle in qualsiasi momento.

  • Le chiavi funzionano tra le regioni, ma consentono di accedere solo ai dati nella regione del tuo account.

  • No: una chiave dell'area di lavoro del team autentica l'utente come proprietario dell'area di lavoro, quindi solo il proprietario può crearla o visualizzarla; condividerla trasferisce i permessi del proprietario. Chiedi a ogni membro di creare una chiave nella propria area di lavoro personale e chiedi al proprietario di generare una chiave dedicata dell'area di lavoro per l'automazione condivisa, ad esempio la CI.

  • No. Una chiave appartiene all'area di lavoro in cui è stata creata e consente di accedere solo alle risorse di quell'area di lavoro. Crea una chiave separata per ogni area di lavoro che automatizzi.

Contributori
GLglenn-jocher17SEsergiuwaxmann2RAraimbekovm1LAlaodouya1MYmykolaxboiko1LALaughing-q1

Commenti