Ejecuta la inferencia del modelo Gemma 4 en Cloud Run con la GPU RTX 6000 Pro y vLLM

1. Introducción

Nota: Esta función está sujeta a las “Condiciones de la oferta de la fase previa a la DG” en la sección Condiciones del servicio generales de las Condiciones específicas del servicio. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Descripción general

Qué aprenderás

• Cómo implementar un modelo de Gemma 4 en una GPU RTX 6000 Pro de Cloud Run
• Cómo usar vLLM y Run:ai Model Streamer para lograr una inferencia más rápida y un inicio de instancia más corto

Nota: En este codelab, se usa el modelo Gemma 4 31B Instruction-Tuned. En el codelab, se muestra cómo usar Run:ai Model Streamer y la salida de VPC directa para minimizar el tiempo que tarda el modelo en cargarse desde Cloud Storage durante el inicio del contenedor. Para obtener más información, consulta la guía de prácticas recomendadas para GPU.

2. Configuración y requisitos

Configura las variables de entorno que se usarán en este 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

Habilita las APIs necesarias para este 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. Crear una cuenta de servicio.

Si no especificas una cuenta de servicio cuando se crea el trabajo o servicio de Cloud Run, Cloud Run usa la cuenta de servicio predeterminada de Compute Engine. Se recomienda usar una cuenta de servicio independiente para el servicio de Cloud Run y evitar ejecutar el servicio con permisos excesivos.

Crea una cuenta de servicio para el servicio de 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 de Cloud Storage para almacenar los pesos del modelo. Esto permitirá usar la salida de VPC directa para descargar los pesos del modelo más rápido cada vez que Cloud Run inicie una instancia de servicio.

En combinación con la función Model Streamer de Run:ai en vLLM, reduce significativamente el tiempo de carga del modelo.

Crea un bucket

Asegúrate de que sea un bucket de una sola región ubicado junto con el servicio de 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. Cómo recuperar y almacenar en caché los pesos del modelo

A continuación, descarga el modelo Gemma 4 en tu bucket de Cloud Storage.

Los pesos de los modelos son de decenas de gigabytes, por lo que es posible que no puedas descargarlos en tu máquina local o en Cloud Shell.

En cambio, usamos Cloud Build con suficiente almacenamiento para contener los pesos del modelo.

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 las redes para la salida de VPC directa

La configuración de la salida de VPC directa requiere la creación de una red y una subred con el Acceso privado a Google habilitado.

Esto permite que los servicios de Cloud Run se conecten al conjunto de direcciones IP externas que usan las APIs y los servicios de Google, incluido Cloud Storage.

Crea una red

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

Crea una subred

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 política de acceso a la cuenta de servicio

La cuenta de servicio de Cloud Run necesita permisos para acceder a los pesos del modelo en el bucket de Storage que creaste.

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. Inicializa variables de configuración

Define las variables para el motor de inferencia de vLLM y el servicio de 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 sobre el ajuste para el rendimiento: El ajuste de estas variables es un equilibrio entre la capacidad de procesamiento y la latencia:

• MAX_NUM_SEQS vs CLOUD_RUN_CONCURRENCY: CLOUD_RUN_CONCURRENCY debe ser al menos tan grande como MAX_NUM_SEQS. Para una utilización óptima con aumentos repentinos de tráfico, configúralo un poco más alto (p.ej., 2 veces).
• Presión de memoria: MAX_MODEL_LEN y MAX_NUM_SEQS consumen memoria de GPU para la caché de KV. Si encuentras errores de memoria insuficiente (OOM) con longitudes de contexto grandes, considera reducir MAX_NUM_SEQS.
• Latencia: Una mayor simultaneidad (MAX_NUM_SEQS) aumenta la capacidad de procesamiento total, pero puede aumentar la latencia de las solicitudes individuales.
• Ajuste de escala: CLOUD_RUN_MAX_INSTANCES te permite ajustar la escala horizontalmente. Si la latencia de una sola instancia es aceptable, pero necesitas más capacidad total, aumenta este valor.

9. Implementa en Cloud Run

Prepara la línea de comandos del contenedor de vLLM

vLLM requiere muchos parámetros para ejecutar modelos grandes de forma rápida y eficiente.

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

Implementa el servicio de Cloud Run

Ejecuta el siguiente comando para implementar el servicio de 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. Prueba el servicio

Una vez que se implemente, podrás interactuar con tu modelo de Gemma 4 a través de la API compatible con OpenAI de vLLM.

Obtén la URL de servicio

Recupera la URL de tu servicio de Cloud Run implementado.

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"

Ejecuta la inferencia

Envía una instrucción al modelo con 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. ¡Felicitaciones!

¡Felicitaciones por completar el codelab!

Te recomendamos que revises la documentación de Cloud Run.

Temas abordados

• Cómo implementar el modelo Gemma 4 en una GPU RTX 6000 Pro de Cloud Run
• Cómo configurar la salida de VPC directa y la transmisión de modelos de vLLM con Cloud Storage para un inicio más rápido del servicio

12. Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, puedes borrar el proyecto o los recursos individuales.

Opción 1: Borra los recursos

Borra el servicio de Cloud Run

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

Borra la cuenta de servicio

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

Borra el bucket de Cloud Storage

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

Borra la red de VPC y la subred

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

Opción 2: Borra el proyecto

Para borrar todo el proyecto, ve a Administrar recursos, selecciona el proyecto que creaste en el paso 2 y elige Borrar. Si borras el proyecto, deberás cambiar de proyecto en el SDK de Cloud. Para ver la lista de todos los proyectos disponibles, ejecuta gcloud projects list.