הרצת היקש של מודל Gemma 4 ב-Cloud Run באמצעות RTX 6000 Pro GPU עם vLLM

1. מבוא

הערה: השימוש בתכונה הזו כפוף לתנאי השימוש במוצרים בגרסת טרום-GA, בחלק "תנאים כלליים לשירות" של התנאים הספציפיים לשירות. השימוש בתכונות בגרסת טרום-GA הוא "כפי שהן" (As is), ויכול להיות שהתמיכה בהן תהיה מוגבלת. מידע נוסף זמין בקטע תיאורים של שלבי ההשקה.

סקירה כללית

מה תלמדו

• איך פורסים מודל Gemma 4 ביחידת GPU מסוג Cloud Run RTX 6000 Pro
• איך משתמשים ב-vLLM וב-Run:ai Model Streamer כדי להריץ היקש מהר יותר ולהפעיל מופע בזמן קצר יותר.

הערה: ב-Codelab הזה נעשה שימוש במודל Gemma 4 31B שעבר כוונון להוראות. ב-Codelab הזה נדגים איך להשתמש ב-Run:ai Model Streamer וב-Direct VPC Egress כדי לצמצם את הזמן שלוקח למודל להיטען מ-Cloud Storage במהלך הפעלת הקונטיינר. מידע נוסף זמין במדריך לשיטות מומלצות לשימוש ב-GPU.

2. הגדרה ודרישות

מגדירים משתני סביבה שישמשו לאורך כל ה-codelab:

# Model name on HuggingFace Hub
export MODEL_NAME="google/gemma-4-31B-it"

# Cloud Run Service name
export SERVICE_NAME=gemma-rtx-vllm-codelab

# Cloud Project and Region for Cloud Run
export GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID> # Change to your Project Id
export GOOGLE_CLOUD_REGION=us-central1 # or europe-west4

# Optional HuggingFace User Access Token for accessing model weights 
# (https://huggingface.co/docs/hub/en/security-tokens),
# if you are loading a private model.
export HF_TOKEN=""

# Service account for Cloud Run service
export SERVICE_ACCOUNT="vllm-service-sa"
export SERVICE_ACCOUNT_EMAIL="${SERVICE_ACCOUNT}@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com"

# GCS Bucket for the model cache.
export MODEL_CACHE_BUCKET="${GOOGLE_CLOUD_PROJECT}-${GOOGLE_CLOUD_REGION}-hf-model-cache"
# Model cache location in GSC bucket
export GCS_MODEL_LOCATION="gs://${MODEL_CACHE_BUCKET}/model-cache/${MODEL_NAME}"

# VPC Network for Direct VPC Egress
export VPC_NETWORK="vllm-${GOOGLE_CLOUD_REGION}-net"
export VPC_SUBNET="vllm-${GOOGLE_CLOUD_REGION}-subnet"
export SUBNET_RANGE="10.8.0.0/26"

# set the project
gcloud config set project $GOOGLE_CLOUD_PROJECT
gcloud config set run/region $GOOGLE_CLOUD_REGION

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

gcloud services enable --project "${GOOGLE_CLOUD_PROJECT}" \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    iam.googleapis.com \
    compute.googleapis.com \
    vpcaccess.googleapis.com \
    storage.googleapis.com

3. יצירת חשבון שירות

אם לא מציינים חשבון שירות כשיוצרים את שירות Cloud Run או את משימת Cloud Run, מערכת Cloud Run משתמשת בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine. מומלץ להשתמש בחשבון שירות נפרד לשירות Cloud Run כדי למנוע הפעלה של השירות עם הרשאות מוגזמות.

יצירת חשבון שירות בשביל שירות Cloud Run

gcloud iam service-accounts create ${SERVICE_ACCOUNT} \
  --project "${GOOGLE_CLOUD_PROJECT}" \
  --display-name "vLLM Service Account"

4. הגדרת Cloud Storage

