Esegui l'inferenza del modello Gemma 4 su Cloud Run con la GPU RTX 6000 Pro con vLLM

1. Introduzione

Nota: questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio

Panoramica

Obiettivi didattici

• Come eseguire il deployment di un modello Gemma 4 su una GPU Cloud Run RTX 6000 Pro
• Come utilizzare vLLM e Run:ai Model Streamer per un'inferenza più rapida e un avvio più breve dell'istanza.

Nota: questo codelab utilizza il modello Gemma 4 31B Instruction-Tuned. Il codelab mostra come utilizzare Run:ai Model Streamer e il traffico in uscita VPC diretto per ridurre al minimo il tempo necessario per caricare il modello da Cloud Storage durante l'avvio del container. Per ulteriori informazioni, consulta la guida alle best practice per le GPU.

2. Configurazione e requisiti

Imposta le variabili di ambiente che verranno utilizzate durante questo codelab:

# 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

Abilita le API necessarie per questo 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

3. Crea service account

Se non specifichi un service account quando viene creato il servizio o il job Cloud Run, Cloud Run utilizza il service account predefinito di Compute Engine. È consigliabile utilizzare un service account separato per il servizio Cloud Run per evitare di eseguire il servizio con autorizzazioni eccessive.

Crea un service account per il servizio Cloud Run

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

4. Configura Cloud Storage

Crea un bucket Cloud Storage per archiviare i pesi del modello. In questo modo, potrai utilizzare il traffico in uscita VPC diretto per scaricare più velocemente i pesi del modello ogni volta che Cloud Run avvia un'istanza del servizio.

In combinazione con la funzionalità Run:ai Model Streamer in vLLM, riduce notevolmente il tempo di caricamento del modello.

Crea un bucket

Assicurati che sia un bucket a regione singola collocato nella stessa regione del servizio 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. Recupera e memorizza nella cache i pesi del modello

Poi scarica il modello Gemma 4 nel bucket Cloud Storage.

I pesi dei modelli sono decine di gigabyte e potrebbe essere impossibile scaricarli sulla macchina locale o su Cloud Shell.

Utilizziamo invece Cloud Build con spazio di archiviazione sufficiente per contenere i pesi del modello.

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. Configura la rete per il traffico in uscita VPC diretto

La configurazione del traffico in uscita VPC diretto richiede la creazione di una rete e di una subnet con l'accesso privato Google abilitato.

In questo modo, i servizi Cloud Run possono connettersi all'insieme di indirizzi IP esterni utilizzati dalle API di Google e dai servizi, incluso Cloud Storage.

Crea una rete

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

Crea una 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. Configura il criterio di accesso del service account

Il service account Cloud Run deve disporre delle autorizzazioni per accedere ai pesi del modello nel bucket Storage che hai creato.

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. Inizializza le variabili di configurazione

Definisci le variabili sia per il motore di inferenza vLLM sia per il servizio 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

Nota sull'ottimizzazione per le prestazioni: l'ottimizzazione di queste variabili è un compromesso tra velocità effettiva e latenza:

• MAX_NUM_SEQS rispetto a CLOUD_RUN_CONCURRENCY: CLOUD_RUN_CONCURRENCY deve essere almeno uguale a MAX_NUM_SEQS. Per un utilizzo ottimale con picchi di traffico, impostalo leggermente più alto (ad es. 2 volte).
• Pressione della memoria: MAX_MODEL_LEN e MAX_NUM_SEQS utilizzano la memoria GPU per la cache KV. Se si verificano errori di memoria insufficiente (OOM) con lunghezze di contesto elevate, valuta la possibilità di ridurre MAX_NUM_SEQS.
• Latenza: una concorrenza più elevata (MAX_NUM_SEQS) aumenta la velocità effettiva totale, ma può aumentare la latenza delle singole richieste.
• Scalabilità: CLOUD_RUN_MAX_INSTANCES consente di scalare orizzontalmente. Se la latenza della singola istanza è accettabile, ma hai bisogno di una capacità totale maggiore, aumenta questo valore.

9. Esegui il deployment in Cloud Run

Prepara la riga di comando del container vLLM

vLLM richiede molti parametri per eseguire modelli di grandi dimensioni in modo rapido ed efficiente.

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

Esegui il deployment del servizio Cloud Run

Esegui questo comando per eseguire il deployment del servizio 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. Prova il servizio

Una volta eseguito il deployment, puoi interagire con il modello Gemma 4 utilizzando l'API compatibile con vLLM OpenAI.

Ottieni l'URL del servizio

Recupera l'URL del servizio Cloud Run di cui hai eseguito il deployment.

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"

Esegui l'inferenza

Invia un prompt al modello utilizzando 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. Complimenti!

Complimenti per aver completato il codelab.

Ti consigliamo di consultare la documentazione di Cloud Run.

Argomenti trattati

• Come eseguire il deployment del modello Gemma 4 su una GPU Cloud Run RTX 6000 Pro
• Come configurare il traffico in uscita VPC diretto e lo streaming del modello vLLM con Cloud Storage per un avvio più rapido del servizio.

12. Libera spazio

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, puoi eliminare il progetto o le singole risorse.

Opzione 1: elimina le risorse

Elimina il servizio Cloud Run

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

Elimina il service account

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

Elimina il bucket Cloud Storage

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

Elimina la rete VPC e la subnet

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

Opzione 2: elimina il progetto

Per eliminare l'intero progetto, vai a Gestisci risorse, seleziona il progetto creato nel passaggio 2 e scegli Elimina. Se elimini il progetto, dovrai cambiarlo in Cloud SDK. Puoi visualizzare l'elenco di tutti i progetti disponibili eseguendo gcloud projects list.