Executar agentes com modelos do Gemma 4 no Cloud Run

Neste guia, descrevemos como implantar modelos abertos do Gemma 4 no Cloud Run usando um contêiner pré-criado com a biblioteca de inferência vLLM e fornecemos orientações sobre como usar o serviço implantado do Cloud Run com agentes de IA criados usando o Kit de Desenvolvimento de Agente.

O Gemma 4 é a família de modelos de peso aberto mais eficiente do Google, com recursos agênticos e de raciocínio avançados.

O contexto longo, a multimodalidade, o raciocínio e a chamada de ferramentas permitem que o Gemma 4 lidar com lógica complexa, planejamento em várias etapas, programação e Agentic Workflows.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Configure o ambiente de desenvolvimento do Cloud Run no projeto do Google Cloud .
2. Instale e inicialize a CLI gcloud.
3. Verifique se você tem os seguintes papéis do IAM concedidos à sua conta:
   • Administrador do Cloud Run (roles/run.admin)
   • Administrador de projetos do IAM (roles/resourcemanager.projectIamAdmin)
   • Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer)

Saiba como conceder os papéis

Console

1. No console do Google Cloud , acesse a página IAM.

   Acessar IAM
2. Selecione o projeto.
3. Clique em Conceder acesso.

4. No campo Novos principais, digite seu identificador de usuário. Normalmente, esse é o endereço de e-mail usado para implantar o serviço do Cloud Run.

5. Na lista Selecionar papel, escolha um.
6. Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
7. Clique em Salvar.

gcloud

Para conceder os papéis do IAM necessários à sua conta no projeto:

        gcloud projects add-iam-policy-binding PROJECT_ID \
            --member=PRINCIPAL \
            --role=ROLE
        

Substitua:

• PROJECT_NUMBER pelo número do projeto do Google Cloud .
• PROJECT_ID pelo ID do projeto do Google Cloud .
• PRINCIPAL pela conta a que você está adicionando a vinculação. Normalmente, esse é o endereço de e-mail usado para implantar o serviço do Cloud Run.
• ROLE pelo papel que você está adicionando à conta de implantador.
4. Por padrão, os novos projetos recebem automaticamente uma cota de 3.000 milliGPUs na implantação inicial. Se você precisar de mais cota, solicite a cota Total Nvidia RTX Pro 6000 GPU allocation, in milli GPU, without zonal redundancy, per project per region na API Cloud Run Admin na página Cotas e limites do sistema.
5. Consulte a página de preços do Cloud Run. Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.

Implantar um modelo do Gemma 4 com um contêiner vLLM

O Gemma 4 oferece recursos agênticos avançados, incluindo raciocínio, chamada de função, geração de código e saída estruturada.

O Kit de Desenvolvimento de Agente (ADK) ajuda você a criar agentes de IA totalmente funcionais com o Gemma 4.

Use o vLLM para disponibilizar o Gemma como um endpoint de API OpenAI. O vLLM oferece uma disponibilização rápida e eficiente para modelos generativos em escala, com capacidade de disponibilização de última geração, gerenciamento de memória eficiente com PagedAttention, lote contínuo de solicitações recebidas, suporte à quantização e kernels CUDA otimizados.

Observação: o Gemma 4 26B e 31B exigem uma configuração mais avançada do Cloud Run e do vLLM com saída de VPC direta e o Run:ai Model Streamer.

Para implantar modelos do Gemma no Cloud Run, use o seguinte comando da CLI gcloud com as configurações recomendadas:

CONTAINER_ARGS=(
    "serve"
    "MODEL_NAME"
    "--enable-chunked-prefill"
    "--enable-prefix-caching"
    "--generation-config=auto"
    "--enable-auto-tool-choice"
    "--tool-call-parser=gemma4"
    "--reasoning-parser=gemma4"
    "--dtype=bfloat16"
    "--max-num-seqs=64"
    "--gpu-memory-utilization=0.95"
    "--tensor-parallel-size=1"
    "--port=8080"
    "--host=0.0.0.0"
)
gcloud beta run deploy SERVICE_NAME \
    --image "us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4" \
    --project PROJECT \
    --region REGION \
    --execution-environment gen2 \
    --no-allow-unauthenticated \
    --cpu 20 \
    --memory 80Gi \
    --gpu 1 \
    --gpu-type nvidia-rtx-pro-6000 \
    --no-gpu-zonal-redundancy \
    --no-cpu-throttling \
    --max-instances 3 \
    --concurrency 64 \
    --timeout 600 \
    --startup-probe tcpSocket.port=8080,initialDelaySeconds=240,failureThreshold=1,timeoutSeconds=240,periodSeconds=240 \
    --command "vllm" \
    --args=$(IFS=','; echo "${CONTAINER_ARGS[*]}")

