Benutzerdefiniertes Dienstkonto verwenden

In dieser Anleitung wird beschrieben, wie Sie die Gemini Enterprise Agent Platform für die Verwendung eines benutzerdefinierten Dienstkontos in den folgenden Szenarien konfigurieren:

Wann sollte ein benutzerdefiniertes Dienstkonto verwendet werden?

Wenn die Agent Platform ausgeführt wird, erfolgt dies in der Regel mit den Berechtigungen von einem von mehreren Dienstkonten, die Google erstellt und für Ihr Google Cloud Projekt verwaltet. Wenn Sie der Agent Platform in bestimmten Kontexten mehr Zugriff auf andere Google Cloud Dienste gewähren möchten, können Sie den Dienst-Agents der Agent Platform bestimmte Rollen hinzufügen.

Eine Anpassung der Berechtigungen von Dienst-Agents ermöglicht jedoch unter Umständen nicht die gewünschte genau abgestimmte Zugriffssteuerung. Typische Anwendungsfälle:

  • Weniger Berechtigungen für Agent Platform-Jobs und -Modelle zulassen. Der Standarddienst-Agent der Agent Platform hat Zugriff auf BigQuery und Cloud Storage.
  • Unterschiedlichen Jobs Zugriff auf unterschiedliche Ressourcen gewähren. Möglicherweise möchten Sie vielen Nutzern erlauben, Jobs in einem einzelnen Projekt zu starten, aber den Jobs jedes Nutzers nur Zugriff auf eine bestimmte BigQuery-Tabelle oder einen bestimmten Cloud Storage-Bucket gewähren.

Beispielsweise möchten Sie eventuell jeden ausgeführten benutzerdefinierten Trainingsjob individuell konfigurieren, um Zugriff auf verschiedeneGoogle Cloud Ressourcen außerhalb Ihres Projekts zu erhalten.

Darüber hinaus ändern sich durch das Anpassen der Berechtigungen von Dienst-Agents nicht die Berechtigungen eines Containers, mit dem Vorhersagen von einem benutzerdefinierten Model bereitgestellt werden.

Wenn Sie den Zugriff jedes Mal anpassen möchten, wenn Sie ein benutzerdefiniertes Training ausführen, oder um die Berechtigungen des Vorhersagecontainers eines benutzerdefinierten Model anzupassen, müssen Sie ein benutzerdefiniertes Dienstkonto verwenden.

Standardzugriff

In diesem Abschnitt wird der Standardzugriff für benutzerdefinierte Trainings- und Vorhersagecontainer von benutzerdefinierten Model-Ressourcen erläutert. Wenn Sie ein benutzerdefiniertes Dienstkonto verwenden, überschreiben Sie diesen Zugriff für eine bestimmte Ressource vom Typ CustomJob, HyperparameterTuningJob, TrainingPipeline oder DeployedModel.

Trainingscontainer

Wenn Sie einen CustomJob, HyperparameterTuningJob oder eine benutzerdefinierte TrainingPipeline erstellen, wird der Trainings container standardmäßig mit dem Google Cloud Dienst-Agent des benutzerdefinierten Gemini Enterprise Agent Platform-Codes Ihres Projekts ausgeführt.

Weitere Informationen zum Dienst-Agent des benutzerdefinierten Gemini Enterprise Agent Platform-Codes, einschließlich der Informationen zum Gewähren des Zugriffs auf zusätzliche Google Cloud Ressourcen

Vorhersagecontainer

Wenn Sie ein benutzerdefiniertes Model für einen Endpoint bereitstellen, wird der Vorhersagecontainer mit einem Dienstkonto ausgeführt, das von der Agent Platform verwaltet wird. Dieses Dienstkonto unterscheidet sich von den Dienst-Agents der Agent Platform agents.

