使用 Agent Development Kit (ADK) 和自行託管的 LLM，在 GKE 上部署代理式 AI 應用程式

本教學課程示範如何使用 Google Kubernetes Engine (GKE) 部署及管理容器化代理程式 AI/ML 應用程式。結合 Google 代理程式開發套件 (ADK) 和自行代管的大型語言模型 (LLM)，例如由 vLLM 提供的 Llama 3.1，您就能有效率地大規模運作 AI 代理程式，同時全面掌控模型堆疊。本教學課程將逐步說明完整流程，包括如何將以 Python 為基礎的代理程式從開發階段，部署至具有 GPU 加速功能的 GKE Autopilot 叢集，以供正式環境使用。

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

注意： 本教學課程採用的方法需要佈建具備 GPU 硬體的 GKE 叢集來執行 LLM，這與 Vertex AI 方法不同，後者是由 Google 的受管理基礎架構處理模型推論作業。如要進一步瞭解 Vertex AI 方法，請參閱「使用 ADK 和 Vertex AI 在 GKE 上部署代理式 AI 應用程式」。

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

• GKE
• 使用 Docker 進行容器化

背景

本節說明本教學課程中使用的主要技術。

Agent Development Kit (ADK)

Agent Development Kit (ADK) 是一個彈性十足的模組化框架，可用於開發及部署 AI 代理。ADK 專為 Gemini 和 Google 生態系統最佳化，但您不必使用特定模型或部署作業，因為 ADK 可與其他架構相容。ADK 的設計宗旨是讓代理程式開發更像軟體開發，方便開發人員建立、部署及協調代理程式架構，處理從基本工作到複雜工作流程的各種任務。

詳情請參閱 ADK 說明文件。

GKE 代管 Kubernetes 服務

Google Cloud 提供一系列服務，包括 GKE，非常適合部署及管理 AI/機器學習工作負載。GKE 是代管 Kubernetes 服務，可簡化容器化應用程式的部署、擴充及管理作業。GKE 提供必要的基礎架構，包括可擴充的資源、分散式運算和高效率網路，可處理 LLM 的運算需求。

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

vLLM

vLLM 是經過高度最佳化的開放原始碼 LLM 服務架構，可提高 GPU 的服務輸送量，並提供下列功能：

• 使用 PagedAttention 實作最佳化轉換器。
• 持續批次處理，提升整體放送輸送量。
• 在多個 GPU 上進行張量平行處理和分散式服務。

詳情請參閱 vLLM 說明文件。

準備環境

本教學課程會使用 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_REGION=REGION
   export PROJECT_ID=PROJECT_ID
   

   替換下列值：

   • PROJECT_ID：您的 Google Cloud 專案 ID。
   • REGION：用於佈建 GKE 叢集、Artifact Registry 和其他區域資源的 Google Cloud 區域 (例如 us-east4)。請務必指定支援 L4 GPU 和 G2 機器類型執行個體的區域。如要查看區域供應情形，請參閱 Compute Engine 說明文件中的「GPU 區域和可用區」。

複製範例專案

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

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

2. 前往教學課程目錄：

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

建立及設定 Google Cloud 資源

如要部署代理程式，請先佈建必要的 Google Cloud 資源。您可以使用 gcloud CLI 或 Terraform 建立 GKE 叢集和 Artifact Registry 存放區。

gcloud

