Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

僅限在 Distributed Cloud 軟體參考實作中提供模型服務

總覽

本文是解決方案參考實作 (SRI) 指南，說明部署、提供及驗證僅限 Distributed Cloud 軟體的開放模型服務解決方案時，必須採取的具體步驟。

本指南會實作最佳化 vLLM 服務引擎的部署作業，在 Distributed Cloud 軟體專屬的單一節點叢集設定 (適用於邊緣部署) 上執行 Gemma 4 (google/gemma-4-31B-it)，並使用實體 NVIDIA GPU 資源 (例如 RTX PRO 6000)。

本逐步操作指南旨在透過 CLI 終端機用戶端執行，且kubectl只能存取 Distributed Cloud 軟體專屬叢集。

目標

完成這項解決方案參考實作後，您將：

透過本機 .env 檔案設定服務環境參數。
使用 local-shared 儲存空間類別部署 Persistent Volume Claim (PVC)，以保留模型權重。
部署最佳化 vLLM 服務引擎，運用 Vertex AI 合格容器，對應實體 nvidia.com/gpu 資源。
部署 Gradio 網頁 UI，提供互動式聊天介面。
建立本機通訊埠轉送通道，透過 API 和網頁版使用者介面驗證服務回應。
確認記錄和指標 (包括 GPU 遙測) 已擷取至 Cloud Logging 和 Cloud Monitoring，藉此驗證觀測能力整合。

事前準備

必要條件 (叢集設定)

本指南假設您已設定支援 GPU 的 Distributed Cloud 軟體專屬叢集，並正在執行中。如要安裝叢集，請參閱官方的裸機適用的 Distributed Cloud 軟體說明文件。GPU 設定必須符合 Google Cloud「設定及使用 NVIDIA GPU」的官方說明文件。

設定用戶端工作站的必要步驟

請確認本機終端機環境已安裝並設定下列工具：

gcloud CLI：用於設定專案及查詢記錄。必須經過驗證 (gcloud auth login)，並設定為已註冊 Distributed Cloud 軟體專屬叢集的有效Google Cloud 專案。
kubectl：管理叢集資源時必須使用。必須設定適當的環境，才能存取目標 Distributed Cloud 軟體專屬叢集 (例如透過連線閘道或直接存取本機網路)。
curl：用於將測試要求傳送至服務端點。
jq：用於剖析服務端點的 JSON 輸出內容。

Hugging Face 模型存取權

如要下載及部署 Gemma 4 模型，您必須有權存取 Hugging Face 存放區：

Hugging Face 帳戶：請確認你已在 Hugging Face 註冊帳戶。
接受模型授權：前往 Gemma 4 31B IT 模型頁面，同意授權條款，即可存取受限模型權重。
產生存取權杖： 從 Hugging Face 帳戶設定 (「設定」->「存取權杖」) 產生具有「讀取」權限的使用者存取權杖。這個權杖將在設定中做為 HF_TOKEN 使用。

中央參考設定

所有部署參數都是透過位於 <local-config-dir>/.env 的中央 .env 檔案管理。請確認這個檔案存在，且包含特定參數 (Hugging Face 權杖、命名空間、模型名稱等)。

範例 .env 結構：

# GDCso Cluster Namespace
NAMESPACE_NAME="your-custom-namespace"

# Hugging Face Token (Required to download gated Gemma models)
HF_TOKEN="your-hf-token-here"

# Model Sizing Parameters
MODEL_NAME="google/gemma-4-31B-it"
SAFE_MODEL_NAME="google-gemma-4-31B-it"

# Hyperparameters
MAX_MODEL_LEN=8192
GPU_MEMORY_UTILIZATION=0.95
MAX_NUM_SEQS=512
MAX_NUM_BATCHED_TOKENS=4096
DTYPE="bfloat16"

# Pod Sizing Requests
CPU_REQUEST="4"
MEMORY_REQUEST="80"

設定環境和憑證

建立命名空間和 Hugging Face 密鑰

部署前，您必須建立命名空間和 Hugging Face 權杖密鑰：

# Navigate to your project root
cd <local-working-dir>

# Sourced from your local .env file
source <local-config-dir>/.env