יוצרים קטגוריה של Cloud Storage לאחסון משקלי המודל. כך תוכלו להשתמש בתעבורת נתונים יוצאת (egress) ישירה של VPC כדי להוריד משקלים של מודלים מהר יותר בכל פעם ש-Cloud Run מפעיל מופע של שירות.

השילוב עם התכונה Run:ai Model Streamer ב-vLLM מקצר משמעותית את זמן הטעינה של המודל.

יצירת קטגוריה

חשוב לוודא שמדובר בקטגוריה של אזור יחיד שנמצאת באותו מיקום עם שירות Cloud Run.

gcloud storage buckets create "gs://${MODEL_CACHE_BUCKET}" \
    --uniform-bucket-level-access --public-access-prevention \
    --project "${GOOGLE_CLOUD_PROJECT}" --location "${GOOGLE_CLOUD_REGION}"

5. אחזור משקלים של מודלים ושמירתם במטמון

בשלב הבא, מורידים את מודל Gemma 4 לקטגוריה שלכם ב-Cloud Storage.

משקלי המודלים הם עשרות גיגה-בייט, ויכול להיות שאי אפשר להוריד אותם למחשב המקומי או ל-Cloud Shell.

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

gcloud builds submit --project="${GOOGLE_CLOUD_PROJECT}" --region="${GOOGLE_CLOUD_REGION}" --no-source \
    --substitutions="_MODEL_NAME=${MODEL_NAME},_HF_TOKEN=${HF_TOKEN},_GCS_MODEL_LOCATION=${GCS_MODEL_LOCATION}" \
    --config=/dev/stdin <<'EOF'
steps:
- name: 'gcr.io/google.com/cloudsdktool/google-cloud-cli:slim'
  entrypoint: 'bash'
  args:
  - '-c'
  - |
    set -e
    pip3 install --root-user-action=ignore --break-system-packages huggingface_hub[cli]
    echo "Downloading the model..."
    if [[ "$_HF_TOKEN" != "" ]]; then
      hf download "$_MODEL_NAME" --token $_HF_TOKEN --local-dir "./model-cache/$_MODEL_NAME"
    else
      hf download "$_MODEL_NAME" --local-dir "./model-cache/$_MODEL_NAME"
    fi
    echo "Uploading the model..."
    gcloud storage cp -r "./model-cache/$_MODEL_NAME" "$_GCS_MODEL_LOCATION"
options:
  machineType: 'E2_HIGHCPU_32'
  diskSizeGb: 500
EOF

6. הגדרת רשתות לתעבורת נתונים יוצאת (egress) ישירה של VPC

ההגדרה של תעבורת נתונים יוצאת (egress) ישירה של VPC מחייבת יצירה של רשת ורשת משנה עם גישה פרטית ל-Google מופעלת.

כך שירותי Cloud Run יכולים להתחבר לסט של כתובות IP חיצוניות שמשמשות את Google APIs והשירותים של Google, כולל Cloud Storage.

יצירת רשת

gcloud compute networks create "$VPC_NETWORK" \
        --subnet-mode=custom \
        --bgp-routing-mode=regional \
        --project "$GOOGLE_CLOUD_PROJECT"

יצירת רשת משנה

gcloud compute networks subnets create "$VPC_SUBNET" \
        --network="$VPC_NETWORK" \
        --region="$GOOGLE_CLOUD_REGION" \
        --range="$SUBNET_RANGE" \
        --enable-private-ip-google-access \
        --project "$GOOGLE_CLOUD_PROJECT"

7. הגדרת מדיניות הגישה לחשבון שירות

לחשבון השירות של Cloud Run צריכות להיות הרשאות גישה למשקלי המודל בדלי האחסון שיצרתם.

gcloud storage buckets add-iam-policy-binding "gs://${MODEL_CACHE_BUCKET}" \
    --member "serviceAccount:${SERVICE_ACCOUNT_EMAIL}" \
    --role "roles/storage.admin" \
    --project "${GOOGLE_CLOUD_PROJECT}"

8. הפעלת משתני הגדרות אישיות

מגדירים את המשתנים גם למנוע ההיסקים vLLM וגם לשירות Cloud Run.

