Ejecuta Gemma 3 en Cloud Run

En esta guía, se describe cómo implementar modelos abiertos de Gemma 3 en Cloud Run con un contenedor compilado previamente y se proporciona orientación para usar el servicio de Cloud Run implementado con el SDK de Gen AI de Google.

Antes de comenzar

Si usaste Google AI Studio para realizar la implementación en Cloud Run, ve a la sección Interactúa de forma segura con el SDK de IA generativa de Google.

Si no usaste Google AI Studio, sigue estos pasos antes de usar Cloud Run para crear un servicio nuevo.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

Go to project selector

Make sure 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.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

1. Configura tu entorno de desarrollo de Cloud Run en tu Google Cloud proyecto.
2. Instala e inicializa gcloud CLI
3. Asegúrate de que tu cuenta tenga los siguientes roles de IAM:
   • 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

1. En la consola de Google Cloud , ve a la página IAM.

   Ir a IAM
2. Selecciona el proyecto.
3. Haz clic en person_addGrant access.

4. En el campo Principales nuevas, ingresa tu identificador de usuario. Por lo general, esta es la dirección de correo electrónico de la Cuenta de Google que se usa para implementar el servicio de Cloud Run.

5. En la lista Seleccionar un rol, elige un rol.
6. Para otorgar funciones adicionales, haz clic en add Agregar otro rol y agrega cada rol adicional.
7. 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 proyecto. Google Cloud
• PROJECT_ID por el ID de tu proyecto Google Cloud .
• PRINCIPAL por la cuenta a la que agregarás la vinculación. Por lo general, esta es la dirección de correo electrónico de la Cuenta de Google que se usa para implementar el servicio de Cloud Run.
• ROLE con el rol que agregas a la cuenta del implementador.
4. Solicita una cuota de Total Nvidia L4 GPU allocation, per project per region en la API de Cloud Run Admin en la página Cuotas y límites del sistema.
5. 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 con un contenedor compilado previamente

Cloud Run proporciona un contenedor compilado previamente para entregar modelos abiertos de Gemma en Cloud Run.

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

gcloud run deploy SERVICE_NAME \
   --image us-docker.pkg.dev/cloudrun/container/gemma/GEMMA_PARAMETER \
   --concurrency 4 \
   --cpu 8 \
   --set-env-vars OLLAMA_NUM_PARALLEL=4 \
   --gpu 1 \
   --gpu-type nvidia-l4 \
   --max-instances 1 \
   --memory 32Gi \
   --no-allow-unauthenticated \
   --no-cpu-throttling \
   --timeout=600 \
   --region REGION

Reemplaza lo siguiente:

• SERVICE_NAME por un nombre único para el servicio de Cloud Run.

• GEMMA_PARAMETER con el modelo de Gemma que usaste:

  • Gemma 3, 1B (gemma-3-1b-it): gemma3-1b
  • Gemma 3 4B (gemma-3-4b-it): gemma3-4b
  • Gemma 3 12B (gemma-3-12b-it): gemma3-12b
  • Gemma 3 27B (gemma-3-27b-it): gemma3-27b

  De manera opcional, reemplaza toda la URL de la imagen por una imagen de Docker que hayas compilado desde el repositorio de GitHub de Gemma en Cloud Run.

• REGION por la región Google Cloud en la que se implementará Cloud Run, comoeurope-west1. Si necesitas modificar la región, consulta Configuración de GPU para obtener información sobre las regiones admitidas para las implementaciones habilitadas para GPU.

Los demás parámetros de configuración son los siguientes:

Opción	Descripción
--concurrency	La cantidad máxima de solicitudes que una instancia determinada puede procesar de forma simultánea, como 4. Consulta Configura la simultaneidad para obtener un rendimiento óptimo para obtener recomendaciones sobre la latencia óptima de las solicitudes.
--cpu	La cantidad de CPU asignada para tu servicio, como 8.
--set-env-vars	Las variables de entorno configuradas para tu servicio. Por ejemplo, OLLAMA_NUM_PARALLEL=4 Consulta Configura la simultaneidad para obtener un rendimiento óptimo para obtener recomendaciones sobre la latencia óptima de las solicitudes.
--gpu	El valor de GPU para tu servicio, como 1.
--gpu-type	El tipo de GPU que se usará para tu servicio, como nvidia-l4.
--max-instances	La cantidad máxima de instancias de contenedor para tu servicio, como 1.
--memory	La cantidad de memoria asignada para tu servicio, como 32Gi.
--no-invoker-iam-check	Inhabilita las verificaciones de IAM del invocador. Consulta Cómo interactuar de forma segura con el SDK de IA generativa de Google para obtener recomendaciones sobre cómo proteger mejor tu app.
--no-cpu-throttling	Este parámetro de configuración inhabilita la regulación de la CPU cuando el contenedor no está publicando solicitudes de forma activa.
--timeout	El tiempo en el que se debe mostrar una respuesta, como 600 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 la implementación del servicio, 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, con el proxy de desarrollador de Cloud Run:

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

   gcloud run services proxy ollama-gemma --port=9090