本節提供 gcloud CLI 指令，用於設定 GKE 叢集和 Artifact Registry。

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

   Autopilot

   在 Cloud Shell 中執行下列指令：

   gcloud container clusters create-auto CLUSTER_NAME \
       --location=$GOOGLE_CLOUD_REGION
   

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

   使用 Autopilot 時，GKE 會根據工作負載的資源要求，自動佈建節點。在 deploy-llm.yaml 資訊清單中，使用 nodeSelector 即可要求 LLM 專用的 GPU。

   如要新增 nodeSelector 要求 nvidia-l4 GPU，請按照下列步驟操作：

   1. 在編輯器中開啟 kubernetes-engine-samples/ai-ml/adk-vllm/deploy-llm/deploy-llm.yaml。

   2. 在 spec.template.spec 下方新增下列 nodeSelector：

      nodeSelector:
      cloud.google.com/gke-accelerator: nvidia-l4
      

   標準

   1. 在 Cloud Shell 中執行下列指令，建立 Standard 叢集：

      gcloud container clusters create CLUSTER_NAME \
          --location=$GOOGLE_CLOUD_REGION
      

      將 CLUSTER_NAME 替換為 GKE 叢集名稱。

   2. 執行下列指令，為叢集建立啟用 GPU 的節點集區：

      gcloud container node-pools create gpu-node-pool \
          --cluster=CLUSTER_NAME \
          --location=$GOOGLE_CLOUD_REGION \
          --machine-type=g2-standard-8 \
          --accelerator=type=nvidia-l4,count=1 \
          --enable-gvnic
      

      deploy-llm.yaml 檔案指定 nvidia-l4 GPU，這類 GPU 可在 G2 機器系列中使用。如要進一步瞭解這類機器類型，請參閱 Compute Engine 說明文件中的「GPU 機器類型」。

2. 建立 Artifact Registry 存放區：建立 Artifact Registry 存放區，安全地儲存及管理代理程式的 Docker 容器映像檔。

   gcloud artifacts repositories create REPO_NAME \
       --repository-format=docker \
       --location=$GOOGLE_CLOUD_REGION
   

   將 REPO_NAME 替換為要使用的 Artifact Registry 存放區名稱 (例如 adk-repo)。

3. 取得存放區網址：如要驗證存放區的完整路徑，請執行這項指令。建構代理程式映像檔時，您會使用這個格式為 Docker 映像檔加上標記。

   gcloud artifacts repositories describe REPO_NAME \
       --location $GOOGLE_CLOUD_REGION
   

Terraform

本節說明如何使用範例存放區中包含的 Terraform 設定，自動佈建 Google Cloud 資源。

1. 前往 Terraform 目錄：\terraform 目錄包含建立 GKE 叢集和其他必要資源的所有必要設定檔。

   cd terraform
   

2. 建立 Terraform 變數檔案：複製提供的範例變數檔案 (example_vars.tfvars)，建立自己的 vars.tfvars 檔案。

   cp example_vars.tfvars vars.tfvars
   

   在編輯器中開啟 vars.tfvars 檔案，並將預留位置值替換為特定設定。您至少必須將 PROJECT_ID 替換為 Google Cloud 專案 IDCLUSTER_NAME，並將 CLUSTER_NAME 替換為 GKE 叢集名稱。

3. 初始化 Terraform：如要下載 Google Cloud的必要供應商外掛程式，請執行這項指令。

   terraform init
   

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

   terraform plan -var-file=vars.tfvars
   

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

   terraform apply -var-file=vars.tfvars
   

執行這些指令後，Terraform 會佈建 GKE 叢集和 Artifact Registry 存放區，並設定必要的 IAM 角色和服務帳戶，包括 GKE 適用的工作負載身分聯盟。

如要進一步瞭解如何使用 Terraform，請參閱「使用 Terraform 佈建 GKE 資源」。

設定 kubectl 與叢集通訊

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

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

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

建構代理程式映像檔

使用 gcloud CLI 或 Terraform 建立基礎架構後，請按照下列步驟建構代理程式應用程式。

1. 授予 Cloud Build 必要的 IAM 角色：Cloud Build 服務需要權限，才能將代理程式的容器映像檔推送至 Artifact Registry。將 roles/artifactregistry.writer 角色授予 Compute Engine 預設服務帳戶，Cloud Build 會使用這個帳戶。

   1. 建構 Compute Engine 預設服務帳戶的電子郵件地址：

      export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
      export COMPUTE_SA_EMAIL=${PROJECT_NUMBER}[e-mail]
      

   2. 將 roles/artifactregistry.writer 角色指派給服務帳戶：

      gcloud projects add-iam-policy-binding $PROJECT_ID \
          --member=serviceAccount:${COMPUTE_SA_EMAIL} \
          --role=roles/artifactregistry.writer
      

