Menayangkan model terbuka hanya pada penerapan referensi software Distributed Cloud

Ringkasan

Dokumen ini berfungsi sebagai panduan Implementasi Referensi Solusi (SRI), yang menjelaskan langkah-langkah konkret yang diperlukan untuk men-deploy, menayangkan, dan memvalidasi solusi Penayangan Model Terbuka di software Distributed Cloud saja.

Panduan ini menerapkan deployment mesin penayangan vLLM yang dioptimalkan yang menjalankan Gemma 4 (google/gemma-4-31B-it) hanya pada software Distributed Cloud dengan konfigurasi Cluster Satu Node yang ditujukan untuk deployment edge menggunakan resource GPU NVIDIA fisik (misalnya, RTX PRO 6000).

Penjelasan ini dirancang untuk dijalankan dari klien terminal CLI dengan akses kubectl ke cluster hanya software Distributed Cloud.

Catatan: Di seluruh panduan ini, placeholder berikut digunakan:

• <local-working-dir>: Direktori root ruang kerja project Anda (misalnya, ~/gdcso-open-model-serving/).
• <local-config-dir>: Direktori yang berisi file konfigurasi dan lingkungan lokal Anda (misalnya, gdcso-open-model-serving-local/).

Tujuan

Dengan menyelesaikan Penerapan Referensi Solusi ini, Anda akan:

• Konfigurasi parameter lingkungan penayangan melalui file .env lokal.
• Deploy Persistent Volume Claim (PVC) menggunakan class penyimpanan local-shared untuk mempertahankan bobot model.
• Men-deploy mesin penayangan vLLM yang dioptimalkan menggunakan container yang memenuhi syarat Vertex AI, yang memetakan resource nvidia.com/gpu fisik.
• Deploy UI Web Gradio untuk menyediakan antarmuka chat interaktif.
• Buat tunnel penerusan port lokal untuk memvalidasi respons penayangan melalui API dan UI Web.
• Verifikasi integrasi kemampuan observasi dengan mengonfirmasi penyerapan log dan metrik (termasuk telemetri GPU) ke Cloud Logging dan Cloud Monitoring.

Sebelum memulai

Prasyarat (penyiapan cluster)

Panduan ini mengasumsikan Anda memiliki cluster software Distributed Cloud yang sedang berjalan dengan konfigurasi dukungan GPU. Untuk menginstal cluster, lihat dokumentasi resmi Distributed Cloud khusus software untuk bare metal. Konfigurasi GPU harus mematuhi dokumentasi resmi Google Cloud untuk Menyiapkan dan menggunakan GPU NVIDIA.

Prasyarat workstation klien

Pastikan lingkungan terminal lokal Anda telah menginstal dan mengonfigurasi alat berikut:

• gcloud CLI: Diperlukan untuk konfigurasi project dan kueri log. Harus diautentikasi (gcloud auth login) dan dikonfigurasi ke project Google Cloud aktif tempat cluster hanya software Distributed Cloud didaftarkan.
• kubectl: Diperlukan untuk mengelola resource cluster. Harus dikonfigurasi dengan konteks yang sesuai untuk mengakses target cluster software Distributed Cloud saja (misalnya, melalui gateway koneksi atau akses jaringan lokal langsung).
• curl: Diperlukan untuk mengirim permintaan pengujian ke endpoint penayangan.
• jq: Diperlukan untuk mengurai output JSON dari endpoint penayangan.

Akses model Hugging Face

Untuk mendownload dan men-deploy model Gemma 4, Anda harus memiliki akses ke repositori Hugging Face:

1. Akun Hugging Face: Pastikan Anda memiliki akun terdaftar di Hugging Face.
2. Setujui Lisensi Model: Buka halaman model IT Gemma 4 31B dan setujui persyaratan lisensi untuk mendapatkan akses ke bobot model yang dibatasi.
3. Buat Token Akses: Buat Token Akses Pengguna dengan izin Baca dari setelan akun Hugging Face Anda (Settings -> Access Tokens). Token ini akan digunakan sebagai HF_TOKEN dalam konfigurasi Anda.

Konfigurasi referensi pusat

Semua parameter deployment dikelola melalui file .env pusat yang terletak di <local-config-dir>/.env. Pastikan file ini ada dan berisi parameter spesifik Anda (token Hugging Face, namespace, nama model, dll.).

Contoh struktur .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"

Menyiapkan lingkungan dan kredensial

