Utiliser un compte de service personnalisé

Ce guide explique comment configurer Gemini Enterprise Agent Platform pour utiliser un compte de service personnalisé dans les scénarios suivants :

Quand utiliser un compte de service personnalisé

Pendant l'exécution, Agent Platform utilise généralement les autorisations de l'un des multiples comptes de service que Google crée et gère pour votre Google Cloud projet. Pour permettre à Agent Platform d'accéder à d'autres Google Cloud services dans certains contextes, vous pouvez ajouter des rôles spécifiques aux agents de service d'Agent Platform.

Toutefois, le fait de personnaliser les autorisations des agents de service peut ne pas fournir le contrôle des accès précis que vous souhaitez. Voici quelques cas d'utilisation courants :

  • Accorder moins d'autorisations aux tâches et modèles Agent Platform L'agent de service Agent Platform par défaut a accès à BigQuery et à Cloud Storage.
  • Autoriser différentes tâches à accéder à différentes ressources. Vous pouvez autoriser de nombreux utilisateurs à lancer des tâches dans un même projet, mais n'autoriser les tâches de chaque utilisateur qu'à accéder à une table BigQuery ou à un bucket Cloud Storage spécifique.

Par exemple, vous pouvez personnaliser individuellement chaque tâche d'entraînement personnalisée que vous exécutez pour avoir accès à différentes Google Cloud ressources en dehors de votre projet.

De plus, la personnalisation des autorisations des agents de service ne modifie pas les autorisations disponibles pour un conteneur qui diffuse des prédictions à partir d'un Model personnalisé.

Pour personnaliser l'accès à chaque fois que vous effectuez un entraînement personnalisé ou pour personnaliser les autorisations d'un conteneur de prédiction Model résultant d'un entraînement personnalisé, vous devez utiliser un compte de service personnalisé.

Accès par défaut

Cette section décrit l'accès par défaut disponible pour les conteneurs d'entraînement personnalisés et pour les conteneurs de prédiction des ressources Model résultant d'un entraînement personnalisé. Lorsque vous utilisez un compte de service personnalisé, vous remplacez cet accès pour une ressource CustomJob, HyperparameterTuningJob, TrainingPipeline ou DeployedModel spécifique.

Conteneurs d'entraînement

Lorsque vous créez un CustomJob, HyperparameterTuningJob ou un personnaliséTrainingPipeline, le conteneur d'entraînement s'exécute par défaut en utilisant l' Google Cloud agent de service de code personnalisé de Gemini Enterprise Agent Platform de votre projet.

Obtenez plus d'informations sur l' agent de service de code personnalisé de Gemini Enterprise Agent Platform et découvrez comment lui donner accès à d'autres Google Cloud ressources.

Conteneurs de prédiction

Lorsque vous déployez un Model personnalisé entraîné sur un Endpoint, le conteneur de prédiction utilise un compte de service géré par Agent Platform. Ce compte de service est différent des agents de service Agent Platform agents.

Le compte de service utilisé par défaut par le conteneur de prédiction a l'autorisation de lire des artefacts de modèle que Agent Platform met à disposition sur un URI stocké dans la AIP_STORAGE_URI variable d'environnement. Ne comptez pas sur le fait que le compte de service dispose d'autres autorisations. Vous ne pouvez pas personnaliser les autorisations du compte de service.

Configurer un compte de service personnalisé

Les sections suivantes décrivent comment configurer un compte de service personnalisé à utiliser avec Agent Platform et comment configurer un CustomJob, HyperparameterTuningJob, TrainingPipeline ou DeployedModel pour utiliser le compte de service. Notez que vous ne pouvez pas configurer de compte de service personnalisé pour extraire des images d'Artifact Registry. Gemini Enterprise Agent Platform utilise le compte de service par défaut pour extraire des images.

Configurer un compte de service personnalisé

