Usar una cuenta de servicio personalizada

En esta guía, se describe cómo configurar Gemini Enterprise Agent Platform para usar una cuenta de servicio personalizada en las siguientes situaciones:

Cuándo usar una cuenta de servicio personalizada

Cuando se ejecuta Agent Platform, suele actuar con los permisos de una de las varias cuentas de servicio que Google crea y administra para tu proyecto de Cloud de Confiance by S3NS . Para otorgar a Agent Platform un mayor acceso a otros servicios de Cloud de Confiance en ciertos contextos, puedes agregar roles específicos a los agentes de servicio de Agent Platform.

Sin embargo, personalizar los permisos de los agentes de servicio podría no proporcionar el control de acceso detallado que deseas. Estos son algunos casos de uso comunes:

  • Otorgar menos permisos a los trabajos y modelos de Agent Platform El agente de servicio predeterminado de Agent Platform tiene acceso a BigQuery y Cloud Storage.
  • Permitir que diferentes trabajos accedan a diferentes recursos. Es posible que desees permitir que muchos usuarios inicien trabajos en un solo proyecto, pero que otorguen acceso a los trabajos de cada usuario solo a una tabla de BigQuery o a un bucket de Cloud Storage determinados.

Por ejemplo, es posible que desees personalizar de forma individual cada trabajo de entrenamiento personalizado que ejecutes para tener acceso a diferentes recursos deCloud de Confiance fuera de tu proyecto.

Además, personalizar los permisos de los agentes de servicio no cambia los permisos disponibles para un contenedor que entrega predicciones desde un Model entrenado de forma personalizada.

Para personalizar el acceso cada vez que realizas un entrenamiento personalizado o los permisos de un contenedor de predicción personalizado de un Model, debes usar una cuenta de servicio personalizada.

Acceso predeterminado

En esta sección, se describe el acceso predeterminado disponible para los contenedores de entrenamiento personalizados y los contenedores de predicción de recursos del Model con entrenamiento personalizado. Cuando usas una cuenta de servicio personalizada, anulas este acceso para un recurso específico de CustomJob, HyperparameterTuningJob, TrainingPipeline o DeployedModel.

Contenedores de entrenamiento

Cuando creas un CustomJob, HyperparameterTuningJob o un TrainingPipeline personalizado, el contenedor de entrenamiento se ejecuta con el agente de servicio de código personalizado de Gemini Enterprise Agent Platform de tu proyecto deCloud de Confiance de forma predeterminada.

Obtén más información sobre el agente de servicio de código personalizado de Gemini Enterprise Agent Platform, incluido cómo otorgarle acceso a recursos adicionales de Cloud de Confiance .

Contenedores de predicción

Cuando implementas un Model con entrenamiento personalizado en un Endpoint, el contenedor de predicción se ejecuta con una cuenta de servicio administrada por Agent Platform. Esta cuenta de servicio es diferente de los agentes de servicio de Agent Platform.

La cuenta de servicio que usa el contenedor de predicción de forma predeterminada tiene permiso para leer los artefactos del modelo que Agent Platform pone a disposición en un URI almacenado en la variable de entorno AIP_STORAGE_URI. No dependas de que la cuenta de servicio tenga otros permisos. No puedes personalizar los permisos de la cuenta de servicio.

Configura una cuenta de servicio personalizada

En las siguientes secciones, se describe cómo configurar una cuenta de servicio personalizada para usar con Agent Platform y cómo configurar CustomJob, HyperparameterTuningJob, TrainingPipeline o DeployedModel para usar la cuenta de servicio. Ten en cuenta que no puedes configurar una cuenta de servicio personalizada para extraer imágenes de Artifact Registry. Gemini Enterprise Agent Platform usa la cuenta de servicio predeterminada para extraer imágenes.

Configura una cuenta de servicio personalizada

Para configurar una cuenta de servicio personalizada, haz lo siguiente:

  1. Crea una cuenta de servicio administrada por el usuario. La cuenta de servicio administrada por el usuario puede estar en el mismo proyecto que los recursos de Agent Platform o en un proyecto diferente.

  2. Otorga a la cuenta de servicio tus funciones nuevas de IAM que proporcionan acceso a los servicios y recursos de Cloud de Confiance que deseas que Agent Platform pueda usar durante el entrenamiento personalizado o predicción.

  3. Opcional: Si la cuenta de servicio administrada por el usuario está en un proyecto diferente del de tus trabajos de entrenamiento, debes otorgar el rol de creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) al agente de servicio de Agent Platform del proyecto en el que usas Agent Platform.

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

  4. Opcional: Si también planeas usar la cuenta de servicio administrada por el usuario para las predicciones, debes otorgar el rol de administrador de cuenta de servicio (roles/iam.serviceAccountAdmin) al agente de servicio de Agent Platform del proyecto en el que usas Agent Platform:

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

    Reemplaza lo siguiente:

    • AI_PLATFORM_SERVICE_AGENT: Es la dirección de correo electrónico del agente de servicio de Agent Platform de tu proyecto, que tiene el siguiente formato:

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

      Para encontrar el agente de servicio de Agent Platform, ve a la página IAM en la consola de Cloud de Confiance .

      Ir a IAM

    • CUSTOM_SERVICE_ACCOUNT: es la dirección de correo electrónico de la cuenta de servicio administrada por el usuario nueva que creaste en el primer paso de esta sección.

Especifica una cuenta de servicio personalizada para los recursos de Agent Platform

El proceso de configurar Agent Platform para que use una cuenta de servicio específica para un recurso se denomina conectar la cuenta de servicio al recurso. En las siguientes secciones, se describe cómo adjuntar la cuenta de servicio que creaste en la sección anterior a varios recursos de Agent Platform.

Conecta una cuenta de servicio a un recurso de entrenamiento personalizado

