Integrazione Amazon S3

L'integrazione Amazon S3 collega i tuoi bucket S3 alla Ultralytics Platform. Le immagini restano nei tuoi bucket: la Platform le indicizza direttamente, così puoi consultarle, annotarle e addestrare modelli YOLO senza caricarne una copia. Con le funzionalità AI attive, la Platform può anche usarle per l'annotazione intelligente, l'annotazione automatica, la ricerca di immagini simili e l'addestramento nel cloud.

Crea un utente IAM#

L'accesso in lettura copre tutto, tranne la generazione di immagini, che crea anche oggetti. La Platform non modifica né elimina mai i tuoi oggetti. Usa un utente IAM dedicato, mai le credenziali root:

1. Nella console AWS, vai a IAM > Utenti e crea un utente senza accesso alla console.

2. Associa una policy che conceda l'accesso per elencare e leggere i bucket che vuoi collegare:

   {
       "Version": "2012-10-17",
       "Statement": [
           { "Effect": "Allow", "Action": "s3:ListAllMyBuckets", "Resource": "*" },
           {
               "Effect": "Allow",
               "Action": ["s3:ListBucket", "s3:GetObject"],
               "Resource": ["arn:aws:s3:::my-bucket", "arn:aws:s3:::my-bucket/*"]
           }
       ]
   }

   s3:ListAllMyBuckets è facoltativo: consente a Platform di individuare i tuoi bucket, così non devi inserirne i nomi.

   Per la generazione di immagini, consenti anche s3:PutObject:

   {
       "Effect": "Allow",
       "Action": "s3:PutObject",
       "Resource": [
           "arn:aws:s3:::my-bucket/generated/*",
           "arn:aws:s3:::my-bucket/*/generated/*",
           "arn:aws:s3:::my-bucket/.ultralytics-write-check"
       ]
   }

   S3 non dispone di un'autorizzazione di sola creazione, quindi questo limita le scritture alle cartelle generated/ e alla chiave .ultralytics-write-check che la Platform usa per verificare l'accesso in scrittura (la verifica viene sempre rifiutata, quindi non viene salvato nulla). Le scritture eseguite dalla Platform non sovrascrivono mai i dati.

3. Apri la scheda Credenziali di sicurezza dell'utente, crea una chiave di accesso e copia l'ID della chiave di accesso e la chiave di accesso segreta.

Connettiti a Platform#

1. Vai a Impostazioni > Integrazioni e seleziona Amazon S3 nell'elenco delle integrazioni.
2. Inserisci l'ID della chiave di accesso, la chiave di accesso segreta e la regione del bucket (ad esempio us-east-1).
3. Fai clic su Trova bucket disponibili, poi seleziona i bucket da collegare. Se la policy non consente di individuarli, inserisci manualmente il nome di un bucket noto.
4. Fai clic su Connetti. Prima di salvare qualsiasi dato, la Platform verifica di poter elencare e leggere ogni bucket selezionato e controlla se la chiave può anche scriverci con una richiesta che S3 rifiuta sempre, così non viene salvato nulla.

Ogni credenziale connessa include un interruttore per le funzionalità AI. Dopo aver modificato la policy IAM, riconnetti lo stesso utente IAM per verificare nuovamente l'accesso in scrittura.

Per collegare lo spazio di archiviazione cloud, ti serve il ruolo di amministratore o proprietario del workspace. Puoi aggiungere fino a 50 bucket alla volta; l'individuazione elenca fino a 300 bucket accessibili con la chiave.

Ricollegando in seguito lo stesso utente IAM, puoi aggiungere nuovi bucket all'integrazione esistente. Una credenziale salvata viene sostituita solo se quella nuova può continuare a leggere tutti i bucket già collegati. Se non è possibile leggere un bucket, il messaggio di errore ne indica il nome, inclusi i bucket collegati in precedenza con lo stesso utente IAM.

Funzionalità AI#

Ogni credenziale connessa include un interruttore Funzionalità AI in Impostazioni > Integrazioni, attivo per impostazione predefinita. Quando è attivo, le GPU Ultralytics e i provider di modelli AI possono usare le immagini associate a quella credenziale per:

• Annotazione intelligente SAM e annotazione automatica di immagini singole e in batch
• Ricerca di immagini simili e analisi di clustering
• Addestramento nel cloud
• Generazione di immagini, nei bucket con accesso in scrittura

I provider di modelli AI intervengono solo nella generazione di immagini, per la quale Google Gemini pianifica i prompt a partire dall'immagine sorgente, e nei modelli di annotazione a pagamento, che funzionano con la chiave del provider del tuo workspace. Platform non conserva copie delle tue immagini: le funzionalità le leggono su richiesta, il training nel cloud usa copie temporanee per la durata di un'esecuzione e la ricerca di immagini simili conserva un embedding per ogni immagine, che viene eliminato quando l'immagine lascia Platform.

Disattiva l'interruttore per impedire alle GPU Ultralytics e ai provider di modelli AI di accedere alle immagini. La disattivazione interrompe l'avvio di nuove attività AI; quelle già in corso vengono completate. I dataset che usano quella credenziale mostrano quindi Funzionalità AI disattivate, con un link a queste impostazioni, e ogni funzionalità non disponibile ne spiega il motivo. L'annotazione manuale, la condivisione e l'addestramento locale continuano a funzionare, e le etichette, i modelli e i risultati di ricerca già creati vengono mantenuti.

Per modificare l'interruttore, ti serve il ruolo di amministratore o proprietario del workspace. Puoi impostarlo anche tramite la REST API, usando l'ID dell'integrazione restituito da GET /api/integrations/buckets:

curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"processing": false}' \
  https://platform.ultralytics.com/api/integrations/buckets/INTEGRATION_ID

Generazione di immagini#

La funzione Genera immagini simili è disponibile per i dataset Amazon S3 il cui bucket consente all'utente IAM di scrivere, mentre le funzionalità AI sono attive. Le immagini aggiunte vengono salvate in una cartella generated/ all'interno della cartella del dataset, quindi aggiunte al dataset come qualsiasi altra immagine indicizzata. La Platform crea nuovi oggetti in quella cartella e non sovrascrive né elimina mai quelli esistenti. Se l'azione segnala che serve l'accesso in scrittura, concedilo se necessario e riconnetti lo stesso utente IAM in Impostazioni > Integrazioni.

Crea un dataset da un bucket S3#

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 delle cartelle train, val e test nella chiave 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 quando le funzionalità AI sono attive. Per la durata dell'esecuzione, l'addestramento usa copie delle immagini fissate create dalla Platform; le tue credenziali AWS non vengono mai esposte ai carichi di lavoro di addestramento. Se le funzionalità AI sono disattivate, la finestra di dialogo dell'addestramento spiega perché l'addestramento nel cloud non è disponibile e propone invece quello locale.

Disconnetti una connessione#

La disconnessione elimina le credenziali salvate senza modificare nulla in AWS. 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 utente IAM. Anche mentre sono disconnessi, puoi rinominare i dataset, modificare le etichette o eliminarli.

Per disconnettere, vai a Impostazioni > Integrazioni, seleziona Amazon S3, fai clic su Disconnetti accanto alla credenziale e conferma. Quando apri uno dei dataset associati, viene mostrato Amazon S3 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, disattiva o elimina la chiave di accesso in AWS IAM.

Limitazioni attuali#

I dataset basati su S3 non supportano le funzionalità che richiedono copie delle immagini di proprietà della Platform: clonazione dei dataset, istantanee di versione immutabili, sfocatura dei volti e incollamento di immagini da altri dataset. L'annotazione intelligente, l'annotazione automatica, la ricerca di immagini simili, il clustering, l'addestramento nel cloud e la generazione di immagini richiedono che le funzionalità AI siano attive.

L'eliminazione di un dataset collegato a S3 o di singole immagini al suo interno rimuove solo i riferimenti di Platform: gli oggetti non vengono mai modificati.

Consulta anche le integrazioni Google Cloud Storage e Azure Blob Storage.

Domande frequenti#