En este instructivo, se muestra cómo implementar y entregar un modelo de lenguaje grande (LLM) Gemma 3 con GPUs en Google Kubernetes Engine (GKE) con el framework de entrega vLLM. Esto proporciona una base para comprender y explorar la implementación práctica de LLM para la inferencia en un entorno de Kubernetes administrado. Implementas en GKE un contenedor compilado previamente que ejecuta vLLM. También configurarás GKE para cargar los pesos de Gemma 1B, 4B, 12B y 27B desde Hugging Face.
Este instructivo está dirigido a ingenieros de aprendizaje automático (AA), administradores y operadores de plataformas, y especialistas en datos y en IA que estén interesados en usar las capacidades de organización de contenedores de Kubernetes para entregar cargas de trabajo de IA/AA en hardware de GPU H200, H100, A100 y L4. Para obtener más información sobre los roles comunes y las tareas de ejemplo a las que hacemos referencia en el contenido de Google Cloud , consulta Roles de usuario y tareas comunes de GKE.
Si necesitas una plataforma de IA administrada unificada diseñada para compilar y entregar modelos de AA con rapidez de forma rentable, te recomendamos que pruebes nuestra solución de implementación de Vertex AI.
Antes de leer esta página, asegúrate de estar familiarizado con lo siguiente:
Fondo
En esta sección, se describen las tecnologías clave que se usan en este instructivo.
Gemma
Gemma es un conjunto de modelos multimodales de Inteligencia Artificial (IA) generativos básicos disponibles de forma abierta que se lanzaron con una licencia abierta. Estos modelos de IA están disponibles para ejecutarse en tus aplicaciones, hardware, dispositivos móviles o servicios alojados. Gemma 3 introduce la multimodalidad y admite entradas de lenguaje visual y salidas de texto. Maneja ventanas de contexto de hasta 128,000 tokens y admite más de 140 idiomas. Gemma 3 también ofrece capacidades mejoradas de matemáticas, razonamiento y chat, lo que incluye salidas estructuradas y llamadas a funciones.
Puedes usar los modelos de Gemma para la generación de texto, pero también puedes ajustar estos modelos en el caso de tareas especializadas.
Para obtener más información, consulta la documentación de Gemma.
GPU
Las GPUs te permiten acelerar cargas de trabajo específicas que se ejecutan en tus nodos, como el aprendizaje automático y el procesamiento de datos. GKE proporciona una variedad de opciones de tipos de máquinas para la configuración de nodos, incluidos los tipos de máquinas con GPUs NVIDIA H200, H100, L4 y A100.
vLLM
vLLM es un framework de entrega de LLM de código abierto altamente optimizado que puede aumentar la capacidad de procesamiento de entrega en GPUs, con funciones como las siguientes:
- Implementación optimizada de transformadores con PagedAttention
- Agrupación en lotes continua para mejorar la capacidad de procesamiento general de la entrega
- Paralelismo de tensor y entrega distribuida en varias GPUs
Para obtener más información, consulta la documentación de vLLM.
Obtén acceso al modelo
Para acceder al modelo a través de Hugging Face, necesitas un token de Hugging Face.
Sigue estos pasos para generar un token nuevo si aún no tienes uno:
- Haz clic en Tu perfil > Configuración > Tokens de acceso.
- Selecciona Token nuevo.
- Especifica el nombre que desees y un rol de al menos
Read. - Selecciona Genera un token.
- Copia el token generado al portapapeles.
Prepara el entorno
En este instructivo, usarás Cloud Shell para administrar recursos alojados enGoogle Cloud. Cloud Shell tiene preinstalado el software que necesitas para este instructivo, incluidos kubectl y la CLI de gcloud.
Para configurar tu entorno con Cloud Shell, sigue estos pasos:
En la Google Cloud consola, haz clic en
Activar Cloud Shell en la Google Cloud consola para iniciar una sesión de Cloud Shell. Esto inicia una sesión en el panel inferior de la consola de Google Cloud .Configura las variables de entorno predeterminadas:
gcloud config set project PROJECT_ID gcloud config set billing/quota_project PROJECT_ID export PROJECT_ID=$(gcloud config get project) export REGION=REGION export CLUSTER_NAME=CLUSTER_NAME export HF_TOKEN=HF_TOKENReemplaza los siguientes valores:
PROJECT_ID: Tu Google Cloud ID del proyecto.REGION: una región que admita el tipo de acelerador que deseas usar, por ejemplo,us-central1para la GPU L4.CLUSTER_NAME: El nombre de tu clúster.HF_TOKEN: El token de Hugging Face que generaste antes.
Crea y configura recursos de Google Cloud
Sigue estas instrucciones para crear los recursos necesarios.
Crea un clúster de GKE y un grupo de nodos
Puedes entregar Gemma en GPU en un clúster de GKE Autopilot o Standard. Te recomendamos que uses un clúster de Autopilot para una experiencia de Kubernetes completamente administrada. Para elegir el modo de operación de GKE que se adapte mejor a tus cargas de trabajo, consulta Elige un modo de operación de GKE.
Autopilot
En Cloud Shell, ejecute el siguiente comando:
gcloud container clusters create-auto CLUSTER_NAME \
--project=PROJECT_ID \
--location=CONTROL_PLANE_LOCATION \
--release-channel=rapid
Reemplaza los siguientes valores:
PROJECT_ID: Tu Google Cloud ID del proyecto.CONTROL_PLANE_LOCATION: La región de Compute Engine del plano de control de tu clúster. Proporciona una región que admita el tipo de acelerador que deseas usar, por ejemplo,us-central1para la GPU L4.CLUSTER_NAME: El nombre de tu clúster.
GKE crea un clúster de Autopilot con nodos de CPU y GPU según lo solicitan las cargas de trabajo implementadas.
Estándar
En Cloud Shell, ejecuta el siguiente comando para crear un clúster estándar:
gcloud container clusters create CLUSTER_NAME \ --project=PROJECT_ID \ --location=CONTROL_PLANE_LOCATION \ --workload-pool=PROJECT_ID.svc.id.goog \ --release-channel=rapid \ --num-nodes=1Reemplaza los siguientes valores:
PROJECT_ID: Tu Google Cloud ID del proyecto.CONTROL_PLANE_LOCATION: La región de Compute Engine del plano de control de tu clúster. Proporciona una región que admita el tipo de acelerador que deseas usar, por ejemplo,us-central1para la GPU L4.CLUSTER_NAME: El nombre de tu clúster.
La creación del clúster puede tomar varios minutos.
Para crear un grupo de nodos para tu clúster con el tamaño de disco adecuado, ejecuta el siguiente comando:
Gemma 3 1B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-8 \ --num-nodes=1GKE crea un grupo de nodos único que contiene una GPU L4 para cada nodo.
Gemma 3 4B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-8 \ --num-nodes=1GKE crea un grupo de nodos único que contiene una GPU L4 para cada nodo.
Gemma 3 12B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=4,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-48 \ --num-nodes=1GKE crea un solo grupo de nodos que contiene cuatro GPU L4 para cada nodo.
Gemma 3 27B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-a100-80gb,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=a2-ultragpu-1g \ --disk-type=pd-ssd \ --num-nodes=1 \ --disk-size=256GKE crea un grupo de nodos único que contiene una GPU A100 de 80 GB.
Crea un secreto de Kubernetes para las credenciales de Hugging Face
En Cloud Shell, haz lo siguiente:
Configura
kubectlpara que pueda comunicarse con tu clúster:gcloud container clusters get-credentials CLUSTER_NAME \ --location=REGIONReemplaza los siguientes valores:
REGION: una región que admita el tipo de acelerador que deseas usar, por ejemplo,us-central1para la GPU L4.CLUSTER_NAME: El nombre de tu clúster.
Crea un Secret de Kubernetes que contenga el token de Hugging Face:
kubectl create secret generic hf-secret \ --from-literal=hf_api_token=${HF_TOKEN} \ --dry-run=client -o yaml | kubectl apply -f -Reemplaza
HF_TOKENpor el token de Hugging Face que generaste antes.
Implementa vLLM
En esta sección, implementarás el contenedor de vLLM para entregar el modelo de Gemma que deseas usar. Para implementar el modelo, en este instructivo, se usan implementaciones de Kubernetes. Un Deployment es un objeto de la API de Kubernetes que te permite ejecutar varias réplicas de Pods que se distribuyen entre los nodos de un clúster.
Gemma 3 1B-it
Sigue estas instrucciones para implementar el modelo ajustado por instrucciones de Gemma 3 1B (entrada solo de texto).
Crea el siguiente manifiesto
vllm-3-1b-it.yaml:Aplica el manifiesto
kubectl apply -f vllm-3-1b-it.yaml
Gemma 3 4B-it
Sigue estas instrucciones para implementar el modelo ajustado por instrucciones de Gemma 3 4B.
Crea el siguiente manifiesto
vllm-3-4b-it.yaml:Aplica el manifiesto
kubectl apply -f vllm-3-4b-it.yamlEn nuestro ejemplo, limitamos la ventana de contexto a 32 K con la opción
--max-model-len=32768de vLLM. Si deseas un tamaño de ventana de contexto más grande (hasta 128 K), ajusta tu manifiesto y la configuración del grupo de nodos con más capacidad de GPU.
Gemma 3 12B-it
Sigue estas instrucciones para implementar el modelo ajustado por instrucciones de Gemma 3 12B.
Crea el siguiente manifiesto
vllm-3-12b-it.yaml:Aplica el manifiesto
kubectl apply -f vllm-3-12b-it.yamlEn nuestro ejemplo, limitamos el tamaño de la ventana de contexto a 16 K con la opción
--max-model-len=16384de vLLM. Si deseas un tamaño de ventana de contexto más grande (hasta 128 K), ajusta la configuración del manifiesto y del grupo de nodos con más capacidad de GPU.
Gemma 3 27B-it
Sigue estas instrucciones para implementar el modelo ajustado por instrucciones de Gemma 3 27B.
Crea el siguiente manifiesto
vllm-3-27b-it.yaml:Aplica el manifiesto
kubectl apply -f vllm-3-27b-it.yamlEn nuestro ejemplo, limitamos el tamaño de la ventana de contexto a 32 K con la opción
--max-model-len=32768de vLLM. Si deseas un tamaño de ventana de contexto más grande (hasta 128 000), ajusta tu manifiesto y la configuración del grupo de nodos con más capacidad de GPU.
Un Pod en el clúster descarga los pesos del modelo de Hugging Face y, luego, inicia el motor de entrega.
Espera a que la implementación esté disponible:
kubectl wait --for=condition=Available --timeout=1800s deployment/vllm-gemma-deployment
Observa los registros de la implementación en ejecución:
kubectl logs -f -l app=gemma-server
El recurso de implementación descarga los datos del modelo. Este proceso puede demorar unos minutos. El resultado es similar a este:
INFO: Automatically detected platform cuda.
...
INFO [launcher.py:34] Route: /v1/chat/completions, Methods: POST
...
INFO: Started server process [13]
INFO: Waiting for application startup.
INFO: Application startup complete.
Default STARTUP TCP probe succeeded after 1 attempt for container "vllm--google--gemma-3-4b-it-1" on port 8080.
Asegúrate de que el modelo se haya descargado por completo antes de continuar con la siguiente sección.
Entrega el modelo
En esta sección, interactuarás con el modelo.
Configura la redirección de puertos
Ejecuta el siguiente comando para configurar la redirección de puertos al modelo:
kubectl port-forward service/llm-service 8000:8000
El resultado es similar al siguiente:
Forwarding from 127.0.0.1:8000 -> 8000
Interactúa con el modelo con curl
En esta sección, se muestra cómo puedes realizar una prueba de humo básica para verificar los modelos de Gemma 3 ajustados por instrucciones que implementaste.
Para otros modelos, reemplaza gemma-3-4b-it por el nombre del modelo respectivo.
En este ejemplo, se muestra cómo probar el modelo ajustado con instrucciones de Gemma 3 4B con entrada solo de texto.
En una sesión de terminal nueva, usa curl para chatear con tu modelo:
curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemma-3-4b-it",
"messages": [
{
"role": "user",
"content": "Why is the sky blue?"
}
]
}'
El resultado es similar al siguiente:
{
"id": "chatcmpl-e4a2e624bea849d9b09f838a571c4d9e",
"object": "chat.completion",
"created": 1741763029,
"model": "google/gemma-3-4b-it",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"reasoning_content": null,
"content": "Okay, let's break down why the sky appears blue! It's a fascinating phenomenon rooted in physics, specifically something called **Rayleigh scattering**. Here's the explanation: ...",
"tool_calls": []
},
"logprobs": null,
"finish_reason": "stop",
"stop_reason": 106
}
],
"usage": {
"prompt_tokens": 15,
"total_tokens": 668,
"completion_tokens": 653,
"prompt_tokens_details": null
},
"prompt_logprobs": null
}
Interactúa con el modelo a través de una interfaz de chat de Gradio (opcional)
En esta sección, compilarás una aplicación de chat web que te permita interactuar con el modelo ajustado a instrucciones. Para simplificar, en esta sección solo se describe el enfoque de prueba con el modelo 4B-it.
Gradio es una biblioteca de Python que tiene un
wrapper ChatInterface de ChatInterface que crea interfaces de usuario para chatbots.
Implementa la interfaz de chat
En Cloud Shell, guarda el siguiente manifiesto como
gradio.yaml. Cambiagoogle/gemma-2-9b-itporgoogle/gemma-3-4b-ito por otro nombre de modelo de Gemma 3 que hayas usado en tu implementación.Aplica el manifiesto
kubectl apply -f gradio.yamlEspera a que la implementación esté disponible:
kubectl wait --for=condition=Available --timeout=900s deployment/gradio
Usa la interfaz de chat
En Cloud Shell, ejecuta el siguiente comando:
kubectl port-forward service/gradio 8080:8080Esto crea una redirección de puertos desde Cloud Shell al servicio de Gradio.
Haz clic en el botón
Vista previa en la Web, que se encuentra en la parte superior derecha de la barra de tareas de Cloud Shell. Haga clic en Vista previa en el puerto 8080. Se abrirá una pestaña nueva en el navegador.Interactúa con Gemma con la interfaz de chat de Gradio. Agrega un mensaje y haz clic en Enviar.
Soluciona problemas
- Si recibes el mensaje
Empty reply from server, es posible que el contenedor no haya terminado de descargar los datos del modelo. Vuelve a verificar los registros del Pod en busca del mensajeConnected, que indica que el modelo está listo para entregar. - Si ves
Connection refused, verifica que tu redirección de puertos esté activa.
Observa el rendimiento del modelo
Para ver los paneles de las métricas de observabilidad de un modelo, sigue estos pasos:
En la consola de Google Cloud , ve a la página Modelos implementados.
Para ver detalles sobre la implementación específica, incluidas sus métricas, registros y paneles, haz clic en el nombre del modelo en la lista.
En la página de detalles del modelo, haz clic en la pestaña Observabilidad para ver los siguientes paneles. Si se te solicita, haz clic en Habilitar para habilitar la recopilación de métricas para el clúster.
- En el panel Uso de la infraestructura, se muestran las métricas de utilización.
- En el panel DCGM, se muestran las métricas de DCGM.
- Si usas vLLM, el panel Rendimiento del modelo está disponible y muestra métricas sobre el rendimiento del modelo de vLLM.
También puedes ver las métricas en la integración del panel de vLLM en Cloud Monitoring. Estas métricas se agregan para todas las implementaciones de vLLM sin filtros preestablecidos.
Para usar el panel en Cloud Monitoring, debes habilitar Google Cloud Managed Service para Prometheus, que recopila las métricas de vLLM, en tu clúster de GKE. vLLM expone las métricas en formato Prometheus de forma predeterminada. No es necesario que instales un exportador adicional. Si deseas obtener información para usar Google Cloud Managed Service para Prometheus y recopilar métricas de tu modelo, consulta la guía de observabilidad de vLLM en la documentación de Cloud Monitoring.