本教學課程將示範如何使用 Google Kubernetes Engine (GKE),部署及管理容器化代理式 AI/ML 應用程式。結合 Google Agent Development Kit (ADK) 和自行代管的大型語言模型 (LLM),例如由 vLLM 提供的 Llama 3.1,您就能有效率地大規模運作 AI 代理,同時全面掌控模型堆疊。本教學課程將逐步引導您完成端對端程序,將 Python 代理從開發階段推進到正式環境,並部署至具備 GPU 加速功能的 GKE Autopilot 叢集。
本教學課程適合機器學習 (ML) 工程師、開發人員和雲端架構師,協助他們瞭解如何使用 Kubernetes 容器自動化調度管理功能,提供代理式 AI/機器學習應用程式。如要進一步瞭解 Google Cloud內容中提及的常見角色和工作範例,請參閱「常見的 GKE 使用者角色和工作」。
開始之前,請務必先熟悉下列事項:
背景
本節說明本教學課程中使用的重要技術。
Agent Development Kit (ADK)
Agent Development Kit (ADK) 是富有彈性的模組化框架,適合用於開發及部署 AI 代理。ADK 雖然是專為 Gemini 和 Google 生態系統最佳化,但不限定模型或部署方式,且可與其他架構相容。ADK 的設計宗旨是讓代理開發過程更像軟體開發,方便開發人員建立、部署及自動調度管理代理式架構,從基本工作到複雜工作流程,都能輕鬆完成。
詳情請參閱 ADK 說明文件。
GKE 代管式 Kubernetes 服務
Google Cloud 提供一系列服務,包括 GKE,非常適合部署及管理 AI/機器學習工作負載。GKE 是代管 Kubernetes 服務,可簡化容器化應用程式的部署、擴充及管理作業。GKE 提供必要的基礎架構,包括可擴充的資源、分散式運算和高效率網路,可處理大型語言模型的運算需求。
如要進一步瞭解 Kubernetes 的重要概念,請參閱「開始學習 Kubernetes」。如要進一步瞭解 GKE,以及如何協助您自動處理、管理 Kubernetes 及調度資源,請參閱 GKE 總覽。
vLLM
vLLM 是經過高度最佳化的開放原始碼 LLM 服務架構,可提高 GPU 的服務處理量,並提供下列功能:
- 使用 PagedAttention 最佳化 Transformer 實作。
- 持續批次處理,提高整體服務處理量。
- 在多個 GPU 上進行張量平行處理和分散式服務。
詳情請參閱 vLLM 說明文件。
目標
本教學課程說明如何執行下列操作:
- 設定 Google Cloud 環境。
- 佈建支援 GPU 的 GKE 叢集。
- 使用 vLLM 推論伺服器部署 Llama 3.1 模型。
- 為以 ADK 為基礎的代理程式建構容器映像檔。
- 將代理程式部署至 GKE 叢集,並連結至自行託管的 LLM。
- 測試已部署的代理。
架構
本教學課程介紹可擴充的架構,說明如何在 GKE 部署代理式 AI 應用程式。ADK 代理程式應用程式在標準 CPU 節點集區上執行,而自行託管的 LLM (vLLM 上的 Llama 3.1) 則在啟用 GPU 的節點集區上執行,兩者都在同一個 GKE 叢集內。這種架構可將代理程式的應用程式邏輯與 LLM 推論工作負載分開,讓每個元件都能獨立擴充及管理。
這個架構有兩個核心元件,分別位於各自的 GKE Deployment:
ADK 代理應用程式:代理的自訂商業邏輯和工具 (例如
get_weather) 位於容器映像檔中。映像檔會在標準 CPU 節點集區中執行,並透過內部 Kubernetes 服務與 LLM 通訊。自行託管的 LLM (vLLM 上的 Llama 3.1):Llama 3.1 模型在啟用 GPU 的節點集區中,在專屬的 vLLM 伺服器上執行。這項部署作業會使用公開容器映像檔 (
vllm/vllm-openai:v0.8.5),該映像檔已設定為在容器啟動時,從 Hugging Face 下載並提供指定的模型。代理程式會透過vllm-llama3-serviceKubernetes 服務公開的 REST API 與這個伺服器通訊。
ADK 代理和 vLLM 部署作業都在同一個 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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the required APIs, if any are not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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, if any are not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
請確認您在專案中具備下列角色: roles/container.admin、roles/iam.serviceAccountAdmin、roles/artifactregistry.admin、roles/cloudbuild.builds.editor、roles/resourcemanager.projectIamAdmin
檢查角色
-
前往 Google Cloud 控制台的「IAM」頁面。
前往「IAM」頁面 - 選取專案。
-
在「主體」欄中,找出所有可識別您或您所屬群組的資料列。如要瞭解您所屬的群組,請與管理員聯絡。
- 在指定或包含您的所有資料列中,查看「Role」(角色) 欄,確認角色清單是否包含必要角色。
授予角色
-
前往 Google Cloud 控制台的「IAM」頁面。
前往「IAM」頁面 - 選取專案。
- 按一下「Grant access」(授予存取權)。
-
在「New principals」(新增主體) 欄位中,輸入您的使用者 ID。 這通常是指 Google 帳戶的電子郵件地址。
- 按一下「Select a role」(選取角色),然後搜尋角色。
- 如要授予其他角色,請按一下「Add another role」(新增其他角色),然後新增其他角色。
- 按一下「Save」(儲存)。
-
- 從 Hugging Face 取得讀取存取權權杖,下載 Llama 模型。您也需要申請 Llama 3.1 模型的存取權。
準備環境
本教學課程會使用 Cloud Shell 管理託管於 Google Cloud的資源。Cloud Shell 已預先安裝本教學課程所需的軟體,包括 kubectl、terraform 和 Google Cloud CLI。
如要使用 Cloud Shell 設定環境,請按照下列步驟操作:
- 在 Google Cloud 控制台中啟動 Cloud Shell 工作階段,然後按一下「Activate Cloud Shell」(啟用 Cloud Shell)。
這項操作會在 Google Cloud 控制台窗格中啟動工作階段。
設定預設環境變數:
gcloud config set project PROJECT_ID export GOOGLE_CLOUD_REGION=REGION export PROJECT_ID=PROJECT_ID替換下列值:
- PROJECT_ID:您的 Google Cloud 專案 ID。
- REGION: Google Cloud 區域 (例如
us-east4),用於佈建 GKE 叢集、Artifact Registry 和其他區域性資源。請務必指定支援 L4 GPU 和 G2 機型執行個體的區域。如要查看區域可用性,請參閱 Compute Engine 說明文件中的「GPU 區域和可用區」。
複製範例專案
在 Cloud Shell 終端機中,複製本教學課程的程式碼範例存放區:
git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.git前往教學課程目錄:
cd kubernetes-engine-samples/ai-ml/adk-vllm
建立及設定 Google Cloud 資源
如要部署代理程式,請先佈建必要的 Google Cloud 資源。您可以使用 gcloud CLI 或 Terraform 建立 GKE 叢集和 Artifact Registry 存放區。
gcloud
本節提供 gcloud CLI 指令,用於設定 GKE 叢集和 Artifact Registry。
建立 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 會根據工作負載的資源要求自動佈建節點。在資訊清單中使用
nodeSelector,即可要求 LLM 專用的 GPU。deploy-llm.yaml如要新增要求
nvidia-l4GPU 的nodeSelector,請按照下列步驟操作:- 在編輯器中開啟
kubernetes-engine-samples/ai-ml/adk-vllm/deploy-llm/deploy-llm.yaml。 在
spec.template.spec下方新增下列nodeSelector:nodeSelector: cloud.google.com/gke-accelerator: nvidia-l4
標準
在 Cloud Shell 執行下列指令,建立 Standard 叢集:
gcloud container clusters create CLUSTER_NAME \ --location=$GOOGLE_CLOUD_REGION將 CLUSTER_NAME 替換為 GKE 叢集名稱。
執行下列指令,為叢集建立啟用 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-gvnicdeploy-llm.yaml檔案會指定nvidia-l4GPU,這類 GPU 適用於 G2 機器系列。如要進一步瞭解這個機型,請參閱 Compute Engine 說明文件中的「GPU 機型」。
- 在編輯器中開啟
建立 Artifact Registry 存放區:建立 Artifact Registry 存放區,安全地儲存及管理代理程式的 Docker 容器映像檔。
gcloud artifacts repositories create REPO_NAME \ --repository-format=docker \ --location=$GOOGLE_CLOUD_REGION將 REPO_NAME 替換為要使用的 Artifact Registry 存放區名稱,例如
adk-repo。取得存放區網址:如要驗證存放區的完整路徑,請執行下列指令。建構代理程式映像檔時,您會使用這個格式為 Docker 映像檔加上標記。
gcloud artifacts repositories describe REPO_NAME \ --location $GOOGLE_CLOUD_REGION
Terraform
本節說明如何使用範例存放區中包含的 Terraform 設定,自動佈建 Google Cloud 資源。
前往 Terraform 目錄:
\terraform目錄包含建立 GKE 叢集和其他必要資源所需的所有設定檔。cd terraform建立 Terraform 變數檔案:複製提供的範例變數檔案 (
example_vars.tfvars),建立自己的vars.tfvars檔案。cp example_vars.tfvars vars.tfvars在編輯器中開啟
vars.tfvars檔案,並將預留位置值替換成特定設定。您至少必須將 PROJECT_ID 替換為 Google Cloud 專案 ID,並將 CLUSTER_NAME 替換為 GKE 叢集名稱。初始化 Terraform:執行這個指令,下載 Google Cloud所需的供應商外掛程式。
terraform init查看執行計畫:這個指令會顯示 Terraform 將執行的基礎架構變更。
terraform plan -var-file=vars.tfvars套用設定:如要在 Google Cloud 專案中建立資源,請執行 Terraform 計畫。在系統提示時,請輸入
yes確認。terraform apply -var-file=vars.tfvars
執行這些指令後,Terraform 會佈建 GKE 叢集和 Artifact Registry 存放區,並設定必要的 IAM 角色和服務帳戶,包括 GKE 適用的 Workload Identity Federation。
如要進一步瞭解如何使用 Terraform,請參閱「使用 Terraform 佈建 GKE 資源」。
設定 kubectl,與叢集通訊
如要設定 kubectl 與叢集通訊,請執行下列指令:
gcloud container clusters get-credentials CLUSTER_NAME \
--location=${GOOGLE_CLOUD_REGION}
將 CLUSTER_NAME 替換為 GKE 叢集名稱。
建構代理映像檔
使用 gcloud CLI 或 Terraform 建立基礎架構後,請按照下列步驟建構代理程式應用程式。
授予 Cloud Build 必要的 IAM 角色:Cloud Build 服務需要權限,才能將代理程式的容器映像檔推送至 Artifact Registry。將
roles/artifactregistry.writer角色授予 Compute Engine 預設服務帳戶,Cloud Build 會使用該帳戶。建構 Compute Engine 預設服務帳戶的電子郵件地址:
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)") export COMPUTE_SA_EMAIL=${PROJECT_NUMBER}-compute@developer.gserviceaccount.com將
roles/artifactregistry.writer角色指派給服務帳戶:gcloud projects add-iam-policy-binding $PROJECT_ID \ --member=serviceAccount:${COMPUTE_SA_EMAIL} \ --role=roles/artifactregistry.writer
建構並推送代理容器映像檔:從專案根目錄 (
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確認映像檔已推送:建構程序成功完成後,請列出存放區中的映像檔,確認代理程式的容器映像檔已推送至 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 提取模型,並在叢集內部提供模型。
為 Hugging Face 憑證建立 Kubernetes Secret:如要允許 GKE 叢集下載受限的 Llama 3.1 模型,您必須以 Kubernetes Secret 形式提供 Hugging Face 權杖。
deploy-llm.yaml資訊清單已設定為使用這個密鑰進行驗證。kubectl create secret generic hf-secret \ --from-literal=hf-token-secret=HUGGING_FACE_TOKEN將 HUGGING_FACE_TOKEN 替換為您的權杖。
查看資訊清單:從專案根目錄 (
adk/llama/vllm) 前往/deploy-llm目錄,該目錄包含模型部署資訊清單。cd deploy-llm套用資訊清單:執行下列指令,將
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。
- 執行 vLLM 伺服器的 Deployment,設為使用
驗證模型部署:vLLM 伺服器會從 Hugging Face 提取模型檔案。這項程序應該會在幾分鐘內完成。你可以監控 Pod 的狀態,確保 Pod 已準備就緒。
等待部署作業完成。
kubectl wait --for=condition=available --timeout=600s deployment/vllm-llama3-deployment查看執行中 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)直接向模型伺服器傳送要求,確認 LLM 是否已準備就緒。如要這麼做,請開啟新的 Cloud Shell 終端機,然後執行下列指令,將
vllm-llama3-service轉送至本機:kubectl port-forward service/vllm-llama3-service 8000:8000在另一個終端機中,使用
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 為基礎的代理程式應用程式。
前往
/deploy-agent目錄:從專案根目錄 (adk/llama/vllm) 前往包含代理原始碼和部署資訊清單的/deploy-agent目錄。cd ../deploy-agent更新代理程式部署資訊清單:
範例
deploy-agent.yaml資訊清單檔案包含容器映像檔網址中的專案 ID 預留位置。請務必將預留位置替換為您的 Google Cloud 專案 ID。image: us-central1-docker.pkg.dev/PROJECT_ID/adk-repo/adk-agent:latest如要在適當位置執行這項替換作業,可以執行下列指令:
sed -i "s/<PROJECT_ID>/$PROJECT_ID/g" deploy-agent.yaml確認
readinessProbe路徑已設為/,而非/dev-ui。 如要在適當位置執行這項替換作業,可以執行下列指令:sed -i "s|path: /dev-ui/|path: /|g" deploy-agent.yaml
套用資訊清單:執行下列指令,將
deploy-agent.yaml資訊清單套用至叢集。kubectl apply -f deploy-agent.yaml這個指令會建立兩項 Kubernetes 資源:
- 名為
adk-agent的 Deployment,可執行您自建的代理程式容器映像檔。 - 名為
adk-agent的 NodePort 類型 Service,可公開代理程式應用程式,以便進行測試。
- 名為
驗證代理程式部署作業:檢查 Pod 的狀態,確保代理程式正常運作。
等待部署作業完成:
kubectl wait --for=condition=available --timeout=300s deployment/adk-agent查看執行中代理程式 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 互動,測試端對端功能。
將代理程式的服務轉送至本機:
adk-agent服務的類型為NodePort,但從 Cloud Shell 殼層環境存取服務最直接的方式是使用kubectl port-forward指令。執行下列指令,建立通往代理程式 Pod 的安全通道。kubectl port-forward $AGENT_POD 8001:8001存取代理程式的網頁 UI:在 Cloud Shell 中,按一下「網頁預覽」按鈕,然後選取「透過以下通訊埠預覽:8001」。系統會開啟新的瀏覽器分頁,顯示服務專員的即時通訊介面。
與代理互動:向代理提出問題,叫用其
get_weather工具。例如:What's the weather like in Tokyo?代理會先呼叫 LLM,瞭解意圖並判斷是否需要使用
get_weather工具。接著,系統會以「東京」做為參數執行工具。最後,系統會使用工具的輸出內容生成回覆。畫面會顯示類似以下的回應:The weather in Tokyo is 25°C and sunny.(選用) 在記錄中驗證工具呼叫:您可以查看相應 Pod 的記錄,觀察代理程式與 LLM 的互動,以及工具的執行情況。
代理 Pod 記錄:在新的終端機中,查看
adk-agentPod 的記錄。您會看到工具呼叫及其結果。kubectl logs -f $AGENT_POD輸出內容會顯示呼叫工具的動作,以及處理結果的過程。
LLM Pod 記錄:查看
vllm-llama3-deploymentPod 的記錄,瞭解代理傳入的要求。kubectl logs -f $LLM_POD記錄會顯示代理程式傳送至 LLM 的完整提示,包括系統訊息、查詢和
get_weather工具的定義。
測試完成後,返回終端機視窗並按下 Ctrl+C,即可終止 port-forward 程序。
清除所用資源
為避免因為本教學課程所用資源,導致系統向 Google Cloud 帳戶收取費用,請刪除含有相關資源的專案,或者保留專案但刪除個別資源。
刪除已部署的資源
如要避免系統向您的 Google Cloud 帳戶收取本教學課程所建立資源的費用,請執行下列指令:
gcloud
如果您使用 gcloud CLI 建立資源,請執行下列指令,刪除 GKE 叢集和 Artifact Registry 存放區,並將服務帳戶的權限還原至原始狀態。
gcloud container clusters delete CLUSTER_NAME \
--location=$GOOGLE_CLOUD_REGION
gcloud artifacts repositories delete REPO_NAME \
--location=$GOOGLE_CLOUD_REGION
gcloud projects remove-iam-policy-binding $PROJECT_ID \
--member=serviceAccount:${COMPUTE_SA_EMAIL} \
--role=roles/artifactregistry.writer
Terraform
如果您使用 Terraform 佈建基礎架構,只要在 /terraform 目錄中執行單一指令,即可刪除所有資源。
從專案根目錄 (
adk/llama/vllm) 前往/terraform目錄:cd terraform執行下列指令,移除 Terraform 設定檔中定義的所有資源:
terraform destroy
後續步驟
- 瞭解如何設定水平 Pod 自動調度器 (HPA),根據需求自動調整代理程式的資源。
- 瞭解如何為在 Google Cloud上執行的網頁應用程式設定 Identity-Aware Proxy (IAP),集中授權存取代理 UI。
- 瞭解如何使用 Cloud Logging 和 Cloud Monitoring,深入瞭解 GKE 叢集中代理程式的效能和健康狀態。
- 探索 GKE AI Labs 中的實驗性範例,瞭解如何運用 GKE 加速代理式 AI 計畫。