本教學課程示範如何使用 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
開始之前,請務必詳閱下列事項:
背景
本節說明本教學課程中使用的主要技術。
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 說明文件。
目標
本教學課程將說明如何執行下列操作:
- 設定 Google Cloud 環境。
- 佈建啟用 GPU 的 GKE 叢集。
- 使用 vLLM 推論伺服器部署 Llama 3.1 模型。
- 為 ADK 型代理程式建構容器映像檔。
- 將代理程式部署到 GKE 叢集,並連線至自行代管的 LLM。
- 測試已部署的代理程式。
架構
本教學課程介紹可擴充的架構,說明如何在 GKE 部署代理式 AI 應用程式。ADK 代理程式應用程式會在標準 CPU 節點集區上執行,而自架 LLM (vLLM 上的 Llama 3.1) 則會在啟用 GPU 的節點集區上執行,兩者都位於同一個 GKE 叢集內。這個架構會將代理程式的應用程式邏輯與 LLM 推論工作負載分開,讓每個元件都能獨立擴充及管理。
這個架構有兩個核心元件,分別位於各自的 GKE 部署作業中:
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-service
Kubernetes 服務公開的 REST API 與這個伺服器通訊。
ADK 代理程式和 vLLM 部署作業都會在同一個 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
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. 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.enable
permission. 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
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. 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.enable
permission. 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」頁面 - 選取專案。
- 按一下「授予存取權」 。
-
在「New principals」(新增主體) 欄位中,輸入您的使用者 ID。 這通常是 Google 帳戶的電子郵件地址。
- 在「Select a role」(選取角色) 清單中,選取角色。
- 如要授予其他角色,請按一下 「新增其他角色」,然後新增每個其他角色。
- 按一下 [Save]。
- 從 Hugging Face 取得 讀取存取權 杖,下載 Llama 模型。您也需要要求存取 Llama 3.1 模型。
- 在 Google Cloud 控制台中啟動 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:用於佈建 GKE 叢集、Artifact Registry 和其他區域資源的 Google Cloud 區域
(例如
us-east4
)。請務必指定支援 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
建立 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,請按照下列步驟操作:- 在編輯器中開啟
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-gvnic
deploy-llm.yaml
檔案指定nvidia-l4
GPU,這類 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
目錄包含建立 GKE 叢集和其他必要資源的所有必要設定檔。cd terraform
建立 Terraform 變數檔案:複製提供的範例變數檔案 (
example_vars.tfvars
),建立自己的vars.tfvars
檔案。cp example_vars.tfvars vars.tfvars
在編輯器中開啟
vars.tfvars
檔案,並將預留位置值替換為特定設定。您至少必須將 PROJECT_ID 替換為 Google Cloud 專案 IDCLUSTER_NAME,並將 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
授予 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
的映像檔。為 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 替換成您的權杖。
查看資訊清單:從專案根目錄 (
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
,即可終止連接埠轉送程序,然後繼續部署代理程式。
前往
/deploy-agent
目錄:從專案根目錄 (adk/llama/vllm
) 前往/deploy-agent
目錄,其中包含代理程式的原始碼和部署資訊清單。cd ../deploy-agent
更新代理程式部署資訊清單:
範例
deploy-agent.yaml
資訊清單檔案包含容器映像檔 URL 中的專案 ID 預留位置。您必須將預留位置換成專案 ID。 Google Cloudimage: 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 類型服務,可公開代理程式應用程式,方便進行測試。
- 名為
驗證代理程式部署作業:檢查 Pod 的狀態,確保 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
將代理程式的服務轉送至本機:
adk-agent
服務的類型為NodePort
,但從 Cloud Shell 環境存取該服務最直接的方式是使用kubectl port-forward
指令。執行下列指令,建立連往代理程式 Pod 的安全通道。kubectl port-forward $AGENT_POD 8001:8001
存取代理程式的網頁使用者介面:在 Cloud Shell 中,按一下「Web Preview」(網頁預覽) 按鈕,然後選取「Preview on port 8001」(透過以下通訊埠預覽: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-agent
Pod 的記錄。您會看到工具呼叫及其結果。kubectl logs -f $AGENT_POD
輸出內容會顯示工具的呼叫情形和結果的處理情形。
LLM Pod 記錄:查看
vllm-llama3-deployment
Pod 的記錄,瞭解代理程式傳送的要求。kubectl logs -f $LLM_POD
記錄會顯示代理程式傳送至 LLM 的完整提示,包括系統訊息、查詢和
get_weather
工具的定義。
從專案根目錄 (
adk/llama/vllm
) 前往/terraform
目錄:cd terraform
執行這項指令,即可移除 Terraform 設定檔中定義的所有資源:
terraform destroy
- 瞭解如何設定 Horizontal Pod Autoscaler (HPA),自動視需求調整代理程式的資源。
- 瞭解如何為在 Google Cloud上執行的網頁應用程式設定 Identity-Aware Proxy (IAP),集中授權存取代理程式的使用者介面。
- 瞭解如何使用 Cloud Logging 和 Cloud Monitoring,深入瞭解 GKE 叢集中代理程式的效能和健康狀態。
- 探索 GKE AI Labs 中的實驗性範例,瞭解如何運用 GKE 加速代理式 AI 計畫。
準備環境
本教學課程會使用 Cloud Shell 管理託管於 Google Cloud的資源。Cloud Shell 已預先安裝本教學課程所需的軟體,包括
kubectl
、terraform
和Google Cloud CLI
。如要使用 Cloud Shell 設定環境,請按照下列步驟操作:
複製範例專案
建立及設定 Google Cloud 資源
如要部署代理程式,請先佈建必要的 Google Cloud 資源。您可以使用 gcloud CLI 或 Terraform 建立 GKE 叢集和 Artifact Registry 存放區。
gcloud
本節提供 gcloud CLI 指令,用於設定 GKE 叢集和 Artifact Registry。
Terraform
本節說明如何使用範例存放區中包含的 Terraform 設定,自動佈建 Google Cloud 資源。
執行這些指令後,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 建立基礎架構後,請按照下列步驟建構代理程式應用程式。
部署模型
設定 GKE 叢集並建構代理程式映像檔後,下一步就是將自架式 Llama 3.1 模型部署至叢集。如要執行這項操作,請部署預先設定的 vLLM 推論伺服器,從 Hugging Face 提取模型,並在叢集內部提供模型。
部署代理程式應用程式
下一步是部署以 ADK 為基礎的代理程式應用程式。
如果看到類似下列的記錄輸出內容,表示部署作業成功,Uvicorn 伺服器正在執行,且已準備好接受要求:
INFO: Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)
測試已部署的代理程式
成功部署 vLLM 伺服器和代理程式應用程式後,您就可以與代理程式的網頁 UI 互動,測試端對端功能。
測試完成後,請返回終端機視窗並按下
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
目錄中執行單一指令,即可刪除所有資源。後續步驟
-