הטמעה לדוגמה של פרסום מודל פתוח בתוכנת Google Distributed Cloud בלבד

סקירה כללית

במדריך הזה, שנקרא 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:

  1. חשבון ב-Hugging Face: ודאו שיש לכם חשבון רשום ב-Hugging Face.
  2. אישור רישיון המודל: עוברים אל דף המודל Gemma 4 31B IT ומאשרים את תנאי הרישיון כדי לקבל גישה למשקלי המודל המוגבלים.
  3. יצירת טוקן גישה: יוצרים טוקן גישה למשתמש עם הרשאות קריאה בהגדרות החשבון ב-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 לפני שמחילים אותם.

  1. עוברים לספריית העבודה שמכילה את קובצי ה-YAML:

    cd <local-working-dir>
    
  2. מגדירים את משתני הסביבה:

    source <local-config-dir>/.env
    
  3. מחילים את המניפסטים לפי הסדר:

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

  1. פותחים את Metrics Explorer במסוף Google Cloud :
    • נכנסים אל https://console.cloud.google.com/monitoring/metrics-explorer (חשוב לבחור את הפרויקט ${GCP_PROJECT_ID}).
  2. בתפריט הנפתח בחירת מדד, מחפשים ובוחרים את האפשרויות הבאות:
    • ‫prometheus.googleapis.com/vllm:num_requests_running/gauge כדי לאמת את המדדים של vLLM.
    • ‫prometheus.googleapis.com/DCGM_FI_DEV_GPU_UTIL/gauge כדי לאמת את מדדי הניצול של ה-GPU.
  3. בודקים את התרשים כדי לוודא שהנקודות על הגרף משורטטות באופן פעיל.

אימות הרישום ביומן

אחרי שעומס העבודה פועל, אפשר לוודא שהיומנים מיוצאים ל-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 :

  1. פותחים את Logs Explorer במסוף Google Cloud :
    • נכנסים אל https://console.cloud.google.com/logs/query (חשוב לבחור את הפרויקט ${GCP_PROJECT_ID}).
  2. בתיבה Query, מזינים את השאילתה הבאה כדי להציג את היומנים של vLLM:

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

    (מחליפים את <NAMESPACE_NAME> במרחב השמות בפועל, למשל your-custom-namespace).

  3. לוחצים על Run query. אמורים להופיע רשומות ביומן מהקונטיינר של vLLM.

  4. כדי לאמת את היומנים של GPU exporter, מריצים את השאילתה הבאה:

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