סקירה כללית
במדריך הזה, שנקרא Solution Reference Implementation (SRI), מוסבר איך לפרוס, להפעיל ולאמת את הפתרון Open Model Serving on Google Distributed Cloud software only.
במדריך הזה נסביר איך לפרוס את מנוע השירות vLLM שעבר אופטימיזציה ומריץ את Gemma 4 (google/gemma-4-31B-it) באשכול עם צומת יחיד שמיועד לפריסה בקצה הרשת, רק באמצעות תוכנה של Google Distributed Cloud ומשאבים פיזיים של NVIDIA GPU (למשל RTX PRO 6000).
ההדרכה הזו מיועדת לביצוע מלקוח טרמינל של CLI עם גישה של kubectl לאשכול Google Distributed Cloud לתוכנה בלבד.
מטרות
בסיום ההטמעה של הפתרון לדוגמה, תוכלו:
- מגדירים את הפרמטרים של סביבת ההצגה באמצעות קובץ
.envמקומי. - פורסים Persistent Volume Claim (PVC) באמצעות סוג האחסון
local-sharedכדי לשמור את משקלי המודל. - פורסים את מנוע השירות vLLM שעבר אופטימיזציה באמצעות קונטיינרים שעומדים בדרישות של Vertex AI, וממפים משאבים פיזיים של
nvidia.com/gpu. - פורסים את ממשק המשתמש של Gradio באינטרנט כדי לספק ממשק צ'אט אינטראקטיבי.
- הגדרת מנהרות מקומיות להעברה ליציאה אחרת כדי לאמת את מהירות התגובה של הצגת המודעות באמצעות ממשקי API וממשק המשתמש באינטרנט.
- אימות של שילוב הניראות (observability) על ידי אישור הטמעת היומנים והמדדים (כולל נתוני טלמטריה של GPU) ב-Cloud Logging וב-Cloud Monitoring.
לפני שמתחילים
דרישות מוקדמות (הגדרת אשכול)
המדריך הזה מבוסס על ההנחה שיש לכם אשכול פעיל של Google Distributed Cloud במצב "תוכנה בלבד", עם תמיכה מוגדרת ב-GPU. כדי להתקין את האשכול, קראו את המסמכים הרשמיים של Google Distributed Cloud לשרת פיזי. הגדרת ה-GPU צריכה להתאים ל Google Cloudהמסמכים הרשמיים של הגדרה ושימוש ב-NVIDIA GPU.
דרישות מוקדמות לתחנת עבודה של לקוח
מוודאים שבסביבת הטרמינל המקומית מותקנים ומוגדרים הכלים הבאים:
- ה-CLI של gcloud: נדרש להגדרת הפרויקט ולשליחת שאילתות ליומנים.
צריך לאמת (
gcloud auth login) ולהגדיר את הפרויקט הפעיל ב-Google Cloud שבו רשום האשכול של Google Distributed Cloud software only. - kubectl: נדרש כדי לנהל את משאבי האשכול. צריך להגדיר אותו עם ההקשר המתאים כדי לגשת לאשכול של Google Distributed Cloud software only (למשל, באמצעות שער התחברות או גישה ישירה לרשת המקומית).
- curl: נדרש כדי לשלוח בקשות בדיקה לנקודת הקצה להצגת המודעות.
- jq: נדרש כדי לנתח את פלט ה-JSON מנקודת הקצה להצגת מודעות.
גישה למודל של Hugging Face
כדי להוריד ולפרוס את המודל Gemma 4, אתם צריכים גישה למאגר Hugging Face:
- חשבון ב-Hugging Face: ודאו שיש לכם חשבון רשום ב-Hugging Face.
- אישור רישיון המודל: עוברים אל דף המודל Gemma 4 31B IT ומאשרים את תנאי הרישיון כדי לקבל גישה למשקלי המודל המוגבלים.
- יצירת טוקן גישה: יוצרים טוקן גישה למשתמש עם הרשאות קריאה בהגדרות החשבון ב-Hugging Face (הגדרות -> טוקני גישה). הטוקן הזה ישמש בתור
HF_TOKENבהגדרות האישיות.
הגדרת קובץ עזר מרכזי
כל הפרמטרים של הפריסה מנוהלים באמצעות קובץ .env מרכזי שנמצא ב-<local-config-dir>/.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 -
פריסת vLLM ב-Kubernetes
הפריסה מורכבת משלושה מניפסטים עיקריים: PVC, Service ו-Deployment. התבניות האלה משתמשות במשתני סביבה שמוחלפים בזמן הפריסה.
בקשה לנפח אחסון קבוע (PVC)
ה-PVC מבטיח שמשקלי המודל יישמרו בהפעלות מחדש של הפודים, באמצעות מחלקת האחסון של Google Distributed Cloud software only
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
שירות
חושף את שרת ה-API של vLLM באופן פנימי ביציאה 8000.
יוצרים קובץ בשם 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. למרות ש-96GB של VRAM מתאים למשקלים של BF16 ללא קוונטיזציה (כ-62GB), ההטמעה לדוגמה הזו מאפשרת קוונטיזציה של Blackwell FP8 (--quantization=fp8, משקלים של כ-31GB) כדי להרחיב את מטמון ה-KV ל-56.53GiB (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
ממשק המשתמש של Gradio מספק ממשק אינטרנט אינטראקטיבי לצ'אט עם המודל. הוא נפרס בתוך האשכול ומתחבר לשירות vLLM דרך רשת Kubernetes הפנימית.
פריסת 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
הגדרת ניראות (observability)
למידע נוסף על הגדרת רישום ביומן ומעקב אחרי אפליקציות, קראו את המדריך הרשמי בנושא רישום ביומן ומעקב אחרי אפליקציות.
מעקב אחרי vLLM
כדי לאפשר איסוף של מדדי vLLM באמצעות השירות המנוהל של Google Cloud ל-Prometheus (GMP), אנחנו פורסים משאב PodMonitoring שמטרגט את הפודים של vLLM.
יוצרים קובץ בשם 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
כדי לאפשר איסוף של מדדי GPU מ-NVIDIA DCGM Exporter באמצעות השירות המנוהל של Google Cloud ל-Prometheus (GMP), אנחנו פורסים משאב PodMonitoring במרחב השמות gpu-operator. מידע נוסף זמין במאמר שליחת מדדי GPU ל-Cloud Monitoring.
יוצרים קובץ בשם 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}
מחכים עד שרואים ביומנים את האות שההצגה הפעילה מוכנה:
INFO: Application startup complete.
יצירת מנהרה להעברה ליציאה אחרת
כדי לבדוק את נקודת הקצה באופן מקומי, מעבירים את יציאת השירות 8000:
kubectl port-forward service/vllm-service 8000:8000 -n ${NAMESPACE_NAME}
משאירים את הטרמינל הזה פתוח או מריצים אותו ברקע.
נקודת קצה (endpoint) להצגת שאילתות
מטרמינל נפרד, בודקים את תגובת ה-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.
בדיקת ה-GPU באמצעות nvidia-smi בתוך ה-pod
מאחזרים את השם של ה-Pod הפעיל של vLLM ומריצים את 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
הפלט הצפוי: הפלט אמור לדווח על ניצול ה-VRAM הפיזי בהתאם לפרמטר GPU_MEMORY_UTILIZATION. לדוגמה, בתחנת עבודה עם NVIDIA RTX PRO 6000 (כ-96GB VRAM) שפועלת בה google/gemma-4-31B-it עם GPU_MEMORY_UTILIZATION=0.95, אמורים לראות כ-95,800MiB שמוקצים ל-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 |
+-----------------------------------------+------------------------+----------------------+
אימות ההקצאה של מטמון 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.53GiB של VRAM שמור למטמון KV של ההקשר, מה שמאפשר מספר גדול של אסימונים בו-זמנית.
אימות הפריסה של ממשק המשתמש של Gradio
אחרי שה-Pod של Gradio פועל, אפשר לגשת לממשק המשתמש על ידי יצירת מנהרה להעברה ליציאה אחרת.
מעקב אחרי הסטטוס של Pod ב-Gradio
מוודאים שה-pod של Gradio פועל:
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
גישה לממשק המשתמש באינטרנט
- אם אתם משתמשים בתחנת עבודה מקומית: פותחים את הדפדפן ועוברים ישירות לכתובת:
http://localhost:7860 - אם מריצים ב-Cloud Shell: לוחצים על הכפתור Web Preview, בוחרים באפשרות Change Port, מזינים
7860ולוחצים על Change and Preview.
ממשק הצ'אט בוט של Gradio אמור להופיע. אתם יכולים להקליד הודעה כדי לנהל אינטראקציה עם מודל Gemma. ה-Pod של Gradio ינתב את הבקשה באופן פנימי לנקודת הקצה 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):
- פותחים את Metrics Explorer במסוף Google Cloud :
- נכנסים אל
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 exporter
מוודאים שיומני הקונטיינר של GPU exporter מיוצאים ל-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 :
- פותחים את Logs Explorer במסוף Google Cloud :
- נכנסים אל
https://console.cloud.google.com/logs/query(חשוב לבחור את הפרויקט${GCP_PROJECT_ID}).
- נכנסים אל
בתיבה Query, מזינים את השאילתה הבאה כדי להציג את היומנים של 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 exporter, מריצים את השאילתה הבאה:
resource.type="k8s_container" resource.labels.namespace_name="gpu-operator" resource.labels.container_name="nvidia-dcgm-exporter"