تشغيل استنتاج نموذج Gemma 4 على Cloud Run باستخدام وحدة معالجة الرسومات RTX 6000 Pro مع vLLM

1- مقدمة

ملاحظة: تخضع هذه الميزة لأحكام "العروض لمرحلة ما قبل التوفّر للجمهور العام" في قسم "الأحكام العامة للخدمة" من الأحكام الخاصة بالخدمة. تتوفّر الميزات في مرحلة ما قبل التوفّر للجمهور العام "كما هي" وقد يكون الدعم محدودًا لها. لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق

نظرة عامة

أهداف الدورة التعليمية

• كيفية نشر نموذج Gemma 4 على وحدة معالجة الرسومات RTX 6000 Pro في Cloud Run
• كيفية استخدام vLLM وRun:ai Model Streamer لإجراء استنتاج أسرع وبدء تشغيل أسرع للآلة الافتراضية

ملاحظة: يستخدم هذا الدرس التطبيقي حول الترميز نموذج Gemma 4 31B Instruction-Tuned. يوضّح الدرس التطبيقي حول الترميز كيفية استخدام Run:ai Model Streamer وDirect VPC Egress لتقليل الوقت الذي يستغرقه تحميل النموذج من Cloud Storage أثناء بدء تشغيل الحاوية. لمزيد من المعلومات، يُرجى الانتقال إلى دليل أفضل ممارسات استخدام وحدات معالجة الرسومات.

2. الإعداد والمتطلبات

يمكنك ضبط متغيرات البيئة التي سيتم استخدامها خلال هذا الدرس التطبيقي حول الترميز:

# 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

تفعيل واجهات برمجة التطبيقات اللازمة لهذا الدرس التطبيقي حول الترميز

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 حساب خدمة 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 لتخزين أوزان النموذج. سيسمح ذلك باستخدام Direct VPC Egress لتنزيل أوزان النموذج بشكل أسرع في كل مرة تبدأ فيها 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. ضبط إعدادات الشبكات لـ Direct VPC Egress

يتطلّب ضبط Direct VPC Egress إنشاء شبكة وشبكة فرعية مع تفعيل "الوصول الخاص إلى Google".

يسمح ذلك لخدمات Cloud Run بالاتصال بمجموعة عناوين IP الخارجية التي تستخدمها Google APIs وخدماتها، بما في ذلك 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. لتحقيق الاستخدام الأمثل مع الارتفاعات المفاجئة في عدد الزيارات، اضبطه على قيمة أعلى قليلاً (مثلاً، ضعف القيمة).
• ضغط الذاكرة: يستهلك كلّ من MAX_MODEL_LEN وMAX_NUM_SEQS ذاكرة وحدة معالجة الرسومات لذاكرة التخزين المؤقت 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 باستخدام واجهة برمجة التطبيقات المتوافقة مع 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- تهانينا!

تهانينا على إكمال الدرس التطبيقي حول الترميز.

ننصحك بمراجعة مستندات Cloud Run.

المواضيع التي تحدثنا عنها

• كيفية نشر نموذج Gemma 4 على وحدة معالجة الرسومات RTX 6000 Pro في Cloud Run
• كيفية ضبط Direct VPC Egress وبث نموذج 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: حذف المشروع

لحذف المشروع بأكمله، انتقِل إلى إدارة الموارد، واختَر المشروع الذي أنشأته في الخطوة 2، ثم انقر على "حذف". إذا حذفت المشروع، عليك تغيير المشاريع في Cloud SDK. يمكنك الاطّلاع على قائمة بجميع المشاريع المتاحة من خلال تشغيل gcloud projects list.