Integrazione con Google Cloud Storage#

L'integrazione con Google Cloud Storage collega i tuoi bucket GCS a Ultralytics Platform. Le tue immagini restano nei tuoi bucket: Platform le indicizza direttamente, così puoi sfogliarle, annotarle e addestrare modelli YOLO senza caricarne una copia.

Crea un account di servizio di sola lettura#

Platform legge esclusivamente dal tuo spazio di archiviazione: non scrive, modifica né elimina mai i tuoi oggetti. Crea un account di servizio dedicato con il solo accesso in lettura:

1. Nella console Google Cloud, vai a IAM & Admin > Service Accounts e crea un account di servizio.
2. Assegna il ruolo Storage Object Viewer (roles/storage.objectViewer) sui bucket che vuoi collegare.
3. Apri l'account di servizio, scegli Keys > Add key > Create new key, seleziona JSON e scarica il file della chiave.

Collegati a Platform#

1. Vai a Settings > Integrations e seleziona Google Cloud Storage dall'elenco delle integrazioni.
2. Incolla il contenuto della chiave JSON dell'account di servizio.
3. Fai clic su Find available buckets, quindi seleziona i bucket da collegare. Se l'account di servizio non può elencare i bucket, inserisci manualmente il nome di un bucket che conosci.
4. Fai clic su Connect. Prima di salvare, Platform verifica di poter elencare e leggere ogni bucket selezionato.

Per collegare lo spazio di archiviazione cloud, ti serve il ruolo di amministratore o proprietario del workspace. Ogni connessione può includere fino a 50 bucket e la procedura di individuazione elenca fino a 300 bucket accessibili all'account di servizio.

Il browser legge il file della chiave incollato e invia solo i tre campi necessari a Platform: client_email, private_key, e project_id. Il resto del JSON non lascia mai la pagina.

Se in seguito ricolleghi lo stesso account di servizio, i nuovi bucket vengono aggiunti all'integrazione esistente. Una credenziale salvata viene sostituita solo quando la credenziale sostitutiva può ancora leggere tutti i bucket che hai già collegato.

Crea un dataset da un bucket GCS#

1. Fai clic su New Dataset e apri la scheda Cloud.
2. Scegli un bucket collegato e individua la cartella che contiene i tuoi dati.
3. Conferma la cartella, modifica il nome del dataset e crealo.

Platform elenca una sola volta il contenuto della cartella e indicizza ciò che trova:

• Immagini — gli oggetti .jpg, .jpeg, .png, .webp e .avif vengono indicizzati con le dimensioni lette tramite richieste con limiti definiti. Platform non salva una seconda copia dell'immagine sorgente.
• Etichette — i file accessori .txt YOLO vengono analizzati e convertiti in annotazioni Platform, associate tramite la struttura standard images/ → labels/ o come file nella stessa cartella.
• Metadati — un file YAML fornisce i nomi delle classi e la struttura dei punti chiave per la posa, proprio come un caricamento di archivio. Se nella cartella ce ne sono diversi, vengono preferiti data.yaml e data.yml.
• Attività — l'attività viene determinata esaminando un campione dei file di etichetta, quindi le cartelle di segmentazione, posa e OBB vengono riconosciute dalla struttura delle etichette, non dall'attività selezionata nella finestra di dialogo.
• Suddivisioni — i nomi delle cartelle train, val e test nel percorso degli oggetti assegnano automaticamente le suddivisioni.

Il dataset si comporta quindi come qualsiasi altro: puoi sfogliarlo e annotarlo, renderlo pubblico o privato, condividerlo con il tuo team e addestrare modelli tramite l'addestramento gestito. Gli originali vengono trasmessi su richiesta e le immagini indicizzate non consumano la tua quota di archiviazione Platform.

Importazioni non riuscite#

Se un'importazione non riesce — perché la cartella è vuota, il percorso contiene un errore di battitura o le autorizzazioni sono state revocate — il dataset mostra l'errore nella sua pagina. Gli editor possono fare clic su Retry import per riavviare l'importazione usando il bucket e la cartella salvati, oppure creare un nuovo dataset che punta al percorso corretto.

Un nuovo tentativo elenca di nuovo la cartella anziché riprendere l'importazione: vengono acquisiti gli oggetti aggiunti dopo il primo tentativo e rimossi dal dataset quelli che non sono più presenti.

Addestramento#

L'addestramento gestito segue il normale flusso di addestramento. Per tutta la durata dell'esecuzione, l'addestramento usa copie proprie di Platform delle immagini associate alle rispettive versioni e le tue credenziali Google Cloud non vengono mai esposte ai carichi di lavoro di addestramento.

Disconnetti una connessione#

La disconnessione elimina le credenziali salvate senza modificare nulla in Google Cloud. I dataset creati a partire da quei bucket restano nel tuo workspace con le relative classi, etichette e annotazioni, ma le loro immagini non possono essere caricate, visualizzate in anteprima o usate per l'addestramento finché non viene ricollegato lo stesso account di servizio.

Usa la REST API con l'ID dell'integrazione restituito da GET /api/integrations/buckets:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/integrations/buckets/INTEGRATION_ID

from ultralytics_platform import Platform

client = Platform()  # reads ULTRALYTICS_API_KEY
integrations = client.storage_integrations.list()
client.storage_integrations.delete("INTEGRATION_ID")

Per revocare l'accesso direttamente all'origine, elimina la chiave dell'account di servizio in Google Cloud.

Limitazioni attuali#

I dataset basati su GCS al momento non includono le funzionalità che richiedono copie delle immagini gestite da Platform: annotazione automatica, analisi dei cluster, clonazione dei dataset e istantanee di versione immutabili.

L'eliminazione di un dataset basato su GCS, o di singole immagini al suo interno, rimuove solo i riferimenti di Platform: i tuoi oggetti non vengono mai modificati.

Vedi anche le integrazioni Amazon S3 e Azure Blob Storage.

Domande frequenti#