Ringkasan
Dokumen ini berfungsi sebagai panduan Implementasi Referensi Solusi (SRI), yang menjelaskan langkah-langkah konkret yang diperlukan untuk men-deploy, menyajikan, dan memvalidasi solusi Penyajian Model Terbuka di Google Distributed Cloud khusus software.
Panduan ini menerapkan deployment mesin inferensi vLLM yang dioptimalkan
yang menjalankan Gemma 4 (google/gemma-4-31B-it) pada konfigurasi Cluster Node Tunggal khusus software Google Distributed Cloud
yang ditargetkan untuk deployment edge menggunakan
resource GPU NVIDIA fisik (misalnya, RTX PRO 6000).
Panduan ini dirancang untuk dijalankan dari klien terminal CLI dengan akses kubectl ke cluster khusus software Google Distributed Cloud.
Tujuan
Dengan menyelesaikan Implementasi Referensi Solusi ini, Anda akan:
- Konfigurasikan parameter lingkungan penyaluran melalui file
.envlokal. - Deploy Persistent Volume Claim (PVC) menggunakan class penyimpanan
local-shareduntuk mempertahankan bobot model. - Deploy mesin inferensi vLLM yang dioptimalkan menggunakan
container yang memenuhi syarat Vertex AI, yang memetakan resource
nvidia.com/gpufisik. - Men-deploy UI Web Gradio untuk menyediakan antarmuka chat interaktif.
- Buat tunnel penerusan port lokal untuk memvalidasi responsivitas penyaluran 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 bahwa Anda memiliki cluster khusus software Google Distributed Cloud yang berjalan dengan dukungan GPU yang telah dikonfigurasi. Untuk menginstal cluster, lihat dokumentasi Google Distributed Cloud khusus software untuk bare metal resmi. Konfigurasi GPU harus mematuhi dokumentasi Google Cloud resmi 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 membuat kueri log.
Harus diautentikasi (
gcloud auth login) dan dikonfigurasi ke projectGoogle Cloud aktif tempat cluster khusus software Google Distributed Cloud didaftarkan. - kubectl: Diperlukan untuk mengelola resource cluster. Harus dikonfigurasi dengan konteks yang sesuai untuk mengakses cluster khusus software Google Distributed Cloud target saja (misalnya, melalui gateway koneksi atau akses jaringan lokal langsung).
- curl: Diperlukan untuk mengirim permintaan pengujian ke endpoint inferensi.
- jq: Diperlukan untuk mengurai output JSON dari endpoint inferensi.
Akses model Hugging Face
Untuk mendownload dan men-deploy model Gemma 4, Anda harus memiliki akses ke repositori Hugging Face:
- Akun Hugging Face: Pastikan Anda memiliki akun terdaftar di Hugging Face.
- Setujui Lisensi Model: Buka halaman model Gemma 4 31B IT dan setujui persyaratan lisensi untuk mendapatkan akses ke bobot model yang dibatasi.
- 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_TOKENdalam 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
Membuat namespace dan secret Hugging Face
Sebelum men-deploy, Anda harus membuat namespace dan secret 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 mulai ulang pod, menggunakan class penyimpanan local-shared khusus software Google Distributed Cloud.
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 API vLLM 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 Blackwell FP8
(--quantization=fp8, bobot ~31 GB) untuk memperluas cache KV menjadi 56,53 GiB
(61,728 token) 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 chat dengan model. Layanan 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), kami
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), kami men-deploy resource PodMonitoring di
namespace gpu-operator. Untuk mengetahui detail selengkapnya, lihat
Mengirim metrik GPU ke Cloud Monitoring.
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.
Buka direktori kerja yang berisi file YAML:
cd <local-working-dir>Ambil variabel lingkungan:
source <local-config-dir>/.envTerapkan 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
Tampilkan log container secara real-time 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:
INFO: Application startup complete.
Membuat 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 inferensi kueri
Dari terminal terpisah, uji responsivitas API:
1. Daftar model kueri
curl -s http://localhost:8000/v1/models | jq
2. Membuat 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 jejak memori sudah benar, Anda dapat menjalankan audit GPU.
Mengaudit 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 sesuai dengan parameter GPU_MEMORY_UTILIZATION Anda. Misalnya, di workstation dengan
NVIDIA RTX PRO 6000 (VRAM sekitar 96 GB) yang menjalankan google/gemma-4-31B-it dengan
GPU_MEMORY_UTILIZATION=0.95, Anda akan melihat sekitar 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 di log
Anda juga dapat memeriksa log alokasi internal vLLM untuk memverifikasi ukuran KV Cache 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 banyak 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 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
Membuat tunnel penerusan port ke Gradio
Teruskan port layanan Gradio 8080 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 Web Preview,
pilih Change Port, masukkan
7860, lalu klik Change and Preview.
Anda akan melihat antarmuka chatbot Gradio. Anda dapat mengetik pesan untuk berinteraksi
dengan model Gemma. Pod Gradio akan mengarahkan permintaan
secara internal ke endpoint vllm-service.
Membersihkan tunnel
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 diserap ke dalam 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 diserap menggunakan konsol Google Cloud (Metrics Explorer):
- Buka Metrics Explorer di konsol Google Cloud :
- Buka
https://console.cloud.google.com/monitoring/metrics-explorer(pastikan Anda memilih project${GCP_PROJECT_ID}).
- Buka
- Di drop-down Select a metric, telusuri dan pilih:
prometheus.googleapis.com/vllm:num_requests_running/gaugeuntuk memverifikasi metrik vLLM.prometheus.googleapis.com/DCGM_FI_DEV_GPU_UTIL/gaugeuntuk memverifikasi metrik pemakaian GPU.
- Amati diagram untuk mengonfirmasi bahwa titik data sedang diplot secara aktif.
Verifikasi logging
Setelah workload berjalan, Anda dapat memverifikasi bahwa log diekspor ke Cloud Logging.
Memverifikasi penyerapan log vLLM
Pastikan log container 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 pengekspor GPU
Pastikan log container pengekspor GPU 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 :
- Buka Logs Explorer di konsol Google Cloud :
- Buka
https://console.cloud.google.com/logs/query(pastikan Anda memilih project${GCP_PROJECT_ID}).
- Buka
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 Anda yang sebenarnya, misalnya,your-custom-namespace).Klik Run query. Anda akan melihat entri log dari container vLLM.
Untuk memverifikasi log pengekspor GPU, jalankan kueri berikut:
resource.type="k8s_container" resource.labels.namespace_name="gpu-operator" resource.labels.container_name="nvidia-dcgm-exporter"