在 GKE 上使用 vLLM 執行 gpt-oss-120b 推論

叢集式 GPU

本教學課程說明如何使用 vLLM 架構部署及提供 gpt-oss-120b 語言模型。您會在 Google Kubernetes Engine (GKE) Autopilot 叢集上部署這個模型，並使用配備 8 個 B200 GPU 的單一 A4 虛擬機器 (VM)。

重要事項： 如要完成本教學課程，您必須預留容量來建立 A4 VM。如要進一步瞭解如何在 AI Hypercomputer 預留未來日期和時間的運算資源，請參閱「選擇計費模式」。

本教學課程適用於機器學習 (ML) 工程師、平台管理員和操作員，以及有興趣使用 Kubernetes 容器自動化調度管理功能處理推論工作負載的資料和 AI 專家。

目標

1. 使用 Hugging Face 存取 gpt-oss-120b。
2. 準備環境。
3. 在 Autopilot 模式中建立 GKE 叢集。
4. 為 Hugging Face 憑證建立 Kubernetes Secret。
5. 建立 Cloud Storage bucket。
6. 將模型下載至 Cloud Storage bucket。
7. 將 vLLM 容器部署至 GKE 叢集。
8. 使用 curl 與 gpt-oss 語言模型互動。
9. 清除所用資源。

費用

本教學課程使用 Google Cloud的計費元件，包括：

• GKE 定價
• Cloud GPU 定價

您可以使用 Pricing Calculator，根據預測用量估算費用。

事前準備

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎 建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

• 選取專案：選取專案時，不需具備特定 IAM 角色，只要您在專案中獲派角色，即可選取該專案。
• 建立專案：如要建立專案，您必須具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，不要選取現有專案。如果採用這種做法，當您完成這些步驟後，就可以直接刪除該專案，並移除相關聯的所有資源。

• 建立 Google Cloud 專案：

  gcloud projects create PROJECT_ID

  將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

• 選取您建立的 Google Cloud 專案：

  gcloud config set project PROJECT_ID

  將 PROJECT_ID 替換為 Google Cloud 專案名稱。

確認 Google Cloud 專案已啟用計費功能。

啟用必要的 API (如果尚未啟用)：

啟用 API 所需的角色

如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過服務使用情形管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

gcloud services enable container.googleapis.com

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

• 選取專案：選取專案時，不需具備特定 IAM 角色，只要您在專案中獲派角色，即可選取該專案。
• 建立專案：如要建立專案，您必須具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，不要選取現有專案。如果採用這種做法，當您完成這些步驟後，就可以直接刪除該專案，並移除相關聯的所有資源。

• 建立 Google Cloud 專案：

  gcloud projects create PROJECT_ID

  將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

• 選取您建立的 Google Cloud 專案：

  gcloud config set project PROJECT_ID

  將 PROJECT_ID 替換為 Google Cloud 專案名稱。

確認 Google Cloud 專案已啟用計費功能。

啟用必要的 API (如果尚未啟用)：

啟用 API 所需的角色

如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過服務使用情形管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

gcloud services enable container.googleapis.com

1. 將角色授予使用者帳戶。針對下列各個 IAM 角色執行下列指令一次：roles/container.admin

   gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

   更改下列內容：

   • PROJECT_ID：專案 ID。
   • USER_IDENTIFIER：使用者帳戶 ID。 例如：[e-mail]。
   • ROLE：授予使用者帳戶的 IAM 角色。
2. 登入或建立 Hugging Face 帳戶。

使用 Hugging Face 存取 gpt-oss

如要透過 Hugging Face 存取 gpt-oss，請按照下列步驟操作：

1. 登入 Hugging Face 並探索 gpt-oss 模型。
2. 建立 Hugging Face read 存取權杖。
3. 複製並儲存 read access 權杖值。本教學課程稍後會用到。

準備環境

如要準備環境，請設定預設環境變數：

export PROJECT_ID="YOUR_PROJECT_ID"
export RESERVATION_URL="YOUR_RESERVATION_NAME"
export REGION="YOUR_REGION"
export CLUSTER_NAME="YOUR_CLUSTER_NAME"
export GCS_BUCKET="YOUR_GCS_BUCKET"
export HUGGING_FACE_TOKEN="YOUR_HF_TOKEN"
export NETWORK="YOUR_NETWORK_NAME"
export SUBNETWORK="YOUR_SUBNETWORK_NAME"
export PROJECT_NUMBER=$(gcloud projects describe "${PROJECT_ID}" --format="value(projectNumber)")

