使用 Agent Development Kit (ADK) 和 Vertex AI，在 GKE 部署代理式 AI 應用程式

標準

---

本指南說明如何使用 Google Kubernetes Engine (GKE) 部署及管理容器化代理程式 AI/ML 應用程式。結合 Google 代理程式開發套件 (ADK) 和 Vertex AI (大型語言模型 (LLM) 提供者)，即可有效率地大規模運作 AI 代理程式。本指南會逐步說明如何使用 Gemini 2.0 Flash，將以 FastAPI 為基礎的代理程式從開發階段部署到 GKE 正式環境。

本指南適用於對使用 Kubernetes 容器自動化調度管理功能，提供代理型 AI/機器學習應用程式服務感興趣的機器學習工程師、開發人員和雲端架構師。如要進一步瞭解內容中的常見角色和範例工作，請參閱「常見的 GKE Enterprise 使用者角色和工作」。 Google Cloud

開始之前，請務必詳閱下列事項：

• GKE
• 使用 Docker 進行容器化
• Vertex AI

背景

本指南結合多項 Google 技術，建立可擴充的代理程式 AI 平台。GKE 會為使用 ADK 建構的代理程式提供容器自動化調度管理功能。使用 Vertex AI API 進行 LLM 推論時，GKE 叢集不需要專用 GPU 硬體，因為推論作業是由 Google 的代管基礎架構處理。

Google Agent Development Kit (ADK)

Agent Development Kit (ADK) 是一個彈性十足的模組化框架，可用於開發及部署 AI 代理。雖然 ADK 專為 Gemini 和 Google 生態系統最佳化，但與模型和部署方式無關，且可與其他架構相容。

詳情請參閱 ADK 說明文件。

GKE 代管 Kubernetes 服務

GKE 是代管 Kubernetes 服務，可部署、擴充及管理容器化應用程式。GKE 提供必要的基礎架構，包括可擴充的資源、分散式運算和高效能網路，可處理 LLM 的運算需求。

如要進一步瞭解 Kubernetes 的重要概念，請參閱「開始學習 Kubernetes」。如要進一步瞭解 GKE，以及如何透過 GKE 自動處理、管理 Kubernetes 及調度資源，請參閱 GKE 總覽。

Vertex AI

Vertex AI 是 Google Cloud的統合式機器學習平台，可讓開發人員建構、部署及擴充 AI/機器學習模型。對於 GKE 上的代理式 AI 應用程式，Vertex AI 提供必要的工具和服務，包括存取 Gemini 2.0 Flash 等 LLM、用於訓練和推論的代管基礎架構，以及用於有效管理生命週期的 MLOps 功能。

透過 Vertex AI API 使用 LLM 時，模型推論會在 Google 的代管基礎架構上進行，因此您在 GKE 叢集中不需要特定 GPU 或 TPU 配額。

如要進一步瞭解 Vertex AI 在代理程式 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的下列計費元件：

• GKE
• Artifact Registry
• Cloud Build
• Vertex AI

請查看各項服務的價格，瞭解可能需要支付的費用。

事前準備

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

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 the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

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 the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

