Usa vLLM en GKE para entregar la inferencia de Gemma 3 27B

GPU en clúster

En este instructivo, se muestra cómo implementar y entregar un modelo de lenguaje grande (LLM) Gemma 3 de 27,000 millones de parámetros con el framework de entrega vLLM. Implementas Gemma 3 en una sola instancia de máquina virtual (VM) A4 en Google Kubernetes Engine (GKE).

Importante: Para completar este instructivo, debes haber reservado la capacidad para crear una VM A4. Para obtener más información sobre las opciones para reservar capacidad en AI Hypercomputer para una fecha y hora futuras, consulta Elige una opción de consumo.

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 controlar las cargas de trabajo de inferencia.

Objetivos

1. Accede a Gemma 3 con Hugging Face.

2. Prepara el entorno.

3. Crea un clúster de GKE en modo Autopilot.

4. Crea un secreto de Kubernetes para las credenciales de Hugging Face.

5. Implementa un contenedor de vLLM en tu clúster de GKE.

6. Interactúa con Gemma 3 con curl.

7. Realiza una limpieza.

Costos

En este instructivo, se usan componentes facturables de Google Cloud, que incluyen lo siguiente:

• Precios de Google Kubernetes Engine
• Precios de GPU

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.

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.

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Seleccionar un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos (roles/resourcemanager.projectCreator), que contiene el resourcemanager.projects.create permiso. Obtén más información para otorgar roles.

Nota: Si no planeas conservar los recursos creados durante este procedimiento, crea un proyecto en lugar de seleccionar un proyecto existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

• Crea un Google Cloud proyecto de:

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el Google Cloud proyecto de que estás creando.

• Selecciona el Google Cloud proyecto de que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto de.

Verifica que la facturación esté habilitada para tu Google Cloud proyecto.

Habilita la API requerida:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

gcloud services enable container.googleapis.com

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Seleccionar un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos (roles/resourcemanager.projectCreator), que contiene el resourcemanager.projects.create permiso. Obtén más información para otorgar roles.

Nota: Si no planeas conservar los recursos creados durante este procedimiento, crea un proyecto en lugar de seleccionar un proyecto existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

• Crea un Google Cloud proyecto de:

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el Google Cloud proyecto de que estás creando.

• Selecciona el Google Cloud proyecto de que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto de.

Verifica que la facturación esté habilitada para tu Google Cloud proyecto.

Habilita la API requerida:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

gcloud services enable container.googleapis.com

1. Otorga roles a tu cuenta de usuario. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM: roles/container.admin

   gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

   Reemplaza lo siguiente:

   • PROJECT_ID: ID del proyecto
   • USER_IDENTIFIER: Es el identificador de tu cuenta de usuario. Por ejemplo, [e-mail].
   • ROLE: Es el rol de IAM que otorgas a tu cuenta de usuario.
2. Accede a una cuenta de Hugging Face o crea una.

Accede a Gemma 3 con Hugging Face

Para usar Hugging Face y acceder a Gemma 3, haz lo siguiente:

1. Accede a Hugging Face.
2. Crea un token de acceso read de Hugging Face. Haz clic en Tu perfil > Configuración > Tokens de acceso > +Crear token nuevo.
3. Copia y guarda el valor del token de read access. Lo usarás más adelante en este instructivo.

Prepara el entorno

Para preparar tu entorno, establece las variables de entorno predeterminadas:

export PROJECT_ID="YOUR_PROJECT_ID"
export RESERVATION_URL="YOUR_RESERVATION_NAME"
export REGION="YOUR_REGION"
export CLUSTER_NAME="YOUR_CLUSTER_NAME"
export HUGGING_FACE_TOKEN="YOUR_HF_TOKEN"
export NETWORK="YOUR_NETWORK_NAME"
export SUBNETWORK="YOUR_SUBNETWORK_NAME"

gcloud config set project "${PROJECT_ID}"
gcloud config set billing/quota_project "${PROJECT_ID}"

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del Google Cloud proyecto de en el que deseas crear el clúster de GKE.

• RESERVATION_URL: Es la URL de la reserva que deseas usar para crear tu clúster de GKE. Según el proyecto en el que existe la reserva, especifica uno de los siguientes valores:

  • La reserva existe en tu proyecto: RESERVATION_NAME

  • La reserva existe en un proyecto diferente y tu proyecto puede usarla: projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME

• REGION: Es la región en la que deseas crear tu clúster de GKE. Solo puedes crear el clúster en la región en la que existe la reserva.

• CLUSTER_NAME: Es el nombre del clúster de GKE que se creará.

• YOUR_HF_TOKEN: Es el token de acceso de Hugging Face que creaste en la sección anterior.

• NETWORK: Es la red que usa el clúster de GKE. Especifica uno de los siguientes valores:

  • Si creaste una red personalizada, especifica el nombre de tu red.

  • De lo contrario, especifica default.

• SUBNETWORK: Es la subred que usa el clúster de GKE. Especifica uno de los siguientes valores:

  • Si creaste una subred personalizada, especifica el nombre de tu subred. Solo puedes especificar una subred que exista en la misma región que la reserva.

  • De lo contrario, especifica default.

Crea un clúster de GKE en modo Autopilot

Para crear un clúster de GKE en modo Autopilot, ejecuta el siguiente comando:

gcloud container clusters create-auto $CLUSTER_NAME \
    --project=$PROJECT_ID \
    --region=$REGION \
    --release-channel=rapid \
    --network=$NETWORK \
    --subnetwork=$SUBNETWORK

La creación del clúster de GKE puede tardar un poco en completarse. Para verificar que Google Cloud haya terminado de crear tu clúster, ve a Clústeres de Kubernetes en la Google Cloud consola de.

