透過預先設定的架構在 GKE 上提供開放原始碼 LLM

本頁面說明如何使用預先設定的參考架構，在 GKE 上快速部署及提供熱門的開放式大型語言模型 (LLM)，以進行推論。這個方法會使用基礎架構即程式碼 (IaC)，並以 CLI 指令碼包裝 Terraform，建立標準化、安全且可擴充的 GKE 環境，專為 AI 推論工作負載設計。

在本指南中，您將使用 vLLM 服務架構，在 GKE 上透過單一主機 GPU 節點部署及提供 LLM。本指南提供部署下列開放模型的說明和設定：

• Google Gemma 3 27B 位元
• Meta Llama 4 Scout 17B-16E-Instruct
• Qwen3 32-B
• OpenAI gpt-oss-20b

本指南適用於機器學習 (ML) 工程師，以及有興趣探索 Kubernetes 容器調度功能，以提供開放模型進行推論的資料和 AI 專家。如要進一步瞭解 Google Cloud 內容中提及的常見角色和範例工作，請參閱「常見的 GKE 使用者角色和工作」。

如要詳細分析這些開放模型的模型服務效能和費用，也可以使用 GKE Inference Quickstart 工具。如要瞭解詳情，請參閱 GKE 推論快速入門指南和隨附的 Colab 筆記本。

取得模型存取權

注意： 如要使用任何受限模型 (例如 Gemma 或 Llama)，請務必在各自的 Hugging Face 模型頁面上接受授權條款。

如要透過 Hugging Face 存取模型，您需要Hugging Face 權杖。

如要產生新權杖 (如果沒有)，請按照下列步驟操作：

1. 依序點選「Your Profile」(你的個人資料) >「Settings」(設定) >「Access Tokens」(存取權杖)。
2. 選取「New Token」。
3. 指定您選擇的「名稱」，以及至少「讀取」的「角色」。
4. 選取「產生權杖」。
5. 將產生的權杖複製到剪貼簿。

佈建 GKE 推論環境

在本節中，您將部署必要的基礎架構，以便提供模型服務。

啟動 Cloud Shell

本指南使用 Cloud Shell 執行指令。Cloud Shell 已預先安裝必要工具，包括 gcloud、kubectl 和 git。

在 Google Cloud 控制台中，啟動 Cloud Shell 執行個體：

開啟 Cloud Shell

這項操作會在 Google Cloud 控制台的底部窗格啟動工作階段。

部署基礎架構

如要佈建 GKE 叢集和存取 Hugging Face 模型所需的資源，請按照下列步驟操作：

1. 在 Cloud Shell 中，複製下列存放區：

   git clone https://github.com/GoogleCloudPlatform/accelerated-platforms --branch hf-model-tutorial && \
   cd accelerated-platforms && \
   export ACP_REPO_DIR="$(pwd)"
   

2. 設定環境變數：

   export TF_VAR_platform_default_project_id=PROJECT_ID
   export HF_TOKEN_READ=HF_TOKEN
   

   替換下列值：

   • PROJECT_ID：您的 Google Cloud 專案 ID。
   • HF_TOKEN：您先前產生的 Hugging Face 權杖。

3. 本指南需要使用 Terraform 1.8.0 以上版本。Cloud Shell 預設安裝 Terraform v1.5.7。

   如要在 Cloud Shell 中更新 Terraform 版本，可以執行下列指令碼。這個指令碼會安裝 terraform-switcher 工具，並變更殼層環境。

   "${ACP_REPO_DIR}/tools/bin/install_terraform.sh"
   source ~/.bashrc
   

4. 執行下列部署指令碼。部署指令碼會啟用必要的 Google Cloud API，並為本指南佈建必要的基礎架構。包括新的 VPC 網路、具有私有節點的 GKE 叢集，以及其他支援資源。指令碼可能需要幾分鐘才能完成。

   您可以在 GKE Autopilot 或 Standard 叢集中，使用 GPU 提供模型。Autopilot 叢集提供全代管的 Kubernetes 體驗。如要進一步瞭解如何為工作負載選擇最合適的 GKE 作業模式，請參閱「關於 GKE 作業模式」。

   Autopilot

   "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/deploy-ap.sh"
   

   標準

   "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/deploy-standard.sh"
   

   這個指令碼執行完畢後，您就會擁有可執行推論工作負載的 GKE 叢集。