Das Dienstkonto, das standardmäßig vom Vorhersagecontainer verwendet wird, ist berechtigt, Modellartefakte zu lesen , die von der Agent Platform unter einem URI verfügbar gemacht werden, der in der AIP_STORAGE_URI Umgebungsvariable gespeichert ist. Wenn Sie andere Berechtigungen benötigen, ist dafür das Dienstkonto nicht geeignet. Sie können die Berechtigungen des Dienstkontos nicht anpassen.

Benutzerdefiniertes Dienstkonto konfigurieren

In den folgenden Abschnitten wird gezeigt, wie Sie ein benutzerdefiniertes Dienstkonto für die Verwendung mit der Agent Platform einrichten und wie Sie CustomJob, HyperparameterTuningJob, TrainingPipeline oder DeployedModel für die Verwendung des Dienstkontos konfigurieren. Sie können kein benutzerdefiniertes Dienstkonto zum Abrufen von Bildern aus Artifact Registry konfigurieren. Die Gemini Enterprise Agent Platform verwendet das Standarddienstkonto zum Abrufen von Bildern.

Benutzerdefiniertes Dienstkonto einrichten

So richten Sie ein benutzerdefiniertes Dienstkonto ein:

  1. Erstellen Sie ein vom Nutzer verwaltetes Dienstkonto. Das vom Nutzer verwaltete Dienstkonto kann sich im selben Projekt wie Ihre Agent Platform-Ressourcen oder in einem anderen Projekt befinden.

  2. Weisen Sie dem neuen Dienstkonto IAM Rollen zu, die Zugriff auf die Google Cloud Dienste und Ressourcen gewähren, die die Agent Platform für das benutzerdefinierte Training oder die Vorhersage verwenden soll.

  3. Optional: Wenn sich das vom Nutzer verwaltete Dienstkonto in einem anderen Projekt als Ihre Trainingsjobs befindet, müssen Sie dem Dienst-Agent der Agent Platform des Projekts, in dem Sie die Agent Platform verwenden, die Rolle „Ersteller von Dienstkonto-Tokens“ (roles/iam.serviceAccountTokenCreator) zuweisen.

    gcloud iam service-accounts add-iam-policy-binding \
    --role=roles/iam.serviceAccountTokenCreator \
    --member=serviceAccount:AI_PLATFORM_SERVICE_AGENT \
    CUSTOM_SERVICE_ACCOUNT

  4. Optional: Wenn Sie auch das vom Nutzer verwaltete Dienstkonto für Vorhersagen verwenden möchten, müssen Sie dem Dienst-Agent der Agent Platform des Projekts, in dem Sie die Agent Platform verwenden, die Rolle „Dienstkontoadministrator“ (roles/iam.serviceAccountAdmin) zuweisen:

    gcloud iam service-accounts add-iam-policy-binding \
  --role=roles/iam.serviceAccountAdmin \
  --member=serviceAccount:AI_PLATFORM_SERVICE_AGENT \
  CUSTOM_SERVICE_ACCOUNT

    Ersetzen Sie Folgendes:

    • AI_PLATFORM_SERVICE_AGENT: Die E-Mail-Adresse des Dienst-Agents der Agent Platform Ihres Projekts im folgenden Format:

      service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com

      Rufen Sie in der Google Cloud Console die Seite IAM auf, um den Dienst-Agent der Agent Platform zu finden.

      IAM aufrufen

    • CUSTOM_SERVICE_ACCOUNT: Die E-Mail-Adresse des neuen vom Nutzer verwalteten Dienstkontos, das Sie im ersten Schritt dieses Abschnitts erstellt haben.

Benutzerdefiniertes Dienstkonto für Agent Platform-Ressourcen angeben

Das Konfigurieren der Agent Platform für die Verwendung eines bestimmten Dienstkontos für eine Ressource wird als Anhängen des Dienstkontos an die Ressource bezeichnet. In den folgenden Abschnitten wird beschrieben, wie Sie das im vorherigen Abschnitt erstellte Dienstkonto an mehrere Agent Platform-Ressourcen anhängen.

Dienstkonto an eine benutzerdefinierte Trainingsressource anhängen

