Executar a inferência do modelo Gemma 4 no Cloud Run com GPU RTX 6000 Pro e vLLM

1. Introdução

Observação:este recurso está sujeito aos Termos da solução pré-GA na seção Termos gerais de serviço dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento

Visão geral

O que você vai aprender

• Como implantar um modelo Gemma 4 em uma GPU RTX 6000 Pro do Cloud Run
• Como usar vLLM e Run:ai Model Streamer para inferência mais rápida e inicialização de instâncias mais curta.

Gemma 4 é uma família de modelos de peso aberto licenciados pelo Apache 2 do Google DeepMind. Os modelos são multimodais, multilíngues, oferecem raciocínio e uma arquitetura eficiente. O Cloud Run é um ambiente sem servidor para contêineres com suporte a GPUs.

Observação:este codelab usa o modelo Gemma 4 31B Instruction-Tuned. O codelab demonstra como usar o Run:ai Model Streamer e a saída direta de VPC para minimizar o tempo que o modelo leva para carregar do Cloud Storage durante a inicialização do contêiner. Para mais informações, consulte o guia de práticas recomendadas para GPU.

2. Configuração e requisitos

Todo este laboratório pode ser executado na linha de comando. Você pode usar o Cloud Shell (clique no ícone de prompt na parte de cima à direita do console) para iniciar o ambiente.

Confira as variáveis de ambiente que serão usadas neste codelab. Você pode salvá-las em um arquivo de ambiente e "originar" o arquivo. Defina corretamente o valor do ID do projeto e, opcionalmente, a região.

# 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

Ativar as APIs necessárias 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. Criar a conta de serviço

Se você não especificar uma conta de serviço quando o serviço ou job do Cloud Run for criado, o Cloud Run vai usar a conta de serviço padrão do Compute Engine. Recomendamos uma conta de serviço separada para o serviço do Cloud Run para evitar a execução do serviço com permissões excessivas.

Criar uma conta de serviço para o serviço do Cloud Run

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

4. Configurar o Cloud Storage

Crie um bucket do Cloud Storage para armazenar os pesos do modelo. Isso permitirá o uso da saída direta de VPC para fazer o download dos pesos do modelo mais rapidamente sempre que o Cloud Run iniciar uma instância de serviço.

Combinado com o recurso Run:ai Model Streamer no vLLM, ele reduz significativamente o tempo de carregamento do modelo.

Criar um bucket

Verifique se é um bucket de região única localizado com o serviço do 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. Recuperar e armazenar em cache os pesos do modelo

Em seguida, faça o download do modelo Gemma 4 para o bucket do Cloud Storage. Os pesos dos modelos são dezenas de gigabytes, e o download deles para sua máquina local ou Cloud Shell pode ser inviável. Em vez disso, use o Cloud Build com armazenamento suficiente para armazenar os pesos do modelo.

Opção 1: copiar os pesos do modelo de um bucket compartilhado do Cloud Storage

O Google Cloud hospeda um bucket do Cloud Storage acessível publicamente com pesos do modelo Gemma 4.

Para copiá-los para o bucket de armazenamento, execute o comando:

gcloud builds submit --project="${GOOGLE_CLOUD_PROJECT}" --region="${GOOGLE_CLOUD_REGION}" --no-source \
    --substitutions="_MODEL_NAME=${MODEL_NAME},_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'
  - |
    gcloud config set storage/parallel_composite_upload_enabled True
    gcloud config set storage/parallel_composite_upload_threshold 150M
    gcloud config set storage/sliced_object_download_threshold 150M
    MODEL_NAME="$_MODEL_NAME"
    SHORT_NAME="$${MODEL_NAME#*/}"
    gcloud storage cp -r -D "gs://vertex-model-garden-public-us/gemma4/$${SHORT_NAME}" "$_GCS_MODEL_LOCATION"
options:
  machineType: 'E2_HIGHCPU_32'
  diskSizeGb: 500
EOF

Opção 2: fazer o download dos pesos do modelo do Hugging Face Hub

Como alternativa, os pesos do modelo podem ser recuperados diretamente do Hugging Face Hub.

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 config set storage/parallel_composite_upload_enabled True
    gcloud config set storage/parallel_composite_upload_threshold 150M
    gcloud storage cp -r "./model-cache/$_MODEL_NAME" "$_GCS_MODEL_LOCATION"
options:
  machineType: 'E2_HIGHCPU_32'
  diskSizeGb: 500
