Google-Cloud-Storage-Integration

Die Integration von Google Cloud Storage verbindet deine GCS-Buckets mit der Ultralytics Platform. Deine Bilder bleiben in deinen Buckets – die Platform indexiert sie direkt dort. So kannst du YOLO-Modelle durchsuchen, annotieren und trainieren, ohne eine Kopie hochzuladen. Wenn KI-Funktionen aktiviert sind, kann die Platform die Bilder außerdem für intelligente Annotation, automatische Annotation, die Suche nach ähnlichen Bildern und Cloud-Training verwenden.

Dienstkonto erstellen#

Der Lesezugriff deckt alles außer der Bildgenerierung ab, bei der auch Objekte erstellt werden. Die Platform ändert oder löscht deine Objekte niemals. Erstelle ein dediziertes Dienstkonto:

1. Öffne in der Google-Cloud-Konsole IAM & Admin > Service Accounts und erstelle ein Dienstkonto.
2. Weise dem Konto für die Buckets, die du verbinden möchtest, die Rolle Storage Object Viewer (roles/storage.objectViewer) zu. Für die Bildgenerierung musst du außerdem Storage Object Creator (roles/storage.objectCreator) zuweisen. Damit können Objekte erstellt, aber nicht überschrieben oder gelöscht werden.
3. Öffne das Dienstkonto, wähle Keys > Add key > Create new key, wähle JSON und lade die Schlüsseldatei herunter.

Mit Platform verbinden#

1. Gehe zu Settings > Integrations und wähle in der Integrationsliste Google Cloud Storage aus.
2. Füge den Inhalt des JSON-Schlüssels für das Dienstkonto ein.
3. Klicke auf Find available buckets und wähle dann die Buckets aus, die du verbinden möchtest. Wenn das Dienstkonto Buckets nicht auflisten kann, gib den Namen eines bekannten Buckets manuell ein.
4. Klicke auf Connect. Die Platform überprüft vor dem Speichern, ob sie jeden ausgewählten Bucket auflisten und daraus lesen kann, und fragt Google Cloud, ob das Dienstkonto auch Objekte erstellen kann. Es werden keine Daten geschrieben.

Für jede verbundene Anmeldeinformation gibt es einen Schalter für KI-Funktionen. Nachdem du die Rollen geändert hast, verbinde dasselbe Dienstkonto erneut, um den Schreibzugriff erneut zu überprüfen.

Zum Verbinden von Cloud-Speicher brauchst du die Rolle eines Arbeitsbereichsadmins oder -inhabers. Du kannst bis zu 50 Buckets gleichzeitig hinzufügen. Bei der Suche werden bis zu 300 der für das Dienstkonto sichtbaren Buckets aufgelistet.

Dein Browser liest die eingefügte Schlüsseldatei und sendet nur die drei Felder, die Platform benötigt: client_email, private_key und project_id. Der Rest der JSON-Datei verlässt die Seite nie.

Wenn du später dasselbe Dienstkonto erneut verbindest, werden neue Buckets zur bestehenden Integration hinzugefügt. Gespeicherte Anmeldedaten werden erst ersetzt, wenn mit den neuen Anmeldedaten weiterhin auf alle bereits verbundenen Buckets zugegriffen werden kann. Ist ein Bucket nicht lesbar, wird er in der Fehlermeldung genannt – auch wenn er zuvor mit demselben Dienstkonto verbunden wurde.

KI-Funktionen#

Für jede verbundene Anmeldeinformation gibt es unter Settings > Integrations einen standardmäßig aktivierten Schalter für KI-Funktionen. Solange er aktiviert ist, können Ultralytics-GPUs und KI-Modellanbieter die Bilder dieser Anmeldeinformation für Folgendes verwenden:

• Intelligente SAM-Annotation sowie automatische Annotation einzelner Bilder und im Stapel
• Suche nach ähnlichen Bildern und Clustering-Analyse
• Cloud-Training
• Bildgenerierung für Buckets mit Schreibzugriff

