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

1. מבוא

סקירה כללית

מה תלמדו

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

‫Gemma 4 היא משפחה של מודלים עם משקלים פתוחים מבית Google DeepMind ברישיון Apache 2. המודלים הם רב-לשוניים, מולטי-מודאליים, מציעים יכולות חשיבה רציונלית וארכיטקטורה יעילה. ‫Cloud Run היא סביבה ללא שרת לקונטיינרים עם תמיכה ביחידות GPU.

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

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

# 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=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. הפרמטרים האלה יועברו כארגומנטים לקונטיינר שנפרס ב-Cloud Run.

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}"
    "--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[*]}"
echo "Deployment string: ${CONTAINER_ARGS_STR}"

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

מריצים את הפקודה הבאה כדי לפרוס את שירות Cloud Run. שימו לב לסוג ה-GPU ‏ (RTX 6000 Pro), לתמונת הבסיס (pytorch-vllm-serve:gemma4) ולצורך באימות כדי להפעיל את השירות (--no-allow-unauthenticated).

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}" \
    --port=8080 \
    --timeout=3600 \
    --cpu-boost \
    --startup-probe tcpSocket.port=8080,initialDelaySeconds=240,failureThreshold=40,timeoutSeconds=10,periodSeconds=15 \
    --command "bash" \
    --args="^;^-c;${CONTAINER_ARGS_STR}"

הפריסה תימשך כמה דקות. אחרי שתסיימו, יהיה לכם סביבה מבוססת-GPU שמכניסה לשימוש בסביבת הייצור את Gemma 4 באמצעות תשתית בלי שרת (serverless) עם התאמה אוטומטית לעומס (automatic scaling) כולל צמצום הפעולה לאפס (אין תעבורת נתונים, אין עלות).

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 מסוג RTX 6000 Pro של Cloud Run
איך מגדירים תעבורת נתונים יוצאת (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. אם אתם רוצים להשתמש בשורת הפקודה, אתם יכולים להשתמש גם בפקודה הזו:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}