# Create namespace
kubectl create namespace ${NAMESPACE_NAME} --dry-run=client -o yaml | kubectl apply -f -

# Create Hugging Face token secret
kubectl create secret generic hf-token-secret \
  --from-literal=token="${HF_TOKEN}" \
  -n "${NAMESPACE_NAME}" --dry-run=client -o yaml | kubectl apply -f -

在 Kubernetes 上部署 vLLM

部署作業包含三個主要資訊清單：PVC、服務和部署作業。這些範本會使用在部署時替換的環境變數。

永久磁碟區要求 (PVC)

PVC 可確保模型權重在 Pod 重新啟動後仍會保留，且僅使用 Distributed Cloud 軟體 local-shared 儲存空間級別。

建立名為 vllm-pvc.yaml 的檔案，並加入以下內容：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: model-cache-pvc
  namespace: ${NAMESPACE_NAME}
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: local-shared
  resources:
    requests:
      storage: 100Gi

服務

在通訊埠 8000 上，於內部公開 vLLM API 伺服器。

建立名為 vllm-service.yaml 的檔案，並加入以下內容：

apiVersion: v1
kind: Service
metadata:
  name: vllm-service
  namespace: ${NAMESPACE_NAME}
  labels:
    app: vllm
  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/path: "/metrics"
    prometheus.io/port: "8000"
spec:
  ports:
    - name: http
      port: 8000
      targetPort: 8000
  selector:
    app: vllm
  type: ClusterIP

部署作業

執行 vLLM 容器、掛接模型快取磁碟區，並要求實體 GPU 資源。雖然 96 GB 的 VRAM 適合未量化的 BF16 權重 (約 62 GB)，但這個參考實作項目可啟用 Blackwell FP8 量化 (--quantization=fp8，約 31 GB 權重)，將 KV 快取擴充至 56.53 GiB (61,728 詞元)，以提高並行處理量。

建立名為 vllm-deployment.yaml 的檔案，並加入以下內容：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-deployment
  namespace: ${NAMESPACE_NAME}
  labels:
    app: vllm
    ai.gke.io/inference-server: vllm
    ai.gke.io/model: ${SAFE_MODEL_NAME}
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app: vllm
  template:
    metadata:
      labels:
        app: vllm
        examples.ai.gke.io/source: user-guide
        ai.gke.io/inference-server: vllm
        ai.gke.io/model: ${SAFE_MODEL_NAME}
    spec:
      runtimeClassName: nvidia
      containers:
        - name: vllm-container
          image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4
          imagePullPolicy: IfNotPresent
          command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
          args:
            - --model=$(MODEL_ID)
            - --host=0.0.0.0
            - --port=8000
            - --tensor-parallel-size=1
            - --enable-log-requests
            - --max-model-len=${MAX_MODEL_LEN}
            - --gpu-memory-utilization=${GPU_MEMORY_UTILIZATION}
            - --max-num-seqs=${MAX_NUM_SEQS}
            - --max-num-batched-tokens=${MAX_NUM_BATCHED_TOKENS}
            - --dtype=${DTYPE}
            - --trust-remote-code
            - --enable-prefix-caching
            - --enable-chunked-prefill
            - --quantization=fp8
          env:
            - name: MODEL_ID
              value: ${MODEL_NAME}
            - name: HUGGING_FACE_HUB_TOKEN
              valueFrom:
                secretKeyRef:
                  name: hf-token-secret
                  key: token
            - name: LD_LIBRARY_PATH
              value: "/usr/local/nvidia/lib64"
          ports:
            - name: http
              containerPort: 8000
          resources:
            requests:
              cpu: ${CPU_REQUEST}
              memory: "${MEMORY_REQUEST}Gi"
              nvidia.com/gpu: "1"
            limits:
              cpu: ${CPU_REQUEST}
              memory: "${MEMORY_REQUEST}Gi"
              nvidia.com/gpu: "1"
          volumeMounts:
            - mountPath: /root/.cache/huggingface
              name: cache-volume
            - mountPath: /dev/shm
              name: dshm
      volumes:
        - name: cache-volume
          persistentVolumeClaim:
            claimName: model-cache-pvc
        - name: dshm
          emptyDir:
            medium: Memory
            sizeLimit: 16Gi