Para configurar Agent Platform de modo que use tu cuenta de servicio nueva durante el entrenamiento personalizado, especifica la dirección de correo electrónico de la cuenta de servicio en el campo serviceAccount de un mensaje CustomJobSpec cuando inicies el entrenamiento personalizado. Según el tipo de recurso de entrenamiento personalizado que crees, la ubicación de este campo en tu solicitud a la API será diferente:

  • Si creas un CustomJob, especifica la dirección de correo electrónico de la cuenta de servicio en CustomJob.jobSpec.serviceAccount.

    Obtén más información sobre cómo crear un CustomJob.

  • Si creas un HyperparameterTuningJob, especifica la dirección de correo electrónico de la cuenta de servicio en HyperparameterTuningJob.trialJobSpec.serviceAccount.

    Obtén más información sobre cómo crear un HyperparameterTuningJob.

  • Si creas una TrainingPipeline personalizada sin ajuste de hiperparámetros, especifica la dirección de correo electrónico de la cuenta de servicio en TrainingPipeline.trainingTaskInputs.serviceAccount.

  • Si creas una TrainingPipeline personalizada con ajuste de hiperparámetros, especifica la dirección de correo electrónico de la cuenta de servicio en TrainingPipeline.trainingTaskInputs.trialJobSpec.serviceAccount.

Conecta una cuenta de servicio a un contenedor que entrega predicciones en línea

A fin de configurar un contenedor de predicción de Model con entrenamiento personalizado para usar tu cuenta de servicio nueva, especifica la dirección de correo electrónico de la cuenta de servicio cuando implementes Model en Endpoint:

Console

Sigue Implementa un modelo con la consola deCloud de Confiance . Cuando especificas la configuración del modelo, selecciona la cuenta de servicio en la lista desplegable Cuenta de servicio.

gcloud

Sigue las instrucciones para implementar un modelo con la API de Agent Platform. Cuando ejecutes el comando de gcloud ai endpoints deploy-model, usa la marca --service-account para especificar la dirección de correo electrónico de tu cuenta de servicio.

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • ENDPOINT_ID: Es el ID del extremo.
  • LOCATION_ID: Es la región en la que usas Agent Platform.
  • MODEL_ID: El ID del modelo que se implementará.
  • DEPLOYED_MODEL_NAME: Un nombre para DeployedModel También puedes usar el nombre comercial de Model para DeployedModel.
  • MACHINE_TYPE: Opcional Los recursos de máquina que se usan para cada nodo de esta implementación. Su configuración predeterminada es n1-standard-2. Obtén más información sobre los tipos de máquinas.
  • MIN_REPLICA_COUNT: La cantidad mínima de nodos para esta implementación. El recuento de nodos se puede aumentar o disminuir según lo requiera la carga de inferencia, hasta la cantidad máxima de nodos y nunca menos que esta cantidad.
  • MAX_REPLICA_COUNT: La cantidad máxima de nodos para esta implementación. El recuento de nodos se puede aumentar o disminuir según lo requiera la carga de inferencia, hasta esta cantidad de nodos y nunca menos que la cantidad mínima de nodos.
  • CUSTOM_SERVICE_ACCOUNT: La dirección de correo electrónico de la cuenta de servicio. Por ejemplo: SA_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com

Ejecuta el comando gcloud ai endpoints deploy-model:

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

Sigue las instrucciones para implementar un modelo con la API de Agent Platform. Cuando envíes la solicitud projects.locations.endpoints.deployModel, establece el campo deployedModel.serviceAccount como la dirección de correo electrónico de la cuenta de servicio.

Adjunta una cuenta de servicio a una solicitud CopyModel

Para configurar Agent Platform de modo que use tu cuenta de servicio nueva cuando se copia un modelo, especifica la dirección de correo electrónico de la cuenta de servicio en el campo customServiceAccount del mensaje CopyModelRequest. Esta cuenta de servicio debe pertenecer al proyecto de destino en el que se copia el modelo, y debes tener el permiso iam.serviceAccounts.actAs en esta cuenta de servicio.

REST

Sigue las instrucciones para copiar un modelo con la API de Agent Platform y agrega el campo customServiceAccount en el cuerpo JSON de la solicitud.

API

Cuando envíes la solicitud projects.locations.models.copy, establece el campo customServiceAccount en la dirección de correo electrónico de la cuenta de servicio.

Accede a los servicios de Cloud de Confiance en tu código

Si configuras Agent Platform para que use una cuenta de servicio personalizada siguiendo las instrucciones de las secciones anteriores, tu contenedor de entrenamiento o tu contenedor de predicción podrán acceder a cualquier servicio y recurso de Cloud de Confiance al que tenga acceso la cuenta de servicio.

Para acceder a los servicios de Cloud de Confiance , escribe tu código de entrenamiento o tu código de entrega de predicciones para usar las credenciales predeterminadas de la aplicación (ADC) y especifica de forma explícita el ID del proyecto o el número del proyecto del recurso al que deseas acceder. Obtén más información para escribir tu código y acceder a otros servicios de Cloud de Confiance.

Limitaciones

Las cuentas de servicio personalizadas en Gemini Enterprise Agent Platform tienen las siguientes limitaciones:

  • Para la inferencia por lotes, se seguirá usando el agente de servicio de Gemini Enterprise Agent Platform para acceder a BigQuery y Cloud Storage, incluso cuando se configure una cuenta de servicio personalizada.
  • Hay un máximo de 20 cuentas de servicio personalizadas por proyecto, por región y por servicio (por ejemplo, Vertex AI Inference).

¿Qué sigue?

  • Obtén más información sobre el control de acceso para Agent Platform.
  • Obtén más información sobre los permisos de IAM específicos y las operaciones que admiten.