# vLLM variables
export MAX_MODEL_LEN=32767      # 32767 to improve concurrency. Keep it empty to use model's maximim context length (256K)
export QUANTIZATION_TYPE="fp8"  # Model quantization for faster performance and lower memory usage.
export KV_CACHE_DTYPE="fp8"     # KV-cache quantization to save GPU memory.
export GPU_MEM_UTIL="0.95"      # Fraction of GPU memory to be used by the vLLM engine.
export TENSOR_PARALLEL_SIZE="1" # Partitioning model across GPUs (1 here as we have only 1 GPU).
export MAX_NUM_SEQS=8           # Max concurrent requests vLLM processes in one batch.

# Cloud Run variables
export CLOUD_RUN_CPU_NUM=20
export CLOUD_RUN_MEMORY_GB=80
export CLOUD_RUN_MAX_INSTANCES=3
export CLOUD_RUN_CONCURRENCY=16

הערה לגבי אופטימיזציה של הביצועים: אופטימיזציה של המשתנים האלה היא איזון בין קצב העברת הנתונים לבין זמן האחזור:

• ‫MAX_NUM_SEQS לעומת CLOUD_RUN_CONCURRENCY: הערך של CLOUD_RUN_CONCURRENCY צריך להיות גדול לפחות כמו הערך של MAX_NUM_SEQS. כדי להשתמש בתקציב בצורה אופטימלית בזמן שיש עלייה חדה בתנועה, כדאי להגדיר אותו קצת יותר גבוה (למשל, פי 2).
• עומס על הזיכרון: גם MAX_MODEL_LEN וגם MAX_NUM_SEQS צורכים זיכרון GPU בשביל מטמון KV. אם אתם נתקלים בשגיאות של חוסר זיכרון (OOM) עם אורכי הקשר גדולים, כדאי להקטין את MAX_NUM_SEQS.
• זמן אחזור: הגדלת מספר הבקשות המקבילות (MAX_NUM_SEQS) מגדילה את התפוקה הכוללת, אבל יכולה להגדיל את זמן האחזור של כל בקשה בנפרד.
• שינוי קנה מידה: CLOUD_RUN_MAX_INSTANCES מאפשר לשנות את קנה המידה אופקית. אם זמן האחזור של המופע היחיד מקובל אבל אתם צריכים קיבולת כוללת גדולה יותר, הגדילו את הערך הזה.

9. פריסה ב-Cloud Run

הכנת שורת הפקודה של קונטיינר vLLM

כדי להריץ מודלים גדולים במהירות וביעילות, vLLM דורש הרבה פרמטרים.

CONTAINER_ARGS=(
    "vllm"
    "serve"
    "${GCS_MODEL_LOCATION}"
    "--served-model-name" "${MODEL_NAME}"
    "--enable-log-requests"
    "--enable-chunked-prefill"
    "--enable-prefix-caching"
    "--generation-config" "auto"
    "--enable-auto-tool-choice"
    "--tool-call-parser" "gemma4"
    "--reasoning-parser" "gemma4"
    "--dtype" "bfloat16"
    "--quantization" "${QUANTIZATION_TYPE}"
    "--kv-cache-dtype" "${KV_CACHE_DTYPE}"
    "--max-num-seqs" "${MAX_NUM_SEQS}"
    "--limit-mm-per-prompt" '{"image":4,"video":2}'
    "--gpu-memory-utilization" "${GPU_MEM_UTIL}"
    "--tensor-parallel-size" "${TENSOR_PARALLEL_SIZE}"
    "--load-format" "runai_streamer"
    "--port" "8080"
    "--host" "0.0.0.0"
)

if [[ "${MAX_MODEL_LEN}" != "" ]]; then
    CONTAINER_ARGS+=("--max-model-len" "${MAX_MODEL_LEN}")
fi

export CONTAINER_ARGS_STR="${CONTAINER_ARGS[*]}"

פריסת שירות Cloud Run

