Entrega LLMs abiertos en GKE con una arquitectura preconfigurada

Autopilot Standard

En esta página, se muestra cómo implementar y entregar rápidamente modelos de lenguaje grandes (LLM) abiertos populares en GKE para la inferencia mediante una arquitectura de referencia de inferencia de GKE preconfigurada y lista para la producción. arquitectura de referencia de inferencia de GKE. Este enfoque usa 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, implementarás y entregarás LLM con nodos de GPU de un solo host en GKE con el framework de entrega 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
• OpenAI gpt-oss-20b

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

Esta guía está dirigida a ingenieros de aprendizaje automático (AA) y especialistas en datos y en IA que estén interesados en explorar las capacidades de organización de contenedores de Kubernetes para entregar modelos abiertos para la inferencia. Para obtener más información sobre los roles comunes y las tareas de ejemplo a las que se hace referencia en el Google Cloud contenido, consulta Roles y tareas comunes del usuario de GKE.

Para obtener un análisis detallado del rendimiento y los costos de la entrega de modelos para estos modelos abiertos, también puedes usar la herramienta GKE Inference Quickstart. Para obtener más información, consulta la guía de GKE Inference Quickstart y el notebook de Colab que la acompaña.

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.

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 role (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 role (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

• Asegúrate de tener los siguientes roles en el proyecto: roles/artifactregistry.admin, roles/browser, roles/compute.networkAdmin, roles/container.clusterAdmin, roles/iam.roleAdmin, roles/iam.serviceAccountAdmin, roles/resourcemanager.projectIamAdmin, roles/serviceusage.serviceUsageAdmin y roles/secretmanager.secretVersionManager

  Verifica los roles

  1. En la Google Cloud consola de, dirígete a la página IAM.

     Ir a IAM
  2. Selecciona el proyecto.

  3. En la columna Principal, busca todas las filas que te identifiquen a ti o a un grupo en el que se te incluya. Para saber en qué grupos estás incluido, comunícate con tu administrador.

  4. Para todas las filas en las que se te especifique o se te incluya, verifica la columna Rol para ver si la lista de roles incluye los roles necesarios.

  Otorga los roles

  1. En la Google Cloud consola de, dirígete a la página IAM.

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

  4. En el campo Principales nuevas, ingresa tu identificador de usuario. Esta suele ser la dirección de correo electrónico de una Cuenta de Google.

  5. Haz clic en Selecciona un rol y, luego, busca el rol.
  6. Para otorgar roles adicionales, haz clic en Agregar otro rol y agrega uno más.
  7. Haz clic en Guardar.

• Crea una cuenta de Hugging Face.
• Asegúrate de que tu proyecto tenga una cuota de GPU suficiente. Para obtener más información, consulta Cuotas de asignación.

Obtén acceso al modelo

Acepta las condiciones de la licencia de los modelos protegidos que quieras usar (como Gemma o Llama) en su página de modelo de Hugging Face respectiva.

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:

1. Haz clic en Tu perfil > Configuración > Tokens de acceso.
2. Selecciona Token nuevo.
3. Especifica el nombre que desees y un rol de al menos Lectura.
4. Selecciona Generate un token.
5. Copia el token generado al portapapeles.

Aprovisiona el entorno de inferencia de GKE

En esta sección, implementarás la infraestructura necesaria para entregar tu modelo.

Inicia Cloud Shell

En esta guía, se usa Cloud Shell para ejecutar comandos. Cloud Shell ya viene instalado con las herramientas necesarias, incluidas gcloud, kubectl y git.

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

Abra Cloud Shell

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

Implementa 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-vllm-gpu-tutorial && \
   cd accelerated-platforms && \
   export ACP_REPO_DIR="$(pwd)"
   

2. Configura las variables de entorno:

   export TF_VAR_platform_default_project_id=PROJECT_ID
   export HF_TOKEN_READ=HF_TOKEN
   

   Reemplaza los siguientes valores:

   • PROJECT_ID: Es tu Google Cloud ID del proyecto.
   • HF_TOKEN: Es el token de Hugging Face que generaste antes.

3. En esta guía, se requiere Terraform versión 1.8.0 o 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 tfswitch herramienta y Terraform v1.8.0 en tu directorio principal. Sigue las instrucciones de la secuencia de comandos para configurar la variable de entorno necesaria o pasar la marca --modify-rc-file a la secuencia de comandos.

   "${ACP_REPO_DIR}/tools/bin/install_terraform.sh" && \
   export PATH=${HOME}/bin:${HOME}/.local/bin:${PATH}
   

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 red de VPC nueva, un clúster de GKE con nodos privados y otros recursos de asistencia. La secuencia de comandos puede tardar varios minutos en completarse.

   Puedes entregar modelos con GPU en un clúster de GKE Autopilot o Standard. Un clúster de Autopilot proporciona una experiencia de Kubernetes completamente administrada. Para obtener más información sobre cómo elegir el modo de operación de GKE que se adapte mejor a tus cargas de trabajo, consulta Acerca de los modos de operación de GKE.

   Autopilot

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

   Standard

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

   Una vez que se complete 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 establecer variables de entorno desde 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 agregar manualmente tu token a este secreto antes de implementar el clúster. En Cloud Shell, ejecuta este comando para agregar 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}
   

Implementa un modelo abierto

Ya estás listo para descargar e implementar el modelo.

Seleccionar un modelo

1. Configura las variables de entorno para el modelo que deseas 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 obtener configuraciones adicionales, incluidas otras variantes de modelo y tipos de GPU, consulta los manifiestos disponibles en el accelerated-platforms repositorio de GitHub.

Descarga el modelo

1. 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 aprovisionaste.

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

2. Ejecuta la siguiente secuencia de comandos para configurar los recursos de descarga del modelo de Hugging Face 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"
   

3. Aplica los recursos de descarga del modelo de Hugging Face:

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

4. Supervisa el trabajo de descarga del modelo de Hugging Face hasta que se complete.

   until kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} wait job/${HF_MODEL_ID_HASH}-hf-model-to-gcs --for=condition=complete --timeout=10s >/dev/null; do
       clear
       kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e 'Complete'
       echo -e "\nhf-model-to-gcs logs(last 10 lines):"
       kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} logs job/${HF_MODEL_ID_HASH}-hf-model-to-gcs --container=hf-model-to-gcs --tail 10
   done
   