5. 執行下列指令，從共用設定檔設定環境變數：

   source "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/terraform/_shared_config/scripts/set_environment_variables.sh"
   

6. 部署指令碼會在 Secret Manager 中建立密鑰，用來儲存 Hugging Face 權杖。部署叢集前，您必須手動將權杖新增至這個密鑰。在 Cloud Shell 中執行這項指令，將權杖新增至 Secret Manager。

   echo ${HF_TOKEN_READ} | gcloud secrets versions add ${huggingface_hub_access_token_read_secret_manager_secret_name} \
       --data-file=- \
       --project=${huggingface_secret_manager_project_id}
   

部署開放式模型

現在可以下載及部署模型。

1. 為要部署的模型設定環境變數：

   Gemma 3 27B-it

   export ACCELERATOR_TYPE="h100"
   export HF_MODEL_ID="google/gemma-3-27b-it"
   

   Llama 4 Scout 17B-16E-Instruct

   export ACCELERATOR_TYPE="h100"
   export HF_MODEL_ID="meta-llama/llama-4-scout-17b-16e-instruct"
   

   Qwen3 32B

   export ACCELERATOR_TYPE="h100"
   export HF_MODEL_ID="qwen/qwen3-32b"
   

   gpt-oss 20B

   export ACCELERATOR_TYPE="h100"
   export HF_MODEL_ID="openai/gpt-oss-20b"
   

   如需其他設定，包括其他模型變體和 GPU 類型，請參閱 accelerated-platforms GitHub 存放區中的資訊清單。

2. 從部署作業中取得環境變數。這些環境變數包含您佈建基礎架構時的必要設定詳細資料。

   source "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/terraform/_shared_config/scripts/set_environment_variables.sh"
   

3. 執行下列指令碼，設定 Kubernetes 工作，將模型下載至 Cloud Storage：

   "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/configure_huggingface.sh"
   

4. 部署模型下載作業：

   kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/huggingface"
   

5. 等待下載作業完成。監控 Job 的狀態，並在 COMPLETIONS 為 1/1 時按下 Ctrl+C 鍵結束。

   watch --color --interval 5 --no-title "kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs
   

6. 將推論工作負載部署至 GKE 叢集。

   "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/configure_deployment.sh"
   
   kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
   

測試部署作業

1. 等待推論伺服器 Pod 準備就緒。當「�」欄為「�」時，請按 � 鍵退出。READY1/1Ctrl+C

   watch --color --interval 5 --no-title "kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
   

2. 執行下列指令碼，設定通訊埠轉送功能，並將範例要求傳送至模型。本範例使用 Gemma 3 27b-it 模型的酬載格式。

   kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} port-forward service/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} 8000:8000 >/dev/null &
   PF_PID=$!
   curl http://127.0.0.1:8000/v1/chat/completions \
     --data '{
       "model": "/gcs/'${HF_MODEL_ID}'",
       "messages": [ { "role": "user", "content": "What is GKE?" } ]
     }' \
     --header "Content-Type: application/json" \
     --request POST \
     --show-error \
     --silent | jq
   kill -9 ${PF_PID}
   

   模型應會傳回 JSON 回覆，回答您的問題。

清除所用資源

為避免產生費用，請刪除您建立的所有資源。

1. 刪除推論工作負載：

   kubectl delete --ignore-not-found --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
   

2. 移除基礎 GKE 叢集：

   Autopilot

   "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/teardown-ap.sh"
   

   標準

   "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/teardown-standard.sh"
   

後續步驟

• 進一步瞭解 GKE 的 AI/機器學習模型推論功能。
• 使用 GKE Inference Quickstart 工具分析模型推論效能和成本。
• 探索以這個架構為基礎建構的其他用途和模式。