本教學課程說明如何使用 Google Kubernetes Engine (GKE) 上的 GPU，透過 vLLM 服務架構部署及提供 Gemma 3 大型語言模型 (LLM)。這項服務可做為基礎，協助您瞭解及探索如何在代管 Kubernetes 環境中，實際部署大型語言模型以進行推論。您將部署執行 vLLM 的預先建構容器至 GKE。您也可以設定 GKE，從 Hugging Face 載入 Gemma 1B、4B、12B 和 27B 的權重。
本教學課程的適用對象為機器學習 (ML) 工程師、平台管理員和操作員，以及有興趣使用 Kubernetes 容器自動化調度管理功能，在 H200、H100、A100 和 L4 GPU 硬體上處理 AI/ML 工作負載的資料和 AI 專家。如要進一步瞭解內容中提及的常見角色和範例工作，請參閱「常見的 GKE Enterprise 使用者角色和工作」。 Google Cloud
如果您需要統一管理的 AI 平台，以便快速建構及提供機器學習模型，同時兼顧成本效益，建議您試用 Vertex AI 部署解決方案。
閱讀本頁面之前，請先熟悉下列概念：
背景
本節說明本指南中使用的重要技術。
Gemma
Gemma 是一組開放式輕量級生成式人工智慧 (AI) 多模態模型，以開放授權形式發布。您可以在應用程式、硬體、行動裝置或代管服務中執行這些 AI 模型。Gemma 3 導入多模態功能，支援視覺語言輸入和文字輸出。可處理最多 128,000 個權杖的脈絡窗口，並支援超過 140 種語言。Gemma 3 的數學、推理和對話能力也有所提升，包括結構化輸出和函式呼叫。
您可以使用 Gemma 模型生成文字，也可以調整這些模型，用於執行特定工作。
詳情請參閱 Gemma 說明文件。
GPU
GPU 可加速處理節點上執行的特定工作負載，例如機器學習和資料處理。GKE 提供各種機器類型選項，可供節點設定使用，包括搭載 NVIDIA H200、H100、L4 和 A100 GPU 的機器類型。
vLLM
vLLM 是經過高度最佳化的開放原始碼 LLM 服務架構，可提高 GPU 的服務輸送量，並提供下列功能：
- 使用 PagedAttention 實作最佳化轉換器
- 持續批次處理，提升整體放送輸送量
- 在多個 GPU 上進行張量平行處理和分散式服務
詳情請參閱 vLLM 說明文件。
目標
- 在 Autopilot 或 Standard 模式中，使用 GKE 叢集準備環境。
- 將 vLLM 容器部署至叢集。
- 透過 curl 和網頁即時通訊介面，使用 vLLM 提供 Gemma 3 模型。
事前準備
- 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.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the required API.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the required API.
-
Make sure that you have the following role or roles on the project: roles/container.admin, roles/iam.serviceAccountAdmin
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 帳戶，請先建立一個。
- 請確認專案有足夠的 L4 GPU 配額。詳情請參閱「關於 GPU」和「分配配額」。
取得模型存取權
如要透過 Hugging Face 存取模型，您需要 Hugging Face 權杖。
如要產生新權杖 (如果沒有)，請按照下列步驟操作：
- 依序點選「Your Profile」(你的個人資料) >「Settings」(設定) >「Access Tokens」(存取權杖)。
- 選取「New Token」。
- 指定所選名稱和至少
Read的角色。 - 選取「產生權杖」。
- 將產生的權杖複製到剪貼簿。
準備環境
在本教學課程中，您將使用 Cloud Shell 管理託管於Google Cloud的資源。Cloud Shell 已預先安裝本教學課程所需的軟體，包括 kubectl 和 gcloud CLI。
如要使用 Cloud Shell 設定環境，請按照下列步驟操作：
在 Google Cloud 控制台中，按一下
Google Cloud 控制台中的「啟用 Cloud Shell」，啟動 Cloud Shell 工作階段。系統會在 Google Cloud 控制台的底部窗格啟動工作階段。設定預設環境變數：
gcloud config set project PROJECT_ID gcloud config set billing/quota_project PROJECT_ID export PROJECT_ID=$(gcloud config get project) export REGION=REGION export CLUSTER_NAME=CLUSTER_NAME export HF_TOKEN=HF_TOKEN替換下列值：
PROJECT_ID：您的 Google Cloud 專案 ID。REGION：支援您要使用的加速器類型，例如 L4 GPU 的us-central1。CLUSTER_NAME：叢集名稱。HF_TOKEN：您先前產生的 Hugging Face 權杖。
建立及設定 Google Cloud 資源
請按照下列操作說明建立必要資源。
建立 GKE 叢集和節點集區
您可以在 GKE Autopilot 或 Standard 叢集的 GPU 上提供 Gemma 服務。建議您使用 Autopilot 叢集，享受全代管 Kubernetes 體驗。如要為工作負載選擇最合適的 GKE 作業模式，請參閱「選擇 GKE 作業模式」。
Autopilot
在 Cloud Shell 中執行下列指令：
gcloud container clusters create-auto CLUSTER_NAME \
--project=PROJECT_ID \
--region=REGION \
--release-channel=rapid
替換下列值：
PROJECT_ID：您的 Google Cloud 專案 ID。REGION：支援您要使用的加速器類型，例如 L4 GPU 的us-central1。CLUSTER_NAME：叢集名稱。
GKE 會根據部署的工作負載要求，建立含 CPU 和 GPU 節點的 Autopilot 叢集。
標準
在 Cloud Shell 中執行下列指令，建立 Standard 叢集：
gcloud container clusters create CLUSTER_NAME \ --project=PROJECT_ID \ --region=REGION \ --workload-pool=PROJECT_ID.svc.id.goog \ --release-channel=rapid \ --num-nodes=1替換下列值：
PROJECT_ID：您的 Google Cloud 專案 ID。REGION：支援您要使用的加速器類型，例如 L4 GPU 的us-central1。CLUSTER_NAME：叢集名稱。
建立叢集可能需要幾分鐘的時間。
如要為叢集建立節點集區，並設定適當的磁碟大小，請執行下列指令：
Gemma 3 1B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-8 \ --num-nodes=1GKE 會為每個節點建立一個包含 L4 GPU 的節點集區。
Gemma 3 4B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-8 \ --num-nodes=1GKE 會為每個節點建立一個包含 L4 GPU 的節點集區。
Gemma 3 12B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=4,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-48 \ --num-nodes=1GKE 會為每個節點建立一個節點集區，內含四個 L4 GPU。
Gemma 3 27B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-a100-80gb,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=a2-ultragpu-1g \ --disk-type=pd-ssd \ --num-nodes=1 \ --disk-size=256GKE 會建立一個節點集區，其中包含一個 A100 80GB GPU。
為 Hugging Face 憑證建立 Kubernetes 密鑰
在 Cloud Shell 中執行下列操作：
設定
kubectl，以便與叢集通訊：gcloud container clusters get-credentials CLUSTER_NAME \ --location=REGION替換下列值：
REGION：支援您要使用的加速器類型，例如 L4 GPU 的us-central1。CLUSTER_NAME：叢集名稱。
建立包含 Hugging Face 權杖的 Kubernetes Secret：
kubectl create secret generic hf-secret \ --from-literal=hf_api_token=${HF_TOKEN} \ --dry-run=client -o yaml | kubectl apply -f -將
HF_TOKEN換成您稍早產生的 Hugging Face 權杖。
部署 vLLM
在本節中，您會部署 vLLM 容器，以提供要使用的 Gemma 模型。本教學課程會使用 Kubernetes Deployment 部署模型。Deployment 是 Kubernetes API 物件，可讓您執行多個 Pod 副本，並將這些副本分散到叢集的節點中。
Gemma 3 1B-it
請按照下列操作說明部署 Gemma 3 1B 指令微調模型 (僅限文字輸入)。
建立下列
vllm-3-1b-it.yaml資訊清單：套用資訊清單：
kubectl apply -f vllm-3-1b-it.yaml
Gemma 3 4B-it
請按照下列操作說明部署 Gemma 3 4B 指令微調模型。
建立下列
vllm-3-4b-it.yaml資訊清單：套用資訊清單：
kubectl apply -f vllm-3-4b-it.yaml在我們的範例中，我們使用 vLLM 選項
--max-model-len=32768，將脈絡窗口限制為 32, 000 個詞元。 如要使用更大的脈絡窗口大小 (最多 128K)，請調整資訊清單和節點集區設定，並增加 GPU 容量。
Gemma 3 120 億參數
請按照下列操作說明部署 Gemma 3 12B 指令微調模型。
建立下列
vllm-3-12b-it.yaml資訊清單：套用資訊清單：
kubectl apply -f vllm-3-12b-it.yaml在我們的範例中，我們使用 vLLM 選項
--max-model-len=16384，將內容視窗大小限制為 16K。如要使用較大的脈絡窗口大小 (最多 128K)，請調整資訊清單和節點集區設定，並增加 GPU 容量。
Gemma 3 27B-it
請按照下列操作說明部署 Gemma 3 27B 指令微調模型。
建立下列
vllm-3-27b-it.yaml資訊清單：套用資訊清單：
kubectl apply -f vllm-3-27b-it.yaml在我們的範例中，我們使用 vLLM 選項
--max-model-len=32768，將脈絡窗口大小限制為 32, 000 個詞元。如要使用較大的脈絡窗口大小 (最多 128K)，請調整資訊清單和節點集區設定，並增加 GPU 容量。
叢集中的 Pod 會從 Hugging Face 下載模型權重，並啟動服務引擎。
等待部署作業完成：
kubectl wait --for=condition=Available --timeout=1800s deployment/vllm-gemma-deployment
查看執行中 Deployment 的記錄：
kubectl logs -f -l app=gemma-server
部署資源會下載模型資料。這項程序可能需要幾分鐘才能完成。輸出結果會與下列內容相似：
INFO: Automatically detected platform cuda.
...
INFO [launcher.py:34] Route: /v1/chat/completions, Methods: POST
...
INFO: Started server process [13]
INFO: Waiting for application startup.
INFO: Application startup complete.
Default STARTUP TCP probe succeeded after 1 attempt for container "vllm--google--gemma-3-4b-it-1" on port 8080.
請先確認模型已完全下載，再繼續進行下一個部分。
提供模型
在本節中，您將與模型互動。
設定通訊埠轉送
執行下列指令，設定模型通訊埠轉送：
kubectl port-forward service/llm-service 8000:8000
輸出結果會與下列內容相似：
Forwarding from 127.0.0.1:8000 -> 8000
使用 curl 與模型互動
本節說明如何執行基本冒煙測試，驗證已部署的 Gemma 3 指令微調模型。如果是其他模型，請將 gemma-3-4b-it 替換為對應模型的名稱。
本例說明如何使用純文字輸入內容，測試 Gemma 3 4B 指令微調模型。
在新的終端機工作階段中，使用 curl 與模型對話：
curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemma-3-4b-it",
"messages": [
{
"role": "user",
"content": "Why is the sky blue?"
}
]
}'
輸出看起來類似以下內容：
{
"id": "chatcmpl-e4a2e624bea849d9b09f838a571c4d9e",
"object": "chat.completion",
"created": 1741763029,
"model": "google/gemma-3-4b-it",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"reasoning_content": null,
"content": "Okay, let's break down why the sky appears blue! It's a fascinating phenomenon rooted in physics, specifically something called **Rayleigh scattering**. Here's the explanation: ...",
"tool_calls": []
},
"logprobs": null,
"finish_reason": "stop",
"stop_reason": 106
}
],
"usage": {
"prompt_tokens": 15,
"total_tokens": 668,
"completion_tokens": 653,
"prompt_tokens_details": null
},
"prompt_logprobs": null
}
(選用) 透過 Gradio 聊天介面與模型互動
在本節中，您將建構網頁聊天應用程式，與經過指令微調的模型互動。為求簡潔，本節僅說明使用 4B-it 模型的測試方法。
Gradio 是 Python 程式庫，內含 ChatInterface 包裝函式，可為聊天機器人建立使用者介面。
部署即時通訊介面
在 Cloud Shell 中，將下列資訊清單儲存為
gradio.yaml。將google/gemma-2-9b-it變更為google/gemma-3-4b-it，或您在部署中使用的其他 Gemma 3 模型名稱。套用資訊清單：
kubectl apply -f gradio.yaml等待部署作業完成：
kubectl wait --for=condition=Available --timeout=900s deployment/gradio
使用即時通訊介面
在 Cloud Shell 中執行下列指令：
kubectl port-forward service/gradio 8080:8080這項操作會建立從 Cloud Shell 到 Gradio 服務的通訊埠轉送。
按一下 Cloud Shell 工作列右上方的「Web Preview」
按鈕。按一下「透過以下通訊埠預覽：8080」。瀏覽器會開啟新分頁。使用 Gradio 對話介面與 Gemma 互動。新增提示，然後按一下「提交」。
排解問題
- 如果收到
Empty reply from server訊息，表示容器可能尚未完成下載模型資料。再次檢查 Pod 的記錄，確認是否有Connected訊息，表示模型已準備好提供服務。 - 如果看到
Connection refused，請確認連接埠轉送已啟用。
觀察模型成效
如要觀察模型效能，可以使用 Cloud Monitoring 中的 vLLM 資訊主頁整合功能。您可以在這個資訊主頁中查看重要成效指標，例如權杖輸送量、要求延遲時間和錯誤率。
如要使用 vLLM 資訊主頁，您必須在 GKE 叢集中啟用 Google Cloud Managed Service for Prometheus，該服務會收集 vLLM 的指標。vLLM 預設會以 Prometheus 格式匯出指標，因此您不需要安裝其他匯出工具。
接著，您可以使用 vLLM 資訊主頁查看指標。如要瞭解如何使用 Google Cloud Managed Service for Prometheus 收集模型指標，請參閱 Cloud Monitoring 說明文件中的 vLLM 可觀測性指南。清除所用資源
如要避免系統向您的 Google Cloud 帳戶收取本教學課程中所用資源的相關費用，請刪除含有該項資源的專案，或者保留專案但刪除個別資源。
刪除已部署的資源
如要避免系統向您的 Google Cloud 帳戶收取本指南所建立資源的費用，請執行下列指令：
gcloud container clusters delete CLUSTER_NAME \
--region=REGION
替換下列值：
REGION：支援您要使用的加速器類型，例如 L4 GPU 的us-central1。CLUSTER_NAME：叢集名稱。
後續步驟
- 進一步瞭解 GKE 中的 GPU。
- 如要瞭解如何在其他加速器 (包括 A100 和 H100 GPU) 上使用 vLLM 搭配 Gemma，請查看 GitHub 中的範例程式碼。
- 瞭解如何在 Autopilot 中部署 GPU 工作負載。
- 瞭解如何在 Standard 中部署 GPU 工作負載。
- 探索 vLLM GitHub 存放區和說明文件。
- 探索 Vertex AI Model Garden。
- 瞭解如何運用 GKE 平台的自動化調度管理功能，執行最佳化的 AI/機器學習工作負載。