Buat namespace dan secret Hugging Face

Sebelum men-deploy, Anda harus membuat namespace dan rahasia token 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 -

Deployment vLLM di Kubernetes

Deployment ini terdiri dari tiga manifes utama: PVC, Service, dan Deployment. Template ini menggunakan variabel lingkungan yang diganti pada waktu deployment.

Persistent Volume Claim (PVC)

PVC memastikan bobot model tetap ada di seluruh proses mulai ulang pod, hanya menggunakan software Distributed Cloud local-shared class penyimpanan.

Buat file bernama vllm-pvc.yaml dengan konten berikut:

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

Layanan

Mengekspos server vLLM API secara internal di port 8000.

Buat file bernama vllm-service.yaml dengan konten berikut:

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

Deployment

Menjalankan container vLLM, memasang volume cache model, dan meminta resource GPU fisik. Meskipun VRAM 96 GB sesuai dengan bobot BF16 yang tidak dikuantisasi (~62 GB), implementasi referensi ini memungkinkan kuantisasi FP8 Blackwell (--quantization=fp8, bobot ~31 GB) untuk memperluas cache KV menjadi 56,53 GiB (token 61,728) untuk throughput serentak yang lebih tinggi.

Buat file bernama vllm-deployment.yaml dengan konten berikut:

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

Deployment UI Gradio

UI Gradio menyediakan antarmuka web interaktif untuk melakukan percakapan dengan model. Aplikasi ini di-deploy dalam cluster dan terhubung ke layanan vLLM melalui jaringan Kubernetes internal.

Deployment Gradio

Buat file bernama gradio-deployment.yaml dengan konten berikut:

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

Layanan Gradio

Buat file bernama gradio-service.yaml dengan konten berikut:

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

Konfigurasi kemampuan observasi

Untuk mengetahui detail tentang cara mengonfigurasi logging dan pemantauan aplikasi, lihat panduan resmi Logging dan pemantauan aplikasi.

Pemantauan vLLM

Untuk mengaktifkan scraping metrik vLLM oleh Google Cloud Managed Service for Prometheus (GMP), kita men-deploy resource PodMonitoring yang menargetkan pod vLLM.

Buat file bernama vllm-pod-monitoring.yaml dengan konten berikut:

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

Pemantauan GPU

Untuk mengaktifkan scraping metrik GPU dari NVIDIA DCGM Exporter oleh Google Cloud Managed Service for Prometheus (GMP), kita men-deploy resource PodMonitoring di namespace gpu-operator. Untuk mengetahui detail selengkapnya, lihat Mengirim metrik GPU ke Cloud Monitoring.

Catatan: Men-deploy resource ini memerlukan izin tulis ke namespace gpu-operator. Tindakan ini mungkin perlu dilakukan oleh administrator cluster.

Buat file bernama gpu-pod-monitoring.yaml dengan konten berikut:

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

Langkah-langkah eksekusi

Men-deploy manifes

Terapkan manifes ke cluster. Karena file YAML berisi placeholder variabel lingkungan, gunakan envsubst untuk mengganti variabel dari file .env Anda sebelum menerapkannya.

1. Buka direktori kerja yang berisi file YAML:

   cd <local-working-dir>
   

2. Sumber variabel lingkungan:

   source <local-config-dir>/.env
   

3. Terapkan manifes secara berurutan:

   # 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 -
   

Verifikasi

Memantau urutan booting pod

Streaming log container untuk melacak urutan startup:

# 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}

Tunggu hingga Anda melihat sinyal siap penayangan aktif di log Anda:

INFO: Application startup complete.

Buat tunnel penerusan port

Untuk menguji endpoint secara lokal, teruskan port layanan 8000:

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

Biarkan terminal ini tetap terbuka atau jalankan di latar belakang.

Endpoint penayangan kueri

Dari terminal terpisah, uji responsivitas API:

1. Daftar model kueri

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

2. Mengirim kueri penyelesaian chat

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

Memverifikasi alokasi GPU dan VRAM

Untuk memastikan model menggunakan hardware secara efisien dan footprint memori sudah benar, Anda dapat menjalankan audit GPU.

Memeriksa GPU melalui nvidia-smi di dalam pod

Ambil nama pod vLLM aktif Anda dan jalankan nvidia-smi di dalam container:

# 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

