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 sul posto, così puoi esplorare, annotare e addestrare modelli YOLO senza caricarne una copia.

Crea un account di servizio in sola lettura#

Platform legge soltanto 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 su IAM & Admin > Service Accounts e crea un account di servizio.
2. Assegnagli 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.

Connettiti a Platform#

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. Fai clic su Find available buckets, quindi seleziona i bucket da collegare. Se l'account di servizio non riesce a elencare i bucket, inserisci manualmente il nome di un bucket noto.
4. Fai clic su Connect. Platform verifica di poter elencare e leggere ogni bucket selezionato prima di salvare qualsiasi dato.

Per collegare lo spazio di archiviazione cloud ti serve il ruolo di amministratore o proprietario dell'area di lavoro. Una connessione supporta fino a 50 bucket e il rilevamento elenca fino a 300 dei bucket visibili all'account di servizio.

Il tuo 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.

Ricollegando in seguito lo stesso account di servizio, aggiungi nuovi bucket all'integrazione esistente. Una credenziale salvata viene sostituita solo quando la sua sostituta può ancora leggere ogni 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 vai alla cartella che contiene i tuoi dati.
3. Conferma la cartella, modifica il nome del dataset se necessario e crea il dataset.

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

• Immagini — Gli oggetti .jpg, .jpeg, .png, .webp e .avif vengono indicizzati con dimensioni lette tramite richieste vincolate. Platform non conserva una seconda copia dell'immagine sorgente.
• Etichette — I file associati YOLO .txt vengono analizzati nelle annotazioni di Platform e associati secondo 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 keypoint della posa, esattamente come un caricamento di archivio. data.yaml e data.yml hanno la precedenza quando la cartella ne contiene diversi.
• Attività — Un campione dei file delle etichette determina l'attività, quindi le cartelle di segmentazione, posa e OBB vengono riconosciute dalla struttura delle etichette anziché dall'attività scelta nella finestra di dialogo.
• Suddivisioni — I nomi delle cartelle train, val e test nel percorso dell'oggetto assegnano automaticamente le suddivisioni.

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

Importazioni non riuscite#

Se un'importazione non riesce — a causa di una cartella vuota, di un errore nel percorso o di autorizzazioni revocate — il dataset mostra l'errore nella relativa pagina. Gli editor possono fare clic su Retry import per riavviarla usando il bucket e la cartella memorizzati, oppure creare un nuovo dataset che punti al percorso corretto.

Un nuovo tentativo elenca nuovamente la cartella invece di riprendere l'operazione: gli oggetti aggiunti dopo il primo tentativo vengono acquisiti, mentre quelli che non si trovano più vengono rimossi dal dataset.

Addestramento#

L'addestramento gestito funziona tramite il normale flusso di addestramento. Durante l'esecuzione, l'addestramento utilizza le copie proprie di Platform delle immagini associate e le tue credenziali Google Cloud non vengono mai esposte ai carichi di lavoro di addestramento.

Disconnetti una connessione#

La disconnessione elimina le credenziali memorizzate senza modificare nulla in Google Cloud. I dataset creati da quei bucket restano nel tuo spazio di lavoro con classi, etichette e annotazioni, ma le relative immagini non possono essere caricate, visualizzate in anteprima o utilizzate per l'addestramento finché lo stesso account di servizio non viene connesso nuovamente.

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 invece l'accesso all'origine, elimina la chiave dell'account di servizio in Google Cloud.

Limitazioni attuali#

I dataset basati su GCS attualmente non includono le funzionalità che richiedono copie delle immagini di proprietà di Platform: annotazione automatica, analisi dei cluster, clonazione dei dataset e snapshot delle versioni 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.

Consulta anche le integrazioni Amazon S3 e Azure Blob Storage.

FAQ#