本教學課程說明如何使用 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 專家。如要進一步瞭解我們在 Google Cloud 內容中提及的常見角色和範例工作，請參閱「常見的 GKE 使用者角色和工作」。
如果您需要統一管理的 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 說明文件。
取得模型存取權
如要透過 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 \
--location=CONTROL_PLANE_LOCATION \
--release-channel=rapid
替換下列值：
PROJECT_ID：您的 Google Cloud 專案 ID。CONTROL_PLANE_LOCATION：叢集控制層的 Compute Engine 區域。提供支援您要使用加速器類型的區域，例如 L4 GPU 的us-central1。CLUSTER_NAME：叢集名稱。
GKE 會根據部署的工作負載要求，建立含 CPU 和 GPU 節點的 Autopilot 叢集。
標準
在 Cloud Shell 中執行下列指令，建立 Standard 叢集：
gcloud container clusters create CLUSTER_NAME \ --project=PROJECT_ID \ --location=CONTROL_PLANE_LOCATION \ --workload-pool=PROJECT_ID.svc.id.goog \ --release-channel=rapid \ --num-nodes=1替換下列值：
PROJECT_ID：您的 Google Cloud 專案 ID。CONTROL_PLANE_LOCATION：叢集控制層的 Compute Engine 區域。提供支援您要使用加速器類型的區域，例如 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 12B-it
請按照下列操作說明部署 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，請確認連接埠轉送功能是否已啟用。
觀察模型成效
如要查看模型可觀測性指標的資訊主頁，請按照下列步驟操作：
前往 Google Cloud 控制台的「Deployed Models」(已部署模型) 頁面。
如要查看特定部署作業的詳細資料，包括指標、記錄和資訊主頁，請按一下清單中的模型名稱。
在模型詳細資料頁面中，按一下「可觀測性」分頁標籤，即可查看下列資訊主頁。出現提示時，請按一下「啟用」，為叢集啟用指標收集功能。
- 「基礎架構用量」資訊主頁會顯示使用率指標。
- 「DCGM」DCGM資訊主頁會顯示 DCGM 指標。
- 如果您使用 vLLM，系統會提供「模型效能」資訊主頁，並顯示 vLLM 模型效能的指標。
您也可以在Cloud Monitoring 中，透過 vLLM 資訊主頁整合功能查看指標。 這些指標會匯總所有 vLLM 部署作業，且���有預設篩選器
如要在 Cloud Monitoring 中使用資訊主頁，必須在 GKE 叢集中啟用 Google Cloud Managed Service for Prometheus，從 vLLM 收集指標。vLLM 預設會以 Prometheus 格式公開指標，您不需要安裝額外的匯出工具。如要瞭解如何使用 Google Cloud Managed Service for Prometheus 收集模型指標，請參閱 Cloud Monitoring 說明文件中的 vLLM 可觀測性指南。