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 com licença 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 no canto superior direito 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 colocalizado 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.

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:

SHORT_NAME="${MODEL_NAME#*/}"
gcloud storage cp --recursive \
    "gs://vertex-model-garden-public-us/gemma4/${SHORT_NAME}" \
    "${GCS_MODEL_LOCATION}"

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. Os pesos dos modelos são dezenas de gigabytes, e fazer o download deles para sua máquina local ou Cloud Shell primeiro pode ser inviável. Em vez disso, use o Cloud Build com armazenamento suficiente para armazenar os pesos do 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

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 a otimização de desempenho:a otimização dessas variáveis é um equilíbrio entre capacidade de processamento 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

Excluir o serviço do Cloud Run

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

Excluir a conta de serviço

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

Excluir o bucket do Cloud Storage

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

Excluir 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. Você pode conferir a lista de todos os projetos disponíveis executando gcloud projects list. Se você quiser usar a linha de comando, também poderá usar este comando:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}