שימוש ב-vLLM ב-GKE להרצת היקש עם Qwen3

במדריך הזה נסביר איך לפרוס ולהכניס לשימוש בסביבת הייצור מודל שפה גדול (LLM) מסוג Qwen3 באמצעות framework לפרסום מודלים של vLLM. אתם פורסים את המודל במכונה וירטואלית (VM) אחת מסוג A4 ב-Google Kubernetes Engine ‏ (GKE).

המדריך הזה מיועד למהנדסי למידת מכונה (ML), לאדמינים ולאופרטורים של פלטפורמות ולמומחי נתונים ו-AI שרוצים להשתמש ביכולות של Kubernetes לניהול קונטיינרים כדי לטפל בעומסי עבודה של הסקת מסקנות.

מטרות

  1. אפשר לגשת אל Qwen3 באמצעות Hugging Face.

  2. הכנת הסביבה.

  3. יוצרים אשכול GKE במצב אוטומטי.

  4. יצירת קטגוריה של Cloud Storage.

  5. יוצרים סוד של Kubernetes לפרטי הכניסה של Hugging Face.

  6. מגדירים את איחוד שירותי אימות הזהויות של עומסי העבודה ב-Cloud Storage.

  7. מאכלסים את הקטגוריה של Cloud Storage במודל Qwen3.

  8. פריסת קונטיינר vLLM ב-GKE.

  9. אפשר ליצור אינטראקציה עם Qwen3 באמצעות curl.

  10. לפנות.

עלויות

במדריך הזה נעשה שימוש ברכיבים של Google Cloudשחלים עליהם חיובים, כולל:

כדי ליצור הערכת עלויות בהתאם לשימוש החזוי, אתם יכולים להשתמש במחשבון עלויות.

לפני שמתחילים

  1. נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

  2. התקינו את ה-CLI של Google Cloud.

  3. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  4. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה: 

    gcloud init

  5. יוצרים או בוחרים Google Cloud פרויקט.

    תפקידים שנדרשים כדי לבחור או ליצור פרויקט

    • Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

    • יוצרים Google Cloud פרויקט:

      gcloud projects create PROJECT_ID

      מחליפים את PROJECT_ID בשם של פרויקט Google Cloud שיוצרים.

    • בוחרים את הפרויקט שיצרתם: Google Cloud 

      gcloud config set project PROJECT_ID

      מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

  6. מוודאים שהחיוב מופעל בפרויקט Google Cloud .

  7. מפעילים את ממשק ה-API הנדרש:

    תפקידים שנדרשים להפעלת ממשקי API

    כדי להפעיל ממשקי API, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים 

    gcloud services enable container.googleapis.com

  8. התקינו את ה-CLI של Google Cloud.

  9. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  10. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה: 

    gcloud init

  11. יוצרים או בוחרים Google Cloud פרויקט.

    תפקידים שנדרשים כדי לבחור או ליצור פרויקט

    • Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

    • יוצרים Google Cloud פרויקט:

      gcloud projects create PROJECT_ID

      מחליפים את PROJECT_ID בשם של פרויקט Google Cloud שיוצרים.

    • בוחרים את הפרויקט שיצרתם: Google Cloud 

      gcloud config set project PROJECT_ID

      מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

  12. מוודאים שהחיוב מופעל בפרויקט Google Cloud .

  13. מפעילים את ממשק ה-API הנדרש:

    תפקידים שנדרשים להפעלת ממשקי API

    כדי להפעיל ממשקי API, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים 

    gcloud services enable container.googleapis.com
    14.

  14. מעניקים תפקידים לחשבון המשתמש. מריצים את הפקודה הבאה לכל אחד מהתפקידים הבאים ב-IAM: roles/container.admin 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט.
    • ‫USER_IDENTIFIER: המזהה של חשבון המשתמש . לדוגמה, myemail@example.com.
    • ‫ROLE: תפקיד ה-IAM שאתם מקצים לחשבון המשתמש.
  15. נכנסים לחשבון Hugging Face או יוצרים חשבון חדש.