gcloud config set project "${PROJECT_ID}"
gcloud config set billing/quota_project "${PROJECT_ID}"

更改下列內容：

• YOUR_PROJECT_ID：要建立 GKE 叢集的 Google Cloud 專案 ID。

• YOUR_RESERVATION_NAME：要用來建立 GKE 叢集的預留項目網址。根據預留項目所在的專案，指定下列其中一個值：

  • 專案中已有預留項目：RESERVATION_NAME

  • 預留項目位於其他專案，且您的專案可以使用該預留項目： projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME

• YOUR_REGION：要建立 GKE 叢集的區域。您只能在預留項目所在的區域建立叢集。

• YOUR_CLUSTER_NAME：要建立的 GKE 叢集名稱。

• YOUR_GCS_BUCKET：下載模型的 Cloud Storage bucket 名稱。

• YOUR_HF_TOKEN：您在上一節建立的 Hugging Face 存取權杖。

• YOUR_NETWORK_NAME：GKE 叢集使用的網路。指定下列其中一個值：

  • 如果您建立了自訂網路，請指定網路名稱。

  • 否則，請指定 default。

• YOUR_SUBNETWORK_NAME：GKE 叢集使用的子網路。指定下列其中一個值：

  • 如果您建立了自訂子網路，請指定子網路名稱。您只能指定與預留項目位於相同區域的子網路。

  • 否則，請指定 default。

在 Autopilot 模式中建立 GKE 叢集

如要在 Autopilot 模式中建立 GKE 叢集，請執行下列指令：

gcloud container clusters create-auto $CLUSTER_NAME \
    --project=$PROJECT_ID \
    --region=$REGION \
    --release-channel=rapid \
    --network=$NETWORK \
    --subnetwork=$SUBNETWORK

GKE 叢集建立作業可能需要一段時間才能完成。如要確認 Google Cloud 已完成建立叢集，請前往 Google Cloud 控制台的「Kubernetes clusters」(Kubernetes 叢集)。

建立 Hugging Face 憑證的 Kubernetes Secret

如要為 Hugging Face 憑證建立 Kubernetes Secret，請按照下列步驟操作：

1. 設定 kubectl 與 GKE 叢集通訊：

   gcloud container clusters get-credentials $CLUSTER_NAME \
       --location=$REGION

2. 建立 Kubernetes Secret 來儲存 Hugging Face 權杖：

   kubectl create secret generic hf-secret \
       --from-literal=hf_token=${HUGGING_FACE_TOKEN} \
       --dry-run=client -o yaml | kubectl apply -f -

建立 Cloud Storage bucket

如果您使用的是現有 Cloud Storage bucket，請確認符合下列條件：

• Cloud Storage bucket 與 GKE 叢集位於相同區域。
• 您的服務帳戶具備 bucket 的必要 write 權限。

如要將模型儲存在新的 Cloud Storage bucket，請完成下列步驟：

1. 執行下列指令來建立 bucket：

   gcloud storage buckets create gs://$GCS_BUCKET --location=$REGION --uniform-bucket-level-access

2. 將 Cloud Storage bucket 的 write 權限授予預設服務帳戶。

   gcloud storage buckets add-iam-policy-binding gs://$GCS_BUCKET \
       --member="principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$PROJECT_ID.svc.id.goog/subject/ns/default/sa/default" \
       --role="roles/storage.objectAdmin"

將模型下載至 Cloud Storage bucket

如要將模型下載到 Cloud Storage bucket，請完成下列步驟：