Substitua:

• SERVICE_NAME por um nome exclusivo para o serviço do Cloud Run.
• PROJECT pelo ID do projeto do Google Cloud .

• REGION por uma região do Google Cloud em que as GPUs nvidia-rtx-pro-6000 são compatíveis com o Cloud Run, como us-central1. Para uma lista completa de regiões com disponibilidade para implantações com GPU, consulte Configuração de GPU.

• MODEL_NAME pelo nome completo de uma variante do Gemma 4.

  • Gemma 4 2B: google/gemma-4-E2B-it
  • Gemma 4 4B: google/gemma-4-E4B-it

As outras configurações são as seguintes:

Opção	Descrição
--concurrency	O número máximo de solicitações que podem ser processadas simultaneamente por uma determinada instância, como 8. Consulte Definir simultaneidade para performance ideal para recomendações sobre latência de solicitação ideal.
--cpu	A quantidade de CPU alocada para o serviço, como 20.
--set-env-vars	As variáveis de ambiente definidas para o serviço. Por exemplo, HF_TOKEN="..."
--gpu	O valor da GPU para seu serviço, como 1.
--gpu-type	O tipo de GPU a ser usado no serviço, como nvidia-rtx-pro-6000.
--max-instances	O número máximo de instâncias de contêiner do serviço, como 1.
--memory	A quantidade de memória alocada para o serviço, como 80Gi.
--no-invoker-iam-check	Desativar as verificações do IAM do invocador. Consulte o tutorial de serviços seguros do Cloud Run para ver recomendações sobre como melhorar a segurança do seu app.
--no-cpu-throttling	Essa configuração desativa a limitação de CPU quando o contêiner não está atendendo a solicitações ativamente.
--timeout	O tempo em que uma resposta precisa ser retornada, como 600 segundos.
--startup-probe	Configurações separadas por vírgulas para a sondagem de inicialização no formato CHAVE=VALOR. Consulte Sondagem de inicialização do Cloud Run para mais detalhes. Com os tamanhos de modelo do Gemma 4, se você não estiver usando a saída VPC direta, recomendamos definir o tempo limite da sondagem de inicialização como pelo menos 240 segundos.

Se você precisar modificar as configurações padrão ou adicionar configurações mais personalizadas ao serviço do Cloud Run, consulte Configurar serviços.

Após a conclusão do serviço implantado, uma mensagem de sucesso é exibida com o URL do endpoint do Cloud Run que termina com run.app.

Testar o serviço Gemma implantado com curl

Agora que você implantou o serviço do Gemma, é possível enviar solicitações para ele. No entanto, se você enviar uma solicitação diretamente, o Cloud Run responderá com HTTP 401 Unauthorized. Isso é intencional, porque uma API de inferência de LLM é destinada a outros serviços para chamada, como um aplicativo de front-end. Para mais informações sobre serviços no Cloud Run, consulte Como autenticar serviço a serviço.

Para enviar solicitações ao serviço do Gemma, adicione um cabeçalho com um token OIDC válido às solicitações, por exemplo, usando o proxy de desenvolvedor do Cloud Run:

1. Inicie o proxy e, quando solicitado a instalar o componente cloud-run-proxy, escolha Y:

   gcloud run services proxy SERVICE_NAME \
     --project PROJECT \
     --region REGION \
     --port=9090

