En este tutorial se muestra cómo desplegar y servir un modelo de lenguaje grande (LLM) Gemma 3 con GPUs en Google Kubernetes Engine (GKE) mediante el framework de servicio vLLM. Esto proporciona una base para comprender y explorar la implementación práctica de LLMs para la inferencia en un entorno de Kubernetes gestionado. Despliega en GKE un contenedor prediseñado que ejecuta vLLM. También puedes configurar GKE para que cargue los pesos de Gemma 1B, 4B, 12B y 27B desde Hugging Face.
Este tutorial está dirigido a ingenieros de aprendizaje automático, administradores y operadores de plataformas, y especialistas en datos e IA que estén interesados en usar las funciones de orquestación de contenedores de Kubernetes para servir cargas de trabajo de IA y aprendizaje automático en hardware de GPU H200, H100, A100 y L4. Para obtener más información sobre los roles habituales y las tareas de ejemplo a las que hacemos referencia en el contenido, consulta Roles y tareas habituales de los usuarios de GKE. Google Cloud
Si necesitas una plataforma de IA gestionada y unificada diseñada para crear y ofrecer modelos de aprendizaje automático rápidamente y de forma rentable, te recomendamos que pruebes nuestra solución de despliegue Vertex AI.
Antes de leer esta página, asegúrese de que conoce los siguientes conceptos:
Fondo
En esta sección se describen las tecnologías clave que se usan en esta guía.
Gemma
Gemma es un conjunto de modelos multimodales de inteligencia artificial (IA) generativa, ligeros y disponibles públicamente, que se han lanzado con una licencia abierta. Estos modelos de IA se pueden ejecutar en tus aplicaciones, hardware, dispositivos móviles o servicios alojados. Gemma 3 introduce la multimodalidad y admite entradas de visión y lenguaje, así como salidas de texto. Gestiona ventanas de contexto de hasta 128.000 tokens y admite más de 140 idiomas. Gemma 3 también ofrece funciones mejoradas de matemáticas, razonamiento y chat, como salidas estructuradas y llamadas de función.
Puedes usar los modelos Gemma para generar texto o ajustarlos para tareas especializadas.
Para obtener más información, consulta la documentación de Gemma.
GPUs
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 ofrece una amplia gama 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 servicio de LLMs de código abierto muy optimizado que puede aumentar el rendimiento del servicio en GPUs. Incluye funciones como las siguientes:
- Implementación optimizada de Transformer con PagedAttention
- Agrupación continua para mejorar el rendimiento general del servicio
- Paralelismo de tensores y servicio distribuido en varias GPUs
Para obtener más información, consulta la documentación de vLLM.
Acceder 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 si aún no tienes uno:
- Haz clic en Tu perfil > Configuración > Tokens de acceso.
- Selecciona New Token (Nuevo token).
- Especifica el nombre que quieras y un rol de al menos
Read. - Selecciona Generar un token.
- Copia el token generado en el portapapeles.
Prepara tu entorno
En este tutorial, usarás Cloud Shell para gestionar los recursos alojados enGoogle Cloud. Cloud Shell tiene preinstalado el software que necesitas para este tutorial, como kubectl y la CLI de gcloud.
Para configurar tu entorno con Cloud Shell, sigue estos pasos:
En la Google Cloud consola, inicia una sesión de Cloud Shell haciendo clic en
Activar Cloud Shell en la Google Cloud consola. Se iniciará una sesión en el panel inferior de la consola Google Cloud .Define 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_TOKENSustituye los siguientes valores:
PROJECT_ID: tu Google Cloud ID de proyecto.REGION: una región que admita el tipo de acelerador que quieras usar. Por ejemplo,us-central1para la GPU L4.CLUSTER_NAME: el nombre de tu clúster.HF_TOKEN: el token de Hugging Face que has generado antes.
Crear y configurar Google Cloud recursos
Sigue estas instrucciones para crear los recursos necesarios.
Crear un clúster y un grupo de nodos de GKE
Puedes servir Gemma en GPUs en un clúster Autopilot o Standard de GKE. Te recomendamos que uses un clúster de Autopilot para disfrutar de una experiencia de Kubernetes totalmente gestionada. Para elegir el modo de funcionamiento de GKE que mejor se adapte a tus cargas de trabajo, consulta Elegir un modo de funcionamiento de GKE.
Autopilot
En Cloud Shell, ejecuta el siguiente comando:
gcloud container clusters create-auto CLUSTER_NAME \
--project=PROJECT_ID \
--location=CONTROL_PLANE_LOCATION \
--release-channel=rapid
Sustituye los siguientes valores:
PROJECT_ID: tu Google Cloud ID de 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 quieras 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 soliciten las cargas de trabajo desplegadas.
Estándar
En Cloud Shell, ejecuta el siguiente comando para crear un clúster Standard:
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=1Sustituye los siguientes valores:
PROJECT_ID: tu Google Cloud ID de 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 quieras usar, por ejemplo,us-central1para la GPU L4.CLUSTER_NAME: el nombre de tu clúster.
La creación del clúster puede tardar 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 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 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 único grupo de nodos que contiene cuatro GPUs L4 por 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 que contiene una GPU A100 de 80 GB.
Crear 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=REGIONSustituye los siguientes valores:
REGION: una región que admita el tipo de acelerador que quieras usar. Por ejemplo,us-central1para la GPU L4.CLUSTER_NAME: el nombre de tu clúster.
Crea un secreto 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 -Sustituye
HF_TOKENpor el token de Hugging Face que has generado anteriormente.
Desplegar vLLM
En esta sección, desplegarás el contenedor vLLM para servir el modelo de Gemma que quieras usar. Para desplegar el modelo, en este tutorial se usan los desplegues de Kubernetes. Un Deployment es un objeto de la API de Kubernetes que te permite ejecutar varias réplicas de pods distribuidas entre los nodos de un clúster.
Gemma 3 1B-it
Sigue estas instrucciones para implementar el modelo Gemma 3 1B ajustado para instrucciones (entrada de solo texto).
Crea el siguiente archivo de manifiesto
vllm-3-1b-it.yaml:Aplica el archivo de manifiesto:
kubectl apply -f vllm-3-1b-it.yaml
Gemma 3 4B-it
Sigue estas instrucciones para implementar el modelo Gemma 3 4B ajustado para instrucciones.
Crea el siguiente archivo de manifiesto
vllm-3-4b-it.yaml:Aplica el archivo de manifiesto:
kubectl apply -f vllm-3-4b-it.yamlEn nuestro ejemplo, limitamos la ventana de contexto a 32 K usando la opción
--max-model-len=32768de vLLM. Si quieres aumentar el tamaño de la ventana de contexto (hasta 128 K), ajusta el manifiesto y la configuración del grupo de nodos con más capacidad de GPU.
Gemma 3 12B-it
Sigue estas instrucciones para desplegar el modelo Gemma 3 12B ajustado para instrucciones.
Crea el siguiente archivo de manifiesto
vllm-3-12b-it.yaml:Aplica el archivo de manifiesto:
kubectl apply -f vllm-3-12b-it.yamlEn nuestro ejemplo, limitamos el tamaño de la ventana de contexto a 16 K mediante la opción
--max-model-len=16384de vLLM. Si quieres aumentar el tamaño de la ventana de contexto (hasta 128 K), ajusta el manifiesto y la configuración del grupo de nodos con más capacidad de GPU.
Gemma 3 27B-it
Sigue estas instrucciones para implementar el modelo Gemma 3 27B ajustado para instrucciones.
Crea el siguiente archivo de manifiesto
vllm-3-27b-it.yaml:Aplica el archivo de manifiesto:
kubectl apply -f vllm-3-27b-it.yamlEn nuestro ejemplo, limitamos el tamaño de la ventana de contexto a 32 K mediante la opción
--max-model-len=32768de vLLM. Si quieres que la ventana de contexto sea más grande (hasta 128 K), ajusta el manifiesto y la configuración del grupo de nodos con más capacidad de GPU.
Un pod del clúster descarga los pesos del modelo de Hugging Face e inicia el motor de servicio.
Espera a que la implementación esté disponible:
kubectl wait --for=condition=Available --timeout=1800s deployment/vllm-gemma-deployment
Consulta los registros de la implementación en ejecución:
kubectl logs -f -l app=gemma-server
El recurso Deployment descarga los datos del modelo. Este proceso puede tardar unos minutos. El resultado debería ser similar al siguiente:
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 pasar a la siguiente sección.
Aplicar el modelo
En esta sección, interactúas con el modelo.
Configurar la redirección de puertos
Ejecuta el siguiente comando para configurar el reenvío de puertos al modelo:
kubectl port-forward service/llm-service 8000:8000
El resultado debería ser similar al siguiente:
Forwarding from 127.0.0.1:8000 -> 8000
Interactuar con el modelo mediante curl
En esta sección se muestra cómo realizar una prueba de humo básica para verificar los modelos ajustados para instrucciones de Gemma 3 que hayas implementado.
En el caso de otros modelos, sustituye gemma-3-4b-it por el nombre del modelo correspondiente.
En este ejemplo se muestra cómo probar el modelo ajustado Gemma 3 4B con una entrada de solo texto.
En una nueva sesión de terminal, 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
}
(Opcional) Interactúa con el modelo a través de una interfaz de chat de Gradio
En esta sección, crearás una aplicación de chat web que te permitirá interactuar con tu modelo ajustado con instrucciones. Para simplificar, en esta sección solo se describe el método de prueba con el modelo de 4 bits.
Gradio es una biblioteca de Python que tiene un
ChatInterface wrapper que crea interfaces de usuario para chatbots.
Implementar 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 archivo de manifiesto:
kubectl apply -f gradio.yamlEspera a que esté disponible el despliegue:
kubectl wait --for=condition=Available --timeout=900s deployment/gradio
Usar la interfaz de chat
En Cloud Shell, ejecuta el siguiente comando:
kubectl port-forward service/gradio 8080:8080De esta forma, se crea un reenvío de puertos de Cloud Shell al servicio de Gradio.
Haz clic en el botón
Vista previa web, situado en la parte superior derecha de la barra de tareas de Cloud Shell. Haz clic en Vista previa en el puerto 8080. Se abrirá una nueva pestaña en el navegador.Interactúa con Gemma mediante la interfaz de chat de Gradio. Añade una petición y haz clic en Enviar.
Solucionar problemas
- Si aparece el mensaje
Empty reply from server, es posible que el contenedor no haya terminado de descargar los datos del modelo. Vuelve a consultar los registros del pod para ver el mensajeConnected, que indica que el modelo está listo para publicarse. - Si ves
Connection refused, comprueba que el reenvío de puertos esté activo.
Observar el rendimiento del modelo
Para ver los paneles de control de las métricas de observabilidad de un modelo, sigue estos pasos:
En la Google Cloud consola, ve a la página Modelos implementados.
Para ver los detalles de una implementación específica, incluidas sus métricas, registros y paneles de control, haz clic en el nombre del modelo de la lista.
En la página de detalles del modelo, haga clic en la pestaña Observabilidad para ver los siguientes paneles de control. Si se te pide, haz clic en Habilitar para habilitar la recogida de métricas del clúster.
- El panel de control Uso de la infraestructura muestra las métricas de uso.
- El panel de control de DCGM muestra las métricas de DCGM.
- Si usas vLLM, el panel de control Rendimiento del modelo está disponible y muestra métricas sobre el rendimiento del modelo vLLM.
También puede ver las métricas en la integración del panel de control de vLLM en Cloud Monitoring. Estas métricas se agregan en todas las implementaciones de vLLM sin filtros predefinidos.
Para usar el panel de control en Cloud Monitoring, debes habilitar Google Cloud Managed Service para Prometheus, que recoge las métricas de vLLM, en tu clúster de GKE. vLLM expone métricas en formato Prometheus de forma predeterminada, por lo que no es necesario instalar ningún exportador adicional. Para obtener información sobre cómo usar Google Cloud Managed Service para Prometheus y recoger métricas de tu modelo, consulta la guía de observabilidad de vLLM en la documentación de Cloud Monitoring.