1. 建立 gpt-download-job.yaml 檔案：

   apiVersion: batch/v1
   kind: Job
   metadata:
     name: gpt-download-job
     namespace: default
   spec:
     template:
       metadata:
         labels:
           app: gpt-oss-downloader
         annotations:
           gke-gcsfuse/volumes: "true"
       spec:
         restartPolicy: OnFailure
         containers:
         - name: downloader
           image: python:3.11-slim
           resources:
             requests:
               cpu: "4"
               memory: "16Gi"
             limits:
               cpu: "4"
               memory: "16Gi"
           env:
           - name: HUGGING_FACE_HUB_TOKEN
             valueFrom:
               secretKeyRef:
                 name: hf-secret
                 key: hf_token
           - name: HF_HUB_ENABLE_HF_TRANSFER
             value: "0"
           - name: HF_HOME
             value: "/tmp/hf_cache"
           command: ["/bin/sh", "-c"]
           args:
           - |
             echo "Installing Hugging Face Hub library..."
             pip install -U "huggingface_hub"
   
             echo "Beginning model snapshot download to GCS Fuse..."
             hf download openai/gpt-oss-120b \
               --token "$HUGGING_FACE_HUB_TOKEN" \
               --local-dir /mnt/gcs/gpt-oss-120b \
               --max-workers 1
   
             DOWNLOAD_STATUS=$?
   
             if [ $DOWNLOAD_STATUS -eq 0 ]; then
               echo "Download Complete!"
             else 
               echo "ERROR: Model download failed with exit code $DOWNLOAD_STATUS"
               exit $DOWNLOAD_STATUS
             fi
   
           volumeMounts:
           - mountPath: /mnt/gcs
             name: gcs-bucket-volume
         volumes:
         - name: gcs-bucket-volume
           csi:
             driver: gcsfuse.csi.storage.gke.io
             volumeAttributes:
               bucketName: $GCS_BUCKET
               mountOptions: "implicit-dirs"

2. 如要初始化下載工作，請套用 gpt-download-job.yaml 資訊清單。

   envsubst '$GCS_BUCKET' < gpt-download-job.yaml | kubectl apply -f -

   工作資源會將 gpt-oss-120b 模型權重從 Hugging Face 下載至 Cloud Storage bucket。下載作業約需 30 分鐘才能完成。下載完成後，請前往下一節啟動模型部署作業。

3. 執行下列指令，查看完成狀態：

   kubectl wait \
       --for=condition=Complete \
       --timeout=7200s job/gpt-download-job

   --timeout 旗標會指定指令監控工作的時間長度，超過這個時間就會逾時。

4. 如要刪除工作，請執行下列指令：

   kubectl delete job gpt-download-job

將 vLLM 容器部署至 GKE 叢集

將模型下載至 Cloud Storage bucket 後，請將 vLLM 容器部署至 GKE 叢集：

1. 使用所選 vLLM 部署作業建立 vllm-gpt-oss-120b.yaml 檔案：

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: vllm-gpt-oss-deployment
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: gpt-oss
     template:
       metadata:
         labels:
           app: gpt-oss
           ai.gke.io/model: gpt-oss-120b
           ai.gke.io/inference-server: vllm
           examples.ai.gke.io/source: user-guide
         annotations:
           gke-gcsfuse/volumes: "true"
       spec:
         containers:
         - name: vllm-inference
           image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:20250822_0916_RC01
           resources:
             requests:
               cpu: "10"
               memory: "128Gi"
               ephemeral-storage: "240Gi"
               nvidia.com/gpu: "8"
             limits:
               cpu: "10"
               memory: "128Gi"
               ephemeral-storage: "240Gi"
               nvidia.com/gpu: "8"
           command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
           args:
           - --model=/mnt/gcs/gpt-oss-120b
           - --tensor-parallel-size=8
           - --host=0.0.0.0
           - --port=8000
           - --max-model-len=8192
           - --max-num-seqs=4
           volumeMounts:
           - mountPath: /dev/shm
             name: dshm
           - mountPath: /mnt/gcs
             name: gcs-bucket-volume
             readOnly: true
           livenessProbe:
             httpGet:
               path: /health
               port: 8000
             initialDelaySeconds: 900
             periodSeconds: 10
           readinessProbe:
             httpGet:
               path: /health
               port: 8000
             initialDelaySeconds: 900
             periodSeconds: 5
         volumes:
         - name: dshm
           emptyDir:
             medium: Memory
         - name: gcs-bucket-volume
           csi:
             driver: gcsfuse.csi.storage.gke.io
             volumeAttributes:
               bucketName: $GCS_BUCKET
               mountOptions: "implicit-dirs,file-cache:max-size-mb:-1,file-cache:enable-parallel-downloads:true,file-cache:max-parallel-downloads:32,file-cache:parallel-downloads-per-file:8,file-cache:download-chunk-size-mb:16"
         nodeSelector:
           cloud.google.com/gke-accelerator: nvidia-b200
           cloud.google.com/reservation-name: $RESERVATION_URL
           cloud.google.com/reservation-affinity: "specific"
           cloud.google.com/gke-gpu-driver-version: latest
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: oss-service
   spec:
     selector:
       app: gpt-oss
     type: ClusterIP
     ports:
     - protocol: TCP
       port: 8000
       targetPort: 8000
   ---
   apiVersion: monitoring.googleapis.com/v1
   kind: PodMonitoring
   metadata:
     name: vllm-gpt-oss-monitoring
   spec:
     selector:
       matchLabels:
         app: gpt-oss
     endpoints:
     - port: 8000
       path: /metrics
       interval: 30s

