在 GKE 上使用 TPU v6e 的 vLLM TorchTPU 提供 Qwen3-30B-A3B

本教學課程說明如何使用單一主機 TPU v6e (Trillium) 加速器和 vLLM TPU 服務框架搭配 TorchTPU (torchtpu),在 Google Kubernetes Engine (GKE) 上部署及提供專家混合模型 Qwen3-30B-A3B (Qwen/Qwen3-30B-A3B-FP8)。您會在單一 ct6e-standard-4t 節點上執行工作負載,該節點包含四個 TPU v6e 晶片,採用 2x2 拓撲,並啟用資料平行處理和專家平行處理。

如要在 TPU7x (Ironwood) 加速器上,使用較大的 Qwen3.5-397B 模型執行類似的單一主機 vLLM TorchTPU 服務工作流程,請參閱「在 GKE 上使用 TPU7x 加速器上的 vLLM TorchTPU 提供 Qwen3.5-397B 服務」。

目標

  • 設定 GKE 叢集和單一主機 TPU v6e 節點集區。
  • 在 GKE 部署單一主機 vLLM TorchTPU 伺服器。
  • 向 vLLM TorchTPU 伺服器傳送推論要求。
  • 執行基準測試工作負載。
  • 清除所用資源。

費用

在本文件中,您會使用下列Google Cloud計費元件:

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

完成本文所述工作後,您可以刪除建立的資源,避免繼續計費,詳情請參閱「清除所用資源」一節。

事前準備

為教學課程設定環境:

取得 Hugging Face 存取權杖

您需要 Hugging Face 存取權杖,才能使用本教學課程。您可以在 Hugging Face 註冊免費帳戶。建立帳戶後,請產生存取權杖:

  1. 在「Welcome to Hugging Face」(歡迎使用 Hugging Face) 頁面,點選帳戶顯示圖片,然後選取「Access tokens」(存取權杖)。
  2. 在「存取權杖」頁面,點選「建立新權杖」。
  3. 選取「Read」權杖類型,並輸入權杖名稱。
  4. 系統會顯示存取權杖。將權杖儲存在安全的地方。

必要的角色

如要取得完成本教學課程所需的權限,請要求管理員在專案中授予您下列 IAM 角色:

如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色,取得必要權限。

設定環境變數

設定驗證機制:

gcloud auth login
gcloud auth application-default login

設定環境變數:

export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION" # for example, us-central1
export ZONE="YOUR_ZONE" # for example, us-central1-b
export CLUSTER_NAME="YOUR_CLUSTER_NAME" # maximum 40 chars; start with a-z; only a-z, 0-9, -
export MACHINE_TYPE="ct6e-standard-4t"
export NODE_POOL_NAME="np-0"
export RESERVATION_NAME="YOUR_RESERVATION_NAME"
export HF_TOKEN="YOUR_HF_TOKEN"
export NETWORK="YOUR_NETWORK_NAME"
export SUBNETWORK="YOUR_SUBNETWORK_NAME"
export VLLM_IMAGE="vllm/vllm-torchtpu:v0.29.0@sha256:3976ccc1a69ffd361e0a7d2831fe317f6b685636014f426321a39ae02f8da0dc"

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

更改下列內容:

  • YOUR_PROJECT_ID: Google Cloud專案的 ID。
  • YOUR_REGION:容量所在及要部署叢集的區域,例如 us-central1。
  • YOUR_ZONE:容量所在及要部署 TPU v6e 節點集區的可用區,例如 us-central1-c。
  • YOUR_CLUSTER_NAME:GKE 叢集的名稱,例如 tpu-v6e-tutorial-cluster。名稱長度不得超過 40 個字元,開頭須為小寫英文字母,且只能使用小寫英文字母、數字和連字號。
  • YOUR_RESERVATION_NAME:如果使用預留項目,請提供 TPU v6e 預留項目的名稱。
  • YOUR_HF_TOKEN:您的 Hugging Face 存取權杖。
  • YOUR_NETWORK_NAME:Google Cloud 網路的名稱。如果您建立了自訂網路,請指定該網路。否則,請指定 default。
  • YOUR_SUBNETWORK_NAME:Google Cloud 子網路的名稱。如果您建立了自訂子網路,請指定該子網路。否則,請指定 default。

如果您使用自訂 vLLM TorchTPU 容器映像檔,請將 VLLM_IMAGE 變數中的預設 vllm/vllm-torchtpu 映像檔 URI 替換為您的映像檔 URI。如需公開映像檔,請參閱 vLLM TorchTPU 存放區。

建立 GKE 叢集

