اجرای استنتاج مدل Gemma 4 روی Cloud Run با پردازنده گرافیکی RTX 6000 Pro با vLLM

۱. مقدمه

توجه: این ویژگی تابع «شرایط ارائه‌های پیش از GA» در بخش شرایط خدمات عمومی از شرایط خاص سرویس است. ویژگی‌های پیش از GA «به همین صورت» در دسترس هستند و ممکن است پشتیبانی محدودی داشته باشند. برای اطلاعات بیشتر، به توضیحات مرحله راه‌اندازی مراجعه کنید .

نمای کلی

آنچه یاد خواهید گرفت

• نحوه‌ی پیاده‌سازی مدل Gemma 4 روی پردازنده‌ی گرافیکی Cloud Run RTX 6000 Pro
• نحوه استفاده از vLLM و Run:ai Model Streamer برای استنتاج سریع‌تر و زمان راه‌اندازی کوتاه‌تر نمونه.

توجه: این آزمایشگاه کد از مدل Gemma 4 31B Instruction-Tuned استفاده می‌کند. این آزمایشگاه کد نحوه استفاده از Run:ai Model Streamer و Direct VPC Egress را نشان می‌دهد که زمان بارگذاری مدل از Cloud Storage را در طول راه‌اندازی کانتینر به حداقل می‌رسانند. برای اطلاعات بیشتر، به راهنمای بهترین شیوه‌های GPU مراجعه کنید.

۲. تنظیمات و الزامات

متغیرهای محیطی که در طول این آزمایشگاه کد استفاده خواهند شد را تنظیم کنید:

# 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

۳. ایجاد حساب کاربری سرویس

اگر هنگام ایجاد سرویس یا کار 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"

۴. راه‌اندازی فضای ذخیره‌سازی ابری

یک مخزن ذخیره‌سازی ابری برای ذخیره وزن‌های مدل ایجاد کنید. این کار به شما امکان می‌دهد هر بار که Cloud Run یک نمونه سرویس را شروع می‌کند، از Direct VPC Egress برای دانلود سریع‌تر وزن‌های مدل استفاده کنید.

همراه با ویژگی 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}"

۵. بازیابی و ذخیره وزن‌های مدل

در مرحله بعد، مدل Gemma 4 را در فضای ذخیره‌سازی ابری خود دانلود کنید.

حجم مدل‌ها ده‌ها گیگابایت است و دانلود آنها روی دستگاه محلی یا 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

۶. پیکربندی شبکه برای خروجی مستقیم VPC

پیکربندی Direct VPC Egress نیاز به ایجاد یک شبکه و زیرشبکه با دسترسی خصوصی گوگل (Private Google Access) فعال دارد.

این به سرویس‌های Cloud Run اجازه می‌دهد تا به مجموعه‌ای از آدرس‌های IP خارجی که توسط APIها و سرویس‌های 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"

۷. پیکربندی سیاست دسترسی به حساب سرویس

حساب کاربری سرویس Cloud Run برای دسترسی به وزن‌های مدل در Storage Bucket که ایجاد کرده‌اید، به مجوز نیاز دارد.

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

۸. مقداردهی اولیه متغیرهای پیکربندی

متغیرها را هم برای موتور استنتاج 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 باشد. برای استفاده بهینه با افزایش ناگهانی ترافیک، آن را کمی بالاتر (مثلاً ۲x) تنظیم کنید.
• فشار بر حافظه : MAX_MODEL_LEN و MAX_NUM_SEQS هر دو حافظه GPU را برای حافظه پنهان KV مصرف می‌کنند. اگر با خطاهای کمبود حافظه (OOM) با طول متن زیاد مواجه شدید، کاهش MAX_NUM_SEQS را در نظر بگیرید.
• تأخیر : همزمانی بالاتر ( MAX_NUM_SEQS ) کل توان عملیاتی را افزایش می‌دهد اما می‌تواند تأخیر درخواست‌های منفرد را نیز افزایش دهد.
• مقیاس‌بندی : CLOUD_RUN_MAX_INSTANCES به شما امکان می‌دهد تا به صورت افقی مقیاس‌بندی کنید. اگر تأخیر تک نمونه‌ای شما قابل قبول است اما به ظرفیت کلی بیشتری نیاز دارید، این مقدار را افزایش دهید.

۹. استقرار در 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}"

۱۰. سرویس را آزمایش کنید

پس از استقرار، می‌توانید با استفاده از API سازگار با vLLM OpenAI با مدل Gemma 4 خود تعامل داشته باشید.

دریافت آدرس اینترنتی سرویس

آدرس اینترنتی سرویس 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'

۱۱. تبریک می‌گویم!

تبریک می‌گویم که آزمایشگاه کد را تمام کردید!

توصیه می‌کنیم مستندات Cloud Run را بررسی کنید.

آنچه ما پوشش داده‌ایم

• نحوه‌ی پیاده‌سازی مدل Gemma 4 روی پردازنده‌ی گرافیکی Cloud Run RTX 6000 Pro
• نحوه پیکربندی Direct VPC Egress و پخش مدل vLLM با Cloud Storage برای راه‌اندازی سریع‌تر سرویس.

۱۲. تمیز کردن

برای جلوگیری از تحمیل هزینه به حساب گوگل کلود خود برای منابع استفاده شده در این آموزش، می‌توانید پروژه یا منابع تکی را حذف کنید.

گزینه ۱: حذف منابع

سرویس 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

سطل ذخیره‌سازی ابری را حذف کنید

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

گزینه ۲: حذف پروژه

برای حذف کل پروژه، به مدیریت منابع بروید، پروژه‌ای را که در مرحله ۲ ایجاد کرده‌اید انتخاب کنید و حذف را انتخاب کنید. اگر پروژه را حذف کنید، باید پروژه‌ها را در Cloud SDK خود تغییر دهید. می‌توانید با اجرای gcloud projects list لیست تمام پروژه‌های موجود را مشاهده کنید.