Integrazione con Google Cloud Storage#

L'integrazione di Google Cloud Storage collega i tuoi bucket GCS a Ultralytics Platform. Le tue immagini rimangono nei tuoi bucket — la Platform le indicizza sul posto, così puoi sfogliare, annotare e addestrare modelli YOLO senza caricarne una copia.

Creare un account di servizio in sola lettura#

La Platform legge esclusivamente dal tuo storage — non scrive, modifica o elimina mai i tuoi oggetti. Crea un service account dedicato con solo accesso in lettura:

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

Collegarsi alla piattaforma#

1. Vai su Settings > Integrations e seleziona Google Cloud Storage dall'elenco delle integrazioni.
2. Incolla il contenuto della chiave JSON dell'account di servizio.
3. Clicca su Find available buckets, quindi seleziona i bucket da connettere. Se l'account di servizio non riesce a elencare i bucket, inserisci manualmente il nome di un bucket noto.
4. Clicca su Connect (Connetti). La piattaforma verifica di poter elencare e leggere ogni bucket selezionato prima di salvare qualsiasi cosa.

Hai bisogno del ruolo di amministratore o proprietario dello spazio di lavoro per connettere l'archiviazione cloud. Una connessione supporta fino a 50 bucket e la ricerca elenca fino a 300 bucket visibili dall'account di servizio.

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

Ricollegare lo stesso account di servizio in seguito aggiunge nuovi bucket all'integrazione esistente. Una credenziale salvata viene sostituita solo quando la sua sostituta è in grado di leggere tutti i bucket che hai già collegato.

Creare un dataset da un bucket GCS#

1. Fai clic su Nuovo set di dati e apri la scheda Cloud.
2. Scegli un bucket collegato e naviga nella cartella che contiene i tuoi dati.
3. Conferma la cartella, regola il nome del dataset e crea il dataset.

La Platform elenca la cartella una volta e indicizza ciò che trova:

• Images — Gli oggetti .jpg, .jpeg, .png, .webp e .avif vengono indicizzati con dimensioni lette tramite richieste limitate. La Platform non memorizza una seconda copia dell'immagine sorgente.
• Labels — I file di supporto .txt YOLO vengono analizzati nelle annotazioni della Platform, abbinati dal layout standard images/ → labels/ o come elementi fratelli nella stessa cartella.
• Metadati: un file YAML fornisce i nomi delle classi e la forma dei keypoint di posa, esattamente come un caricamento di un archivio. data.yaml e data.yml sono preferiti quando la cartella ne contiene diversi.
• Attività: un campione dei file di etichetta determina l'attività, per cui le cartelle di segment, pose e OBB vengono riconosciute dalla forma delle loro etichetta piuttosto che dall'attività scelta nella finestra di dialogo.
• Splits — I nomi delle cartelle train, val e test nel percorso dell'oggetto assegnano automaticamente gli split.

Il dataset si comporta quindi come qualsiasi altro: sfoglialo e annotalo, impostalo come pubblico o privato, condividilo con il tuo team e addestra su di esso tramite l'addestramento gestito. Gli originali vengono trasmessi in streaming su richiesta e le immagini indicizzate non consumano la tua storage quota della Platform.

Importazioni fallite#

Se un'importazione fallisce (una cartella vuota, un errore di battitura nel percorso o permessi revocati), il dataset mostra l'errore sulla sua pagina. Gli editori possono cliccare su Retry import (Riprova importazione) per riavviarla con il bucket e la cartella archiviati, oppure creare un nuovo dataset che punta al percorso corretto.

Un nuovo tentativo elenca nuovamente la cartella anziché riprendere: gli oggetti aggiunti dal primo tentativo vengono inclusi e gli oggetti non più presenti vengono rimossi dal set di dati.

Addestramento#

L'addestramento gestito funziona tramite il normale flusso di addestramento. L'addestramento utilizza le copie personali di Platform delle immagini bloccate per la durata dell'esecuzione e le tue credenziali Google Cloud non vengono mai esposte ai carichi di lavoro di addestramento.

Disconnetti una connessione#

La disconnessione elimina le credenziali archiviate senza toccare nulla in Google Cloud. I set di dati creati da quei bucket rimangono nel tuo spazio di lavoro con le relative classi, etichetta e annotazioni, ma le loro immagini non possono essere caricate, visualizzate in anteprima o utilizzate per l'addestramento finché lo stesso account di servizio non viene riconnesso.

Usa la REST API con l'ID di 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 invece l'accesso alla fonte, elimina la chiave dell'account di servizio in Google Cloud.

Limitazioni attuali#

I dataset basati su GCS attualmente escludono le funzionalità che richiedono copie di proprietà della Platform delle tue immagini: auto-annotazione, clustering analysis, clonazione del dataset e version snapshots immutabili.

Eliminare un dataset basato su GCS, o singole immagini da esso, rimuove solo i riferimenti della piattaforma: i tuoi oggetti non vengono mai toccati.

Consulta anche le integrazioni Amazon S3 e Azure Blob Storage.