部署 Gradio UI

Gradio UI 提供互動式網頁介面，可與模型對話。並部署在叢集內，透過內部 Kubernetes 網路連線至 vLLM 服務。

部署 Gradio

建立名為 gradio-deployment.yaml 的檔案，並加入以下內容：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gradio-deployment
  namespace: ${NAMESPACE_NAME}
  labels:
    app: gradio
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gradio
  template:
    metadata:
      labels:
        app: gradio
    spec:
      containers:
      - name: gradio
        image: us-docker.pkg.dev/google-samples/containers/gke/gradio-app:v1.0.4
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "500m"
            memory: "512Mi"
        env:
        - name: CONTEXT_PATH
          value: "/v1/chat/completions"
        - name: HOST
          value: "http://vllm-service:8000"
        - name: MODEL_ID
          value: "${MODEL_NAME}"
        ports:
        - containerPort: 7860

Gradio 服務

建立名為 gradio-service.yaml 的檔案，並加入以下內容：

apiVersion: v1
kind: Service
metadata:
  name: gradio-service
  namespace: ${NAMESPACE_NAME}
spec:
  selector:
    app: gradio
  ports:
  - protocol: TCP
    port: 8080
    targetPort: 7860
  type: ClusterIP

可觀測性設定

如要瞭解如何設定應用程式記錄和監控功能，請參閱官方的「應用程式記錄和監控」指南。

vLLM 監控

如要啟用 Google Cloud Managed Service for Prometheus (GMP) 擷取 vLLM 指標，請部署 PodMonitoring 資源，以 vLLM Pod 為目標。

建立名為 vllm-pod-monitoring.yaml 的檔案，並加入以下內容：

apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: vllm-pod-monitoring
  namespace: ${NAMESPACE_NAME}
spec:
  selector:
    matchLabels:
      app: vllm
  endpoints:
  - port: http
    interval: 30s

GPU 監控

如要透過 Google Cloud Managed Service for Prometheus (GMP) 啟用從 NVIDIA DCGM Exporter 擷取 GPU 指標，請在 PodMonitoring 命名空間中部署 gpu-operator 資源。詳情請參閱「將 GPU 指標傳送至 Cloud Monitoring」。

注意：部署這項資源時，必須具備 gpu-operator 命名空間的寫入權限。這項操作可能需要由叢集管理員執行。

建立名為 gpu-pod-monitoring.yaml 的檔案，並加入以下內容：

apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: dcgm-gmp
  namespace: gpu-operator
spec:
  selector:
    matchLabels:
      app: nvidia-dcgm-exporter
  endpoints:
  - port: metrics
    interval: 30s

執行步驟

部署資訊清單

將資訊清單套用至叢集。由於 YAML 檔案含有環境變數預留位置，請先使用 envsubst 替換 .env 檔案中的變數，再套用這些變數。

前往包含 YAML 檔案的目前使用的目錄：
```
cd <local-working-dir>
```
取得環境變數：
```
source <local-config-dir>/.env
```

依序套用資訊清單：

# Apply core serving manifests
envsubst < vllm-pvc.yaml | kubectl apply -f -
envsubst < vllm-service.yaml | kubectl apply -f -
envsubst < vllm-deployment.yaml | kubectl apply -f -

# Apply observability manifests
envsubst < vllm-pod-monitoring.yaml | kubectl apply -f -
kubectl apply -f gpu-pod-monitoring.yaml

# Apply Gradio UI manifests
envsubst < gradio-deployment.yaml | kubectl apply -f -
envsubst < gradio-service.yaml | kubectl apply -f -

驗證

監控 Pod 啟動序列

串流容器記錄，追蹤啟動順序：

# 1. Check pod status (wait until it is Running)
kubectl get pods -n ${NAMESPACE_NAME} -l app=vllm

# 2. Stream logs to verify model loading
kubectl logs -f -l app=vllm -n ${NAMESPACE_NAME}

等待記錄檔顯示「active serving ready」訊號：

INFO: Application startup complete.

建立通訊埠轉送通道

如要在本機測試端點，請轉送服務通訊埠 8000：

kubectl port-forward service/vllm-service 8000:8000 -n ${NAMESPACE_NAME}

