Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

標準

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

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

開始之前，請先確認您瞭解下列事項：

背景

本指南結合多項 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 提供必要的基礎架構，包括可擴充的資源、分散式運算和高效能網路，可處理大型語言模型的運算需求。

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

Vertex AI

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

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

如要進一步瞭解 Vertex AI 在代理式 AI 應用程式中的用途，請參閱 Vertex AI 說明文件。

Gemini 2.5 Flash

Gemini 2.5 Flash 提供新一代功能，並提升專為代理工作負載設計的能力，包括速度更快、內建工具使用功能、多模態生成，以及 100 萬個詞元的脈絡窗口。Gemini 2.5 Flash 比先前的 Flash 模型更進步，品質提升，速度則與先前相近。

如要瞭解 Gemini 2.5 Flash 的技術資訊 (例如效能基準、訓練資料集資訊、永續發展工作、預期用途和限制，以及我們的倫理和安全方法)，請參閱 Gemini 2.5 Flash 的模型資訊卡。

目標

本指南說明如何執行下列操作：

設定 Google Cloud 環境。
為代理程式建構容器映像檔。
將代理程式部署至 GKE 叢集。
測試已部署的代理程式。

費用

本指南使用下列 Google Cloud計費元件：

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

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

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 the resourcemanager.projects.create permission. Learn how to grant roles.

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

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

確認您在專案中具備下列角色： roles/container.admin、roles/iam.serviceAccountAdmin、roles/artifactregistry.admin、roles/cloudbuild.builds.editor、roles/resourcemanager.projectIamAdmin
檢查角色
1. 前往 Google Cloud 控制台的「IAM」頁面。
  前往「IAM」頁面
2. 選取專案。
3. 在「主體」欄中，找出所有識別您或您所屬群組的資料列。如要瞭解自己所屬的群組，請與管理員聯絡。
4. 針對指定或包含您的所有列，請檢查「角色」欄，確認角色清單是否包含必要角色。
授予角色
1. 前往 Google Cloud 控制台的「IAM」頁面。
  前往「IAM」頁面
2. 選取專案。
3. 按一下「Grant access」(授予存取權)。
4. 在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。這通常是指 Google 帳戶的電子郵件地址。
5. 按一下「選取角色」，然後搜尋角色。
6. 如要授予其他角色，請按一下「Add another role」(新增其他角色)，然後新增其他角色。
7. 按一下「Save」(儲存)。

準備環境

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

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

在 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-vertex

建立及設定 Google Cloud 資源

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

gcloud

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

建立 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 替換為您的標準叢集名稱。
為 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
```
取得存放區網址：執行這項指令，確認存放區的完整路徑。您會在下一個步驟中使用這個路徑格式，為 Docker 映像檔加上標記。
```
gcloud artifacts repositories describe adk-repo \
    --location $GOOGLE_CLOUD_LOCATION \
    --project=$PROJECT_ID
```

將必要的 IAM 角色授予 Compute Engine 預設服務帳戶：根據預設，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}-compute@developer.gserviceaccount.com" \
        --role="${ROLE}"
done

建構及推送代理程式容器映像檔：執行這項指令，建構 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

確認映像檔已推送：

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：前往 terraform 目錄並初始化 Terraform。
```
terraform init
```
檢查執行計畫：這個指令會顯示 Terraform 將進行的基礎架構變更。
```
terraform plan -var-file=default_env.tfvars
```
套用設定：執行 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 for GKE 存取權

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

建立服務帳戶以存取 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-sa
```

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

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]"

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

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

瞭解代理程式應用程式結構：/app 目錄包含代理程式應用程式的核心檔案：
- main.py：FastAPI 應用程式的進入點，負責公開代理程式的 API。
- 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 的 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 區域。

套用部署資訊清單：
```
kubectl apply -f agent-deployment.yaml
```
這個指令會在 GKE 叢集中，為代理程式應用程式建立 Deployment 和相關聯的 Pod。
公開代理程式：您可以使用這些方法公開代理程式，供他人存取。
- 如要從叢集外部存取代理程式，請建立 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。

找出代理的端點：視您在上一個部分選擇公開代理的方式而定，找出可存取的端點：
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。
測試代理程式的 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 模型互動。回覆內容包含代理程式根據您的訊息生成的答覆。
存取代理程式的網頁 UI (如適用)：如果代理程式包含網頁式使用者介面，請在網頁瀏覽器中前往 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

在 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)，集中授權存取代理程式的使用者介面。
瞭解如何使用 Cloud Logging 和 Cloud Monitoring，深入瞭解 GKE 叢集中代理程式的效能和健康狀態。
在 GKE AI Labs 中探索實驗性範例，瞭解如何運用 GKE 加速推動代理程式 AI 計畫。

使用 Agent Development Kit (ADK) 和 Vertex AI，在 GKE 部署代理式 AI 應用程式 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

背景

Google Agent Development Kit (ADK)

GKE 代管 Kubernetes 服務

Vertex AI

Gemini 2.5 Flash

目標

費用

事前準備

檢查角色

授予角色

準備環境

複製範例專案

建立及設定 Google Cloud 資源

gcloud

Autopilot

標準

Terraform

設定 kubectl 與叢集通訊

設定 Workload Identity Federation for GKE 存取權

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

LoadBalancer

port-forward

測試已部署的代理

LoadBalancer

port-forward

清除所用資源

刪除已部署的資源

gcloud

Terraform

後續步驟

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

設定 `kubectl` 與叢集通訊