Ejecuta agentes con modelos de Gemma 4 en Cloud Run

En esta guía, se describe cómo implementar modelos abiertos de Gemma 4 en Cloud Run con un contenedor precompilado con la biblioteca de inferencia de vLLM y se proporcionan instrucciones para usar el servicio de Cloud Run implementado con agentes de IA creados con el Kit de desarrollo de agentes.

Gemma 4 es la familia de modelos de código abierto más eficiente de Google, que ofrece sólidas capacidades de razonamiento y de agentes.

El contexto largo, la multimodalidad, el razonamiento y la llamada a herramientas permiten que Gemma 4 controle la lógica compleja, la planificación de varios pasos, la codificación y los flujos de trabajo de agentes.

Antes de comenzar

Accede a tu Google Cloud cuenta de. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Configura tu entorno de desarrollo de Cloud Run en tu Google Cloud proyecto.
Instala e inicializa gcloud CLI.
Asegúrate de tener los siguientes roles de IAM otorgados a tu cuenta:
- Administrador de Cloud Run (roles/run.admin)
- Administrador de IAM de proyecto (roles/resourcemanager.projectIamAdmin)
- Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer)

Obtén más información para otorgar los roles

Console

En la Google Cloud consola de, dirígete a la página IAM.
Ir a IAM
Selecciona el proyecto.
Haz clic en Grant access.
En el campo Principales nuevas, ingresa tu identificador de usuario. Por lo general, es la dirección de correo electrónico que se usa para implementar el servicio de Cloud Run.
En la lista Seleccionar un rol, elige uno.
Para otorgar roles adicionales, haz clic en Agregar otro rol y agrega uno más.
Haz clic en Guardar.

gcloud

Para otorgar los roles de IAM necesarios a tu cuenta en tu proyecto, haz lo siguiente:

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

Reemplaza lo siguiente:

PROJECT_NUMBER por el número de tu Google Cloud proyecto
PROJECT_ID por el ID del Google Cloud proyecto
PRINCIPAL por la cuenta a la que agregarás la vinculación. Por lo general, es la dirección de correo electrónico que se usa para implementar el servicio de Cloud Run.
ROLE por el rol que agregas a la cuenta del implementador.

Si es necesario, solicita la cuota Total Nvidia RTX Pro 6000 GPU allocation, in milli GPU, without zonal redundancy, per project per region en la API de Cloud Run Admin en la página Cuotas y límites del sistema.
Revisa la página de precios de Cloud Run. Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.

Implementa un modelo de Gemma 4 con un contenedor de vLLM

Gemma 4 ofrece capacidades avanzadas de agentes, como razonamiento, llamada a funciones, generación de código y salida estructurada.

El Kit de desarrollo de agentes (ADK) te ayuda a crear agentes de IA completamente funcionales con Gemma 4.

Usa vLLM para entregar Gemma como un extremo de API de OpenAI. vLLM proporciona una entrega rápida y eficiente para modelos generativos a gran escala, con un rendimiento de entrega de vanguardia, una administración de memoria eficiente con PagedAttention, el procesamiento por lotes continuo de solicitudes entrantes, compatibilidad con la cuantización y kernels de CUDA optimizados.

Para implementar modelos de Gemma en Cloud Run, usa el siguiente comando de gcloud CLI con la configuración recomendada:

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

Reemplaza lo siguiente:

SERVICE_NAME por un nombre único para el servicio de Cloud Run.
PROJECT con tu Google Cloud ID del proyecto.
REGION por una Google Cloud región en la que se admitan las GPUs nvidia-rtx-pro-6000 para Cloud Run, como us-central1. Para obtener una lista completa de las regiones admitidas para las implementaciones habilitadas para GPU, consulta Configuración de GPU.
MODEL_NAME por el nombre completo de una variante de Gemma 4.
- Gemma 4 2B: google/gemma-4-E2B-it
- Gemma 4 4B: google/gemma-4-E4B-it

La otra configuración es la siguiente:

Opción	Descripción
`--concurrency`	Es la cantidad máxima de solicitudes que una instancia determinada puede procesar de forma simultánea, como `8`. Consulta Configura la simultaneidad para obtener un rendimiento óptimo para obtener recomendaciones sobre la latencia de solicitud óptima.
`--cpu`	Es la cantidad de CPU asignada para tu servicio, como `20`.
`--set-env-vars`	Son las variables de entorno configuradas para tu servicio. Por ejemplo, `HF_TOKEN="..."`
`--gpu`	Es el valor de GPU para tu servicio, como `1`.
`--gpu-type`	Es el tipo de GPU que se usará para tu servicio, como `nvidia-rtx-pro-6000`.
`--max-instances`	Es la cantidad máxima de instancias de contenedor para tu servicio, como `1`.
`--memory`	Es la cantidad de memoria asignada para tu servicio, como `80Gi`.
`--no-invoker-iam-check`	Inhabilita las verificaciones de IAM del invocador. Consulta el instructivo para proteger los servicios de Cloud Run para obtener recomendaciones sobre cómo proteger mejor tu app.
`--no-cpu-throttling`	Esta configuración inhabilita la regulación de la CPU cuando el contenedor no entrega solicitudes de forma activa.
`--timeout`	Es el tiempo en el que se debe mostrar una respuesta, como `600` segundos.
`--startup-probe`	Es la configuración separada por comas para la sonda de inicio en el formato KEY=VALUE. Consulta Sonda de inicio de Cloud Run para obtener más detalles. Con los tamaños de modelo de Gemma 4, si no usas la salida de VPC directa, se recomienda configurar el tiempo de espera de la sonda de inicio en al menos 240 segundos.