如要以 Standard 模式建立 GKE 叢集,並連結單一主機 TPU v6e 節點集區,請完成下列步驟:

  1. 建立區域性 GKE 叢集:

    gcloud container clusters create "${CLUSTER_NAME}" \
        --project="${PROJECT_ID}" \
        --location="${REGION}" \
        --machine-type=e2-standard-4 \
        --network="${NETWORK}" \
        --subnetwork="${SUBNETWORK}"

    GKE 叢集的預設機器類型 (e2-medium) 沒有足夠的 CPU 容量來執行工作負載控制器,因此這個指令會指定 e2-standard-4。

    輸出結果會與下列內容相似:

    NAME                      LOCATION     MASTER_VERSION      MASTER_IP      MACHINE_TYPE   NODE_VERSION        NUM_NODES  STATUS
    tpu-v6e-tutorial-cluster  us-central1  1.35.7-gke.1027000  34.63.222.246  e2-standard-4  1.35.7-gke.1027000  3          RUNNING
    
  2. 使用預留項目,建立含有一個 ct6e-standard-4t 節點 (2x2 拓撲中的四個 TPU v6e 晶片) 的單一主機 TPU v6e 節點集區:

    gcloud container node-pools create "${NODE_POOL_NAME}" \
        --cluster="${CLUSTER_NAME}" \
        --machine-type="${MACHINE_TYPE}" \
        --location="${REGION}" \
        --node-locations="${ZONE}" \
        --project="${PROJECT_ID}" \
        --num-nodes=1 \
        --reservation-affinity=specific \
        --reservation="${RESERVATION_NAME}"

    除了使用特定預留項目,您也可以使用 Spot 運算資源或彈性啟動型 VM 建立節點集區,只要將 --reservation-affinity 和 --reservation 旗標替換為下列旗標即可:

    • Spot VM:如要使用 Spot 容量佈建節點集區,請傳遞 --spot 旗標。使用 Spot 容量的執行個體可能需要一些時間才能建立,且在節點集區建立後,在工作負載執行期間可能會遭到先占。如果 Pod 需要一段時間才能建立,或工作負載在執行期間停止,可能就是這個原因。
    • 彈性啟動型 VM:如要使用彈性啟動用量方案佈建節點集區,請傳遞 --flex-start 旗標。詳情請參閱「使用 TPU 和彈性啟動 VM 執行小型批次工作負載」。

    輸出結果會與下列內容相似:

    NAME  MACHINE_TYPE      DISK_SIZE_GB  NODE_VERSION
    np-0  ct6e-standard-4t  100           1.35.7-gke.1027000
    
  3. 設定 kubectl 憑證,以便與叢集通訊:

    gcloud container clusters get-credentials "${CLUSTER_NAME}" \
        --location="${REGION}" \
        --project="${PROJECT_ID}"

設定憑證

建立名為 hf-secret 的 Kubernetes Secret,用於儲存 Hugging Face 存取權杖:

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

部署 vLLM TorchTPU 伺服器

工作負載資訊清單 (qwen3_server.yaml) 定義下列資源:

  • StorageClass (hyperdisk-balanced-qwen3) 和 500 GiB PersistentVolumeClaim (hd-claim-qwen3),由 Google Cloud Hyperdisk Balanced 儲存空間支援,用於儲存下載的模型權重。

  • Deployment (vllm-qwen3) 排定在單一 TPU v6e 節點上,採用 2x2 拓撲 (google.com/tpu: '4')。容器會執行 vllm serve,用於 Qwen/Qwen3-30B-A3B-FP8,並使用下列旗標:

    • --data-parallel-size=4
    • --tensor-parallel-size=1
    • --enable-expert-parallel
    • --kv-cache-dtype=fp8
    • --max-model-len=9236
    • --max-num-seqs=64
  • 公開通訊埠 8000 的 ClusterIP Service (vllm-qwen3-service)。

