カスタム サービス アカウントを使用する

このガイドでは、以下のシナリオでカスタム サービス アカウントを使用するように Gemini Enterprise エージェント プラットフォームを構成する方法について説明します。

カスタム サービス アカウントを使用する場合

Agent Platform は通常、Google がご自身の Google Cloud プロジェクト用に自動的に作成し、管理している複数のサービス アカウントのいずれかの権限を使って処理を行います。特定のコンテキストで Agent Platform に別の Google Cloudサービスへのアクセスを許可する場合、Agent Platform のサービス エージェントに特別なロールを追加できます。

ただし、サービス エージェントの権限をカスタマイズすると、きめ細かいアクセス制御が実施されなくなる可能性があります。一般的な使用例は次のとおりです。

  • Agent Platform のジョブとモデルに対する権限を減らす。デフォルトの Agent Platform サービス エージェントは BigQuery と Cloud Storage にアクセスできます。
  • 異なるジョブに異なるリソースへのアクセスを許可する。1 つのプロジェクトで複数のユーザーがジョブを起動できるようにしながら、各ユーザーのジョブアクセスを特定の BigQuery テーブルまたは Cloud Storage バケットに制限できます。

たとえば、プロジェクト外の別のGoogle Cloud リソースにアクセスできるようにするには、実行するカスタム トレーニング ジョブを個別にカスタマイズできます。

さらに、サービス エージェントの権限をカスタマイズしても、カスタム トレーニング済みの Model から予測を提供するコンテナで使用可能な権限は変更されません。

カスタム トレーニングを行うたびにアクセスをカスタマイズする場合や、カスタム トレーニング済みの Model 予測コンテナの権限をカスタマイズする場合は、カスタム サービス アカウントを使用する必要があります。

デフォルトのアクセス権

このセクションでは、カスタム トレーニング コンテナで使用可能なデフォルトのアクセス権と、カスタム トレーニング済みの Model リソースの予測コンテナについて説明します。カスタム サービス アカウントを使用すると、特定の CustomJob、HyperparameterTuningJob、TrainingPipeline、DeployedModel リソースに対するアクセス権をオーバーライドします。

コンテナのトレーニング

CustomJob、HyperparameterTuningJob、またはカスタム TrainingPipeline を作成すると、Google Cloud プロジェクトの Gemini Enterprise Agent Platform カスタム コード サービス エージェントを使用してトレーニング コンテナがデフォルトで実行されます。

別の Google Cloud リソースへのアクセス権を付与する方法など、詳細については、Gemini Enterprise Agent Platform カスタムコード サービス エージェントをご覧ください。

予測コンテナ

カスタム トレーニング済みの Model を Endpoint にデプロイすると、Agent Platform で管理されているサービス アカウントを使用して予測コンテナが実行されます。このサービス アカウントは、Agent Platform サービス エージェントとは異なります。

予測コンテナがデフォルトで使用するサービス アカウントには、AIP_STORAGE_URI 環境変数に保存された URI で Agent Platform が使用できるモデル アーティファクトの読み取り権限が必要です。サービス アカウントに他の権限を付与しないでください。サービス アカウントの権限はカスタマイズできません。

カスタム サービス アカウントを構成する

以降のセクションでは、Agent Platform で使用するカスタム サービス アカウントの設定方法を説明します。また、サービス アカウントを使用するように CustomJob、HyperparameterTuningJob、TrainingPipeline、DeployedModel を構成する方法についても説明します。Artifact Registry からイメージを pull するようにカスタム サービス アカウントを構成することはできません。Gemini Enterprise Agent Platform は、デフォルトのサービス アカウントを使用してイメージを pull します。

カスタム サービス アカウントを設定する

カスタム サービス アカウントを設定する方法は、次のとおりです。

  1. ユーザーが管理するサービス アカウントを作成します。ユーザー管理のサービス アカウントは、Agent Platform リソースと同じプロジェクトまたは別のプロジェクトに作成できます。

  2. 新しいサービス アカウントに IAM ロールを付与します。これにより、カスタム トレーニングと予測中に Agent Platform が使用する Google Cloud サービスとリソースにアクセスできるようになります。

  3. 省略可: ユーザー管理のサービス アカウントがトレーニング ジョブとは異なるプロジェクトにある場合は、Agent Platform を使用しているプロジェクトの Agent Platform サービス エージェントにサービス アカウント トークン作成者のロール（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. 省略可: 予測のユーザー管理のサービス アカウントも使用する場合は、サービス アカウント管理者のロール（roles/iam.serviceAccountAdmin）を以下のとおり、Agent Platform を使用しているプロジェクトの Agent Platform サービス エージェントに付与する必要があります。

    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-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com

      Agent Platform サービス エージェントを確認するには、 Google Cloud コンソールの [IAM] ページに移動します。

      IAM に移動

    • CUSTOM_SERVICE_ACCOUNT: このセクションの最初の手順で作成した新しいユーザー管理のサービス アカウントのメールアドレス。

Agent Platform リソースのカスタム サービス アカウントを指定する

リソースに特定のサービス アカウントを使用するように Agent Platform を構成することをサービス アカウントをリソースに「関連付ける」といいます。以降のセクションでは、前のセクションで作成したサービス アカウントを複数の Agent Platform リソースに関連付ける方法について説明します。

カスタム トレーニング リソースとサービス アカウントを関連付ける

カスタム トレーニング中に新しいサービス アカウントを使用するように Agent Platform を構成するには、カスタム トレーニングの開始時に表示される CustomJobSpec メッセージの serviceAccount フィールドに、サービス アカウントのメールアドレスを指定します。作成するカスタム トレーニング リソースの種類に応じて、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 の名前。DeployedModel の Model の表示名を使用することもできます。
  • 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 を構成するには、CopyModelRequest メッセージの customServiceAccount フィールドにサービス アカウントのメールアドレスを指定します。このサービス アカウントは、モデルのコピー先のプロジェクトに属している必要があります。また、このサービス アカウントに対する 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 エージェント プラットフォームのカスタム サービス アカウントには、次の制限があります。

  • バッチ推論では、カスタム サービス アカウントが構成されている場合でも、BigQuery と Cloud Storage へのアクセスには引き続き Gemini Enterprise Agent Platform サービス エージェントが使用されます。
  • プロジェクトごと、リージョンごと、サービス（Vertex AI Inference など）ごとに、最大 20 個のカスタム サービス アカウントを設定できます。

次のステップ

  • 詳しくは、Agent Platform のアクセス制御をご覧ください。
  • 特定の IAM 権限とサポートされるオペレーションについて学習する。