Si necesitas modificar la configuración predeterminada o agregar más parámetros de configuración personalizados a tu servicio de Cloud Run, consulta Configura servicios.

Una vez que se completa el servicio implementado, se muestra un mensaje de éxito junto con la URL del extremo de Cloud Run que termina con run.app.

Prueba el servicio de Gemma implementado con curl

Ahora que implementaste el servicio de Gemma, puedes enviarle solicitudes. Sin embargo, si envías una solicitud directamente, Cloud Run responde con HTTP 401 Unauthorized. Esto es intencional, ya que una API de inferencia de LLM está diseñada para que otros servicios la llamen, como una aplicación de frontend. Para obtener más información sobre la autenticación de servicio a servicio en Cloud Run, consulta Autenticación de servicio a servicio.

Para enviar solicitudes al servicio de Gemma, agrega un encabezado con un token de OIDC válido a las solicitudes, por ejemplo, mediante el proxy de desarrollador de Cloud Run :

Inicia el proxy y, cuando se te solicite instalar el componente cloud-run-proxy, elige Y:

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

Ejecuta el siguiente comando para enviar una solicitud en una pestaña separada de la terminal para dejar el proxy en ejecución. El proxy se ejecuta en localhost:9090. Especifica el modelo de Gemma que usaste 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
  }'

Este comando debería proporcionar un resultado similar al siguiente:

{
 "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
 }
}

Configura la simultaneidad para obtener un rendimiento óptimo

En esta sección, se proporciona contexto sobre la configuración de simultaneidad recomendada. Para obtener una latencia de solicitud óptima, asegúrate de que la configuración --concurrency sea igual al argumento de línea de comandos --max-num-seqs de vLLM.

--max-num-seqs determina cuántas secuencias (solicitudes) están disponibles por cada instancia de vLLM para controlar la inferencia de forma simultánea.
--concurrency determina cuántas solicitudes envía Cloud Run a una instancia de vLLM al mismo tiempo.

Si --concurrency excede --max-num-seqs, Cloud Run puede enviar más solicitudes a una instancia de vLLM que para las ranuras de solicitud disponibles. Esto lleva a que se pongan en cola las solicitudes dentro de vLLM, lo que aumenta la latencia de las solicitudes en cola. También genera un ajuste de escala automático menos responsivo, ya que las solicitudes en fila no activan Cloud Run para escalar horizontalmente y comenzar instancias nuevas.

Para evitar por completo que las solicitudes se pongan en cola en la instancia de vLLM, debes configurar --concurrency para que coincida con --max-num-seqs.

Es importante tener en cuenta que aumentar --max-num-seqs también hace que las solicitudes paralelas tarden más tiempo y requiere más memoria de GPU para la caché de KV.

Optimizar el uso

Para obtener un uso de GPU óptimo, aumenta --concurrency y mantenlo dentro del doble del valor de --max-num-seqs. Si bien esto genera colas de solicitudes en vLLM, puede ayudar a mejorar la utilización: las instancias de vLLM pueden procesar inmediatamente las solicitudes de su cola, y las colas ayudan a absorber los aumentos repentinos del tráfico.

Crea agentes de IA con el Kit de desarrollo de agentes usando Gemma 4

Después de implementar tu servicio de Cloud Run, puedes usar el extremo de Cloud Run con Gemma 4 para crear agentes de IA con el Kit de desarrollo de agentes.

Antes de usar el Kit de desarrollo de agentes, asegúrate de que las solicitudes entrantes pasen el token de identidad adecuado. Para obtener más información sobre el uso de la autenticación de IAM y Cloud Run, consulta Autenticación de servicio a servicio.

En el siguiente ejemplo, se muestra cómo usar el Kit de desarrollo de agentes en Python con la autenticación de 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",
)

Limpia

Borra los siguientes Google Cloud recursos creados:

Servicio de Cloud Run

¿Qué sigue?

Para modelos más grandes y un tiempo de inicio más rápido con Run:ai Model Streamer, usa el codelab Ejecuta la inferencia del modelo de Gemma 4 en Cloud Run con la GPU RTX 6000 Pro con vLLM.
Configura la GPU
Prácticas recomendadas: Inferencia de IA en Cloud Run con GPU
Ejecuta modelos de Gemma 4 con varios frameworks de entorno de ejecución de IA

Ejecuta agentes con modelos de Gemma 4 en Cloud Run Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Obtén más información para otorgar los roles

Console

gcloud

Implementa un modelo de Gemma 4 con un contenedor de vLLM

Prueba el servicio de Gemma implementado con curl

Configura la simultaneidad para obtener un rendimiento óptimo

Optimizar el uso

Crea agentes de IA con el Kit de desarrollo de agentes usando Gemma 4

Limpia

¿Qué sigue?

Ejecuta agentes con modelos de Gemma 4 en Cloud Run