2. Execute o comando a seguir para enviar uma solicitação em uma guia de terminal separada, deixando o proxy em execução. O proxy é executado em localhost:9090. Especifique o modelo do Gemma que você usou anteriormente:

   curl http://localhost:9090/v1/chat/completions \
     -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
     }'

   O comando vai fornecer uma saída semelhante a esta:

   {
    "id": "chatcmpl-9cf1ab1450487047",
    "object": "chat.completion",
    "created": 1774904187,
    "model": "google/gemma-4-E2B-it",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "The short answer is a phenomenon called **Rayleigh scattering**...",
          "function_call": null,
          "tool_calls": [],
          "reasoning": "*   Question: \"Why is the sky blue?\"\n..."
        },
        "finish_reason": "stop",
        "stop_reason": 106
      }
    ],
    "usage": {
      "prompt_tokens": 21,
      "total_tokens": 877,
      "completion_tokens": 856
    }
   }
   

   Sucesso :você implantou um serviço do Cloud Run com GPU com o Gemma 4 e enviou uma solicitação de inferência para ele.

Definir a simultaneidade para performance ideal

Nesta seção, fornecemos contexto sobre as configurações de simultaneidade recomendadas. Para uma latência de solicitação ideal, verifique se a configuração --concurrency é igual ao argumento de linha de comando --max-num-seqs do vLLM.

• --max-num-seqs determina quantas sequências (solicitações) estão disponíveis para cada instância do vLLM para processar a inferência simultaneamente.
• --concurrency determina quantas solicitações o Cloud Run envia para uma instância do vLLM ao mesmo tempo.

Se --concurrency exceder --max-num-seqs, o Cloud Run poderá enviar mais solicitações a uma instância do vLLM do que os slots disponíveis para ele. Isso leva à formação de filas de solicitações no vLLM, aumentando a latência das solicitações na fila. Isso também leva a um escalonamento automático menos responsivo, já que as solicitações em fila não acionam o Cloud Run para escalonar horizontalmente e iniciar novas instâncias.

Para evitar completamente a fila de solicitações na instância do vLLM, defina --concurrency para corresponder a --max-num-seqs.

É importante observar que aumentar --max-num-seqs também faz com que as solicitações paralelas demorem mais e requer mais memória de GPU para o cache de chave-valor.

Utilização otimizada

Para uma utilização ideal da GPU, aumente --concurrency, mantendo-o dentro do dobro do valor de --max-num-seqs. Embora isso leve à fila de solicitações no vLLM, ele pode ajudar a melhorar a utilização: as instâncias do vLLM podem processar imediatamente as solicitações da fila, e as filas ajudam a absorver picos de tráfego.

Criar agentes de IA com o Kit de Desenvolvimento de Agente usando o Gemma 4

Depois de implantar o serviço do Cloud Run, use o endpoint do Cloud Run com o Gemma 4 para criar agentes de IA com o Kit de Desenvolvimento de Agente.

Antes de usar o Kit de Desenvolvimento de Agente, verifique se as solicitações recebidas transmitem o token de identidade apropriado. Para saber mais sobre como usar a autenticação do IAM e o Cloud Run, consulte Como autenticar serviço a serviço.

O exemplo a seguir mostra como usar o Kit de Desenvolvimento de Agente em Python com a autenticação do IAM:

import subprocess
from google.adk.models.lite_llm import LiteLlm
from google.adk.agents import Agent

# Get the identity token using gcloud
id_token = subprocess.run(
    ["gcloud", "auth", "print-identity-token"],
    capture_output=True, text=True
).stdout.strip()

gemma_model = LiteLlm(
    model=f'openai/MODEL_NAME',
    base_url='https://YOUR_CLOUD_RUN_SERVICE_URL/v1',
    extra_body={
        "chat_template_kwargs": {
            "enable_thinking": True
        },
        "skip_special_tokens": False
    },
    extra_headers={
        "Authorization": f"Bearer {id_token}",
    },
)

root_agent = Agent(
    model=gemma_model,
    name='assistant',
    instruction="You are a helpful assistant",
)

Limpar

Exclua os seguintes recursos do Google Cloud criados:

• Serviço do Cloud Run

A seguir

• Para modelos de IA maiores e um tempo de inicialização mais rápido com o Run:ai Model Streamer, use o codelab Executar inferência do modelo Gemma 4 no Cloud Run com a GPU RTX 6000 Pro com vLLM.
• Configurar a GPU
• Práticas recomendadas: inferência de IA no Cloud Run com GPUs
• Executar modelos do Gemma 4 com vários frameworks de ambiente de execução de IA