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

1. مقدمة

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

نظرة عامة

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

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

ملاحظة: يستخدم هذا الدرس التطبيقي حول الترميز نموذج Gemma 4 31B المحسَّن بالتعليمات. يوضّح الدرس التطبيقي حول الترميز كيفية استخدام 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 لتخزين أوزان النموذج. سيسمح ذلك باستخدام ميزة "الخروج المباشر من سحابة 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. ضبط إعدادات الشبكة للخروج المباشر من سحابة VPC

يتطلّب إعداد الخروج المباشر من سحابة VPC إنشاء شبكة وشبكة فرعية مع تفعيل الوصول الخاص إلى 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}"
    "--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 باستخدام واجهة برمجة التطبيقات المتوافقة مع vLLM OpenAI.

الحصول على عنوان 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.