Menjalankan inferensi model Gemma 4 di Cloud Run dengan GPU RTX 6000 Pro menggunakan vLLM

1. Pengantar

Catatan: Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "apa adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran

Ringkasan

Yang akan Anda pelajari

• Cara men-deploy model Gemma 4 di GPU Cloud Run RTX 6000 Pro
• Cara menggunakan vLLM dan Run:ai Model Streamer untuk inferensi yang lebih cepat dan startup instance yang lebih singkat.

Catatan: Codelab ini menggunakan model Gemma 4 31B Instruction-Tuned. Codelab ini menunjukkan cara menggunakan Run:ai Model Streamer dan Direct VPC Egress untuk meminimalkan waktu yang diperlukan model untuk dimuat dari Cloud Storage selama startup container. Untuk mengetahui informasi selengkapnya, lihat panduan praktik terbaik GPU.

2. Penyiapan dan Persyaratan

Tetapkan variabel lingkungan yang akan digunakan di seluruh codelab ini:

# 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

Aktifkan API yang diperlukan untuk Codelab ini

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. Buat Akun Layanan

Jika Anda tidak menentukan akun layanan saat layanan atau tugas Cloud Run dibuat, Cloud Run akan menggunakan akun layanan default Compute Engine. Sebaiknya gunakan Akun Layanan terpisah untuk layanan Cloud Run guna menghindari menjalankan layanan dengan izin yang berlebihan.

Membuat Akun Layanan untuk layanan Cloud Run

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

4. Menyiapkan Cloud Storage

Buat bucket Cloud Storage untuk menyimpan bobot model. Hal ini akan memungkinkan penggunaan Direct VPC Egress untuk mendownload bobot model lebih cepat setiap kali Cloud Run memulai instance layanan.

Jika dikombinasikan dengan fitur Run:ai Model Streamer di vLLM, waktu pemuatan model akan berkurang secara signifikan.

Membuat bucket

Pastikan bucket tersebut adalah bucket satu region yang ditempatkan bersama dengan layanan 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. Mengambil dan Menyimpan Bobot Model ke Cache

Selanjutnya, download model Gemma 4 ke bucket Cloud Storage Anda.

Bobot model berukuran puluhan gigabyte, dan mendownloadnya ke komputer lokal atau Cloud Shell mungkin tidak memungkinkan.

Sebagai gantinya, kita akan menggunakan Cloud Build dengan penyimpanan yang cukup untuk menyimpan bobot model.

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. Mengonfigurasi Jaringan untuk Direct VPC Egress

Konfigurasi Direct VPC Egress memerlukan pembuatan jaringan dan subnet dengan Akses Google Pribadi yang diaktifkan.

Hal ini memungkinkan layanan Cloud Run terhubung ke kumpulan alamat IP eksternal yang digunakan oleh Google API dan layanan, termasuk Cloud Storage.

Membuat Jaringan

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

Membuat Subnet

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. Mengonfigurasi Kebijakan Akses Akun Layanan

Akun Layanan Cloud Run memerlukan izin untuk mengakses bobot model di Bucket Penyimpanan yang Anda buat.

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. Menginisialisasi Variabel Konfigurasi

Tentukan variabel untuk mesin inferensi vLLM dan layanan 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

Catatan tentang Penyesuaian untuk Performa: Penyesuaian variabel ini adalah keseimbangan antara throughput dan latensi:

• MAX_NUM_SEQS vs CLOUD_RUN_CONCURRENCY: CLOUD_RUN_CONCURRENCY harus setidaknya sebesar MAX_NUM_SEQS. Untuk penggunaan yang optimal dengan lonjakan traffic, tetapkan nilai ini sedikit lebih tinggi (misalnya, 2x).
• Tekanan Memori: MAX_MODEL_LEN dan MAX_NUM_SEQS menggunakan memori GPU untuk cache KV. Jika Anda mengalami error Kehabisan Memori (OOM) dengan panjang konteks yang besar, pertimbangkan untuk mengurangi MAX_NUM_SEQS.
• Latensi: Concurrency yang lebih tinggi (MAX_NUM_SEQS) meningkatkan total throughput, tetapi dapat meningkatkan latensi permintaan individual.
• Penskalaan: CLOUD_RUN_MAX_INSTANCES memungkinkan Anda melakukan penskalaan secara horizontal. Jika latensi instance tunggal Anda dapat diterima, tetapi Anda memerlukan kapasitas total yang lebih besar, tingkatkan nilai ini.

9. Men-deploy ke Cloud Run

Menyiapkan Command Line Container vLLM

vLLM memerlukan banyak parameter untuk menjalankan model besar dengan cepat dan efisien.

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[*]}"

Men-deploy Layanan Cloud Run

Jalankan perintah berikut untuk men-deploy layanan 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. Menguji Layanan

Setelah di-deploy, Anda dapat berinteraksi dengan model Gemma 4 menggunakan vLLM API yang kompatibel dengan OpenAI.

Mendapatkan URL Layanan

Ambil URL layanan Cloud Run yang di-deploy.

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"

Menjalankan Inferensi

Kirim perintah ke model menggunakan 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. Selamat!

Selamat, Anda telah menyelesaikan codelab ini.

Sebaiknya tinjau dokumentasi Cloud Run.

Yang telah kita bahas

• Cara men-deploy model Gemma 4 di GPU Cloud Run RTX 6000 Pro
• Cara mengonfigurasi Direct VPC Egress dan streaming model vLLM dengan Cloud Storage untuk startup layanan yang lebih cepat.

12. Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, Anda dapat menghapus project atau menghapus setiap resource.

Opsi 1: Menghapus Resource

Menghapus Layanan Cloud Run

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

Menghapus Akun Layanan

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

Menghapus Bucket Cloud Storage

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

Menghapus Jaringan dan Subnet 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

Opsi 2: Menghapus Project

Untuk menghapus seluruh project, buka Mengelola Resource, pilih project yang Anda buat di Langkah 2, lalu pilih Hapus. Jika Anda menghapus project, Anda harus mengubah project di Cloud SDK. Anda dapat melihat daftar semua project yang tersedia dengan menjalankan gcloud projects list.