如要部署及監控工作負載,請完成下列步驟:

  1. 擷取伺服器資訊清單:

    curl -fLO https://raw.githubusercontent.com/GoogleCloudSamples/AIHypercomputerSamples/refs/heads/main/tpu/inference/qwen3-5-397b/qwen3_server.yaml

    或者,您也可以選擇建立名為 qwen3_server.yaml 的檔案,並加入下列內容:

    apiVersion: storage.k8s.io/v1
    kind: StorageClass
    metadata:
      name: hyperdisk-balanced-qwen3
    provisioner: pd.csi.storage.gke.io
    parameters:
      type: hyperdisk-balanced
    reclaimPolicy: Delete
    volumeBindingMode: WaitForFirstConsumer
    allowVolumeExpansion: true
    ---
    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: hd-claim-qwen3
      namespace: default
    spec:
      storageClassName: hyperdisk-balanced-qwen3
      accessModes:
        - ReadWriteOnce
      resources:
        requests:
          storage: 500Gi
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: vllm-qwen3
      namespace: default
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: vllm-qwen3
      template:
        metadata:
          labels:
            app: vllm-qwen3
        spec:
          enableServiceLinks: false
          nodeSelector:
            cloud.google.com/gke-tpu-accelerator: tpu-v6e-slice
            cloud.google.com/gke-tpu-topology: 2x2
          tolerations:
          - key: "cloud.google.com/gke-spot"
            operator: "Equal"
            value: "true"
            effect: "NoSchedule"
          containers:
          - name: vllm-tpu
            image: $VLLM_IMAGE
            command: ["vllm", "serve"]
            args:
            - --host=0.0.0.0
            - --port=8000
            - --model=Qwen/Qwen3-30B-A3B-FP8
            - --tokenizer=Qwen/Qwen3-30B-A3B-FP8
            - --max-model-len=9236
            - --max-num-batched-tokens=1024
            - --max-num-seqs=64
            - --no-enable-prefix-caching
            - --gpu-memory-utilization=0.9
            - --data-parallel-size=4
            - --tensor-parallel-size=1
            - --reasoning-parser=qwen3
            - --async-scheduling
            - --kv-cache-dtype=fp8
            - --enable-expert-parallel
            - --download-dir=/data
            - --block-size=128
            env:
            - name: MODEL_IMPL_TYPE
              value: "vllm"
            - name: DP_SCHED_ENABLED
              value: "1"
            - name: VLLM_ENGINE_READY_TIMEOUT_S
              value: "9600"
            - name: VLLM_ENGINE_ITERATION_TIMEOUT_S
              value: "1800"
            - name: USE_MOE_SPARSE_CORE
              value: "1"
            - name: TPU_MOE_SKIP_PADDED_TOKENS
              value: "1"
            - name: VLLM_CACHE_ROOT
              value: "/data/vllm_cache"
            - name: TORCHINDUCTOR_CACHE_DIR
              value: "/data/torch_compile_cache"
            - name: XLA_CACHE_DIR
              value: "/data/xla_cache"
            - name: HF_HOME
              value: /data
            - name: HF_TOKEN
              valueFrom:
                secretKeyRef:
                  name: hf-secret
                  key: hf_api_token
            ports:
            - containerPort: 8000
            resources:
              limits:
                google.com/tpu: '4'
              requests:
                google.com/tpu: '4'
            startupProbe:
              httpGet:
                path: "/health"
                port: 8000
              periodSeconds: 15
              failureThreshold: 120
            readinessProbe:
              tcpSocket:
                port: 8000
              initialDelaySeconds: 15
              periodSeconds: 10
            volumeMounts:
            - mountPath: "/data"
              name: data-volume
            - mountPath: /dev/shm
              name: dshm
          volumes:
          - emptyDir:
              medium: Memory
            name: dshm
          - name: data-volume
            persistentVolumeClaim:
              claimName: hd-claim-qwen3
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: vllm-qwen3-service
      namespace: default
    spec:
      selector:
        app: vllm-qwen3
      type: ClusterIP
      ports:
      - name: http
        protocol: TCP
        port: 8000
        targetPort: 8000
  2. 將 vLLM TorchTPU 伺服器資訊清單套用至叢集:

    envsubst '$VLLM_IMAGE' < "qwen3_server.yaml" | kubectl apply -f -
  3. 監控伺服器部署記錄,直到應用程式啟動完成:

    kubectl wait --for=condition=Ready pod -l app=vllm-qwen3 --timeout=1800s
    kubectl logs deployment/vllm-qwen3 -c vllm-tpu -f

    如要停止串流記錄,請隨時按下 Control+C 鍵。Pod 下載模型權重並編譯模型時,初始服務啟動作業可能需要約 15 到 30 分鐘。

    如果使用 Spot 或彈性啟動等先占式運算資源,建立節點集區後,可能需要較長時間才能建立 TPU 切片節點,而且這些節點可能會在工作負載執行期間遭到先占。如果 Pod 啟動時間比預期長,或工作負載中途停止,可能就是這個原因。詳情請參閱「Spot VM 先占」。如要確認 TPU 切片節點是否已建立,請參閱「查看節點的狀態和條件」。

    請等到記錄回報 Application startup complete 後,再傳送流量:

    (APIServer pid=1) INFO:     Started server process [1]
    (APIServer pid=1) INFO:     Waiting for application startup.
    (APIServer pid=1) INFO:     Application startup complete.
    
  4. 開啟第二個終端機工作階段。

  5. 在第二個終端機工作階段中,將本機通訊埠 8000 轉送至 vllm-qwen3-service:

    kubectl port-forward service/vllm-qwen3-service 8000:8000

    讓通訊埠轉送功能在這個終端機工作階段中保持運作。

