vLLM ile RTX 6000 Pro GPU'lu Cloud Run'da Gemma 4 modelinin çıkarımını çalıştırma

1. Giriş

Not: Bu özellik, Hizmete Özel Şartlar'ın Genel Hizmet Şartları bölümündeki "GKST Öncesi Teklif Şartları"na tabidir. GKST öncesi özellikler "olduğu gibi" sunulur ve desteği sınırlı olabilir. Daha fazla bilgi için lansman aşamalarının açıklamalarını inceleyin.

Genel Bakış

Neler öğreneceksiniz?

• Cloud Run RTX 6000 Pro GPU'da Gemma 4 modelini dağıtma
• Daha hızlı çıkarım ve daha kısa örnek başlatma için vLLM ve Run:ai Model Streamer'ı kullanma

Not: Bu codelab'de Gemma 4 31B Instruction-Tuned modeli kullanılmaktadır. Bu codelab'de, Run:ai Model Streamer ve doğrudan VPC çıkışının, kapsayıcı başlatma sırasında modelin Cloud Storage'dan yüklenmesi için gereken süreyi nasıl en aza indirdiği gösterilmektedir. Daha fazla bilgi için GPU en iyi uygulamalar kılavuzunu inceleyin.

2. Kurulum ve Gereksinimler

Bu codelab boyunca kullanılacak ortam değişkenlerini ayarlayın:

# 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

Bu Codelab için gereken API'leri etkinleştirin

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. Hizmet hesabı oluşturma

Cloud Run hizmeti veya işi oluşturulurken bir hizmet hesabı belirtmezseniz Cloud Run, varsayılan Compute Engine hizmet hesabını kullanır. Hizmeti aşırı izinlerle çalıştırmamak için Cloud Run hizmeti için ayrı bir hizmet hesabı kullanılması önerilir.

Cloud Run hizmeti için hizmet hesabı oluşturma

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

4. Cloud Storage'ı kurma

Model ağırlıklarını depolamak için bir Cloud Storage paketi oluşturun. Bu işlem, Cloud Run her hizmet örneğini başlattığında model ağırlıklarının daha hızlı indirilmesi için doğrudan VPC çıkışının kullanılmasına olanak tanır.

vLLM'deki Run:ai Model Streamer özelliğiyle birlikte kullanıldığında model yükleme süresini önemli ölçüde azaltır.

Paket oluşturma

Paketin, Cloud Run hizmetiyle aynı konumda bulunan tek bölgeli bir paket olduğundan emin olun.

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

5. Model Ağırlıklarını Alma ve Önbelleğe Alma

Ardından, Gemma 4 modelini Cloud Storage paketinize indirin.

Model ağırlıkları onlarca gigabayt olduğundan bunları yerel makinenize veya Cloud Shell'e indirmeniz mümkün olmayabilir.

Bunun yerine, model ağırlıklarını tutacak kadar depolama alanına sahip Cloud Build'i kullanırız.

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. Doğrudan VPC çıkışı için ağı yapılandırma

Doğrudan VPC çıkışı yapılandırması için Özel Google Erişimi'nin etkin olduğu bir ağ ve alt ağ oluşturulması gerekir.

Bu sayede Cloud Run hizmetleri, Cloud Storage dahil olmak üzere Google API'leri ve hizmetleri tarafından kullanılan harici IP adresleri grubuna bağlanabilir.

Ağ oluşturma

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

Alt ağ oluşturma

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. Hizmet hesabı erişim politikasını yapılandırma

Cloud Run hizmet hesabının, oluşturduğunuz depolama paketindeki model ağırlıklarına erişme izni olması gerekir.

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. Yapılandırma Değişkenlerini Başlatma

Hem vLLM çıkarım motoru hem de Cloud Run hizmeti için değişkenleri tanımlayın.

# 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

Performans için ayarlama ile ilgili not: Bu değişkenlerin ayarlanması, işleme hızı ve gecikme arasında bir denge kurmayı gerektirir:

• MAX_NUM_SEQS - CLOUD_RUN_CONCURRENCY: CLOUD_RUN_CONCURRENCY, en az MAX_NUM_SEQS kadar büyük olmalıdır. Trafik artışlarında optimum kullanım için bu değeri biraz daha yüksek (ör. 2 kat) ayarlayın.
• Bellek Baskısı: MAX_MODEL_LEN ve MAX_NUM_SEQS, KV önbelleği için GPU belleğini tüketir. Büyük bağlam uzunluklarında bellek yetersiz (OOM) hatalarıyla karşılaşırsanız MAX_NUM_SEQS değerini düşürmeyi deneyin.
• Gecikme: Daha yüksek eşzamanlılık (MAX_NUM_SEQS), toplam işleme hızını artırır ancak tek tek isteklerin gecikmesini de artırabilir.
• Ölçeklendirme: CLOUD_RUN_MAX_INSTANCES yatay olarak ölçeklendirmenize olanak tanır. Tek örnek gecikmeniz kabul edilebilir düzeydeyse ancak daha fazla toplam kapasiteye ihtiyacınız varsa bu değeri artırın.

9. Cloud Run'a dağıt

vLLM Container komut satırını hazırlama

vLLM, büyük modelleri hızlı ve verimli bir şekilde çalıştırmak için çok sayıda parametre gerektirir.

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 hizmetini dağıtma

Cloud Run hizmetini dağıtmak için aşağıdaki komutu çalıştırın.

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. Hizmeti test etme

Dağıtım tamamlandıktan sonra vLLM OpenAI uyumlu API'yi kullanarak Gemma 4 modelinizle etkileşim kurabilirsiniz.

Hizmet URL'sini alma

Dağıtılan Cloud Run hizmetinizin URL'sini alın.

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"

Çıkarım Çalıştırma

curl kullanarak modele bir istem gönderin.

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. Tebrikler!

Tebrikler, codelab'i tamamladınız.

Cloud Run belgelerini incelemenizi öneririz.

İşlediğimiz konular

• Gemma 4 modelini Cloud Run RTX 6000 Pro GPU'ya dağıtma
• Daha hızlı hizmet başlatma için Cloud Storage ile doğrudan VPC çıkışını ve vLLM modeli akışını yapılandırma

12. Temizleme

Bu eğiticide kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız projeyi veya tek tek kaynakları silebilirsiniz.

1. seçenek: Kaynakları silme

Cloud Run hizmetini silme

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

Hizmet Hesabını Silme

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

Cloud Storage paketini silme

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

VPC ağını ve alt ağı silme

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. seçenek: Projeyi silme

Projenin tamamını silmek için Kaynakları Yönet'e gidin, 2. adımda oluşturduğunuz projeyi seçin ve Sil'i tıklayın. Projeyi silerseniz Cloud SDK'nızda projeleri değiştirmeniz gerekir. gcloud projects list komutunu çalıştırarak kullanılabilir tüm projelerin listesini görüntüleyebilirsiniz.