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 saperne di più, 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 saperne di più, consulta la guida alle best practice per le GPU.

2. Configurazione e requisiti

Imposta le variabili di ambiente che verranno utilizzate in 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. Per evitare di eseguire il servizio con autorizzazioni eccessive, è consigliabile utilizzare un service account separato per il servizio Cloud Run.

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. Configurare Cloud Storage

Crea un bucket Cloud Storage per archiviare i pesi del modello. In questo modo, potrai utilizzare l'uscita VPC diretto per scaricare più rapidamente i pesi del modello ogni volta che Cloud Run avvia un'istanza di 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 insieme al 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. Recuperare e memorizzare nella cache i pesi del modello

Successivamente, scarica il modello Gemma 4 nel bucket Cloud Storage.

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

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 il networking per l'uscita VPC diretto

La configurazione dell'uscita VPC diretta richiede la creazione di una rete e di una subnet con l'accesso privato Google abilitato.

Ciò consente ai servizi Cloud Run di connettersi all'insieme di indirizzi IP esterni utilizzati dalle API di Google e dai servizi Google, 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 la policy di accesso al service account

L'account di servizio 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. Inizializzare le variabili di configurazione

Definisci le variabili per il motore di inferenza vLLM e 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 sulla regolazione per il rendimento:la regolazione di queste variabili è un equilibrio tra velocità effettiva e latenza:

• MAX_NUM_SEQS rispetto a CLOUD_RUN_CONCURRENCY: CLOUD_RUN_CONCURRENCY deve essere almeno grande quanto MAX_NUM_SEQS. Per un utilizzo ottimale con i picchi di traffico, impostalo su un valore leggermente superiore (ad es. 2x).
• Pressione della memoria: MAX_MODEL_LEN e MAX_NUM_SEQS consumano memoria GPU per la cache KV. Se riscontri errori di memoria insufficiente (OOM) con lunghezze del contesto elevate, valuta la possibilità di ridurre MAX_NUM_SEQS.
• Latenza: una concorrenza più elevata (MAX_NUM_SEQS) aumenta il throughput totale, ma può aumentare la latenza delle singole richieste.
• Scalabilità: CLOUD_RUN_MAX_INSTANCES consente di scalare orizzontalmente. Se la latenza di una 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}"
    "--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[*]}"

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. Testare il servizio

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

Recuperare l'URL del servizio

Recupera l'URL del servizio Cloud Run di cui è stato 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 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!

Congratulazioni 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. Esegui la pulizia

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 che hai creato nel passaggio 2 e scegli Elimina. Se elimini il progetto, dovrai cambiare progetto in Cloud SDK. Puoi visualizzare l'elenco di tutti i progetti disponibili eseguendo gcloud projects list.