Crea un secreto de Kubernetes para las credenciales de Hugging Face

Para crear un secreto de Kubernetes para las credenciales de Hugging Face, sigue estos pasos:

1. Configura kubectl para comunicarse con tu clúster de GKE:

   gcloud container clusters get-credentials $CLUSTER_NAME \
       --location=$REGION

2. Crea un secreto de Kubernetes para almacenar tu token de Hugging Face:

   kubectl create secret generic hf-secret \
       --from-literal=hf_api_token=${HUGGING_FACE_TOKEN} \
       --dry-run=client -o yaml | kubectl apply -f -

Implementa un contenedor de vLLM en tu clúster de GKE

Para implementar el contenedor de vLLM para entregar el modelo de Gemma 3 27B con implementaciones de Kubernetes, sigue estos pasos:

1. Crea un archivo vllm-3-27b-it.yaml con la implementación de vLLM que elegiste:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: vllm-gemma-deployment
   spec:
     progressDeadlineSeconds: 900
     replicas: 1
     selector:
       matchLabels:
         app: gemma-server
     template:
       metadata:
         labels:
           app: gemma-server
           ai.gke.io/model: gemma-3-27b-it
           ai.gke.io/inference-server: vllm
           examples.ai.gke.io/source: user-guide
       spec:
         containers:
         - name: inference-server
           image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:20250801_0916_RC01
           resources:
             requests:
               cpu: "10"
               memory: "128Gi"
               ephemeral-storage: "120Gi"
               nvidia.com/gpu: "8"
             limits:
               cpu: "10"
               memory: "128Gi"
               ephemeral-storage: "120Gi"
               nvidia.com/gpu: "8"
           command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
           args:
           - --model=$(MODEL_ID)
           - --tensor-parallel-size=8
           - --host=0.0.0.0
           - --port=8000
           - --max-model-len=4096
           - --max-num-seqs=4
           env:
           - name: MODEL_ID
             value: google/gemma-3-27b-it
           - name: HUGGING_FACE_HUB_TOKEN
             valueFrom:
               secretKeyRef:
                 name: hf-secret
                 key: hf_api_token
           volumeMounts:
           - mountPath: /dev/shm
             name: dshm
           livenessProbe:
             httpGet:
               path: /health
               port: 8000
             initialDelaySeconds: 720
             periodSeconds: 10
           readinessProbe:
             httpGet:
               path: /health
               port: 8000
             initialDelaySeconds: 720
             periodSeconds: 5
         volumes:
         - name: dshm
           emptyDir:
               medium: Memory
         nodeSelector:
           cloud.google.com/gke-accelerator: nvidia-b200
           cloud.google.com/reservation-name: $RESERVATION_URL
           cloud.google.com/reservation-affinity: "specific"
           cloud.google.com/gke-gpu-driver-version: latest
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: llm-service
   spec:
     selector:
       app: gemma-server
     type: ClusterIP
     ports:
       - protocol: TCP
         port: 8000
         targetPort: 8000

2. Aplica el archivo vllm-3-27b-it.yaml a tu clúster de GKE:

   envsubst < vllm-3-27b-it.yaml | kubectl apply -f -

   Durante el proceso de implementación, el contenedor debe descargar Gemma 3 de Hugging Face. Por este motivo, la implementación del contenedor puede tardar hasta 30 minutos en completarse.

3. Espera a que se complete la implementación:

   kubectl wait \
       --for=condition=Available \
       --timeout=1800s deployment/vllm-gemma-deployment

Interactúa con Gemma 3 con curl

Para verificar los modelos ajustados por instrucciones de Gemma 3 27B implementados, sigue estos pasos:

1. Configura la redirección de puertos a Gemma 3:

   kubectl port-forward service/llm-service 8000:8000

2. Abre una nueva ventana de terminal. Luego, puedes chatear con tu modelo con curl:

   curl http://127.0.0.1:8000/v1/chat/completions \
   -X POST \
   -H "Content-Type: application/json" \
   -d '{
     "model": "google/gemma-3-27b-it",
     "messages": [
       {
         "role": "user",
         "content": "Why is the sky blue?"
       }
     ]
   }' | jq .

   El resultado es similar a este:

   {
     "id": "chatcmpl-e4a2e624bea849d9b09f838a571c4d9e",
     "object": "chat.completion",
     "created": 1741763029,
     "model": "google/gemma-3-27b-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
   }
   

Si deseas observar el rendimiento de tu modelo, puedes usar la integración del panel de vLLM en Cloud Monitoring. Este panel te ayuda a ver las métricas de rendimiento críticas de tu modelo, como la capacidad de procesamiento de tokens, la latencia de la red y las tasas de error. Para obtener información, consulta vLLM en la documentación de Monitoring.

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

Borra recursos

1. Para borrar la implementación y el servicio definidos en el archivo vllm-3-27b-it.yaml y el secreto de Kubernetes del clúster de GKE, ejecuta lo siguiente:

   envsubst < vllm-3-27b-it.yaml | kubectl delete -f -
   kubectl delete secret hf-secret

2. Para borrar tu clúster de GKE, ejecuta el siguiente comando:

   gcloud container clusters delete $CLUSTER_NAME \
       --region=$REGION \
       --quiet

Borra tu proyecto

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

• Se borra todo su contenido. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los IDs personalizados de los proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID personalizado del proyecto que desees utilizar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto, en lugar de todo el proyecto.

Si planeas explorar varios instructivos, arquitecturas o guías de inicio rápido, reutilizar proyectos puede ser útil para no exceder los límites de cuota de los proyectos.

Borra un Google Cloud proyecto de:

gcloud projects delete PROJECT_ID

¿Qué sigue?

• Administra clústeres de GKE optimizados para IA