מריצים את הפקודה הבאה כדי לפרוס את שירות Cloud Run.

gcloud beta run deploy "${SERVICE_NAME}" \
    --image="us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4" \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --region "${GOOGLE_CLOUD_REGION}" \
    --service-account "${SERVICE_ACCOUNT_EMAIL}" \
    --execution-environment gen2 \
    --no-allow-unauthenticated \
    --cpu="${CLOUD_RUN_CPU_NUM}" \
    --memory="${CLOUD_RUN_MEMORY_GB}Gi" \
    --gpu=1 \
    --gpu-type=nvidia-rtx-pro-6000 \
    --no-gpu-zonal-redundancy \
    --no-cpu-throttling \
    --max-instances ${CLOUD_RUN_MAX_INSTANCES} \
    --concurrency ${CLOUD_RUN_CONCURRENCY} \
    --network ${VPC_NETWORK} \
    --subnet ${VPC_SUBNET} \
    --vpc-egress all-traffic \
    --set-env-vars "MODEL_NAME=${MODEL_NAME}" \
    --set-env-vars "GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}" \
    --set-env-vars "GOOGLE_CLOUD_REGION=${GOOGLE_CLOUD_REGION}" \
    --startup-probe tcpSocket.port=8080,initialDelaySeconds=240,failureThreshold=1,timeoutSeconds=240,periodSeconds=240 \
    --command "bash" \
    --args="^;^-c;${CONTAINER_ARGS_STR}"

10. בדיקת השירות

אחרי הפריסה, אפשר לקיים אינטראקציה עם מודל Gemma 4 באמצעות API שתואם ל-OpenAI של vLLM.

קבלת כתובת URL של שירות

מאחזרים את כתובת ה-URL של שירות Cloud Run שפרסתם.

SERVICE_URL=$(gcloud run services describe $SERVICE_NAME --project "${GOOGLE_CLOUD_PROJECT}" --region "${GOOGLE_CLOUD_REGION}" --format 'value(status.url)')
echo "Service URL: $SERVICE_URL"

הרצת הסקה

שולחים הנחיה למודל באמצעות curl.

curl -s "$SERVICE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "'"${MODEL_NAME}"'",
  "messages": [
    {"role": "user", "content": "Why is the sky blue?"}
  ],
  "chat_template_kwargs": {
    "enable_thinking": true
  },
  "skip_special_tokens": false
}' | jq -r '.choices[0].message.content'

‫11. מזל טוב!

כל הכבוד, סיימתם את ה-Codelab!

מומלץ לעיין במסמכי התיעוד של Cloud Run.

מה נכלל

• איך פורסים את מודל Gemma 4 ביחידת GPU מסוג Cloud Run RTX 6000 Pro
• איך מגדירים תעבורת נתונים יוצאת (egress) ישירה של VPC וסטרימינג של מודל vLLM עם Cloud Storage כדי להפעיל את השירות מהר יותר.

12. הסרת המשאבים

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

אפשרות 1: מחיקת משאבים

מחיקת שירות Cloud Run

gcloud run services delete $SERVICE_NAME \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --region "${GOOGLE_CLOUD_REGION}"
      --quiet

מחיקת חשבון השירות

gcloud iam service-accounts delete \
      ${SERVICE_ACCOUNT_EMAIL} \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --quiet

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

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

מחיקת רשת ה-VPC ותת-הרשת

gcloud compute networks subnets delete $VPC_SUBNET \
    --region "${GOOGLE_CLOUD_REGION}" \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --quiet

gcloud compute networks delete $VPC_NETWORK \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --quiet

אפשרות 2: מחיקת הפרויקט

כדי למחוק את הפרויקט כולו, עוברים אל Manage Resources (ניהול משאבים), בוחרים את הפרויקט שיצרתם בשלב 2 ולוחצים על Delete (מחיקה). אם תמחקו את הפרויקט, תצטרכו לשנות את הפרויקטים ב-Cloud SDK. כדי לראות את רשימת כל הפרויקטים הזמינים, מריצים את הפקודה gcloud projects list.