5. Verifica que el trabajo de descarga del modelo de Hugging Face esté completo.

   kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e 'Complete'
   

6. Borra los recursos de descarga del modelo de Hugging Face.

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

Implementa el modelo

1. Obtén las variables de entorno de tu implementación.

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

2. Verifica que se haya configurado el nombre del modelo de Hugging Face.

   echo "HF_MODEL_NAME=${HF_MODEL_NAME}"
   

3. Configura los recursos de vLLM.

   "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/configure_vllm.sh"
   

4. Implementa la carga de trabajo de inferencia en tu clúster de GKE.

   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}"
   

Prueba tu implementación

1. Supervisa la implementación de la carga de trabajo de inferencia hasta que esté disponible.

   until kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} wait deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --for=condition=available --timeout=10s >/dev/null; do
       clear
       kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e '1/1     1            1'
       echo -e "\nfetch-safetensors logs(last 10 lines):"
       kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=fetch-safetensors --tail 10
       echo -e "\ninference-server logs(last 10 lines):"
       kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=inference-server --tail 10
   done
   

1. Verifica que la implementación de la carga de trabajo de inferencia esté disponible.

   kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e '1/1     1            1'
   echo -e "\nfetch-safetensors logs(last 10 lines):"
   kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=fetch-safetensors --tail 10
   echo -e "\ninference-server logs(last 10 lines):"
   kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=inference-server --tail 10
   

2. Ejecuta la siguiente secuencia de comandos para configurar la redirección de puertos y enviar una solicitud de muestra al modelo.

   kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} port-forward service/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} 8000:8000 >/dev/null &
   PF_PID=$!
   while ! echo -e '\x1dclose\x0d' | telnet localhost 8000 >/dev/null 2>&1; do
       sleep 0.1
   done
   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 responde la pregunta.

Limpia

Para evitar que se generen cobros, borra todos los recursos que creaste.

1. Borra 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. Limpia los recursos:

   Autopilot

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

   Standard

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

¿Qué sigue?

• Obtén más información sobre la inferencia de modelos de IA/AA en GKE.
• Analiza el rendimiento y los costos de la inferencia de modelos con la herramienta GKE Inference Quickstart.
• Explora el repositorio de GitHub accelerated-platforms que se usó para compilar esta arquitectura.