2. 建構並推送代理程式容器映像檔：從專案根目錄 (adk/llama/vllm) 建構 Docker 映像檔，然後執行下列指令，將映像檔推送至 Artifact Registry。

   export IMAGE_URL="${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME/adk-agent:latest"
   gcloud builds submit --tag $IMAGE_URL
   

3. 確認映像檔已推送：建構程序順利完成後，請列出存放區中的映像檔，確認代理程式的容器映像檔已推送至 Artifact Registry。

   gcloud artifacts docker images list ${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME
   

   輸出內容應會列出您剛推送並標記為 latest 的映像檔。

部署模型

設定 GKE 叢集並建構代理程式映像檔後，下一步就是將自架式 Llama 3.1 模型部署至叢集。如要執行這項操作，請部署預先設定的 vLLM 推論伺服器，從 Hugging Face 提取模型，並在叢集內部提供模型。

1. 為 Hugging Face 憑證建立 Kubernetes 密鑰：如要允許 GKE 叢集下載受限的 Llama 3.1 模型，您必須以 Kubernetes 密鑰的形式提供 Hugging Face 權杖。deploy-llm.yaml 資訊清單已設定為使用這個密鑰進行驗證。

   kubectl create secret generic hf-secret \
       --from-literal=hf-token-secret=HUGGING_FACE_TOKEN
   

   將 HUGGING_FACE_TOKEN 替換成您的權杖。

2. 查看資訊清單：從專案根目錄 (adk/llama/vllm) 前往 /deploy-llm 目錄，該目錄包含模型部署資訊清單。

   cd deploy-llm
   

3. 套用資訊清單：執行下列指令，將 deploy-llm.yaml 資訊清單套用至叢集。

   kubectl apply -f deploy-llm.yaml
   

   這個指令會建立三項 Kubernetes 資源：

   • 執行 vLLM 伺服器的 Deployment，設定為使用 meta-llama/Llama-3.1-8B-Instruct 模型。
   • 名為 vllm-llama3-service 的 Service，會透過內部叢集 IP 位址公開 vLLM 伺服器，讓 ADK 代理程式與其通訊。
   • 包含 Llama 3.1 模型所需的 Jinja 聊天範本的 ConfigMap。

4. 驗證模型部署作業：vLLM 伺服器會從 Hugging Face 提取模型檔案。這項作業可能需要幾分鐘才能完成。您可以監控 Pod 的狀態，確保 Pod 已準備就緒。

   1. 等待部署作業完成。

      kubectl wait --for=condition=available --timeout=600s deployment/vllm-llama3-deployment
      

   2. 查看執行中 Pod 的記錄，確認伺服器已順利啟動。

      export LLM_POD=$(kubectl get pods -l app=vllm-llama3 -o jsonpath='{.items[0].metadata.name}')
      kubectl logs -f $LLM_POD
      

      當您看到類似下列內容的記錄輸出時，即表示部署作業已完成，這代表 LLM 伺服器已啟動，且 API 路徑可用：

      INFO 07-16 14:15:16 api_server.py:129] Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
      

   3. 直接將要求傳送至模型伺服器，確認 LLM 是否已準備就緒。如要執行這項操作，請開啟新的 Cloud Shell 終端機，然後執行下列指令，將 vllm-llama3-service 轉送至本機：

      kubectl port-forward service/vllm-llama3-service 8000:8000
      

   4. 在另一個終端機中，使用 curl 將範例要求傳送至模型的 API 端點。例如：

      curl -X POST http://localhost:8000/v1/completions \
        -H "Content-Type: application/json" \
        -d '{
          "model": "meta-llama/Llama-3.1-8B-Instruct",
          "prompt": "Hello!",
          "max_tokens": 10
        }'
      

      如果指令傳回成功的 JSON 回應，表示 LLM 已準備就緒。 現在返回終端機視窗並按下 Ctrl+C，即可終止連接埠轉送程序，然後繼續部署代理程式。

部署代理程式應用程式

下一步是部署以 ADK 為基礎的代理程式應用程式。

1. 前往 /deploy-agent 目錄：從專案根目錄 (adk/llama/vllm) 前往 /deploy-agent 目錄，其中包含代理程式的原始碼和部署資訊清單。

   cd ../deploy-agent
   