EOF

Isso usa uma máquina virtual bastante grande. Em vez disso, você também pode executar usando E2_HIGHCPU_8 ou até mesmo remover a linha machineType. É provável que o build leve mais tempo, mas também permite que você execute dentro de restrições de cota mais baixas.

6. Configurar a rede para saída direta de VPC

A configuração de saída direta de VPC requer a criação de uma rede e uma sub-rede com o Acesso privado do Google ativado.

Isso permite que os serviços do Cloud Run se conectem ao conjunto de endereços IP externos usados pelas APIs e serviços do Google, incluindo o Cloud Storage.

Criar uma rede

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

Criar uma sub-rede

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. Configurar a política de acesso da conta de serviço

A conta de serviço do Cloud Run precisa de permissões para acessar os pesos do modelo no bucket de armazenamento que você criou.

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. Inicializar variáveis de configuração

Defina as variáveis para o mecanismo de inferência vLLM e o serviço do 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

Observação sobre ajuste de desempenho:o ajuste dessas variáveis é um equilíbrio entre capacidade e latência:

• MAX_NUM_SEQS vs CLOUD_RUN_CONCURRENCY: CLOUD_RUN_CONCURRENCY precisa ser pelo menos tão grande quanto MAX_NUM_SEQS. Para uma utilização ideal com picos de tráfego, defina um valor um pouco maior (por exemplo, 2x).
• Pressão de memória: MAX_MODEL_LEN e MAX_NUM_SEQS consomem memória da GPU para o cache KV. Se você encontrar erros de memória insuficiente (OOM) com grandes comprimentos de contexto, considere reduzir MAX_NUM_SEQS.
• Latência: uma simultaneidade maior (MAX_NUM_SEQS) aumenta a capacidade total, mas pode aumentar a latência de solicitações individuais.
• Escalonamento: CLOUD_RUN_MAX_INSTANCES permite escalonar horizontalmente. Se a latência de instância única for aceitável, mas você precisar de mais capacidade total, aumente esse valor.

9. Implantar no Cloud Run

Preparar a linha de comando do contêiner vLLM

O vLLM requer muitos parâmetros para executar modelos grandes de forma rápida e eficiente. Esses parâmetros serão transmitidos como argumentos para o contêiner implantado no Cloud Run.

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

Implantar o serviço do Cloud Run

Execute o comando a seguir para implantar o serviço do Cloud Run. Observe o tipo de GPU (RTX 6000 Pro), a imagem de base (pytorch-vllm-serve:gemma4) e a necessidade de autenticação para invocar o serviço (--no-allow-unauthenticated).

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}" \
    --port=8080 \
    --timeout=3600 \
    --cpu-boost \
    --startup-probe tcpSocket.port=8080,initialDelaySeconds=240,failureThreshold=40,timeoutSeconds=10,periodSeconds=15 \
    --command "bash" \
    --args="^;^-c;${CONTAINER_ARGS_STR}"

Isso levará alguns minutos para ser implantado. Quando terminar, você terá um ambiente com tecnologia de GPU que serve o Gemma 4 usando uma infraestrutura sem servidor com escalonamento automático, incluindo o escalonamento para zero (sem tráfego, sem custo).

10. Testar o serviço

Depois de implantado, você pode interagir com o modelo Gemma 4 usando a API compatível com vLLM OpenAI.

Receber o URL do serviço

Recupere o URL do serviço do Cloud Run implantado.

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"

Executar inferência

Envie um comando para o modelo usando 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. Parabéns!

Parabéns por concluir o codelab.

Recomendamos revisar a documentação do Cloud Run.

O que aprendemos

• Como implantar o modelo Gemma 4 em uma GPU RTX 6000 Pro do Cloud Run
• Como configurar a saída direta de VPC e o streaming de modelos vLLM com o Cloud Storage para uma inicialização de serviço mais rápida.

12. Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Opção 1: excluir recursos

Exclua o serviço do Cloud Run

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

Exclua a conta de serviço

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

Exclua o bucket do Cloud Storage

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

Exclua a sub-rede e a rede 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

Opção 2: excluir o projeto

Para excluir todo o projeto, acesse Gerenciar recursos, selecione o projeto criado na etapa 2 e escolha Excluir. Se você excluir o projeto, será necessário mudar os projetos no Cloud SDK. Para conferir a lista de todos os projetos disponíveis, execute gcloud projects list. Se você quiser usar a linha de comando, também poderá usar este comando:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}