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 Gemma 4 en una GPU RTX 6000 Pro de Cloud Run
• Cómo usar vLLM y Run:ai Model Streamer para obtener 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. El codelab 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

Establece 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=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 un trabajo o servicio de Cloud Run, Cloud Run usa la cuenta de servicio predeterminada de Compute Engine. Se recomienda una cuenta de servicio independiente para el servicio de Cloud Run para 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 Run:ai Model Streamer 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. Recupera y almacena 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 decenas de gigabytes, y descargarlos en tu máquina local o Cloud Shell puede ser imposible.

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 la red 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 de 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 las variables de configuración

Define las variables para el motor de inferencia 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 un uso óptimo con picos 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 simultaneidad más alta (MAX_NUM_SEQS) aumenta la capacidad de procesamiento total, pero puede aumentar la latencia de la solicitud individual.
• Ajuste de escala: CLOUD_RUN_MAX_INSTANCES te permite escalar 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 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}"
    "--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 implementado, puedes interactuar con tu modelo Gemma 4 mediante la API compatible con vLLM OpenAI.

Obtén la URL del 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 vLLM con Cloud Storage para un inicio de servicio más rápido

12. Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o borra 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 los proyectos en tu SDK de Cloud. Para ver la lista de todos los proyectos disponibles, ejecuta gcloud projects list.