• 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

  1. In the Google Cloud console, go to the IAM page.

     Go to IAM
  2. Select the project.

  3. 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.

  4. 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

  1. In the Google Cloud console, go to the IAM page.

     前往「IAM」頁面
  2. 選取專案。
  3. 按一下「授予存取權」。

  4. 在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。 這通常是 Google 帳戶的電子郵件地址。

  5. 在「Select a role」(選取角色) 清單中，選取角色。
  6. 如要授予其他角色，請按一下 「新增其他角色」，然後新增每個其他角色。
  7. 按一下 [Save]。

  準備環境

  本教學課程會使用 Cloud Shell 管理託管於 Google Cloud的資源。Cloud Shell 已預先安裝本教學課程所需的軟體，包括 kubectl、terraform 和 Google Cloud CLI。

  如要使用 Cloud Shell 設定環境，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中啟動 Cloud Shell 工作階段，然後按一下「啟用 Cloud Shell」。這項操作會在 Google Cloud 控制台的底部窗格啟動工作階段。

  2. 設定預設環境變數：

     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)。

  複製範例專案

  1. 在 Cloud Shell 終端機中，複製本教學課程的範例程式碼存放區：

     git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.git
     

  2. 前往教學課程目錄：

     cd kubernetes-engine-samples/ai-ml/adk-vertex
     

  建立及設定 Google Cloud 資源

  如要將代理程式部署至 GKE，請佈建必要的Google Cloud 資源。您可以透過 gcloud CLI 直接執行指令列，或使用 Terraform 進行基礎架構即程式碼作業，部署代理程式。

  gcloud

  本節提供 gcloud CLI 指令，可設定 GKE 叢集、Artifact Registry 和 Workload Identity Federation for GKE，與 Vertex AI 順暢整合。請確認您已按照「準備環境」一文所述設定環境變數。

  1. 建立 GKE 叢集：您可以在 GKE Autopilot 或 Standard 叢集中部署容器化代理程式應用程式。使用 Autopilot 叢集，享有全代管 Kubernetes 服務。如要選擇最適合工作負載的 GKE 作業模式，請參閱「選擇 GKE 作業模式」。

     Autopilot

     在 Cloud Shell 中執行下列指令：

     gcloud container clusters create-auto CLUSTER_NAME \
             --location=$GOOGLE_CLOUD_LOCATION \
             --project=$PROJECT_ID
     

     將 CLUSTER_NAME 替換為 GKE Autopilot 叢集的名稱。

     標準

     在 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.goog
     

     將 CLUSTER_NAME 替換為您的 Standard 叢集名稱。

  2. 為 Docker 容器建立 Artifact Registry 存放區：建立 Artifact Registry 存放區，安全地儲存及管理代理程式的 Docker 容器映像檔。這個私人登錄檔可確保應用程式隨時可部署至 GKE，並與 Cloud Build 整合。

     gcloud artifacts repositories create adk-repo \
         --repository-format=docker \
         --location=$GOOGLE_CLOUD_LOCATION \
         --project=$PROJECT_ID
     

  3. 取得存放區網址：執行這項指令，確認存放區的完整路徑。您會在下一個步驟中使用這個路徑格式，為 Docker 映像檔加上標記。

     gcloud artifacts repositories describe adk-repo \
         --location $GOOGLE_CLOUD_LOCATION \
         --project=$PROJECT_ID
     

  4. 授予 Compute Engine 預設服務帳戶必要的 IAM 角色： 根據預設，Compute Engine 預設服務帳戶沒有權限將映像檔推送至 Artifact Registry，也無法查看 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}[e-mail]" \
             --role="${ROLE}"
     done
     

  5. 建構及推送代理程式容器映像檔：執行這項指令，建構 Docker 映像檔並推送至 Artifact Registry。確認 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
     

  6. 確認映像檔已推送：

     gcloud artifacts docker images list \
         $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$PROJECT_ID/adk-repo/adk-agent \
         --project=$PROJECT_ID
     

  Terraform

  本節說明如何使用 Terraform 佈建 Google Cloud資源。您複製的範例存放區包含必要的 Terraform 設定檔。

  注意： 如果您使用 Terraform，請務必在 default_env.tfvars 檔案中指定 REGION 值。

  1. 初始化 Terraform：前往 terraform 目錄並初始化 Terraform。

     terraform init
     

  2. 檢查執行計畫：這個指令會顯示 Terraform 將進行的基礎架構變更。

     terraform plan -var-file=default_env.tfvars
     

  3. 套用設定：執行 Terraform 方案，在 Google Cloud 專案中建立資源。系統提示時，請使用 yes 確認。

     terraform apply -var-file=default_env.tfvars
     

     執行這些指令後，Terraform 會佈建 GKE 叢集和 Artifact Registry 存放區，並設定必要的 IAM 角色和服務帳戶，包括 GKE 的 Workload Identity Federation。

  如要進一步瞭解如何使用 Terraform，請參閱「GKE 的 Terraform 支援」。

  設定 kubectl 與叢集通訊

  如果尚未設定 kubectl 與叢集通訊，請執行下列指令：

  gcloud container clusters get-credentials CLUSTER_NAME \
      --location=${GOOGLE_CLOUD_LOCATION}
  

  將 CLUSTER_NAME 替換為您的 GKE 叢集名稱。

  設定 Workload Identity Federation，以便存取 GKE

  如果您使用 Terraform，可以略過這個步驟。這個程序會將 Kubernetes 服務帳戶 (KSA) 連結至 IAM 服務帳戶，安全地授予代理程式 Google Cloud 服務的存取權。

  1. 建立服務帳戶，以存取 Vertex AI：

     gcloud iam service-accounts create vertex-sa \
         --project=$PROJECT_ID
     

  2. 將 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"
     

  3. 在叢集中建立 KSA。執行這項指令前，請務必按照「設定 kubectl 與叢集通訊」一文中的操作說明進行設定。

     kubectl create serviceaccount vertex-sa
     

  4. 為 KSA 加入註解，將其連結至服務帳戶：

     kubectl annotate serviceaccount vertex-sa \
         iam.gke.io/gcp-service-account=vertex-sa@$PROJECT_ID.iam.gserviceaccount.com
     

  5. 授予服務帳戶權限，使其以 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]"
     

  部署及設定代理程式應用程式

  設定 Google Cloud 資源後，請準備部署代理程式應用程式，並在 GKE 上設定其執行階段。這包括定義代理程式的程式碼、建立 Dockerfile 以將其容器化，以及編寫 Kubernetes 資訊清單，將其部署至叢集。

  1. 瞭解代理程式應用程式結構：/app 目錄包含代理程式應用程式的核心檔案：
     • main.py：FastAPI 應用程式的進入點，負責公開代理程式的 API。
     • agent.py：包含 ADK 代理程式的邏輯，定義代理程式如何使用 Vertex AI 和處理要求。
     • __init__.py：初始化 Python 套件。
     • requirements.txt：列出代理程式的所有 Python 依附元件。
     • Dockerfile：定義如何將應用程式封裝至 Docker 映像檔。

  2. 建立代理程式部署資訊清單：在 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 的 Docker 映像檔完整網址 (例如 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 區域。

  3. 套用部署資訊清單：

     kubectl apply -f agent-deployment.yaml
     

     這個指令會在 GKE 叢集中，為代理程式應用程式建立 Deployment 和相關聯的 Pod。

  4. 公開代理程式：您可以使用這些方法公開代理程式，供他人存取。

     • 如要從叢集外部存取代理程式，請建立 Kubernetes Service。如果是 Web API，則通常是 LoadBalancer 類型服務。

     • 如要進行本機開發和測試，請使用 kubectl port-forward 指令直接存取代理程式。

     LoadBalancer

     1. 建立下列資訊清單，並命名為 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
        

     2. 套用資訊清單：

        kubectl apply -f agent-service.yaml
        

        佈建外部 IP 位址可能需要幾分鐘的時間。

     3. 確認 IP 位址已佈建完成：

        kubectl get service adk-agent-service
        

        在輸出內容中尋找 EXTERNAL-IP 值。取得值後，即可使用這個 IP 位址與已部署的代理程式互動。

     port-forward

     如果您主要使用 port-forward，請考慮使用 ClusterIP 服務類型，而非 LoadBalancer，因為 ClusterIP 服務是內部服務，耗用的資源較少。

     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 叢集內執行的代理程式。

  測試已部署的代理程式

  現在代理程式應用程式已部署並公開，請測試其功能。

  本節說明如何找出代理程式的端點，並測試代理程式的 API。

  1. 找出代理程式的端點：視您在前一節中選擇公開代理程式的方式而定，找出可存取的端點：

     LoadBalancer

     1. 擷取外部 IP 位址：

        kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
        

     2. 將外部 IP 位址儲存在環境變數中，方便使用：

        export AGENT_IP=$(kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
        

        代理程式的基本網址為 http://${AGENT_IP}。

     port-forward

     請確認 kubectl port-forward 指令是在獨立的終端機中執行。代理程式的基本網址為 http://localhost:8000。

  2. 測試代理程式的 API：向代理程式的 /run 端點發出 curl 要求，測試代理程式的 API。代理程式預期會收到含有訊息欄位的 JSON 酬載。將 AGENT_BASE_URL 替換為 http://${AGENT_IP} (適用於 LoadBalancer) 或 http://localhost:8000 (適用於連接埠轉送)。

     1. 建立新工作階段。這項操作會為服務專員準備新的對話。

        # 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
        

     2. 使用上一個步驟的會期詳細資料，向代理程式傳送查詢。

        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 模型互動。回覆內容包含代理程式根據你的訊息生成的答覆。

  3. 存取代理程式的網頁使用者介面 (如適用)：如果代理程式包含網頁使用者介面，請在網路瀏覽器中前往 AGENT_BASE_URL，即可存取該介面。ADK 通常會提供基本網頁 UI，方便互動和偵錯。舉例來說，如果您透過 LoadBalancer 公開代理程式，且 EXTERNAL-IP 為 34.123.45.67，請在瀏覽器中前往 http://34.123.45.67。

  清除所用資源

  如要避免系統向您的 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_ID
  

  將 CLUSTER_NAME 替換為您的 GKE 叢集名稱。

  Terraform

  1. 在 Cloud Shell 終端機中，前往 tutorials-and-examples/adk/vertex/ 目錄：

     cd tutorials-and-examples/adk/vertex/
     

  2. 執行這項指令，即可移除 Terraform 設定檔中定義的所有資源。

     cd terraform
     terraform destroy
     

  後續步驟

  • 瞭解如何設定 Horizontal Pod Autoscaler (HPA)，自動視需求調整代理程式的資源。
  • 瞭解如何為在Google Cloud上執行的網頁應用程式設定 Identity-Aware Proxy (IAP)，集中授權存取代理程式的使用者介面。
  • 瞭解如何使用 Cloud Logging 和 Cloud Monitoring，深入瞭解 GKE 叢集中代理程式的效能和健康狀態。
  • 在 GKE AI Labs 中探索實驗性範例，瞭解如何運用 GKE 加速代理式 AI 計畫。