Integrazione con Google Cloud Storage#

L'integrazione con Google Cloud Storage collega i tuoi bucket GCS a Ultralytics Platform. Le immagini restano nei tuoi bucket: Platform le indicizza sul posto, 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 solo accesso in lettura:

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

Connettiti a Platform#

1. Vai a Settings > Integrations e seleziona Google Cloud Storage nell'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 qualsiasi dato, Platform verifica di poter elencare e leggere ogni bucket selezionato.

Per collegare lo spazio di archiviazione cloud, devi avere il ruolo di amministratore o proprietario dello spazio di lavoro. Puoi aggiungere fino a 50 bucket alla volta e l'individuazione ne elenca fino a 300 tra quelli 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 riconnetti lo stesso account di servizio, i nuovi bucket vengono aggiunti all'integrazione esistente. Una credenziale salvata viene sostituita solo se quella nuova può ancora leggere tutti i bucket già collegati. Se non è possibile leggere un bucket, l'errore ne indica il nome, inclusi quelli collegati in precedenza con lo stesso account di servizio.

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 la cartella una volta e indicizza gli elementi trovati:

• Immagini — vengono indicizzati gli oggetti .jpg, .jpeg, .png, .webp e .avif; le dimensioni vengono lette tramite richieste con limiti. Platform non conserva una seconda copia dell'immagine originale.
• Etichette — i file associati YOLO .txt vengono analizzati e convertiti in annotazioni Platform, abbinate usando la struttura standard images/ → labels/ o come elementi adiacenti nella stessa cartella.
• Metadati — un file YAML fornisce i nomi delle classi e la struttura dei punti chiave della posa, proprio come un caricamento di archivio. Se la cartella ne contiene diversi, vengono preferiti data.yaml e data.yml.
• Attività — l'attività viene determinata da un campione dei file di etichette, quindi le cartelle di segmentazione, posa e OBB vengono riconosciute in base alla struttura delle etichette, non all'attività scelta nella finestra di dialogo.
• Suddivisioni — i nomi di cartella train, val e test nel percorso dell'oggetto assegnano automaticamente le suddivisioni.

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

Importazioni non riuscite#

Se un'importazione non riesce — per una cartella vuota, un errore di battitura nel percorso o permessi revocati — il dataset mostra l'errore nella propria pagina. Gli editor possono fare clic su Riprova importazione per riavviarla usando il bucket e la cartella salvati, oppure creare un nuovo dataset che punti al percorso corretto.

Un nuovo tentativo elenca nuovamente la cartella invece di riprendere da dove si era interrotto: gli oggetti aggiunti dopo il primo tentativo vengono inclusi, mentre quelli che non sono più presenti vengono rimossi dal dataset.

Addestramento#

L'addestramento gestito segue il normale flusso di addestramento. Durante l'esecuzione, l'addestramento usa le copie delle immagini bloccate create da Platform, 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 questi bucket rimangono nel tuo workspace con le relative classi, etichette e annotazioni, ma le immagini non possono essere caricate, visualizzate in anteprima o usate per l'addestramento finché non viene riconnesso lo stesso account di servizio. Anche mentre sono disconnessi, puoi rinominare i dataset, modificare le etichette o eliminarli.

Per disconnettere, vai a Impostazioni > Integrazioni, seleziona Google Cloud Storage, fai clic su Disconnetti accanto alla credenziale e conferma. Quando apri uno dei dataset associati, viene mostrato Google Cloud Storage disconnesso con un link a queste impostazioni; il dataset torna disponibile automaticamente una volta effettuata la riconnessione.

Puoi anche disconnetterti tramite la REST API, usando 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 alla fonte, elimina la chiave dell'account di servizio in Google Cloud.

Limitazioni attuali#

I dataset collegati a GCS al momento non supportano 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 collegato a GCS o di singole immagini al suo interno rimuove solo i riferimenti di Platform: gli oggetti non vengono mai modificati.

Consulta anche le integrazioni Amazon S3 e Azure Blob Storage.

Domande frequenti#