Wenn Sie die Agent Platform für die Verwendung Ihres neuen Dienstkontos während des benutzerdefinierten Trainings konfigurieren möchten, geben Sie die E-Mail-Adresse des Dienstkontos im serviceAccount Feld einer CustomJobSpec Nachricht an, wenn Sie das benutzerdefinierte Training starten. Je nachdem, welche Art von benutzerdefinierter Trainings ressource Sie erstellen, unterscheidet sich die Platzierung dieses Felds in Ihrer API-Anfrage:

  • Wenn Sie einen CustomJob erstellen, geben Sie die E-Mail-Adresse des Dienstkontos in CustomJob.jobSpec.serviceAccount an.

    Weitere Informationen erhalten Sie im Abschnitt über das Erstellen eines CustomJob.

  • Wenn Sie einen HyperparameterTuningJob erstellen, geben Sie die E-Mail-Adresse des Dienstkontos in HyperparameterTuningJob.trialJobSpec.serviceAccount an.

    Weitere Informationen im Abschnitt über das Erstellen eines HyperparameterTuningJob.

  • Wenn Sie eine benutzerdefinierte TrainingPipeline ohne Hyperparameter-Abstimmung erstellen, geben Sie die E-Mail-Adresse des Dienstkontos in TrainingPipeline.trainingTaskInputs.serviceAccount an.

  • Wenn Sie eine benutzerdefinierte TrainingPipeline mit Hyperparameter-Abstimmung erstellen, geben Sie die E-Mail-Adresse des Dienstkontos in TrainingPipeline.trainingTaskInputs.trialJobSpec.serviceAccount an.

Dienstkonto an einen Container für Onlinevorhersagen anhängen

Um einen Vorhersagecontainer für ein benutzerdefiniertes Model für die Verwendung Ihres neuen Dienstkontos zu konfigurieren, geben Sie die E-Mail-Adresse des Dienstkontos an, wenn Sie das Model für einen Endpoint bereitstellen:

Console

Folgen Sie den Erläuterungen unter Modell mit der Google Cloud Console bereitstellen. Beim Festlegen von Modelleinstellungen wählen Sie das Dienstkonto in der Drop-down-Liste Dienstkonto aus.

gcloud

Folgen Sie den Erläuterungen unter Modell mithilfe der Agent Platform API bereitstellen. Verwenden Sie beim Ausführen des Befehls gcloud ai endpoints deploy-model das Flag --service-account, um die E-Mail-Adresse Ihres Dienstkontos anzugeben.

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • ENDPOINT_ID: Die ID des Endpunkts.
  • LOCATION_ID: Die Region, in der Sie die Agent Platform verwenden.
  • MODEL_ID: Die ID des bereitzustellenden Modells.
  • DEPLOYED_MODEL_NAME: Ein Name für DeployedModel. Sie können auch den Anzeigenamen von Model für DeployedModel verwenden.
  • MACHINE_TYPE: Optional. Die für jeden Knoten dieser Bereitstellung verwendeten Maschinenressourcen. Die Standardeinstellung ist n1-standard-2. Weitere Informationen zu Maschinentypen.
  • MIN_REPLICA_COUNT: Die minimale Anzahl von Knoten für diese Bereitstellung. Die Knotenzahl kann je nach der Inferenzlast erhöht oder verringert werden, bis zur maximalen Anzahl von Knoten und niemals auf weniger als diese Anzahl von Knoten.
  • MAX_REPLICA_COUNT: Die maximale Anzahl von Knoten für diese Bereitstellung. Die Knotenzahl kann je nach der Inferenzlast erhöht oder verringert werden, bis zu dieser Anzahl von Knoten und niemals auf weniger als die minimale Anzahl von Knoten.
  • CUSTOM_SERVICE_ACCOUNT: Die E-Mail-Adresse des Dienstkontos. Beispiel: SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

Führen Sie den Befehl gcloud ai endpoints deploy-model aus:

Linux, macOS oder Cloud Shell