請勿關閉這個終端機，或在背景執行。

查詢服務端點

在另一個終端機中，測試 API 回應速度：

1. 查詢模型清單

curl -s http://localhost:8000/v1/models | jq

2. 查詢對話完成

curl -s http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_NAME}"'",
    "messages": [
      {"role": "user", "content": "What is AGI in 100 words"}
    ],
    "max_tokens": 150
  }' | jq

驗證 GPU 和 VRAM 分配

如要確保模型有效運用硬體，且記憶體用量正確，可以執行 GPU 稽核。

透過 Pod 內的 nvidia-smi 稽核 GPU

擷取目前使用的 vLLM Pod 名稱，並在容器內執行 nvidia-smi：

# Dynamically get the pod name
export VLLM_POD_NAME=$(kubectl get pods -n ${NAMESPACE_NAME} -l app=vllm -o jsonpath='{.items[0].metadata.name}')

# Run nvidia-smi inside the container
kubectl exec ${VLLM_POD_NAME} -n ${NAMESPACE_NAME} -- nvidia-smi

預期輸出內容：輸出內容應會回報與 GPU_MEMORY_UTILIZATION 參數相符的實體 VRAM 使用率。舉例來說，在搭載 NVIDIA RTX PRO 6000 (約 96 GB VRAM) 的工作站上，如果執行 google/gemma-4-31B-it 並搭配 GPU_MEMORY_UTILIZATION=0.95，您應該會看到分配給 VLLM::EngineCore 的記憶體約為 95,800 MiB：

+-----------------------------------------------------------------------------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA RTX PRO 6000 Blac...    On  |   00000000:05:00.0 Off |                    0 |
| N/A   36C    P0             85W /  600W |   95805MiB /  97887MiB |      0%      Default |
+-----------------------------------------+------------------------+----------------------+

在記錄中驗證 KV 快取分配

您也可以查看 vLLM 內部分配記錄，確認 KV 快取大小和權杖並行：

kubectl logs ${VLLM_POD_NAME} -n ${NAMESPACE_NAME} | grep -E "Available KV cache|GPU KV cache size"

預期輸出內容：

(EngineCore pid=362) INFO 06-18 15:03:43 [gpu_worker.py:456] Available KV cache memory: 56.53 GiB
(EngineCore pid=362) INFO 06-18 15:03:43 [kv_cache_utils.py:1316] GPU KV cache size: 61,728 tokens

這會確認 56.53 GiB 的 VRAM 保留給脈絡 KV 快取，可支援大量並行權杖。

驗證 Gradio UI 部署作業

Gradio Pod 執行後，您就能建立通訊埠轉送通道，存取使用者介面。

監控 Gradio Pod 狀態

確認 Gradio Pod 正在執行：

kubectl get pods -n ${NAMESPACE_NAME} -l app=gradio

預期輸出內容：

NAME                                READY   STATUS    RESTARTS   AGE
gradio-deployment-yyyyyyyy-yyyyy    1/1     Running   0          1m

建立通訊埠轉送通道至 Gradio

將 Gradio 服務通訊埠 8080 轉送到本機通訊埠 7860：

kubectl port-forward service/gradio-service 7860:8080 -n ${NAMESPACE_NAME}

請將這個終端機保持為開啟狀態，或在背景運作執行：

kubectl port-forward service/gradio-service 7860:8080 -n ${NAMESPACE_NAME} > pf_gradio.log 2>&1 & sleep 3

存取網頁版 UI

如果在本機工作站上執行：開啟瀏覽器並直接前往：http://localhost:7860
如果是在 Cloud Shell 中執行：使用「網頁預覽」按鈕，選取「變更通訊埠」，輸入 7860，然後按一下「變更並預覽」。

您應該會看到 Gradio 聊天機器人介面。你可以輸入訊息與 Gemma 模型互動。Gradio Pod 會在內部將要求轉送至 vllm-service 端點。

清理通道

如要停止連接埠轉送通道：

pkill -f "port-forward service/gradio-service"

監控驗證

部署 vLLM 並套用 PodMonitoring 資源後，您可以確認指標是否已擷取至 Cloud Monitoring。

驗證 PodMonitoring 狀態