גישה ל-Qwen3 באמצעות Hugging Face

כדי להשתמש ב-Hugging Face כדי לגשת ל-Qwen3, פועלים לפי השלבים הבאים:

  1. כניסה לחשבון Hugging Face
  2. יוצרים טוקן גישה ל-Hugging Face read. לוחצים על Your Profile > Settings > Access Tokens > +Create new token (הפרופיל שלך > הגדרות > טוקנים לגישה > +יצירת טוקן חדש).
  3. מציינים שם לבחירתכם לטוקן ואז בוחרים תפקיד. רמת ההרשאה המינימלית בתפקיד שאפשר לבחור במדריך הזה היא קריאה.
  4. לוחצים על יצירת טוקן.
  5. מעתיקים את הטוקן שנוצר ושומרים אותו בלוח. תשתמשו בו בהמשך המדריך הזה.

הכנת הסביבה

כדי להכין את הסביבה, מגדירים את משתני הסביבה שמוגדרים כברירת מחדל:

export PROJECT_ID="YOUR_PROJECT_ID"
export RESERVATION_NAME="YOUR_RESERVATION_NAME"
export REGION="YOUR_REGION"
export CLUSTER_NAME="YOUR_CLUSTER_NAME"
export GCS_BUCKET_NAME="YOUR_GCS_BUCKET"
export HUGGING_FACE_TOKEN="YOUR_HF_TOKEN"
export NETWORK="YOUR_NETWORK_NAME"
export SUBNETWORK="YOUR_SUBNETWORK_NAME"

gcloud config set project "${PROJECT_ID}"
gcloud config set billing/quota_project "${PROJECT_ID}"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫YOUR_PROJECT_ID: המזהה של Google Cloud הפרויקט שבו רוצים ליצור את אשכול GKE.

  • ‫YOUR_RESERVATION_NAME: השם של ההזמנה שרוצים להשתמש בה כדי ליצור את אשכול GKE. בהתאם לפרויקט שבו קיימת ההזמנה, מציינים אחד מהערכים הבאים:

    • ההזמנה קיימת בפרויקט: RESERVATION_NAME

    • ההזמנה קיימת בפרויקט אחר, והפרויקט שלכם יכול להשתמש בה: projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME

  • ‫YOUR_REGION: האזור שבו רוצים ליצור את אשכול GKE. אפשר ליצור את האשכול רק באזור שבו קיימת ההזמנה.

  • ‫YOUR_CLUSTER_NAME: השם של אשכול GKE שרוצים ליצור.

  • ‫YOUR_BUCKET_NAME: השם של קטגוריה של Cloud Storage האזורית שרוצים ליצור.

  • ‫YOUR_HF_TOKEN: טוקן הגישה ל-Hugging Face שיצרתם בקטע הקודם.

  • ‫YOUR_NETWORK_NAME: הרשת שבה נעשה שימוש באשכול GKE. מציינים אחד מהערכים הבאים:

    • אם יצרתם רשת בהתאמה אישית, צריך לציין את שם הרשת.

    • אחרת, מציינים את הערך default.

  • ‫YOUR_SUBNETWORK_NAME: רשת המשנה שבה נעשה שימוש באשכול GKE. מציינים אחד מהערכים הבאים:

    • אם יצרתם רשת משנה בהתאמה אישית, צריך לציין את השם של רשת המשנה. אפשר לציין רק רשת משנה שנמצאת באותו אזור של השריין.

    • אחרת, מציינים את הערך default.

יצירת אשכול GKE במצב אוטומטי

כדי ליצור אשכול GKE במצב אוטומטי, מריצים את הפקודה הבאה:

gcloud container clusters create-auto "$CLUSTER_NAME" \
    --project="$PROJECT_ID" \
    --region="$REGION" \
    --release-channel=rapid \
    --network="$NETWORK" \
    --subnetwork="$SUBNETWORK"
