Executar agentes com modelos do Gemma 4 no Cloud Run

Este guia descreve como implantar modelos abertos do Gemma 4 no Cloud Run usando um contêiner pré-criado com a biblioteca de inferência vLLM e fornece orientações sobre como usar o serviço do Cloud Run implantado 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, oferecendo recursos de raciocínio e de agente.

O contexto longo, a multimodalidade, o raciocínio e a chamada de ferramentas permitem que o Gemma 4 processe lógica complexa, planejamento de várias etapas, programação e fluxos de trabalho de agentes.

Antes de começar

Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloud, 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.

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 seu Google Cloud projeto do.
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 Google Cloud console, 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 necessários do IAM à sua conta no seu projeto:

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

Substitua:

• PROJECT_NUMBER pelo número do projeto. Google Cloud
• PROJECT_ID pelo ID do Google Cloud projeto.
• PRINCIPAL pela conta a que você está adicionando a vinculação. Normalmente, esse é o endereço de e-mail que é usado para implantar o serviço do Cloud Run.
• ROLE pelo papel que você está adicionando à conta do implantador.
4. Se necessário, 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, use a calculadora de preços.

Implantar um modelo Gemma 4 com um contêiner vLLM

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

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

Use vLLM para disponibilizar o Gemma como um endpoint de API OpenAI. O vLLM oferece 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, loteamento 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 VPC direta e Run:ai Model Streamer.

Para implantar modelos 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 Google Cloud .

• REGION por uma Google Cloud região em que nvidia-rtx-pro-6000 GPUs são compatíveis com o Cloud Run, como us-central1. Para uma lista completa de regiões compatíveis com 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 a latência ideal da solicitação.
--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 o serviço, como 1.
--gpu-type	O tipo de GPU a ser usado para o serviço, como nvidia-rtx-pro-6000.
--max-instances	O número máximo de instâncias de contêiner para o 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 Proteger serviços do Cloud Run para recomendações sobre como proteger melhor seu app.
--no-cpu-throttling	Essa configuração desativa a limitação de CPU quando o contêiner não está veiculando 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 KEY=VALUE. Consulte a sondagem de inicialização do Cloud Run para mais detalhes. Com tamanhos de modelo do Gemma 4, se você não estiver usando Saída VPC Direta, é recomendável definir o tempo limite da verificação de inicialização para 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 será 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 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 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 seguinte comando 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 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
     }'

   Esse 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
    }
   }
   

   Muito bem! Você implantou um serviço do Cloud Run com aceleração de GPU com o Gemma 4 e enviou uma solicitação de inferência.

Definir 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 exige mais memória da GPU para o cache KV.

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, você pode usar 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 Google Cloud recursos criados:

• Serviço do Cloud Run

A seguir

• Para modelos maiores e tempo de inicialização mais rápido com 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 Gemma 4 com várias estruturas de tempo de execução de IA