2. 將 vllm-gpt-oss-120b.yaml 檔案套用至 GKE 叢集：

   envsubst < vllm-gpt-oss-120b.yaml | kubectl apply -f -

3. 執行下列指令，查看完成狀態：

   kubectl wait \
       --for=condition=Available \
       --timeout=7200s deployment/vllm-gpt-oss-deployment

   --timeout 旗標可讓指令在指定時間內監控部署作業。

使用 curl 與 gpt-oss 模型互動

如要驗證部署的 gpt-oss 模型，請按照下列步驟操作：

1. 設定通訊埠轉送至 gpt-oss 模型：

   kubectl port-forward service/oss-service 8000:8000

2. 開啟新的終端機視窗。接著，您可以使用 curl 與模型對話：

   curl http://127.0.0.1:8000/v1/chat/completions \
   -X POST \
   -H "Content-Type: application/json" \
   -d '{
     "model": "openai/gpt-oss-120b",
     "messages": [
       {
         "role": "user",
         "content": "Describe a sailboat in one short sentence?"
       }
     ]
   }' | jq .

3. 您會看到類似下方的輸出內容：

   {
     "id": "chatcmpl-2235c39759c040daae23ce2addc40c0a",
     "object": "chat.completion",
     "created": 1756831629,
     "model": "openai/gpt-oss-120b",
     "choices": [
       {
         "index": 0,
         "message": {
           "role": "assistant",
           "content": "A sleek vessel gliding on water, its cloth sails billowing like captured wind.",
           "refusal": null,
           "annotations": null,
           "audio": null,
           "function_call": null,
           "tool_calls": [],
           "reasoning_content": "User asks: \"Describe a sailboat in one short sentence?\" We need to produce a short sentence description. Should comply with policy. It's fine. Provide a short sentence."
         },
         "logprobs": null,
         "finish_reason": "stop",
         "stop_reason": null
       }
     ],
     "service_tier": null,
     "system_fingerprint": null,
     "usage": {
       "prompt_tokens": 80,
       "total_tokens": 142,
       "completion_tokens": 62,
       "prompt_tokens_details": null
     },
     "prompt_logprobs": null,
     "kv_transfer_params": null
   }
   

觀察模型效能

如要觀察模型效能，可以使用 Cloud Monitoring 中的 vLLM 資訊主頁整合功能。這個資訊主頁可協助您查看模型的關鍵成效指標，例如詞元處理量、網路延遲時間和錯誤率。詳情請參閱 Monitoring 說明文件中的「vLLM」。

清除所用資源

為避免因為本教學課程所用資源，導致系統向 Google Cloud 帳戶收取費用，請刪除含有相關資源的專案，或者保留專案但刪除個別資源。

刪除資源

完成教學課程後，請刪除不再需要的資源。

1. 如要從 GKE 叢集刪除 vllm-gpt-oss-120b.yaml 檔案中定義的 Deployment 和 Service，以及 Kubernetes 密鑰，請執行下列指令：

   envsubst < vllm-gpt-oss-120b.yaml | kubectl delete -f -
   kubectl delete secret hf-secret

2. 如要刪除 Cloud Storage bucket，請執行下列指令：

   gcloud storage rm --recursive gs://$GCS_BUCKET

3. 如要刪除 GKE 叢集，請按照下列步驟操作：

   gcloud container clusters delete $CLUSTER_NAME \
       --region=$REGION \
       --quiet

刪除專案

注意：刪除專案會造成以下影響：

• 專案中的所有內容都會遭到刪除。如果使用現有專案來進行本文中的任務，刪除專案將一併移除當中已完成的其他任務'。
• 自訂專案 ID 會消失。當您之前建立這個專案時，可能建立了想要在日後使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (例如 appspot.com 網址)，請刪除在該專案中選取的資源，而不是刪除整個專案。

如果打算探索多種架構、教學課程或快速入門導覽課程，重複使用專案可避免超出專案配額限制。

刪除 Google Cloud 專案：

gcloud projects delete PROJECT_ID

後續步驟

• 管理 AI 最佳化 GKE 叢集
• 瞭解 AI 和機器學習工作負載的建議儲存空間服務