傳送推論要求

返回第一個終端機工作階段,並將對話完成要求傳送至 /v1/chat/completions 端點:

curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen3-30B-A3B-FP8",
        "messages": [
            {"role": "user", "content": "Hello! Tell me a joke."}
        ],
        "max_tokens": 512,
        "temperature": 0.7
    }' | jq .

執行基準工作負載

如要使用 InferenceX 基準套件,以 8,192 個詞元的輸入和 1,024 個詞元的輸出 (8k/1k) 工作負載,對部署的 Qwen3-30B-A3B 模型進行基準測試,請完成下列步驟:

  1. 擷取基準測試資訊清單:

    curl -fLO https://raw.githubusercontent.com/GoogleCloudSamples/AIHypercomputerSamples/refs/heads/main/tpu/inference/qwen3-5-397b/qwen3-benchmark-8k1k.yaml

    或者,您也可以建立名為 qwen3-benchmark-8k1k.yaml 的檔案,並在其中加入下列內容:

    apiVersion: v1
    kind: Pod
    metadata:
      name: qwen3-bench-8k1k
      namespace: default
    spec:
      restartPolicy: OnFailure
      terminationGracePeriodSeconds: 60
      containers:
      - name: vllm-bench
        image: $VLLM_IMAGE
        command: ["/bin/bash", "-c"]
        args:
        - |
          while ! curl -sf http://vllm-qwen3-service:8000/health > /dev/null; do sleep 30 && echo 'Waiting for server...'; done
          if ! command -v git >/dev/null 2>&1; then apt-get update && apt-get install -y git; fi && \
          git clone https://github.com/SemiAnalysisAI/InferenceX.git /ubench/inferencex && \
          cd /ubench/inferencex && \
          git checkout 89ce6098ef2bc4576a735c43f39c7d972b091cfc && \
          python3 /ubench/inferencex/utils/bench_serving/benchmark_serving.py \
            --backend=vllm \
            --percentile-metrics='ttft,tpot,itl,e2el' \
            --host=vllm-qwen3-service \
            --port=8000 \
            --model=Qwen/Qwen3-30B-A3B-FP8 \
            --tokenizer=Qwen/Qwen3-30B-A3B-FP8 \
            --dataset-name=random \
            --random-input-len=8192 \
            --random-output-len=1024 \
            --random-range-ratio=1.0 \
            --num-prompts=2560 \
            --num-warmups=512 \
            --max-concurrency=256 \
            --ignore-eos
        env:
        - name: VLLM_PLUGINS
          value: ""
        - name: VLLM_TARGET_DEVICE
          value: "cpu"
        - name: JAX_PLATFORMS
          value: "cpu"
        - name: PYTHONUNBUFFERED
          value: "1"
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              key: hf_api_token
              name: hf-secret
  2. 套用基準測試 Pod 資訊清單:

    envsubst '$VLLM_IMAGE' < "qwen3-benchmark-8k1k.yaml" | kubectl apply -f -
  3. 監控基準記錄:

    kubectl wait --for=jsonpath='{.status.phase}'=Running pod/qwen3-bench-8k1k --timeout=600s
    kubectl logs -f qwen3-bench-8k1k

    基準測試約需 25 到 30 分鐘才能完成。基準工作負載開始執行後,可能要等到執行完畢才會產生輸出記錄。

  4. 基準測試完成後,請尋找包含下列指標的輸出內容:

    • Output token throughput
    • Total token throughput
    • TTFT
    • TPOT

清除所用資源

為避免系統持續向您的 Google Cloud 帳戶收取本教學課程所用資源的額外費用,請刪除 Kubernetes 工作負載、TPU 節點集區和 GKE 叢集:

  1. 刪除 vLLM TorchTPU 伺服器 Deployment、Service、PersistentVolumeClaim 和 Hugging Face Secret:

    kubectl delete -f qwen3-benchmark-8k1k.yaml --ignore-not-found || true
    kubectl delete -f qwen3_server.yaml --ignore-not-found || true
    kubectl wait --for=delete pvc/hd-claim-qwen3 --timeout=120s || true
    kubectl delete secret hf-secret --ignore-not-found || true
  2. 刪除 TPU v6e 節點集區和 GKE 叢集:

    gcloud container node-pools delete "${NODE_POOL_NAME}" \
        --cluster="${CLUSTER_NAME}" \
        --location="${REGION}" \
        --project="${PROJECT_ID}" \
        --quiet || true
    
    gcloud container clusters delete "${CLUSTER_NAME}" \
        --location="${REGION}" \
        --project="${PROJECT_ID}" \
        --quiet || true

後續步驟