gcloud ai endpoints deploy-model ENDPOINT_ID \
  --region=LOCATION \
  --model=MODEL_ID \
  --display-name=DEPLOYED_MODEL_NAME \
  --machine-type=MACHINE_TYPE \
  --min-replica-count=MIN_REPLICA_COUNT \
  --max-replica-count=MAX_REPLICA_COUNT \
  --traffic-split=0=100 \
  --service-account=CUSTOM_SERVICE_ACCOUNT

Windows (PowerShell)

gcloud ai endpoints deploy-model ENDPOINT_ID `
  --region=LOCATION `
  --model=MODEL_ID `
  --display-name=DEPLOYED_MODEL_NAME `
  --machine-type=MACHINE_TYPE `
  --min-replica-count=MIN_REPLICA_COUNT `
  --max-replica-count=MAX_REPLICA_COUNT `
  --traffic-split=0=100 `
  --service-account=CUSTOM_SERVICE_ACCOUNT

Windows (cmd.exe)

gcloud ai endpoints deploy-model ENDPOINT_ID ^
  --region=LOCATION ^
  --model=MODEL_ID ^
  --display-name=DEPLOYED_MODEL_NAME ^
  --machine-type=MACHINE_TYPE ^
  --min-replica-count=MIN_REPLICA_COUNT ^
  --max-replica-count=MAX_REPLICA_COUNT ^
  --traffic-split=0=100 ^
  --service-account=CUSTOM_SERVICE_ACCOUNT
  

API

Folgen Sie den Erläuterungen unter Modell mithilfe der Agent Platform API bereitstellen. Wenn Sie die projects.locations.endpoints.deployModel Anfragesenden, legen Sie für das deployedModel.serviceAccount Feld die E-Mail-Adresse des Dienstkontos fest.

Dienstkonto an eine CopyModel-Anfrage anhängen

Wenn Sie die Agent Platform für die Verwendung Ihres neuen Dienstkontos beim Kopieren eines Modells konfigurieren möchten, geben Sie die E-Mail-Adresse des Dienstkontos im Feld customServiceAccount der Nachricht CopyModelRequest an. Dieses Dienstkonto muss zum Zielprojekt gehören, in das das Modell kopiert wird, und Sie benötigen die Berechtigung iam.serviceAccounts.actAs für dieses Dienstkonto.

REST

Folgen Sie den Erläuterungen unter Modell mithilfe der Agent Platform API kopieren und fügen Sie das Feld customServiceAccount in den JSON-Anfragetext ein.

API

Wenn Sie die projects.locations.models.copy Anfrage senden, legen Sie für das customServiceAccount Feld die E-Mail-Adresse des Dienstkontos fest.

Auf Google Cloud Dienste in Ihrem Code zugreifen

Wenn Sie die Agent Platform für die Verwendung eines benutzerdefinierten Dienstkontos gemäß der Anleitung in den vorherigen Abschnitten konfigurieren, kann Ihr Trainings- oder Vorhersagecontainer auf alle Dienste und Ressourcen zugreifen, auf die das Dienstkonto Zugriff hat. Google Cloud

Um auf Google Cloud Dienste zuzugreifen, legen Sie in Ihrem Trainings code oder in Ihrem Code zur Vorhersagebereitstellung code die Verwendung von Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) fest und geben Sie explizit die Projekt-ID oder Projektnummer der Ressource an, auf die Sie zugreifen möchten. Weitere Informationen zum Schreiben von Code für den Zugriff auf andere Google Cloud Dienste.

Beschränkungen

Für benutzerdefinierte Dienstkonten in der Gemini Enterprise Agent Platform gelten die folgenden Beschränkungen:

  • Für die Batchinferenz wird weiterhin der Dienst-Agent der Gemini Enterprise Agent Platform verwendet, um auf BigQuery und Cloud Storage zuzugreifen, auch wenn ein benutzerdefiniertes Dienstkonto konfiguriert ist.
  • Pro Projekt, Region und Dienst (z. B. Vertex AI Inference) sind maximal 20 benutzerdefinierte Dienstkonten zulässig.

Nächste Schritte