Anbieter von KI-Modellen kommen nur bei der Bilderzeugung zum Einsatz, deren Prompts Google Gemini anhand des Ausgangsbilds erstellt, sowie bei kostenpflichtigen Annotationsmodellen, die mit dem eigenen Anbieterschlüssel deines Arbeitsbereichs ausgeführt werden. Die Platform speichert keine Kopien deiner Bilder: Funktionen lesen sie bei Bedarf ein, beim Cloud-Training werden für die Dauer eines Trainingslaufs temporäre Kopien verwendet und die Suche nach ähnlichen Bildern speichert ein Embedding für jedes Bild, das gelöscht wird, sobald das Bild die Platform verlässt.

Deaktiviere den Schalter, damit die Bilder nicht auf Ultralytics-GPUs und bei KI-Modellanbietern verwendet werden. Dadurch werden keine neuen KI-Aufgaben mehr gestartet; bereits laufende Aufgaben werden abgeschlossen. Bei Datensätzen mit dieser Anmeldeinformation wird dann AI features off angezeigt, zusammen mit einem Link zu diesen Einstellungen. Für jede nicht verfügbare Funktion wird der Grund erläutert. Manuelle Annotation, Freigabe und lokales Training funktionieren weiterhin. Bereits erstellte Beschriftungen, Modelle und Suchergebnisse bleiben erhalten.

Du benötigst die Rolle eines Workspace-Administrators oder -Eigentümers, um den Schalter zu ändern. Du kannst die Einstellung auch über die REST API ändern. Verwende dazu die Integrations-ID, die von GET /api/integrations/buckets zurückgegeben wird:

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

Bildgenerierung#

Ähnliche Bilder generieren funktioniert bei Datensätzen in Google Cloud Storage, deren Bucket das Dienstkonto beschreiben kann, sofern KI-Funktionen aktiviert sind. Hinzugefügte Bilder werden in einen Ordner generated/ innerhalb des Datensatzordners geschrieben und anschließend wie jedes andere indexierte Bild zum Datensatz hinzugefügt. Die Platform erstellt dort nur neue Objekte und überschreibt oder löscht niemals vorhandene Objekte. Wenn für die Aktion Schreibzugriff erforderlich ist, erteile ihn bei Bedarf und verbinde dasselbe Dienstkonto erneut unter Settings > Integrations.

Einen Datensatz aus einem GCS-Bucket erstellen#

1. Klicke auf New Dataset und öffne den Tab Cloud.
2. Wähle einen verbundenen Bucket aus und navigiere zum Ordner mit deinen Daten.
3. Bestätige den Ordner, passe den Datensatznamen an und erstelle den Datensatz.

Platform listet den Ordner einmal auf und indiziert die gefundenen Inhalte:

• Bilder – Objekte mit den Endungen .jpg, .jpeg, .png, .webp und .avif werden indiziert. Die Abmessungen werden mit begrenzten Anfragen ausgelesen. Platform speichert keine zweite Kopie des Quellbilds.
• Labels – YOLO-.txt-Begleitdateien werden in Platform-Annotationen umgewandelt. Die Zuordnung erfolgt anhand der üblichen Struktur images/ → labels/ oder über gleichgeordnete Dateien im selben Ordner.
• Metadaten – Eine YAML-Datei enthält Klassennamen und die Form der Pose-Keypoints, genau wie beim Hochladen eines Archivs. Wenn der Ordner mehrere Dateien enthält, werden data.yaml und data.yml bevorzugt.
• Aufgabe – Die Aufgabe wird anhand einer Stichprobe der Labeldateien bestimmt. Segmentierungs-, Pose- und OBB-Ordner werden daher an der Form ihrer Labels erkannt und nicht anhand der im Dialog ausgewählten Aufgabe.
• Aufteilungen – Ordnernamen train, val und test im Objektpfad weisen die Aufteilungen automatisch zu.

