Se usó la API de Cloud Translation para traducir esta página.

Entrega LLMs abiertos en GKE con una arquitectura preconfigurada

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 con una arquitectura de referencia preconfigurada y lista para producción. Este enfoque usa infraestructura como código (IaC), con Terraform encapsulado en secuencias de comandos de CLI, para crear un entorno de GKE estandarizado, seguro y escalable diseñado para cargas de trabajo de inferencia basadas en IA.

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

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 los que se hace referencia en el contenido de Google Cloud , consulta Roles y tareas comunes de los usuarios 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 de inicio rápido de GKE Inference. Para obtener más información, consulta la guía de inicio rápido de GKE Inference y el notebook de Colab que la acompaña.

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 Lectura.
Selecciona Generate un token.
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 consola Google Cloud , 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:

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

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: Tu Google Cloud ID del proyecto.
- HF_TOKEN: El token de Hugging Face que generaste antes.
En esta guía, se requiere la versión 1.8.0 o posterior de Terraform. Cloud Shell tiene instalada la versión 1.5.7 de Terraform 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 realiza cambios en tu entorno de shell.
```
"${ACP_REPO_DIR}/tools/bin/install_terraform.sh"
source ~/.bashrc
```
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 de asistencia. La secuencia de comandos puede tardar varios minutos en completarse.

Puedes entregar modelos con GPUs 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"
```
Estándar
```
"${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.

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"

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 puedes descargar e implementar el modelo.

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 más información sobre otras configuraciones, incluidas otras variantes de modelos y tipos de GPU, consulta los manifiestos disponibles en el repositorio de GitHub de accelerated-platforms.
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"
```

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"

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

Espere a que se complete la descarga. Supervisa el estado del trabajo y, cuando COMPLETIONS sea 1/1, presiona 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

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

Prueba tu implementación

Espera a que el Pod del servidor de inferencia esté listo. Cuando la columna READY sea 1/1, presiona 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}"

Ejecuta la siguiente secuencia de comandos para configurar la redirección de puertos y enviar una solicitud de muestra al modelo. En este ejemplo, se usa el formato de carga útil para 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 responde la pregunta.

Limpia

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

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

Quita el clúster de GKE fundamental:

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 del modelo con la herramienta de inicio rápido de GKE Inference.
Explora otros casos de uso y patrones en GitHub basados en esta arquitectura.

Entrega LLMs abiertos en GKE con una arquitectura preconfigurada

Obtén acceso al modelo

Aprovisiona el entorno de inferencia de GKE

Inicia Cloud Shell

Implementa la arquitectura base

Autopilot

Estándar

Implementa un modelo abierto

Gemma 3 27B-it

Llama 4 Scout 17B-16E-Instruct

Qwen3 32B

gpt-oss 20B

Prueba tu implementación

Limpia

Autopilot

Standard

¿Qué sigue?