Usar uma conta de serviço personalizada

Neste guia, descrevemos como configurar a Gemini Enterprise Agent Platform para usar uma conta de serviço personalizada nos seguintes cenários:

Quando usar uma conta de serviço personalizada

Quando a Plataforma de Agentes é executada, ela geralmente age com as permissões de uma das várias contas de serviço que o Google cria e gerencia para seu projeto do Cloud de Confiance by S3NS . Para conceder à Agent Platform mais acesso a outros serviços do Cloud de Confiance em determinados contextos, adicione papéis específicos aos agentes de serviço da Agent Platform.

No entanto, personalizar as permissões de agentes de serviços pode não fornecer o controle de acesso refinado que você quer. Veja alguns casos de uso comuns:

  • Conceder menos permissões para jobs e modelos da plataforma de agentes. O agente de serviço padrão da Agent Platform tem acesso ao BigQuery e ao Cloud Storage.
  • Permitir que jobs diferentes acessem recursos diferentes. Talvez você queira permitir que muitos usuários iniciem jobs em um único projeto, mas conceda o acesso dos jobs de cada um deles apenas a uma determinada tabela do BigQuery ou bucket do Cloud Storage.

Por exemplo, talvez você queira personalizar individualmente cada job de treinamento personalizado executado para ter acesso a diferentes recursos doCloud de Confiance fora do projeto.

Além disso, personalizar as permissões de agentes de serviço não altera as permissões disponíveis para um contêiner que exibe previsões de um Model treinado personalizado.

Para personalizar o acesso sempre que você realizar o treinamento personalizado ou para personalizar as permissões do contêiner de previsão de um Model treinado, use uma conta de serviço personalizada.

Acesso padrão

Nesta seção, descrevemos o acesso padrão disponível para contêineres de treinamento personalizado e os contêineres de previsão de recursos Model treinados. Ao usar uma conta de serviço personalizada, você substitui esse acesso a um recurso CustomJob, HyperparameterTuningJob, TrainingPipeline ou DeployedModel específico.

Como treinar contêineres

Quando você cria um CustomJob, HyperparameterTuningJob ou um TrainingPipeline personalizado, o contêiner de treinamento é executado usando o agente de serviço de código personalizado da Gemini Enterprise Agent Platform do seu projeto doCloud de Confiance por padrão.

Saiba mais sobre o agente de serviço de código personalizado da Gemini Enterprise Agent Platform, incluindo como conceder acesso a outros recursos do Cloud de Confiance .

Contêineres de previsão

Quando você implanta um Model treinado de forma personalizada em um Endpoint, o contêiner de previsão é executado usando uma conta de serviço gerenciada pela Agent Platform. Essa conta de serviço é diferente dos agentes de serviço da plataforma de agentes.

A conta de serviço que o contêiner de previsão usa por padrão tem permissão para ler artefatos de modelo que a Agent Platform disponibiliza em um URI armazenado na variável de ambiente AIP_STORAGE_URI. Não dependa da conta de serviço para ter outras permissões. Não é possível personalizar as permissões da conta de serviço.

Configurar uma conta de serviço personalizada

As seções a seguir descrevem como configurar uma conta de serviço personalizada para usar com a plataforma de agentes e como configurar um CustomJob, HyperparameterTuningJob, TrainingPipeline ou DeployedModel para usar a conta de serviço. Observe que não é possível configurar uma conta de serviço personalizada para extrair imagens do Artifact Registry. A Gemini Enterprise Agent Platform usa a conta de serviço padrão para extrair imagens.

Configurar uma conta de serviço personalizada

Para configurar uma conta de serviço personalizada, faça o seguinte:

  1. Crie uma conta de serviço gerenciada pelo usuário. A conta de serviço gerenciado pelo usuário pode estar no mesmo projeto que seus recursos da Agent Platform ou em um projeto diferente.

  2. Conceda à nova conta de serviço papéis do IAM que fornecem acesso aos serviços e recursos do Cloud de Confiance que você quer que a plataforma de agente use durante o treinamento ou a previsão personalizados.

  3. Opcional: se a conta de serviço gerenciado pelo usuário estiver em um projeto diferente dos jobs de treinamento, conceda o papel de criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) ao agente de serviço da Agent Platform do projeto em que você está usando a 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: se você também pretende usar a conta serviço gerenciado pelo usuário para previsões, é necessário conceder o papel de administrador da conta de serviço (roles/iam.serviceAccountAdmin) ao agente de serviço da Agent Platform do projeto em que você está usando a Agent Platform:

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

    Substitua:

    • AI_PLATFORM_SERVICE_AGENT: o endereço de e-mail do agente de serviço da plataforma de agentes do seu projeto, que tem o seguinte formato:

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

      Para encontrar o agente de serviço da plataforma de agentes, acesse a página IAM no console do Cloud de Confiance .

      Acessar IAM

    • CUSTOM_SERVICE_ACCOUNT: o endereço de e-mail da nova conta de serviço gerenciada pelo usuário que você criou na primeira etapa desta seção.

Especificar uma conta de serviço personalizada para recursos da Agent Platform

O processo de configuração da plataforma de agente para usar uma conta de serviço específica para um recurso é chamado de anexar a conta de serviço ao recurso. As seções a seguir descrevem como anexar a conta de serviço que você criou na seção anterior a vários recursos da Agent Platform.