確認 PodMonitoring 資源已建立並處於有效狀態：

kubectl get podmonitoring -n ${NAMESPACE_NAME}

使用 Google Cloud 控制台驗證指標擷取作業

您可以使用 Google Cloud Metrics Explorer (指標探索器) 確認指標是否正在擷取：

在 Google Cloud 控制台中開啟 Metrics Explorer：
- 前往 https://console.cloud.google.com/monitoring/metrics-explorer (請務必選取專案 ${GCP_PROJECT_ID})。
在「選取指標」下拉式選單中，搜尋並選取：
- prometheus.googleapis.com/vllm:num_requests_running/gauge，驗證 vLLM 指標。
- prometheus.googleapis.com/DCGM_FI_DEV_GPU_UTIL/gauge，即可查看 GPU 使用率指標。
觀察圖表，確認系統是否主動繪製資料點。

記錄驗證

工作負載執行後，您可以確認記錄是否匯出至 Cloud Logging。

驗證 vLLM 記錄擷取作業

確認 vLLM 容器記錄檔是否匯出至 Cloud Logging：

project_id=$(gcloud config get-value project)

gcloud logging read "resource.type=\"k8s_container\" AND resource.labels.namespace_name=\"${NAMESPACE_NAME}\" AND resource.labels.container_name=\"vllm-container\"" --limit=10 --project=${project_id}

驗證 GPU 匯出工具記錄匯入作業

確認 GPU 匯出工具容器記錄檔已匯出至 Cloud Logging：

project_id=$(gcloud config get-value project)

gcloud logging read "resource.type=\"k8s_container\" AND resource.labels.namespace_name=\"gpu-operator\" AND resource.labels.container_name=\"nvidia-dcgm-exporter\"" --limit=10 --project=${project_id}

使用 Google Cloud 控制台 (Logs Explorer) 驗證記錄

您也可以使用 Google Cloud 控制台驗證記錄檔擷取作業：

在 Google Cloud 控制台中開啟「Logs Explorer」(記錄檔探索工具)：
- 前往 https://console.cloud.google.com/logs/query (請務必選取專案 ${GCP_PROJECT_ID})。
在「查詢」方塊中，輸入下列查詢來查看 vLLM 記錄：
```
resource.type="k8s_container"
resource.labels.namespace_name="<NAMESPACE_NAME>"
resource.labels.container_name="vllm-container"
```
(將 <NAMESPACE_NAME> 替換為實際的命名空間，例如 your-custom-namespace)。
按一下「Run query」(執行查詢)。畫面上應會顯示 vLLM 容器的記錄項目。

如要驗證 GPU 匯出工具記錄，請執行下列查詢：

resource.type="k8s_container"
resource.labels.namespace_name="gpu-operator"
resource.labels.container_name="nvidia-dcgm-exporter"

僅限在 Distributed Cloud 軟體參考實作中提供模型服務 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

目標

事前準備

必要條件 (叢集設定)

設定用戶端工作站的必要步驟

Hugging Face 模型存取權

中央參考設定

設定環境和憑證

建立命名空間和 Hugging Face 密鑰

在 Kubernetes 上部署 vLLM

永久磁碟區要求 (PVC)

服務

部署作業

部署 Gradio UI

部署 Gradio

Gradio 服務

可觀測性設定

vLLM 監控

GPU 監控

執行步驟

部署資訊清單

驗證

監控 Pod 啟動序列

建立通訊埠轉送通道

查詢服務端點

1. 查詢模型清單

2. 查詢對話完成

驗證 GPU 和 VRAM 分配

透過 Pod 內的 nvidia-smi 稽核 GPU

在記錄中驗證 KV 快取分配

驗證 Gradio UI 部署作業

監控 Gradio Pod 狀態

建立通訊埠轉送通道至 Gradio

存取網頁版 UI

清理通道

監控驗證

驗證 PodMonitoring 狀態

使用 Google Cloud 控制台驗證指標擷取作業

記錄驗證

驗證 vLLM 記錄擷取作業

驗證 GPU 匯出工具記錄匯入作業

使用 Google Cloud 控制台 (Logs Explorer) 驗證記錄

僅限在 Distributed Cloud 軟體參考實作中提供模型服務