Pour configurer un compte de service personnalisé, procédez comme suit :

  1. Créez un compte de service géré par l'utilisateur. Le compte de service géré par l'utilisateur peut se trouver dans le même projet que vos ressources Agent Platform ou dans un projet différent.

  2. Accordez à votre nouveau compte de service des rôles IAM qui lui permettent d'accéder aux services et ressources que vous souhaitez qu' Agent Platform puisse utiliser lors de l'entraînement personnalisé ou de la prédiction. Google Cloud

  3. Facultatif : Si le compte de service géré par l'utilisateur se trouve dans un projet différent de vos jobs d'entraînement, vous devez attribuer le rôle de créateur de jetons du compte de service (roles/iam.serviceAccountTokenCreator) à l'agent de service Agent Platform du projet dans lequel vous utilisez Agent Platform.

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

  4. Facultatif : Si vous envisagez également d'utiliser le compte de service géré par l'utilisateur pour les prédictions, vous devez attribuer le rôle "Administrateur de compte de service" (roles/iam.serviceAccountAdmin) à l'agent de service Agent Platform du projet dans lequel vous utilisez Agent Platform :

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

    Remplacez les éléments suivants :

    • AI_PLATFORM_SERVICE_AGENT : adresse e-mail de l'agent de service Agent Platform de votre projet, au format suivant :

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

      Pour trouver l'agent de service Agent Platform, accédez à la page IAM dans la Google Cloud console.

      Accéder à IAM

    • CUSTOM_SERVICE_ACCOUNT : adresse e-mail du nouveau compte de service géré par l'utilisateur que vous avez créé à la première étape de cette section.

Spécifier un compte de service personnalisé pour les ressources Agent Platform

Le processus de configuration d'Agent Platform permettant d'utiliser un compte de service spécifique pour une ressource s'appelle la liaison ou l'association du compte de service à la ressource. Les sections suivantes expliquent comment associer le compte de service que vous avez créé dans la section précédente à plusieurs ressources Agent Platform.

Associer un compte de service à une ressource d'entraînement personnalisé

Pour configurer Agent Platform afin qu'il utilise votre nouveau compte de service lors de l'entraînement personnalisé, spécifiez l'adresse e-mail du compte de service dans le serviceAccount champ d'un CustomJobSpec message lorsque vous démarrez l'entraînement personnalisé. Selon le type de ressource d'entraînement personnalisé que vous créez, l'emplacement de ce champ dans votre requête API peut varier :

  • Si vous créez un CustomJob, spécifiez l'adresse e-mail du compte de service dans CustomJob.jobSpec.serviceAccount.

    Découvrez comment créer un CustomJob.

  • Si vous créez un HyperparameterTuningJob, spécifiez l'adresse e-mail du compte de service dans HyperparameterTuningJob.trialJobSpec.serviceAccount.

    Découvrez comment créer un HyperparameterTuningJob.

  • Si vous créez un TrainingPipeline personnalisé sans réglage d'hyperparamètres, spécifiez l'adresse e-mail du compte de service dans TrainingPipeline.trainingTaskInputs.serviceAccount.

  • Si vous créez un TrainingPipeline personnalisé avec réglage d'hyperparamètres, spécifiez l'adresse e-mail du compte de service dans TrainingPipeline.trainingTaskInputs.trialJobSpec.serviceAccount.

Associer un compte de service à un conteneur qui diffuse des prédictions en ligne

Pour configurer le conteneur de prédiction Model résultant d'un entraînement personnalisé afin qu'il utilise votre nouveau compte de service, spécifiez l'adresse e-mail du compte de service lorsque vous déployez le Model sur un Endpoint :

Console

Suivez le guide Déployer un modèle à l'aide de la Google Cloud console. Lorsque vous spécifiez les paramètres du modèle, sélectionnez le compte de service dans la liste déroulante Compte de service.

gcloud

