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

自動駕駛 標準

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

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

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

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

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

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

事前準備

登入 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 the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

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 the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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 the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

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 the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

• 確認您在專案中具備下列角色： roles/artifactregistry.admin、roles/browser、roles/compute.networkAdmin、 roles/container.clusterAdmin、roles/iam.roleAdmin、roles/iam.serviceAccountAdmin、 roles/resourcemanager.projectIamAdmin、roles/serviceusage.serviceUsageAdmin，以及 roles/secretmanager.secretVersionManager

  檢查角色

  1. 前往 Google Cloud 控制台的「IAM」頁面。

     前往「IAM」頁面
  2. 選取專案。

  3. 在「主體」欄中，找出所有識別您或您所屬群組的資料列。如要瞭解自己所屬的群組，請與管理員聯絡。

  4. 針對指定或包含您的所有列，請檢查「角色」欄，確認角色清單是否包含必要角色。

  授予角色

  1. 前往 Google Cloud 控制台的「IAM」頁面。

     前往「IAM」頁面
  2. 選取專案。
  3. 按一下「Grant access」(授予存取權)。

  4. 在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。 這通常是指 Google 帳戶的電子郵件地址。

  5. 按一下「選取角色」，然後搜尋角色。
  6. 如要授予其他角色，請按一下「Add another role」(新增其他角色)，然後新增其他角色。
  7. 按一下「Save」(儲存)。

• 建立 Hugging Face 帳戶。
• 請確認專案有足夠的 GPU 配額。詳情請參閱「分配配額」。

取得模型存取權

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

如要透過 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-vllm-gpu-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 版本，可以執行下列指令碼。這個指令碼會安裝 tfswitch 工具，並在主目錄中安裝 Terraform 1.8.0 版。按照指令碼的指示設定必要的環境變數，或將 --modify-rc-file 旗標傳遞至指令碼。

   "${ACP_REPO_DIR}/tools/bin/install_terraform.sh" && \
   export PATH=${HOME}/bin:${HOME}/.local/bin:${PATH}
   

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 中建立 Secret，用於儲存 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 存放區中的資訊清單。

下載模型

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

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

2. 執行下列指令碼，設定 Hugging Face 模型下載資源，將模型下載至 Cloud Storage：

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

3. 套用 Hugging Face 模型下載資源：

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

4. 監控 Hugging Face 模型下載作業，直到完成為止。

   until kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} wait job/${HF_MODEL_ID_HASH}-hf-model-to-gcs --for=condition=complete --timeout=10s >/dev/null; do
       clear
       kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e 'Complete'
       echo -e "\nhf-model-to-gcs logs(last 10 lines):"
       kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} logs job/${HF_MODEL_ID_HASH}-hf-model-to-gcs --container=hf-model-to-gcs --tail 10
   done
   

5. 確認 Hugging Face 模型下載工作已完成。

   kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e 'Complete'
   

6. 刪除 Hugging Face 模型下載資源。

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

部署模型

1. 從部署作業中取得環境變數。

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

2. 確認已設定 Hugging Face 模型名稱。

   echo "HF_MODEL_NAME=${HF_MODEL_NAME}"
   

3. 設定 vLLM 資源。

   "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/configure_vllm.sh"
   

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

   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. 監控推論工作負載部署作業，直到部署完成為止。

   until kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} wait deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --for=condition=available --timeout=10s >/dev/null; do
       clear
       kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e '1/1     1            1'
       echo -e "\nfetch-safetensors logs(last 10 lines):"
       kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=fetch-safetensors --tail 10
       echo -e "\ninference-server logs(last 10 lines):"
       kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=inference-server --tail 10
   done
   

1. 確認推論工作負載部署作業是否可用。

   kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e '1/1     1            1'
   echo -e "\nfetch-safetensors logs(last 10 lines):"
   kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=fetch-safetensors --tail 10
   echo -e "\ninference-server logs(last 10 lines):"
   kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=inference-server --tail 10
   

2. 執行下列指令碼，設定通訊埠轉送功能，並將範例要求傳送至模型。

   kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} port-forward service/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} 8000:8000 >/dev/null &
   PF_PID=$!
   while ! echo -e '\x1dclose\x0d' | telnet localhost 8000 >/dev/null 2>&1; do
       sleep 0.1
   done
   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. 清理資源：

   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 工具分析模型推論效能和成本。
• 探索用於建構此架構的 accelerated-platforms GitHub 存放區。