Servir LLMs abiertos en GKE con una arquitectura preconfigurada

Autopilot Standard

---

En esta página se explica cómo desplegar y servir rápidamente modelos de lenguaje grandes (LLMs) abiertos populares en GKE para la inferencia mediante una arquitectura de referencia preconfigurada y lista para producción. Este enfoque usa la infraestructura como código (IaC), con Terraform envuelto en secuencias de comandos de la CLI, para crear un entorno de GKE estandarizado, seguro y escalable diseñado para cargas de trabajo de inferencia de IA.

En esta guía, desplegarás y servirás LLMs mediante nodos de GPU de un solo host en GKE con el framework de servicio vLLM. En esta guía se proporcionan instrucciones y configuraciones para implementar los siguientes modelos abiertos:

• Google Gemma 3 27B-it
• Meta Llama 4 Scout 17B-16E-Instruct
• Qwen3 32-B
• gpt-oss-20b de OpenAI

Esta guía está dirigida a ingenieros de aprendizaje automático (ML) y especialistas en datos e IA que quieran explorar las funciones de orquestación de contenedores de Kubernetes para servir modelos abiertos con fines de inferencia. Para obtener más información sobre los roles habituales y las tareas de ejemplo que se mencionan en el contenido de Google Cloud , consulta Roles y tareas de usuario habituales de GKE.

Antes de empezar

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.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the required APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