2. Envía una solicitud a él en una pestaña separada de la terminal para dejar el proxy en ejecución. Ten en cuenta que el proxy se ejecuta en localhost:9090:

   curl http://localhost:9090/api/generate -d '{
     "model": "gemma3:4b",
     "prompt": "Why is the sky blue?"
   }'

   Este comando debe proporcionar un resultado de transmisión similar al siguiente:

   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.641492408Z","response":"That","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.687529153Z","response":"'","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.753284927Z","response":"s","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.812957381Z","response":" a","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.889102649Z","response":" fantastic","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.925748116Z","response":",","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.958391572Z","response":" decept","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.971035028Z","response":"ively","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.989678484Z","response":" tricky","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.999321940Z","response":" question","done":false}
   ...
   

Interactúa de forma segura con el SDK de IA generativa de Google

Después de implementar tu servicio de Cloud Run, puedes usar el extremo de Cloud Run con el SDK de IA generativa de Google.

Antes de usar el SDK de IA generativa de Google, 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 los siguientes ejemplos, se muestra cómo usar el SDK de IA generativa de Google con la autenticación de IAM.

JavaScript o TypeScript

Si usas el SDK de IA generativa de Google para JavaScript y TypeScript, el código podría verse de la siguiente manera:

import { GoogleGenAI, setDefaultBaseUrls } from "@google/genai";
import { GoogleAuth} from 'google-auth-library'

const cloudrunurl = 'https://CLOUD_RUN_SERVICE_URL';
const targetAudience = url;

const auth = new GoogleAuth();

async function main() {

  const client = await auth.getIdTokenClient(targetAudience);
  const headers = await client.getRequestHeaders(targetAudience);
  const idToken = headers['Authorization']

const ai = new GoogleGenAI({
  apiKey:"placeholder",
  httpOptions: { baseUrl: url, headers: {'Authorization': idToken}  },
});

  const response = await ai.models.generateContent({
    model: "gemma-3-1b-it",
    contents: "I want a pony",
  });
  console.log(response.text);
}

main();

curl

Si usas curl, ejecuta los siguientes comandos para acceder a los extremos del SDK de IA generativa de Google:

• Para Generate Content, usa /v1beta/{model=models/*}:generateContent: Genera una respuesta del modelo a partir de una entrada GenerateContentRequest.

  curl "<cloud_run_url>/v1beta/models/<model>:generateContent" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -X POST \
  -d '{
    "contents": [{
      "parts":[{"text": "Write a story about a magic backpack. You are the narrator of an interactive text adventure game."}]
      }]
      }'
  

• Para Stream Generate Content, usa /v1beta/{model=models/*}:streamGenerateContent: Genera una respuesta transmitida del modelo a partir de una entrada GenerateContentRequest.

  curl "<cloud_run_url>/v1beta/models/<model>:streamGenerateContent" \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
    -X POST \
    -d '{
      "contents": [{
        "parts":[{"text": "Write a story about a magic backpack. You are the narrator of an interactive text adventure game."}]
        }]
        }'
  

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 a la variable de entorno OLLAMA_NUM_PARALLEL de Ollama.

• OLLAMA_NUM_PARALLEL determina cuántos espacios de solicitud están disponibles por cada modelo para controlar las solicitudes de inferencia de forma simultánea.
• --concurrency determina cuántas solicitudes envía Cloud Run a una instancia de Ollama al mismo tiempo.

Si --concurrency excede OLLAMA_NUM_PARALLEL, Cloud Run puede enviar más solicitudes a un modelo en Ollama que para las ranuras de solicitud disponibles. Esto lleva a que se pongan en cola las solicitudes dentro de Ollama, 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.

Ollama también admite la entrega de varios modelos desde una GPU. A fin de evitar por completo que las solicitudes se pongan en cola en la instancia de Ollama, debes configurar --concurrency para que coincida con OLLAMA_NUM_PARALLEL.

Es importante tener en cuenta que aumentar OLLAMA_NUM_PARALLEL también hace que las solicitudes paralelas tarden más tiempo.

Optimizar el uso

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

Limpia

Borra los siguientes recursos Google Cloud que creaste:

• Servicio de Cloud Run
• Imagen de contenedor

¿Qué sigue?

• Configura la GPU
• Prácticas recomendadas: Inferencia de IA en Cloud Run con GPU
• Ejecuta modelos de Gemma 3 con varios frameworks de tiempo de ejecución de IA