2. 更新代理程式部署資訊清單：

   1. 範例 deploy-agent.yaml 資訊清單檔案包含容器映像檔 URL 中的專案 ID 預留位置。您必須將預留位置換成專案 ID。 Google Cloud

      image: us-central1-docker.pkg.dev/PROJECT_ID/adk-repo/adk-agent:latest
      

      如要就地執行這項替換作業，可以執行下列指令：

      sed -i "s/<PROJECT_ID>/$PROJECT_ID/g" deploy-agent.yaml
      

   2. 確認 readinessProbe 路徑已設為 /，而非 /dev-ui。 如要就地執行這項替換作業，可以執行下列指令：

      sed -i "s|path: /dev-ui/|path: /|g" deploy-agent.yaml
      

3. 套用資訊清單：執行下列指令，將 deploy-agent.yaml 資訊清單套用至叢集。

   kubectl apply -f deploy-agent.yaml
   

   這個指令會建立兩項 Kubernetes 資源：

   • 名為 adk-agent 的 Deployment，用於執行您自訂建構的代理程式容器映像檔。
   • 名為 adk-agent 的 NodePort 類型服務，可公開代理程式應用程式，方便進行測試。

4. 驗證代理程式部署作業：檢查 Pod 的狀態，確保 Pod 正常運作。

   1. 等待部署作業完成：

      kubectl wait --for=condition=available --timeout=300s deployment/adk-agent
      

   2. 查看執行中代理程式 Pod 的記錄：

      export AGENT_POD=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}')
      kubectl logs -f $AGENT_POD
      

如果看到類似下列的記錄輸出內容，表示部署作業成功，Uvicorn 伺服器正在執行，且已準備好接受要求：

INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)

測試已部署的代理程式

成功部署 vLLM 伺服器和代理程式應用程式後，您就可以與代理程式的網頁 UI 互動，測試端對端功能。

注意： 本教學課程會使用 LLM 根據提示判斷要呼叫的工具，但為求簡單，工具本身會使用硬式編碼的模擬資料，而非即時 API。代理程式的 get_weather 工具會從預先定義的字典中擷取「巴黎」、「渥太華」和「東京」的天氣資訊，而不是即時外部服務。

1. 將代理程式的服務轉送至本機：adk-agent 服務的類型為 NodePort，但從 Cloud Shell 環境存取該服務最直接的方式是使用 kubectl port-forward 指令。執行下列指令，建立連往代理程式 Pod 的安全通道。

   kubectl port-forward $AGENT_POD 8001:8001
   

2. 存取代理程式的網頁介面：在 Cloud Shell 中，按一下「Web Preview」(網頁預覽) 按鈕，然後選取「Preview on port 8001」(透過以下通訊埠預覽：8001)。系統會開啟新的瀏覽器分頁，顯示服務專員的即時通訊介面。

3. 與代理程式互動：向代理程式提出問題，系統會叫用 get_weather 工具。例如：

   What's the weather like in Tokyo?
   

   代理程式會先呼叫 LLM，瞭解意圖並判斷是否需要使用 get_weather 工具。接著，系統會以「東京」做為參數執行工具。最後，系統會使用工具的輸出內容生成回覆。畫面會顯示類似以下的回應：

     The weather in Tokyo is 25°C and sunny.
   

4. (選用) 在記錄中驗證工具呼叫：您可以查看相應 Pod 的記錄，觀察代理程式與 LLM 的互動，以及工具的執行情況。

   1. 代理程式 Pod 記錄：在新終端機中，查看 adk-agent Pod 的記錄。您會看到工具呼叫及其結果。

      kubectl logs -f $AGENT_POD
      

      輸出內容會顯示工具的呼叫情形和結果的處理情形。

   2. LLM Pod 記錄：查看 vllm-llama3-deployment Pod 的記錄，瞭解代理程式傳送的要求。

      kubectl logs -f $LLM_POD
      

      記錄會顯示代理程式傳送至 LLM 的完整提示，包括系統訊息、查詢和 get_weather 工具的定義。

測試完成後，請返回終端機視窗並按下 Ctrl+C，終止 port-forward 程序。