יצירת אשכול GKE עשויה להימשך זמן מה. כדי לוודא ש- Google Cloud סיים ליצור את האשכול, עוברים אל Kubernetes clusters במסוף Google Cloud .

יצירת קטגוריה של Cloud Storage

כדי ליצור קטגוריה אזורית של Cloud Storage לאחסון המודל, מריצים את הפקודה הבאה:

gcloud storage buckets create gs://$GCS_BUCKET_NAME \
    --project=$PROJECT_ID \
    --location=$REGION

יצירת סוד ב-Kubernetes לפרטי הכניסה של Hugging Face

כדי ליצור סוד של Kubernetes לפרטי הכניסה של Hugging Face, פועלים לפי השלבים הבאים:

  1. מגדירים את kubectl לתקשורת עם אשכול GKE:

    gcloud container clusters get-credentials "$CLUSTER_NAME" \
    --location="$REGION" \
    --project="$PROJECT_ID"

  2. יוצרים סוד של Kubernetes לאחסון הטוקן של Hugging Face:

    kubectl create secret generic hf-secret \
    --from-literal=hf_token="${HUGGING_FACE_TOKEN}" \
    --dry-run=client -o yaml | kubectl apply -f -

הגדרת איחוד שירותי אימות הזהות של עומסי עבודה ל-Cloud Storage

כדי לאפשר ל-GKE לגשת באופן מאובטח לקטגוריית Cloud Storage, צריך להגדיר איחוד של Workload Identity ב-GKE:

gcloud iam service-accounts create qwen-gcs-sa \
    --project=$PROJECT_ID

gcloud storage buckets add-iam-policy-binding gs://$GCS_BUCKET_NAME \
    --member="serviceAccount:qwen-gcs-sa@$PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/storage.objectAdmin"

kubectl create serviceaccount qwen-ksa \
    --namespace=default

gcloud iam service-accounts add-iam-policy-binding qwen-gcs-sa@$PROJECT_ID.iam.gserviceaccount.com \
    --project=$PROJECT_ID \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:$PROJECT_ID.svc.id.goog[default/qwen-ksa]"

kubectl annotate serviceaccount qwen-ksa \
    --namespace=default \
    iam.gke.io/gcp-service-account="qwen-gcs-sa@$PROJECT_ID.iam.gserviceaccount.com"

מילוי הקטגוריה של Cloud Storage במשקלים של מודל Qwen3

כדי לאכלס את הקטגוריה של Cloud Storage במשקלים של מודל Qwen3, מריצים Kubernetes Job שמשתמש במנהל התקן ה-CSI של Cloud Storage FUSE כדי לטעון את הקטגוריה כנפח אחסון. העבודה מורידה את המודל מ-Hugging Face אם הוא עדיין לא קיים בדלי.

  1. יוצרים קובץ בשם qwen3-model-loader.yaml עם התוכן הבא:

    apiVersion: batch/v1
kind: Job
metadata:
  name: qwen3-model-loader