Der Datensatz funktioniert anschließend wie jeder andere: Du kannst ihn durchsuchen, annotieren, öffentlich oder privat schalten, mit deinem Team teilen und über verwaltetes Training damit trainieren. Originale werden bei Bedarf übertragen und indizierte Bilder werden nicht auf dein Speicherkontingent in Platform angerechnet.

Fehlgeschlagene Importe#

Wenn ein Import fehlschlägt – etwa wegen eines leeren Ordners, eines Tippfehlers im Pfad oder entzogener Berechtigungen –, wird der Fehler auf der Datensatzseite angezeigt. Editoren können auf Import wiederholen klicken, um den Import mit dem gespeicherten Bucket und Ordner erneut zu starten, oder einen neuen Datensatz mit dem korrigierten Pfad erstellen.

Bei einem erneuten Versuch wird der Ordner neu aufgelistet, statt den Import fortzusetzen: Seit dem ersten Versuch hinzugefügte Objekte werden erfasst, und nicht mehr vorhandene Objekte werden aus dem Datensatz entfernt.

Training#

Bei aktiviertem KI-Funktionen funktioniert das verwaltete Training über den üblichen Trainingsablauf. Für die Dauer des Trainingslaufs verwendet das Training eigene Kopien der angehefteten Bilder, die von der Platform erstellt werden. Deine Google Cloud-Anmeldedaten werden niemals den Trainingsprozessen zugänglich gemacht. Wenn KI-Funktionen deaktiviert sind, erklärt der Trainingsdialog, warum Cloud-Training nicht verfügbar ist, und bietet stattdessen lokales Training an.

Verbindung trennen#

Beim Trennen der Verbindung werden die gespeicherten Anmeldedaten gelöscht, ohne etwas in Google Cloud zu ändern. Aus diesen Buckets erstellte Datensätze bleiben mit ihren Klassen, Beschriftungen und Anmerkungen in deinem Arbeitsbereich, aber ihre Bilder können erst wieder geladen, in der Vorschau angezeigt oder für das Training verwendet werden, wenn dasselbe Dienstkonto erneut verbunden wird. Auch ohne Verbindung kannst du sie umbenennen, ihre Beschriftungen bearbeiten oder sie löschen.

Um die Verbindung zu trennen, gehe zu Einstellungen > Integrationen, wähle Google Cloud Storage aus, klicke neben den Anmeldedaten auf Trennen und bestätige den Vorgang. Wenn du anschließend einen der zugehörigen Datensätze öffnest, wird Google Cloud Storage getrennt mit einem Link zu diesen Einstellungen angezeigt. Nach der erneuten Verbindung ist der Datensatz automatisch wieder verfügbar.

Du kannst die Verbindung auch über die REST API trennen. Verwende dazu die von GET /api/integrations/buckets zurückgegebene Integrations-ID:

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")

Um den Zugriff stattdessen direkt an der Quelle zu widerrufen, lösche den Schlüssel des Dienstkontos in Google Cloud.

Derzeitige Einschränkungen#

Bei Datensätzen in GCS sind Funktionen nicht verfügbar, die eigene Bildkopien in der Platform benötigen: das Klonen von Datensätzen, unveränderliche Versions-Snapshots, das Weichzeichnen von Gesichtern und das Einfügen von Bildern aus anderen Datensätzen. Für intelligente Annotation, automatische Annotation, die Suche nach ähnlichen Bildern, Clustering, Cloud-Training und Bildgenerierung müssen KI-Funktionen aktiviert sein.

Beim Löschen eines Datensatzes auf GCS oder einzelner Bilder daraus werden nur die Verweise von Platform entfernt – deine Objekte bleiben unberührt.

Siehe auch die Integrationen für Amazon S3 und Azure Blob Storage.

Häufig gestellte Fragen#