Usar una cuenta de servicio personalizada

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

Cuándo usar una cuenta de servicio personalizada

Cuando se ejecuta Agent Platform, por lo general, actúa con los permisos de una de varias cuentas de servicio que Google crea y administra para tu proyecto de Google Cloud . Para otorgar a Agent Platform un mayor acceso a otros servicios de Google Clouden 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, te recomendamos personalizar de forma individual cada trabajo de entrenamiento personalizado que ejecutas para tener acceso a diferentes recursos deGoogle Cloud 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 de forma predeterminada con el agente de servicio de código personalizado de Gemini Enterprise Agent Platform de tu proyectoGoogle Cloud .

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

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 el contenedor de predicción usa de forma predeterminada tiene permiso para leer artefactos del modelo que Agent Platform pone a disposición en un URI almacenado en la variable de entorno de 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. Agent Platform de Gemini Enterprise 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 tu cuenta de servicio nuevas funciones de IAM que proporcionan acceso a los servicios y recursos de Google Cloud que deseas que Agent Platform pueda usar durante el entrenamiento personalizado o la 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: 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.iam.gserviceaccount.com

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

      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 configuración de Agent Platform para usar una cuenta de servicio específica para un recurso se llama conectar la cuenta de servicio al recurso. En las siguientes secciones, se describe cómo conectar 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 para usar 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 comiences 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 laGoogle Cloud consola. Cuando especifiques la configuración del modelo, selecciona la cuenta de servicio en la lista desplegable Cuenta de servicio.

gcloud

Sigue Implementa 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, realiza 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.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 Implementa 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.

Conecta una cuenta de servicio a una solicitud de CopyModel

Para configurar Agent Platform de modo que use tu cuenta de servicio nueva cuando copies 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 al que se copia el modelo, y debes tener el permiso iam.serviceAccounts.actAs en esta cuenta de servicio.

REST

Sigue los pasos en Cómo 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 Google Cloud servicios en tu código

Si seguiste las instrucciones de las secciones anteriores para configurar Agent Platform a fin de usar una cuenta de servicio personalizada, tu contenedor de entrenamiento o tu contenedor de predicción puede acceder a cualquier servicio y recurso de Google Cloud al que tenga acceso la cuenta de servicio.

Para acceder a los Google Cloud servicios, 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 para acceder a otros servicios de Google Cloud.

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 Agent Platform de Gemini Enterprise 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.