Anexar uma conta de serviço a um recurso de treinamento personalizado

Para configurar a plataforma de agente para usar sua nova conta de serviço durante o treinamento personalizado, especifique o endereço de e-mail da conta de serviço no campo serviceAccount de uma mensagem CustomJobSpec ao iniciar o treinamento personalizado. Dependendo do tipo de recurso de treinamento personalizado que você está criando, a colocação desse campo na solicitação de API é diferente:

  • Se você estiver criando um CustomJob, especifique o endereço de e-mail da conta de serviço em CustomJob.jobSpec.serviceAccount.

    Saiba mais sobre como criar um CustomJob.

  • Se você estiver criando um HyperparameterTuningJob, especifique o endereço de e-mail da conta de serviço em HyperparameterTuningJob.trialJobSpec.serviceAccount.

    Saiba mais sobre como criar um HyperparameterTuningJob.

  • Se você estiver criando um TrainingPipeline personalizado sem ajuste de hiperparâmetro, especifique o endereço de e-mail da conta de serviço em TrainingPipeline.trainingTaskInputs.serviceAccount.

  • Se você estiver criando uma TrainingPipeline personalizada com ajuste de hiperparâmetros, especifique o endereço de e-mail da conta de serviço em TrainingPipeline.trainingTaskInputs.trialJobSpec.serviceAccount.

Anexar uma conta de serviço a um contêiner que exiba predições on-line;

Para configurar um contêiner de previsão Model treinado e treinado para usar sua nova conta de serviço, especifique o endereço de e-mail da conta de serviço ao implantar o Model em um Endpoint:

Console

Siga as instruções em Como implantar um modelo usando o console doCloud de Confiance . Ao especificar as configurações do modelo, selecione a conta de serviço na lista suspensa Conta de serviço.

gcloud

Siga as instruções em Como implantar um modelo usando a API Agent Platform. Ao executar o comando gcloud ai endpoints deploy-model, use a sinalização --service-account para especificar o endereço de e-mail da conta de serviço.

Antes de usar os dados do comando abaixo, faça estas substituições:

  • ENDPOINT_ID: o ID do endpoint.
  • LOCATION_ID: a região em que você está usando a Plataforma de Agentes.
  • MODEL_ID: o ID do modelo a ser implantado.
  • DEPLOYED_MODEL_NAME: um nome para DeployedModel. Também é possível usar o nome de exibição do Model para o DeployedModel.
  • MACHINE_TYPE: opcional. Os recursos de máquina usados para cada nó desta implantação. A configuração padrão é n1-standard-2. Saiba mais sobre tipos de máquinas.
  • MIN_REPLICA_COUNT: o número mínimo de nós para esta implantação. A contagem de nós pode ser aumentada ou reduzida conforme necessário pela carga de inferência, até o número máximo de nós e nunca menos que esse número.
  • MAX_REPLICA_COUNT: o número máximo de nós para esta implantação. A contagem de nós pode ser aumentada ou reduzida conforme necessário pela carga de inferência, até esse número de nós e nunca menos que o número mínimo de nós.
  • CUSTOM_SERVICE_ACCOUNT: o endereço de e-mail da conta de serviço. Por exemplo, SA_NAME@PROJECT_ID.s3ns.iam.gserviceaccount.com.

Execute o comando 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

Siga as instruções em Como implantar um modelo usando a API Agent Platform. Ao enviar a solicitação projects.locations.endpoints.deployModel, defina o campo deployedModel.serviceAccount como o endereço de e-mail.

Anexar uma conta de serviço a uma solicitação CopyModel

Para configurar a Agent Platform para usar sua nova conta de serviço ao copiar um modelo, especifique o endereço de e-mail da conta de serviço no campo customServiceAccount da mensagem CopyModelRequest. Essa conta de serviço precisa pertencer ao projeto de destino em que o modelo é copiado, e você precisa ter a permissão iam.serviceAccounts.actAs nela.

REST

Siga as instruções em Como copiar um modelo usando a API Agent Platform e adicione o campo customServiceAccount no corpo JSON da solicitação.

API

Ao enviar a solicitação projects.locations.models.copy, defina o campo customServiceAccount como o endereço de e-mail da conta de serviço.

Acessar os serviços do Cloud de Confiance no seu código

Se você configurar a Agent Platform para usar uma conta de serviço personalizada seguindo as instruções nas seções anteriores, o contêiner de treinamento ou de previsão poderá acessar todos os serviços e recursos do Cloud de Confiance que a conta de serviço pode acessar.

Para acessar os serviços do Cloud de Confiance , escreva o código de treinamento ou o código de exibição de previsões para usar o Application Default Credentials (ADC) e especifique explicitamente o ID do projeto ou o número do projeto do recurso que você quer acessar. Saiba mais sobre como escrever seu código para acessar outros serviços do Cloud de Confiance.

Limitações

As contas de serviço personalizadas na Gemini Enterprise Agent Platform têm as seguintes limitações:

  • Para inferência em lote, o agente de serviço da Gemini Enterprise Agent Platform ainda será usado para acessar o BigQuery e o Cloud Storage, mesmo quando uma conta de serviço personalizada estiver configurada.
  • Há um máximo de 20 contas de serviço personalizadas por projeto, por região e por serviço (por exemplo, Vertex AI Inference).

A seguir