spec:
  template:
    metadata:
      annotations:
        gke-gcsfuse/volumes: "true"
        gke-gcsfuse/cpu-limit: "0"
        gke-gcsfuse/memory-limit: "0"
        gke-gcsfuse/ephemeral-storage-limit: "0"
    spec:
      serviceAccountName: qwen-ksa
      restartPolicy: OnFailure
      containers:
      - name: downloader
        image: python:3.11-slim
        resources:
          requests:
            cpu: "4"
            memory: "16Gi"
            ephemeral-storage: "100Gi"
          limits:
            cpu: "4"
            memory: "16Gi"
            ephemeral-storage: "100Gi"
        command: ["/bin/sh", "-c"]
        args:
        - |
          pip install huggingface_hub
          python3 -c '
          import os
          from huggingface_hub import snapshot_download
          model_id = "Qwen/Qwen3-235B-A22B-Instruct-2507"
          local_dir = "/data/Qwen/Qwen3-235B-A22B-Instruct-2507"
          config_path = os.path.join(local_dir, "config.json")
          if os.path.exists(config_path):
              print(f"Model already exists at {local_dir}. Skipping download.")
          else:
              print(f"Downloading model {model_id} to {local_dir}...")
              snapshot_download(
                  repo_id=model_id,
                  local_dir=local_dir,
                  local_dir_use_symlinks=False,
                  token=os.environ.get("HUGGING_FACE_HUB_TOKEN")
              )
              print("Download completed successfully!")
          '
        env:
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_token
        volumeMounts:
        - name: gcs-fuse-volume
          mountPath: /data
      volumes:
      - name: gcs-fuse-volume
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: $GCS_BUCKET_NAME
            mountOptions: "implicit-dirs"

  2. מחילים את קובץ המניפסט qwen3-model-loader.yaml כדי לאתחל את משימת ההורדה:

    envsubst < qwen3-model-loader.yaml | kubectl apply -f -

  3. כדי לוודא שהעבודה פועלת, מפעילים סטרימינג של יומני עבודת ההורדה:

    kubectl logs -f job/qwen3-model-loader -c downloader

  4. ממתינים לסיום של משימת ההורדה של המודל:

    kubectl wait \
    --for=condition=Complete \
    --timeout=1800s job/qwen3-model-loader

  5. כדי למחוק את העבודה, מריצים את הפקודה הבאה:

    kubectl delete job qwen3-model-loader --ignore-not-found

פריסת קונטיינר vLLM באשכול GKE

כדי לפרוס את קונטיינר vLLM כדי להכניס לשימוש בסביבת הייצור את מודל Qwen3 באמצעות Kubernetes Deployments, מבצעים את הפעולות הבאות:

  1. יוצרים קובץ qwen3-235b-deploy.yaml עם הפריסה של vLLM שבחרתם:

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-qwen3-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: qwen3-server
  template:
    metadata:
      labels:
        app: qwen3-server
        ai.gke.io/model: Qwen3-235B-A22B-Instruct-2507
        ai.gke.io/inference-server: vllm
        examples.ai.gke.io/source: user-guide
    spec:
      serviceAccountName: qwen-ksa
      containers:
      - name: qwen-inference-server
        image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:20250801_0916_RC01
        resources:
          requests:
            cpu: "10"
            memory: "1000Gi"
            ephemeral-storage: "500Gi"
            nvidia.com/gpu: "8"
          limits:
            cpu: "10"
            memory: "1000Gi"
            ephemeral-storage: "500Gi"
            nvidia.com/gpu: "8"
        command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
        args:
        - --model=$(MODEL_ID)
        - --load-format=runai_streamer
        - --model-loader-extra-config={"distributed":true}
        - --tensor-parallel-size=8
        - --host=0.0.0.0
        - --port=8000
        - --max-model-len=8192
        - --max-num-seqs=4
        - --dtype=bfloat16
        env:
        - name: MODEL_ID
          value: "gs://$GCS_BUCKET_NAME/Qwen/Qwen3-235B-A22B-Instruct-2507"
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_token
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 200
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 200
          periodSeconds: 5
      volumes:
      - name: dshm
        emptyDir:
          medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-b200
        cloud.google.com/reservation-name: $RESERVATION_NAME
        cloud.google.com/reservation-affinity: "specific"
        cloud.google.com/gke-gpu-driver-version: latest
---
apiVersion: v1
kind: Service
metadata:
  name: qwen3-service
spec:
  selector:
    app: qwen3-server
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000
---
apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: vllm-qwen3-monitoring
spec:
  selector:
    matchLabels:
      app: qwen3-server
  endpoints:
  - port: 8000
    path: /metrics
    interval: 30s

  2. מחילים את קובץ qwen3-235b-deploy.yaml על אשכול GKE:

    envsubst < qwen3-235b-deploy.yaml | kubectl apply -f -
    הקונטיינר משתמש ב-Run:ai Model Streamer כדי להזרים משקלים של מודלים ישירות מ-Cloud Storage, ולכן זמן ההפעלה מתקצר משמעותית.

  3. כדי לראות את סטטוס ההשלמה, מריצים את הפקודה הבאה:

    kubectl wait \
    --for=condition=Available \
    --timeout=1800s deployment/vllm-qwen3-deployment
    הדגל --timeout=600s מאפשר לפקודה לעקוב אחרי הפריסה למשך עד 10 דקות.