• Make sure that you have the following role or roles on the project: roles/artifactregistry.admin, roles/browser, roles/compute.networkAdmin, roles/container.clusterAdmin, roles/iam.serviceAccountAdmin, roles/resourcemanager.projectIamAdmin, and roles/serviceusage.serviceUsageAdmin

  Check for the roles

  1. In the Google Cloud console, go to the IAM page.

     Go to IAM
  2. Select the project.

  3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

  4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

  Grant the roles

  1. In the Google Cloud console, go to the IAM page.

     Ir a IAM
  2. Selecciona el proyecto.
  3. Haz clic en Conceder acceso.

  4. En el campo Nuevos principales, introduce tu identificador de usuario. Normalmente, se trata de la dirección de correo de una cuenta de Google.

  5. En la lista Selecciona un rol, elige un rol.
  6. Para conceder más roles, haz clic en Añadir otro rol y añade cada rol adicional.
  7. Haz clic en Guardar.
  • Crea una cuenta de Hugging Face.
  • Asegúrate de que tu proyecto tenga suficiente cuota de GPU. Para obtener más información, consulta Cuotas de asignación.

  Acceder al modelo

  Nota: Debes aceptar los términos de la licencia de los modelos protegidos que quieras usar (como Gemma o Llama) en su página de modelo de Hugging Face correspondiente.

  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:

  1. Haz clic en Tu perfil > Configuración > Tokens de acceso.
  2. Selecciona New Token (Nuevo token).
  3. Especifica el Nombre que quieras y un Rol de al menos Lectura.
  4. Selecciona Generar un token.
  5. Copia el token generado en el portapapeles.

  Aprovisionar el entorno de inferencia de GKE

  En esta sección, desplegarás la infraestructura necesaria para ofrecer tu modelo.

  Abrir Cloud Shell

  En esta guía se usa Cloud Shell para ejecutar comandos. Cloud Shell tiene preinstaladas las herramientas necesarias, como gcloud, kubectl y git.

  En la Google Cloud consola, inicia una instancia de Cloud Shell:

  Abrir Cloud Shell

  Esta acción inicia una sesión en el panel inferior de la consola Google Cloud .

  Implementar la arquitectura base

  Para aprovisionar el clúster de GKE y los recursos necesarios para acceder a los modelos de Hugging Face, sigue estos pasos:

  1. En Cloud Shell, clona el siguiente repositorio:

     git clone https://github.com/GoogleCloudPlatform/accelerated-platforms --branch hf-model-tutorial && \
     cd accelerated-platforms && \
     export ACP_REPO_DIR="$(pwd)"
     

  2. Define las variables de entorno:

     export TF_VAR_platform_default_project_id=PROJECT_ID
     export HF_TOKEN_READ=HF_TOKEN
     

     Sustituye los siguientes valores:

     • PROJECT_ID: tu Google Cloud ID de proyecto.
     • HF_TOKEN: el token de Hugging Face que has generado anteriormente.

  3. Para seguir esta guía, necesitas Terraform 1.8.0 o una versión posterior. Cloud Shell tiene Terraform v1.5.7 instalado de forma predeterminada.

     Para actualizar la versión de Terraform en Cloud Shell, puedes ejecutar la siguiente secuencia de comandos. Esta secuencia de comandos instala la herramienta terraform-switcher y hace cambios en tu entorno de shell.

     "${ACP_REPO_DIR}/tools/bin/install_terraform.sh"
     source ~/.bashrc
     

  4. Ejecuta la siguiente secuencia de comandos de implementación. La secuencia de comandos de implementación habilita las APIs Google Cloud necesarias y aprovisiona la infraestructura necesaria para esta guía. Esto incluye una nueva red de VPC, un clúster de GKE con nodos privados y otros recursos complementarios. La secuencia de comandos puede tardar varios minutos en completarse.

     Puedes servir modelos con GPUs en un clúster Autopilot o Standard de GKE. Un clúster de Autopilot ofrece una experiencia de Kubernetes totalmente gestionada. Para obtener más información sobre cómo elegir el modo de funcionamiento de GKE que mejor se adapte a tus cargas de trabajo, consulta el artículo Acerca de los modos de funcionamiento de GKE.

     Autopilot

     "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/deploy-ap.sh"
     

     Estándar

     "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/deploy-standard.sh"
     

     Una vez que se haya completado esta secuencia de comandos, tendrás un clúster de GKE listo para las cargas de trabajo de inferencia.

  5. Ejecuta el siguiente comando para definir las variables de entorno de la configuración compartida:

     source "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/terraform/_shared_config/scripts/set_environment_variables.sh"
     

  6. La secuencia de comandos de implementación crea un secreto en Secret Manager para almacenar tu token de Hugging Face. Debes añadir manualmente tu token a este secreto antes de implementar el clúster. En Cloud Shell, ejecuta este comando para añadir el token a Secret Manager.

     echo ${HF_TOKEN_READ} | gcloud secrets versions add ${huggingface_hub_access_token_read_secret_manager_secret_name} \
         --data-file=- \
         --project=${huggingface_secret_manager_project_id}
     

  Desplegar un modelo abierto

  Ya puedes descargar e implementar el modelo.

  1. Define las variables de entorno del modelo que quieras implementar:

     Gemma 3 27B-it

     export ACCELERATOR_TYPE="h100"
     export HF_MODEL_ID="google/gemma-3-27b-it"
     

     Llama 4 Scout 17B-16E-Instruct

     export ACCELERATOR_TYPE="h100"
     export HF_MODEL_ID="meta-llama/llama-4-scout-17b-16e-instruct"
     

     Qwen3 32B

     export ACCELERATOR_TYPE="h100"
     export HF_MODEL_ID="qwen/qwen3-32b"
     

     gpt-oss 20B

     export ACCELERATOR_TYPE="h100"
     export HF_MODEL_ID="openai/gpt-oss-20b"
     

     Para ver otras configuraciones, como otras variantes de modelo y tipos de GPU, consulta los manifiestos disponibles en el repositorio de GitHub accelerated-platforms.

  2. Obtén las variables de entorno de tu implementación. Estas variables de entorno contienen los detalles de configuración necesarios de la infraestructura que has aprovisionado.

     source "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/terraform/_shared_config/scripts/set_environment_variables.sh"
     

  3. Ejecuta la siguiente secuencia de comandos para configurar el trabajo de Kubernetes que descarga el modelo en Cloud Storage:

     "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/configure_huggingface.sh"
     

  4. Despliega el trabajo de descarga del modelo:

     kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/huggingface"
     

  5. Espera a que se complete la descarga. Monitoriza el estado del trabajo y, cuando COMPLETIONS sea 1/1, pulsa Ctrl+C para salir.

     watch --color --interval 5 --no-title "kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs
     

  6. Despliega la carga de trabajo de inferencia en tu clúster de GKE.

     "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/configure_deployment.sh"
     
     kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
     

  Probar la implementación

  1. Espera a que el pod del servidor de inferencia esté listo. Cuando la columna READY sea 1/1, pulsa Ctrl+C para salir.

     watch --color --interval 5 --no-title "kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
     

  2. Ejecuta la siguiente secuencia de comandos para configurar el reenvío de puertos y enviar una solicitud de muestra al modelo. En este ejemplo se usa el formato de carga útil de un modelo Gemma 3 27b-it.

     kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} port-forward service/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} 8000:8000 >/dev/null &
     PF_PID=$!
     curl http://127.0.0.1:8000/v1/chat/completions \
       --data '{
         "model": "/gcs/'${HF_MODEL_ID}'",
         "messages": [ { "role": "user", "content": "What is GKE?" } ]
       }' \
       --header "Content-Type: application/json" \
       --request POST \
       --show-error \
       --silent | jq
     kill -9 ${PF_PID}
     

     Deberías ver una respuesta JSON del modelo que responda a la pregunta.

  Limpieza

  Para evitar que se te apliquen cargos, elimina todos los recursos que hayas creado.

  1. Elimina la carga de trabajo de inferencia:

     kubectl delete --ignore-not-found --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
     

  2. Elimina el clúster de GKE básico:

     Autopilot

     "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/teardown-ap.sh"
     

     Estándar

     "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/teardown-standard.sh"
     

  Siguientes pasos

  • Más información sobre la inferencia de modelos de IA y aprendizaje automático en GKE
  • Analiza el rendimiento y los costes de la inferencia de modelos con la herramienta de inicio rápido de inferencia de GKE.
  • Consulta otros casos prácticos y patrones en GitHub basados en esta arquitectura.