使用自定义服务账号

本指南介绍了如何在以下情况下配置 Gemini Enterprise Agent Platform 以使用自定义服务账号：

何时使用自定义服务帐号

Agent Platform 运行时，通常会使用 Google 为您的项目创建和管理的多个 服务账号之一 的权限。 Google Cloud 如需在特定环境中授予 Agent Platform 对其他 Google Cloud服务的更多访问权限，您可以向 Agent Platform 服务代理添加特定角色。

但是，自定义 Service Agent 的权限可能无法提供您所需的精细访问权限控制。一些常见使用场景包括：

  • 允许对 Agent Platform 作业和模型具有较少的权限。 默认的 Agent Platform 服务代理有权访问 BigQuery 和 Cloud Storage。
  • 允许不同的作业访问不同的资源。 您可能希望允许许多用户在单个项目中启动作业，但仅允许每个用户的作业访问特定的 BigQuery 表或 Cloud Storage 存储桶。

例如，您可能希望单独自定义您运行的每个自定义训练作业，以便其能够访问您项目外部的其他Google Cloud 资源。

此外，自定义 Service Agent 的权限不会更改可对经过自定义训练的 Model 执行预测的容器的可用权限。

要在每次执行自定义训练时自定义访问权限，或自定义训练 Model 的预测容器的权限，您必须使用自定义服务账号。

默认访问权限

本部分介绍自定义训练容器可用的默认访问权限以及自定义训练的 Model 资源的预测容器。使用自定义服务账号时，您需要为特定 CustomJob、HyperparameterTuningJob、TrainingPipeline 或 DeployedModel 资源替换此访问权限。

训练容器

创建 CustomJob、HyperparameterTuningJob 或自定义 TrainingPipeline 时，训练 容器 默认情况下利用您的 Google Cloud 项目's Gemini Enterprise Agent Platform Custom Code Service Agent 运行。

详细了解 Gemini Enterprise Agent Platform Custom Code Service Agent，包括如何 向其授予其他 Google Cloud 资源的访问权限。

预测容器

将自定义训练的 Model 部署到 Endpoint 时，预测容器使用由 Agent Platform 管理的服务帐号运行。此 服务帐号与Agent Platform 服务 代理不同。

默认情况下，预测容器使用的服务帐号有权 读取模型工件 ，Agent Platform 在 AIP_STORAGE_URI环境变量中存储的 URI 中提供了这些工件。请勿依赖服务帐号获得任何其他权限。您无法自定义服务账号的权限。

配置自定义服务帐号

以下部分介绍如何设置用于 Agent Platform 的自定义服务帐号，以及如何配置要使用的 CustomJob、HyperparameterTuningJob、TrainingPipeline 或 DeployedModel 服务帐号。请注意，您无法配置自定义服务帐号以从 Artifact Registry 拉取映像。Gemini Enterprise Agent Platform 使用默认服务帐号拉取映像。

设置自定义服务帐号

如需设置自定义服务账号，请执行以下操作：

  1. 创建用户代管式服务账号。 用户代管式服务账号可以与 Agent Platform 资源位于同一项目中，也可以位于其他项目中。

  2. 为您的新服务帐号授予 IAM 角色，以便其能够访问您希望 Agent Platform 在自定义训练或预测期间使用的 Google Cloud 服务和资源。

  3. 可选：如果用户代管式服务账号**与训练作业位于不同的**项目**中，您必须向您在其中使用 Agent Platform 的**项目**的 Agent Platform **服务代理**授予Service Account Token Creator **角色**(roles/iam.serviceAccountTokenCreator)。

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

  4. 可选：如果您还计划将用户代管式服务账号用于 预测，则必须向您在其中使用 Agent Platform 的项目的 Agent Platform 服务代理授予 Service Account Admin 角色 （roles/iam.serviceAccountAdmin）：

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

    替换以下内容：

    • AI_PLATFORM_SERVICE_AGENT：项目的 Agent Platform Service Agent 的电子邮件地址，格式如下：

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

      如需查找 Agent Platform 服务代理，请前往IAM页面中的 Google Cloud 控制台。

      转到 IAM

    • CUSTOM_SERVICE_ACCOUNT：您在本节的上一步中创建的新用户代管式服务账号的电子邮件地址。

为 Agent Platform 资源指定自定义服务帐号

将 Agent Platform 配置为使用特定资源的服务账号的过程称为将服务帐号附加到资源。以下部分介绍如何将您在上部分中创建的服务账号 附加到多个 Agent Platform 资源。