אינטראקציה עם Qwen3 באמצעות curl

כדי לאמת את מודל Qwen3 שפרסתם:

  1. מגדירים העברה ליציאה אחרת ל-Qwen3:

    kubectl port-forward service/qwen3-service 8000:8000

  2. פותחים חלון טרמינל חדש. אחרי זה תוכלו לשוחח עם המודל באמצעות curl:

    curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "model": "Qwen/Qwen3-235B-A22B-Instruct-2507",
  "messages": [
    {
      "role": "user",
      "content": "Describe a GPU in one short sentence?"
    }
  ],
  "stream": false
}' | jq .

  3. הפלט אמור להיראות כך:

    {
  "id": "chatcmpl-a926ddf7ef2745ca832bda096e867764",
  "object": "chat.completion",
  "created": 1755023619,
  "model": "Qwen/Qwen3-235B-A22B-Instruct-2507",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A GPU is a specialized electronic circuit designed to rapidly process and render graphics and perform parallel computations.",
        "refusal": null,
        "annotations": null,
        "audio": null,
        "function_call": null,
        "tool_calls": [],
        "reasoning_content": null
      },
      "logprobs": null,
      "finish_reason": "stop",
      "stop_reason": null
    }
  ],
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "prompt_tokens": 16,
    "total_tokens": 36,
    "completion_tokens": 20,
    "prompt_tokens_details": null
  },
  "prompt_logprobs": null,
  "kv_transfer_params": null
}

מעקב אחר ביצועי המודל

אם רוצים לבחון את הביצועים של המודל, אפשר להשתמש בשילוב של לוח הבקרה של vLLM ב-Cloud Monitoring. לוח הבקרה הזה עוזר לכם לראות מדדי ביצועים חשובים של המודל, כמו קצב העברת טוקנים, זמן אחזור ברשת ושיעורי שגיאה. מידע נוסף מופיע במאמר בנושא vLLM במסמכי התיעוד בנושא מעקב.

הסרת המשאבים

כדי להימנע מחיובים בחשבון Google Cloud בגלל השימוש במשאבים שנעשה במסגרת המדריך הזה, אפשר למחוק את הפרויקט שמכיל את המשאבים, או להשאיר את הפרויקט ולמחוק את המשאבים בנפרד.

כדי להימנע מחיובים בחשבון לחיוב ב-Cloud על המשאבים שבהם השתמשתם במדריך הזה, אתם יכולים למחוק את הפרויקט שמכיל את המשאבים או להשאיר את הפרויקט ולמחוק את המשאבים הספציפיים.

מחיקת המשאבים

כדי למחוק את משאבי ההדרכה, מריצים את הפקודות הבאות:

envsubst < qwen3-235b-deploy.yaml | kubectl delete -f -
envsubst < qwen3-model-loader.yaml | kubectl delete -f -
kubectl delete secret hf-secret
kubectl delete serviceaccount qwen-ksa

gcloud iam service-accounts delete qwen-gcs-sa@$PROJECT_ID.iam.gserviceaccount.com \
    --project=$PROJECT_ID --quiet

gcloud storage rm --recursive gs://$GCS_BUCKET_NAME

מחיקת אשכול GKE

כדי למחוק את אשכול GKE, מריצים את הפקודה הבאה:

gcloud container clusters delete "$CLUSTER_NAME" \
    --region="$REGION" \
    --project="$PROJECT_ID" \
    --quiet

מחיקת פרויקט

כדי למחוק Google Cloud פרויקט:

gcloud projects delete PROJECT_ID

המאמרים הבאים