Suivez le guide Déployer un modèle à l'aide de l' API Agent Platform. Lorsque vous exécutez la commande gcloud ai endpoints deploy-model, utilisez l'option --service-account pour spécifier l'adresse e-mail de votre compte de service.

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

  • ENDPOINT_ID : ID du point de terminaison.
  • LOCATION_ID : région dans laquelle vous utilisez Agent Platform.
  • MODEL_ID : ID du modèle à déployer.
  • DEPLOYED_MODEL_NAME : nom de l'élément DeployedModel. Vous pouvez également utiliser le nom à afficher du Model pour le DeployedModel.
  • MACHINE_TYPE (facultatif) : Ressources machine utilisées pour chaque nœud de ce déploiement. Le paramètre par défaut est n1-standard-2. En savoir plus sur les types de machines
  • MIN_REPLICA_COUNT : nombre minimal de nœuds pour ce déploiement. Le nombre de nœuds peut être augmenté ou réduit selon les besoins de la charge d'inférence, dans la limite du nombre maximal de nœuds et sans jamais être inférieur à ce nombre minimal de nœuds.
  • MAX_REPLICA_COUNT : nombre maximal de nœuds pour ce déploiement. Le nombre de nœuds peut être augmenté ou réduit selon les besoins de la charge d'inférence, dans la limite de ce nombre maximal de nœuds, et sans jamais être inférieur au nombre minimal de nœuds.
  • CUSTOM_SERVICE_ACCOUNT : adresse e-mail du compte de service. Par exemple : SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

Exécutez la commande gcloud ai endpoints deploy-model :

Linux, macOS ou 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

Suivez le guide Déployer un modèle à l'aide de l' API Agent Platform. Lorsque vous envoyez la projects.locations.endpoints.deployModel requête, définissez le deployedModel.serviceAccount champ sur l'adresse e-mail du compte de service.

Associer un compte de service à une requête CopyModel

Pour configurer Agent Platform afin qu'il utilise votre nouveau compte de service lors de la copie d'un modèle, spécifiez l'adresse e-mail du compte de service dans le champ customServiceAccount du message CopyModelRequest. Ce compte de service doit appartenir au projet de destination dans lequel le modèle est copié, et vous devez disposer de l'autorisation iam.serviceAccounts.actAs sur ce compte de service.

REST

Suivez le guide Copier un modèle à l'aide de l' API Agent Platform, puis ajoutez le champ customServiceAccount dans le corps JSON de la requête.

API

Lorsque vous envoyez la requête projects.locations.models.copy, définissez le champ customServiceAccount sur l'adresse e-mail du compte de service.

Accéder aux Google Cloud services dans votre code

Si vous configurez Agent Platform pour utiliser un compte de service personnalisé en suivant les instructions des sections précédentes, votre conteneur d'entraînement ou votre conteneur de prédiction peut accéder à tous les Google Cloud services et ressources auxquels le compte de service a accès.

Pour accéder aux Google Cloud services, rédigez votre code d'entraînement ou votre code de diffusion de prédictions de manière à utiliser les Identifiants par défaut de l'application (ADC) et spécifiez explicitement l'ID du projet ou le numéro du projet correspondant à la ressource à laquelle vous souhaitez accéder. Découvrez comment écrire votre code pour accéder à d'autres Google Cloud services.

Limites

Les comptes de service personnalisés dans Gemini Enterprise Agent Platform présentent les limites suivantes :

  • Pour l'inférence par lot, l'agent de service Gemini Enterprise Agent Platform sera toujours utilisé pour accéder à BigQuery et à Cloud Storage, même lorsqu'un compte de service personnalisé est configuré.
  • Vous ne pouvez pas créer plus de 20 comptes de service personnalisés par projet, par région et par service (par exemple, Vertex AI Inference).

Étape suivante

  • En savoir plus sur le contrôle des accès pour Agent Platform.
  • Découvrez les autorisations IAM spécifiques et les opérations qu'elles acceptent.