将服务帐号关联到自定义训练资源

如需将 Agent Platform 配置为在自定义训练期间使用新的服务账号，请在开始自定义训练时，在 serviceAccount 字段中指定服务帐号的电子邮件地址。CustomJobSpec根据您正在创建的自定义训练 资源，此字段在 API 请求中的展示位置会有所不同：

  • 如果您要创建 CustomJob，请在 CustomJob.jobSpec.serviceAccount 中指定服务账号的电子邮件地址。

    详细了解如何创建 CustomJob。

  • 如果您要创建 HyperparameterTuningJob，请在 HyperparameterTuningJob.trialJobSpec.serviceAccount 中指定服务账号的电子邮件地址。

    详细了解如何创建 HyperparameterTuningJob。

  • 如果要创建不含超参数调节的自定义 TrainingPipeline，请在 TrainingPipeline.trainingTaskInputs.serviceAccount 中指定服务账号的电子邮件地址。

  • 如果要创建具有超参数调节的自定义 TrainingPipeline，请在 TrainingPipeline.trainingTaskInputs.trialJobSpec.serviceAccount 中指定服务账号的电子邮件地址。

将服务账号附加到执行在线预测的容器

如需将自定义训练的 Model 的预测容器配置为使用新的服务账号，请在将 Model 部署到Endpoint：

控制台

按照使用Google Cloud 控制台部署模型执行操作。指定模型设置时，请在服务账号 下拉列表中选择服务帐号。

gcloud

按照使用Agent Platform API 部署模型执行操作。运行 gcloud ai endpoints deploy-model 命令时，请使用 --service-account 标志来 指定服务帐号的电子邮件地址。

在使用下面的命令数据之前，请先进行以下替换：

  • ENDPOINT_ID：端点的 ID。
  • LOCATION_ID：您使用 Agent Platform 的区域。
  • MODEL_ID：要部署的模型的 ID。
  • DEPLOYED_MODEL_NAME：DeployedModel 的名称。您还可以将 Model 的显示名用于 DeployedModel。
  • MACHINE_TYPE：可选。用于此部署的每个节点的机器资源。其默认设置为 n1-standard-2。详细了解机器类型。
  • MIN_REPLICA_COUNT：此部署的最小节点数。 节点数可根据推理负载的需要而增加或减少，直至达到节点数上限并且绝不会少于此节点数。
  • MAX_REPLICA_COUNT：此部署的节点数上限。 节点数可根据推理负载的需要而增加或减少，直至达到此节点数并且绝不会少于节点数下限。
  • CUSTOM_SERVICE_ACCOUNT：服务账号的电子邮件地址。例如：SA_NAME@PROJECT_ID.iam.gserviceaccount.com

执行 gcloud ai endpoints deploy-model 命令：

Linux、macOS 或 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

按照使用Agent Platform API 部署模型执行操作。发送 projects.locations.endpoints.deployModel 请求时，请将 deployedModel.serviceAccount 字段 设置为服务帐号的电邮地址。

将服务帐号附加到 CopyModel 请求

如需将 Agent Platform 配置为在复制模型时使用您的 新服务账号，请在 customServiceAccount 字段的 CopyModelRequest 消息中指定服务帐号的电子邮件地址。此服务帐号必须属于模型复制到的目标项目，并且您需要对此服务帐号拥有 iam.serviceAccounts.actAs 权限。

REST

按照使用 Agent Platform API复制模型执行操作，并在请求 JSON 正文中添加 customServiceAccount 字段。

API

发送 projects.locations.models.copy 请求时，请将 customServiceAccount 字段设置为服务帐号的电邮地址。

在代码中访问 Google Cloud 服务

如果您按照前面部分中的说明将 Agent Platform 配置为使用自定义服务帐号，那么您的训练容器 或您的预测容器将可以访问该服务帐号有权访问的任何服务和 资源。 Google Cloud

如需访问 Google Cloud 服务，请编写您的训练 代码或您的预测服务 代码，以使用应用默认 凭证 (ADC)，并明确 指定要访问的资源的 项目 ID 或项目编号。详细了解如何编写代码来访问其他 Google Cloud服务。

限制

Gemini Enterprise Agent Platform 中的自定义服务账号具有以下限制：

  • 对于批量推理，即使配置了自定义服务账号，Gemini Enterprise Agent Platform 服务代理仍将用于访问 BigQuery 和 Cloud Storage。
  • 每个项目、每个区域、每个服务（例如 Vertex AI 推理）最多有 20 个自定义服务账号。

后续步骤