Output yang Diharapkan: Output harus melaporkan penggunaan VRAM fisik yang cocok dengan parameter GPU_MEMORY_UTILIZATION Anda. Misalnya, pada workstation dengan NVIDIA RTX PRO 6000 (sekitar 96 GB VRAM) yang menjalankan google/gemma-4-31B-it dengan GPU_MEMORY_UTILIZATION=0.95, Anda akan melihat ~95. 800 MiB dialokasikan ke VLLM::EngineCore:

+-----------------------------------------------------------------------------------------+
| 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 |
+-----------------------------------------+------------------------+----------------------+

Memverifikasi alokasi cache KV dalam log

Anda juga dapat memeriksa log alokasi internal vLLM untuk memverifikasi ukuran Cache KV dan konkurensi token:

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

Output yang Diharapkan:

(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

Hal ini mengonfirmasi bahwa 56,53 GiB VRAM dicadangkan untuk cache KV konteks, sehingga memungkinkan sejumlah besar token serentak.

Memverifikasi deployment UI Gradio

Setelah pod Gradio berjalan, Anda dapat mengakses UI dengan membuat tunnel penerusan port.

Memantau status pod Gradio

Pastikan pod Gradio sedang berjalan:

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

Output yang Diharapkan:

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

Buat tunnel penerusan port ke Gradio

Teruskan port 8080 layanan Gradio ke port lokal 7860:

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

Biarkan terminal ini tetap terbuka atau jalankan di latar belakang:

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

Mengakses UI web

• Jika berjalan di Workstation Lokal: Buka browser Anda dan buka langsung ke: http://localhost:7860
• Jika berjalan di dalam Cloud Shell: Gunakan tombol Pratinjau Web, pilih Ubah Port, masukkan 7860, lalu klik Ubah dan Pratinjau.

Anda akan melihat antarmuka chatbot Gradio. Anda dapat mengetik pesan untuk berinteraksi dengan model Gemma. Pod Gradio akan merutekan permintaan secara internal ke endpoint vllm-service.

Membersihkan terowongan

Untuk menghentikan tunnel penerusan port:

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

Memantau verifikasi

Setelah vLLM di-deploy dan resource PodMonitoring diterapkan, Anda dapat memverifikasi bahwa metrik sedang di-ingest ke Cloud Monitoring.

Memverifikasi status PodMonitoring

Pastikan resource PodMonitoring dibuat dan aktif:

kubectl get podmonitoring -n ${NAMESPACE_NAME}

Memverifikasi penyerapan metrik menggunakan konsol Google Cloud

Anda dapat memverifikasi bahwa metrik sedang di-ingest menggunakan konsol Google Cloud (Metrics Explorer):

1. Buka Metrics Explorer di konsol Google Cloud :
   • Buka https://console.cloud.google.com/monitoring/metrics-explorer (pastikan Anda memilih project ${GCP_PROJECT_ID}).
2. Di drop-down Pilih metrik, telusuri dan pilih:
   • prometheus.googleapis.com/vllm:num_requests_running/gauge untuk memverifikasi metrik vLLM.
   • prometheus.googleapis.com/DCGM_FI_DEV_GPU_UTIL/gauge untuk memverifikasi metrik pemakaian GPU.
3. Amati diagram untuk mengonfirmasi bahwa titik data sedang diplot secara aktif.

Verifikasi logging

Setelah beban kerja berjalan, Anda dapat memverifikasi bahwa log diekspor ke Cloud Logging.

Memverifikasi penyerapan log vLLM

Pastikan log penampung vLLM diekspor ke 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}

Memverifikasi penyerapan log GPU exporter

Verifikasi bahwa log container GPU exporter diekspor ke 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}

Memverifikasi log menggunakan konsol Google Cloud (Logs Explorer)

Anda juga dapat memverifikasi penyerapan log menggunakan konsol Google Cloud :

1. Buka Logs Explorer di konsol Google Cloud :
   • Buka https://console.cloud.google.com/logs/query (pastikan Anda memilih project ${GCP_PROJECT_ID}).

2. Di kotak Query, masukkan kueri berikut untuk melihat log vLLM:

   resource.type="k8s_container"
   resource.labels.namespace_name="<NAMESPACE_NAME>"
   resource.labels.container_name="vllm-container"
   

   (Ganti <NAMESPACE_NAME> dengan namespace sebenarnya, misalnya, your-custom-namespace).

3. Klik Run query. Anda akan melihat entri log dari container vLLM.

4. Untuk memverifikasi log eksportir GPU, jalankan kueri berikut:

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