このガイドでは、Google Kubernetes Engine（GKE）を使用して、コンテナ化されたエージェント AI / ML アプリケーションをデプロイおよび管理する方法について説明します。Google Agent Development Kit（ADK）と大規模言語モデル（LLM）プロバイダとしての Vertex AI を組み合わせることで、AI エージェントを効率的かつ大規模に運用できます。このガイドでは、Gemini 2.0 Flash を搭載した FastAPI ベースのエージェントを開発から GKE への本番環境デプロイまで行うエンドツーエンドのプロセスについて説明します。
このガイドは、エージェント AI / ML アプリケーションのサービングに Kubernetes コンテナ オーケストレーション機能を使用することに関心がある ML エンジニア、デベロッパー、クラウド アーキテクトを対象としています。 Google Cloud のコンテンツで使用されている一般的なロールとタスクの例の詳細については、一般的な GKE ユーザーのロールとタスクをご覧ください。
始める前に、次の内容を理解しておいてください。
背景
このガイドでは、複数の Google テクノロジーを組み合わせて、エージェント AI 用のスケーラブルなプラットフォームを作成します。GKE は、ADK を使用して構築されたエージェントのコンテナ オーケストレーションを提供します。LLM 推論に Vertex AI API を使用すると、推論は Google のマネージド インフラストラクチャによって処理されるため、GKE クラスタに専用の GPU ハードウェアは必要ありません。
Google の Agent Development Kit（ADK）
Agent Development Kit（ADK）は、AI エージェントの開発とデプロイ用に設計された、柔軟性の高いモジュール型のフレームワークです。ADK は Gemini と Google エコシステム向けに最適化されていますが、モデルに依存せず、デプロイに依存せず、他のフレームワークとの互換性を考慮して構築されています。
詳細については、ADK のドキュメントをご覧ください。
GKE マネージド Kubernetes サービス
GKE は、コンテナ化されたアプリケーションのデプロイ、スケーリング、管理を行うためのマネージド Kubernetes Service です。GKE は、LLM のコンピューティング需要を処理するために必要なインフラストラクチャ（スケーラブルなリソース、分散コンピューティング、効率的なネットワーキングなど）を提供します。
Kubernetes の主なコンセプトの詳細については、Kubernetes の学習を開始するをご覧ください。GKE の詳細と、GKE が Kubernetes のスケーリング、自動化、管理にどのように役立つかについては、GKE の概要をご覧ください。
Vertex AI
Vertex AI は Google Cloudの統合 ML プラットフォームで、デベロッパーは AI / ML モデルを構築、デプロイ、スケーリングできます。GKE 上のエージェント AI アプリケーションの場合、Vertex AI は、Gemini 2.0 Flash などの LLM へのアクセス、トレーニングと推論用のマネージド インフラストラクチャ、効率的なライフサイクル管理のための MLOps 機能など、不可欠なツールとサービスを提供します。
Vertex AI API を介して LLM を使用する場合、モデル推論は Google のマネージド インフラストラクチャで行われるため、GKE クラスタで特定の GPU または TPU の割り当てが必要になることはありません。
エージェント AI アプリケーション用の Vertex AI の詳細については、Vertex AI のドキュメントをご覧ください。
Gemini 2.0 Flash
Gemini 2.0 Flash は、高速、組み込みツールの使用、マルチモーダル生成、100 万トークンのコンテキスト ウィンドウなど、エージェント ワークロード向けに設計された次世代の機能と強化された機能を提供します。Gemini 2.0 Flash は、以前の Flash モデルを改良したもので、同程度の速度で品質が向上しています。
Gemini 2.0 Flash の技術的な情報（パフォーマンス ベンチマーク、トレーニング データセットに関する情報、持続可能性への取り組み、想定される使用方法と制限事項、倫理と安全性へのアプローチなど）については、Gemini 2.0 Flash のモデルカードをご覧ください。
目標
このガイドでは、次の方法について説明します。
- Google Cloud 環境をセットアップする。
- エージェントのコンテナ イメージをビルドする。
- エージェントを GKE クラスタにデプロイする。
- デプロイしたエージェントをテストする。
費用
このガイドでは、課金対象である次の Google Cloudのコンポーネントを使用します。
各サービスの料金を確認して、どの程度の費用が発生するか把握してください。
始める前に
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the required APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles. -
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the required APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles. -
Make sure that you have the following role or roles on the project: roles/container.admin, roles/iam.serviceAccountAdmin, roles/artifactregistry.admin, roles/cloudbuild.builds.editor, roles/resourcemanager.projectIamAdmin
Check for the roles
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
-
In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.
- For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.
Grant the roles
-
In the Google Cloud console, go to the IAM page.
IAM に移動 - プロジェクトを選択します。
- [ アクセスを許可] をクリックします。
-
[新しいプリンシパル] フィールドに、ユーザー ID を入力します。 これは通常、Google アカウントのメールアドレスです。
- [ロールを選択] リストでロールを選択します。
- 追加のロールを付与するには、 [別のロールを追加] をクリックして各ロールを追加します。
- [保存] をクリックします。
- Google Cloud コンソールで Cloud Shell セッションを起動し、
（Cloud Shell をアクティブにする）をクリックします。このアクションにより、 Google Cloud コンソールの下部ペインでセッションが起動します。 デフォルトの環境変数を設定します。
gcloud config set project PROJECT_ID export GOOGLE_CLOUD_LOCATION=REGION export PROJECT_ID=PROJECT_ID export GOOGLE_CLOUD_PROJECT=$PROJECT_ID export WORKLOAD_POOL=$PROJECT_ID.svc.id.goog export PROJECT_NUMBER=$(gcloud projects describe --format json $PROJECT_ID | jq -r ".projectNumber")次の値を置き換えます。
- PROJECT_ID: 実際の Google Cloud プロジェクト ID。
- REGION: GKE クラスタ、Artifact Registry、その他のリージョン リソースをプロビジョニングする Google Cloud リージョン（例:
us-central1）。
Cloud Shell ターミナルから、チュートリアルのサンプルコード リポジトリのクローンを作成します。
git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.gitチュートリアル ディレクトリに移動します。
cd kubernetes-engine-samples/ai-ml/adk-vertexGKE クラスタを作成する: コンテナ化されたエージェント アプリケーションは、GKE Autopilot クラスタまたは GKE Standard クラスタにデプロイできます。フルマネージドの Kubernetes エクスペリエンスを実現するには、Autopilot クラスタを使用します。ワークロードに最適な GKE の運用モードを選択するには、GKE の運用モードを選択するをご覧ください。
Autopilot
Cloud Shell で、次のコマンドを実行します。
gcloud container clusters create-auto CLUSTER_NAME \ --location=$GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_IDCLUSTER_NAME を GKE Autopilot クラスタの名前に置き換えます。
Standard
Cloud Shell で、次のコマンドを実行します。
gcloud container clusters create CLUSTER_NAME \ --location=$GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_ID \ --release-channel=stable \ --num-nodes=1 \ --machine-type=e2-medium \ --workload-pool=$PROJECT_ID.svc.id.googCLUSTER_NAME は、Standard クラスタの名前に置き換えます。
Docker コンテナ用の Artifact Registry リポジトリを作成する: エージェントの Docker コンテナ イメージを安全に保存して管理するための Artifact Registry リポジトリを作成します。このプライベート レジストリは、アプリケーションを GKE にデプロイする準備を整え、Cloud Build と統合するのに役立ちます。
gcloud artifacts repositories create adk-repo \ --repository-format=docker \ --location=$GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_IDリポジトリの URL を取得する: リポジトリの完全なパスを確認するには、次のコマンドを実行します。このパス形式は、次のステップで Docker イメージにタグを付けるために使用します。
gcloud artifacts repositories describe adk-repo \ --location $GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_IDCompute Engine のデフォルト サービス アカウントに必要な IAM ロールを付与する: デフォルトでは、Compute Engine のデフォルト サービス アカウントには、Artifact Registry にイメージを push する権限や、Cloud Storage のオブジェクトやログを表示する権限がありません。これらのオペレーションに必要なロールを付与します。
ROLES_TO_ASSIGN=( "roles/artifactregistry.writer" "roles/storage.objectViewer" "roles/logging.viewer" ) for ROLE in "${ROLES_TO_ASSIGN[@]}"; do gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \ --role="${ROLE}" doneエージェント コンテナ イメージをビルドして push する: このコマンドを実行して、Docker イメージをビルドし、Artifact Registry に push します。Dockerfile とアプリケーション コードが
/appディレクトリ内にあることを確認します。export IMAGE_URL="${GOOGLE_CLOUD_LOCATION}-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest" gcloud builds submit \ --tag "$IMAGE_URL" \ --project="$PROJECT_ID" \ appイメージが push されたことを確認します。
gcloud artifacts docker images list \ $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$PROJECT_ID/adk-repo/adk-agent \ --project=$PROJECT_IDTerraform を初期化する:
terraformディレクトリに移動し、Terraform を初期化します。terraform init実行プランを確認する: 次のコマンドを実行すると、Terraform によってインフラストラクチャに加えられる変更が表示されます。
terraform plan -var-file=default_env.tfvars構成を適用する: Terraform プランを実行して、 Google Cloud プロジェクトにリソースを作成します。プロンプトが表示されたら、
yesで確定します。terraform apply -var-file=default_env.tfvarsこれらのコマンドを実行すると、GKE クラスタと Artifact Registry リポジトリがプロビジョニングされ、Workload Identity Federation for GKE を含む必要な IAM ロールとサービス アカウントが構成されます。
Vertex AI アクセス用のサービス アカウントを作成します。
gcloud iam service-accounts create vertex-sa \ --project=$PROJECT_IDサービス アカウントに
aiplatform.userロールを付与します。これにより、サービス アカウントは Vertex AI とやり取りできます。gcloud projects add-iam-policy-binding $PROJECT_ID \ --member "serviceAccount:vertex-sa@$PROJECT_ID.iam.gserviceaccount.com" \ --role "roles/aiplatform.user"クラスタに KSA を作成します。このコマンドを実行する前に、クラスタと通信するように
kubectlを構成するの手順に沿って操作してください。kubectl create serviceaccount vertex-saKSA にアノテーションを付けて、サービス アカウントにリンクします。
kubectl annotate serviceaccount vertex-sa \ iam.gke.io/gcp-service-account=vertex-sa@$PROJECT_ID.iam.gserviceaccount.comサービス アカウントに、KSA の Workload Identity Federation for GKE ユーザーとして機能する権限を付与します。
gcloud iam service-accounts add-iam-policy-binding vertex-sa@$PROJECT_ID.iam.gserviceaccount.com \ --role roles/iam.workloadIdentityUser \ --member "serviceAccount:$PROJECT_ID.svc.id.goog[default/vertex-sa]"- エージェント アプリケーションの構造を理解する:
/appディレクトリには、エージェント アプリケーションのコアファイルが含まれています。main.py: エージェントの API を公開する FastAPI アプリケーションのエントリ ポイント。agent.py: ADK エージェントのロジックが含まれており、Vertex AI の使用方法とリクエストの処理方法が定義されています。__init__.py: Python パッケージを初期化します。requirements.txt: エージェントのすべての Python 依存関係を一覧表示します。Dockerfile: アプリケーションを Docker イメージにパッケージ化する方法を定義します。
エージェントのデプロイ マニフェストを作成する:
tutorials-and-examples/adk/vertexディレクトリに、次のマニフェストをagent-deployment.yamlという名前のファイルとして作成します。apiVersion: apps/v1 kind: Deployment metadata: name: adk-agent-deployment labels: app: adk-agent spec: replicas: 1 selector: matchLabels: app: adk-agent template: metadata: labels: app: adk-agent spec: serviceAccountName: vertex-sa containers: - name: adk-agent image: IMAGE_URL ports: - containerPort: 8000 env: - name: GOOGLE_CLOUD_PROJECT_ID value: PROJECT_ID - name: GOOGLE_CLOUD_LOCATION value: REGION - name: GOOGLE_GENAI_USE_VERTEXAI value: "1" - name: PORT value: "8000" resources: requests: memory: "512Mi" cpu: "500m" limits: memory: "1Gi" cpu: "1"次の値を置き換えます。
- IMAGE_URL: Artifact Registry に push した Docker イメージの完全な URL（例:
us-central1-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest）。この値は、前のセクションのgcloud artifacts docker images listコマンドの出力から取得できます。または、sed -i "s|image: IMAGE_URL|image: $IMAGE_URL|" agent-deployment.yamlなどのコマンドを実行します。 - PROJECT_ID: 実際の Google Cloud プロジェクト ID。
- REGION: GKE クラスタがプロビジョニングされる Google Cloud リージョン。
- IMAGE_URL: Artifact Registry に push した Docker イメージの完全な URL（例:
Deployment マニフェストを適用する:
kubectl apply -f agent-deployment.yamlこのコマンドは、GKE クラスタにエージェント アプリケーションの Deployment と関連する Pod を作成します。
エージェントを公開する: これらのメソッドを使用して、アクセス用にエージェントを公開できます。
- クラスタの外部からエージェントにアクセスするには、Kubernetes Service を作成します。ウェブ API の場合、
LoadBalancerタイプのサービスが一般的です。 ローカルでの開発とテストでは、
kubectl port-forwardコマンドを使用してエージェントに直接アクセスします。
LoadBalancer
次のマニフェストを
agent-service.yamlという名前のファイルとして作成します。apiVersion: v1 kind: Service metadata: name: adk-agent-service spec: selector: app: adk-agent type: LoadBalancer # Creates an external IP address for access ports: - protocol: TCP port: 80 targetPort: 8000 # Matches the containerPort exposed in the Deployment次のようにマニフェストを適用します。
kubectl apply -f agent-service.yaml外部 IP アドレスのプロビジョニングには数分かかることがあります。
IP アドレスがプロビジョニングされていることを確認します。
kubectl get service adk-agent-service出力で
EXTERNAL-IPの値を探します。値が使用可能になったら、この IP アドレスを使用してデプロイされたエージェントを操作します。
port-forward
主に
port-forwardを使用する場合は、LoadBalancerではなくClusterIPService タイプを使用することを検討してください。ClusterIPService は内部で、使用するリソースが少なくなります。POD_NAME=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}') kubectl port-forward $POD_NAME 8000:8000このコマンドはターミナルをブロックしますが、マシン上の
localhost:8000から GKE クラスタ内で実行されているエージェントにトラフィックを転送します。- クラスタの外部からエージェントにアクセスするには、Kubernetes Service を作成します。ウェブ API の場合、
エージェントのエンドポイントを特定する: 前のセクションでエージェントを公開する方法に応じて、アクセス可能なエンドポイントを特定します。
LoadBalancer
外部 IP アドレスを取得します。
kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}'使いやすいように、外部 IP アドレスを環境変数に保存します。
export AGENT_IP=$(kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}')エージェントのベース URL は
http://${AGENT_IP}です。
port-forward
kubectl port-forwardコマンドが別のターミナルで実行されていることを確認します。エージェントのベース URL はhttp://localhost:8000です。エージェントの API をテストする: エージェントの
/runエンドポイントに curl リクエストを送信して、エージェントの API をテストします。エージェントは、メッセージ フィールドを含む JSON ペイロードを想定しています。AGENT_BASE_URL は、http://${AGENT_IP}（LoadBalancer の場合）またはhttp://localhost:8000（ポート転送の場合）に置き換えます。新しいセッションを作成するこれにより、エージェントは新しい会話の準備をします。
# The user ID and session ID are arbitrary. # The appName must match the agent's Python package directory name (in this case, "capital-agent"). curl -X POST AGENT_BASE_URL/apps/capital-agent/users/user-123/sessions/session-123次のコマンドを使用すると、利用可能なアプリを一覧表示できます。
curl -X GET AGENT_BASE_URL/list-apps前の手順のセッションの詳細を使用して、エージェントにクエリを送信します。
curl -X POST AGENT_BASE_URL/run \ -H "Content-Type: application/json" \ -d '{ "appName": "capital-agent", "userId": "user-123", "sessionId": "session-123", "newMessage": { "role": "user", "parts": [{ "text": "Hello, agent! What can you do for me?" }] } }'エージェントから JSON レスポンスが返されます。これは、リクエストが正常に処理され、Vertex AI を介して Gemini モデルとやり取りが行われたことを示します。レスポンスには、メッセージに基づいてエージェントが生成した返信が含まれます。
エージェントのウェブ UI にアクセスする（該当する場合）: エージェントにウェブベースのユーザー インターフェースが含まれている場合は、ウェブブラウザで AGENT_BASE_URL に移動してアクセスします。通常、ADK にはインタラクションとデバッグ用の基本的なウェブ UI が含まれています。たとえば、LoadBalancer を介してエージェントを公開し、その
EXTERNAL-IPが34.123.45.67の場合は、ブラウザでhttp://34.123.45.67に移動します。Cloud Shell ターミナルで、
tutorials-and-examples/adk/vertex/ディレクトリに移動します。cd tutorials-and-examples/adk/vertex/次のコマンドを実行して、Terraform 構成ファイルで定義されているすべてのリソースを削除します。
cd terraform terraform destroy- エージェントのリソースをオンデマンドで自動的に調整するために Horizontal Pod Autoscaler（HPA）を構成する方法を学ぶ。
- Google Cloudで実行されているウェブ アプリケーション用に Identity-Aware Proxy（IAP）を構成し、エージェントの UI へのアクセスに対する認可を一元化する方法を学ぶ。
- Cloud Logging と Cloud Monitoring を使用して GKE クラスタ内のエージェントのパフォーマンスと健全性に関する情報を取得する方法を学ぶ。
- GKE を使用してエージェント AI イニシアチブを加速させるため、GKE AI Labs で試験運用版のサンプルを探す。
環境を準備する
このチュートリアルでは、Cloud Shell を使用して Google Cloudでホストされているリソースを管理します。Cloud Shell には、このチュートリアルに必要なソフトウェア（
kubectl、terraform、Google Cloud CLIなど）がプリインストールされています。Cloud Shell を使用して環境を設定するには、次の操作を行います。
サンプル プロジェクトのクローンを作成する
Google Cloud リソースを作成して構成する
エージェントを GKE にデプロイするには、必要なGoogle Cloud リソースをプロビジョニングします。エージェントをデプロイするには、直接コマンドライン実行用の gcloud CLI または Infrastructure as Code 用の Terraform を使用します。
gcloud
このセクションでは、Vertex AI とのシームレスなインテグレーションのために GKE クラスタ、Artifact Registry、Workload Identity Federation for GKE を設定する gcloud CLI コマンドについて説明します。環境を準備するの説明に従って、環境変数が設定されていることを確認します。
Terraform
このセクションでは、Terraform を使用して Google Cloudリソースをプロビジョニングする方法について説明します。クローン作成したサンプル リポジトリには、必要な Terraform 構成ファイルが含まれています。
Terraform の使用方法の詳細については、GKE での Terraform のサポートをご覧ください。
クラスタと通信するように
kubectlを構成するクラスタと通信するように
kubectlを構成していない場合は、次のコマンドを実行します。gcloud container clusters get-credentials CLUSTER_NAME \ --location=${GOOGLE_CLOUD_LOCATION}CLUSTER_NAME を GKE クラスタの名前に置き換えます。
Workload Identity Federation for GKE アクセスを構成する
Terraform を使用している場合は、この手順をスキップできます。このプロセスでは、Kubernetes サービス アカウント（KSA）を IAM サービス アカウントにリンクして、エージェントに Google Cloud サービスへのアクセス権を安全に付与します。
エージェント アプリケーションをデプロイして構成する
Google Cloud リソースを設定したら、エージェント アプリケーションをデプロイ用に準備し、GKE でランタイムを構成します。これには、エージェントのコードの定義、コンテナ化するための Dockerfile の作成、クラスタにデプロイするための Kubernetes マニフェストの作成が含まれます。
デプロイしたエージェントをテストする
エージェント アプリケーションがデプロイされ、公開されたので、その機能をテストします。
このセクションでは、エージェントのエンドポイントを特定してエージェントの API をテストする方法について説明します。
クリーンアップ
このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。
デプロイされたリソースを削除する
このガイドで作成したリソースについて Google Cloud アカウントに課金されないようにするには、次のコマンドを実行します。
gcloud
gcloud container clusters delete CLUSTER_NAME \ --location=${GOOGLE_CLOUD_LOCATION} \ --project=$PROJECT_ID gcloud projects remove-iam-policy-binding $PROJECT_ID \ --member "serviceAccount:vertex-sa@$PROJECT_ID.iam.gserviceaccount.com" \ --role "roles/aiplatform.user" gcloud iam service-accounts delete vertex-sa@$PROJECT_ID.iam.gserviceaccount.com gcloud artifacts repositories delete adk-repo \ --location=$GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_IDCLUSTER_NAME を GKE クラスタの名前に置き換えます。
Terraform
次のステップ
-