Chiavi API
Le chiavi API della Piattaforma Ultralytics consentono un accesso programmatico sicuro per l'addestramento remoto, l'inferenza e l'automazione. Crea chiavi con ambiti specifici e permessi definiti per diversi casi d'uso.
Crea chiave API
Crea una nuova chiave API:
- Vai a Impostazioni > Chiavi API
- Clicca su Crea chiave
- Inserisci un nome per la chiave
- Seleziona gli ambiti di permesso
- Clicca su Crea
Nome Chiave
Assegna un nome descrittivo alla tua chiave:
training-server- Per macchine di addestramento remotoci-pipeline- Per l'integrazione CI/CDmobile-app- Per applicazioni mobili
Ambiti di Autorizzazione
Seleziona gli ambiti per limitare i permessi della chiave:
| Ambito | Permessi |
|---|---|
| addestramento | Avvia l'addestramento, trasmetti metriche |
| models | Carica, scarica, elimina modelli |
| datasets | Accedi e modifica i dataset |
| lettura | Accesso in sola lettura a tutte le risorse |
| scrittura | Accesso completo in scrittura |
| admin | Gestione account (usare con cautela) |
Minimo privilegio
Creare chiavi con le sole autorizzazioni necessarie. Utilizzare chiavi separate per applicazioni diverse.
Visualizzazione Chiave
Dopo la creazione, la chiave viene visualizzata una sola volta:
Copiare la chiave
La chiave completa viene mostrata una sola volta. Copiarla immediatamente e conservarla in modo sicuro. Non sarà possibile recuperarla in seguito.
Formato Chiave
Le chiavi API seguono questo formato:
ul_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
- Prefisso:
ul_identifica le chiavi Ultralytics - Corpo: 40 caratteri esadecimali casuali
- Totale: 43 caratteri
Utilizzo delle Chiavi API
Variabile d'Ambiente
Impostare la chiave come variabile d'ambiente:
export ULTRALYTICS_API_KEY="ul_your_key_here"
$env:ULTRALYTICS_API_KEY = "ul_your_key_here"
Nel Codice
Utilizzare la chiave negli script Python:
import os
# From environment (recommended)
api_key = os.environ.get("ULTRALYTICS_API_KEY")
# Or directly (not recommended for production)
api_key = "ul_your_key_here"
Header HTTP
Includere la chiave nelle richieste API:
curl -H "Authorization: Bearer ul_your_key_here" \
https://platform.ultralytics.com/api/...
Addestramento remoto
Abilitare lo streaming delle metriche con la propria chiave.
Requisiti di versione del pacchetto
L'integrazione della Piattaforma richiede Ultralytics>=8.4.0. Versioni precedenti NON funzioneranno con la Piattaforma.
pip install "ultralytics>=8.4.0"
export ULTRALYTICS_API_KEY="ul_your_key_here"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1
Gestisci Chiavi
Visualizza Chiavi
Tutte le chiavi sono elencate in Impostazioni > Chiavi API:
| Colonna | Descrizione |
|---|---|
| Nome | Identificatore chiave |
| Ambiti | Autorizzazioni assegnate |
| Creata | Data di creazione |
| Ultimo utilizzo | Utilizzo più recente |
Revoca Chiave
Revocare una chiave compromessa o non più necessaria:
- Clicca sul menu della chiave
- Seleziona Revoca
- Conferma la revoca
Effetto Immediato
La revoca è immediata. Tutte le applicazioni che utilizzano la chiave smetteranno di funzionare.
Rigenera Chiave
Se una chiave è compromessa:
- Crea una nuova chiave con gli stessi ambiti
- Aggiorna le tue applicazioni
- Revoca la vecchia chiave
Migliori Pratiche di Sicurezza
Fai
- Archivia le chiavi nelle variabili d'ambiente
- Utilizza chiavi separate per ambienti diversi
- Revoca tempestivamente le chiavi non utilizzate
- Utilizza gli ambiti minimi richiesti
- Ruota periodicamente le chiavi
Non fare
- Non effettuare il commit delle chiavi nel controllo versione
- Non condividere le chiavi tra applicazioni
- Non utilizzare ambiti di amministrazione inutilmente
- Non registrare le chiavi nell'output dell'applicazione
- Non incorporare le chiavi nel codice lato client
Rotazione delle Chiavi
Ruota periodicamente le chiavi per sicurezza:
- Crea una nuova chiave con gli stessi ambiti
- Aggiorna le applicazioni per utilizzare la nuova chiave
- Verifica che le applicazioni funzionino correttamente
- Revoca la vecchia chiave
Programma di Rotazione
Considera di ruotare le chiavi ogni 90 giorni per applicazioni sensibili.
Risoluzione dei problemi
Errore Chiave Non Valida
Error: Invalid API key
Soluzioni:
- Verifica che la chiave sia stata copiata correttamente
- Controlla che la chiave non sia stata revocata
- Assicurati che la chiave abbia gli ambiti richiesti
- Conferma che la variabile d'ambiente sia impostata
Autorizzazione Negata
Error: Permission denied for this operation
Soluzioni:
- Verifica che gli ambiti della chiave includano il permesso richiesto
- Verifica di essere il proprietario della risorsa
- Crea una nuova chiave con gli ambiti corretti
Frequenza limitata
Error: Rate limit exceeded
Soluzioni:
- Riduci la frequenza delle richieste
- Implementa un backoff esponenziale
- Contatta il supporto per un aumento del limite
FAQ
Quante chiavi posso creare?
Non c'è un limite rigido al numero di chiavi API. Creane quante ne servono per diverse applicazioni e ambienti.
Le chiavi scadono?
Le chiavi non scadono automaticamente. Rimangono valide fino alla revoca. Considera di implementare la rotazione per motivi di sicurezza.
Posso visualizzare la mia chiave dopo la creazione?
No, la chiave completa viene mostrata solo una volta al momento della creazione. Se persa, crea una nuova chiave e revoca quella vecchia.
Le chiavi sono specifiche per regione?
Le chiavi funzionano tra le regioni ma accedono ai dati solo nella regione del tuo account.
Posso condividere le chiavi con i membri del team?
Prassi migliore: Fai in modo che ogni membro del team crei la propria chiave. Questo consente:
- Tracking delle attività individuali
- Revoca selettiva
- Controllo degli accessi adeguato
