Implementa GKE Inference Gateway con tecnología de llm-d

En este documento, se describe cómo implementar GKE Inference Gateway.

Este documento está dirigido a los especialistas en redes responsables de administrar la infraestructura de GKE y a los administradores de plataformas que administran cargas de trabajo de IA.

Antes de leer esta página, asegúrate de estar familiarizado con los siguientes temas:

La puerta de enlace de inferencia de GKE mejora la puerta de enlace de Google Kubernetes Engine (GKE) para optimizar la entrega de aplicaciones y cargas de trabajo de IA generativa en GKE. Proporciona una administración y un escalamiento eficientes de las cargas de trabajo de IA, permite establecer objetivos de rendimiento específicos para cada carga de trabajo, como la latencia, y mejora la utilización de recursos, la observabilidad y la seguridad de la IA.

Antes de comenzar

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

  • Habilita la API de Google Kubernetes Engine.
    • Habilitar la API de Google Kubernetes Engine
  • Si deseas usar Google Cloud CLI para esta tarea, instala y, luego, inicializa gcloud CLI. Si ya instalaste la gcloud CLI, ejecuta el comando gcloud components update para obtener la versión más reciente. Es posible que las versiones anteriores de la gcloud CLI no admitan la ejecución de los comandos que se describen en este documento.

  • Si es necesario, habilita la API de Compute Engine, la API de Kubernetes Engine, la API de Network Services y la API de Model Armor.

    Ve a Habilita el acceso a las APIs y sigue las instrucciones.

  • Asegúrate de tener los siguientes roles en el proyecto: roles/container.admin, roles/iam.serviceAccountAdmin.

  • Asegúrate de que tu proyecto tenga la cuota suficiente para las GPU H100. Para obtener más información, consulta Planifica la cuota de GPU y Cuotas de asignación.

  • Crea una cuenta de Hugging Face si aún no tienes una. Lo necesitarás para acceder a los recursos del modelo de este instructivo.

  • Solicita acceso al modelo Llama 3.1 y genera un token de acceso. El acceso a este modelo requiere una solicitud aprobada en Hugging Face, y la implementación fallará si no se otorgó el acceso.

    • Firma el acuerdo de consentimiento de licencia: Debes firmar el acuerdo de consentimiento para usar el modelo de Llama 3.1. Ve a la página del modelo en Hugging Face, verifica tu cuenta y acepta las condiciones.
    • Genera un token de acceso: Para acceder al modelo, necesitas un token de Hugging Face. En tu cuenta de Hugging Face, ve a Tu perfil > Configuración > Tokens de acceso, crea un token nuevo con al menos permisos de lectura y cópialo en el portapapeles.

Requisitos del controlador de la puerta de enlace de GKE

  • GKE versión 1.32.3 o posterior.
  • Versión 407.0.0 o posterior de Google Cloud CLI.
  • La API de Gateway solo es compatible con los clústeres nativos de la VPC.
  • Debes habilitar una subred exclusiva de proxy.
  • El clúster debe tener el complemento HttpLoadBalancing habilitado.
  • Si usas Istio, debes actualizarlo a una de las siguientes versiones:
    • 1.15.2 o una versión posterior
    • 1.14.5 o una versión posterior
    • 1.13.9 o una versión posterior
  • Si usas una VPC compartida, en el proyecto host, debes asignar el rol Compute Network User a la cuenta de servicio de GKE para el proyecto de servicio.

Restricciones y limitaciones

Se aplican las siguientes restricciones y limitaciones:

  • No se admiten las puertas de enlace de varios clústeres.
  • La puerta de enlace de inferencia de GKE solo es compatible con los recursos GatewayClass gke-l7-regional-external-managed y gke-l7-rilb.
  • No se admiten los balanceadores de cargas de aplicaciones internos entre regiones.
  • Un InferencePool puede tener un máximo de ocho targetPorts.

Configura GKE Inference Gateway

Para configurar GKE Inference Gateway, considera este ejemplo. Un equipo ejecuta modelos de vLLM y Llama3, y experimenta de forma activa con dos adaptadores distintos ajustados con LoRA: "food-review" y "cad-fabricator".

El flujo de trabajo de alto nivel para configurar GKE Inference Gateway es el siguiente:

  1. Prepara tu entorno: Configura la infraestructura y los componentes necesarios.
  2. Crea un grupo de inferencia: Define un grupo de servidores de modelos con el recurso personalizado InferencePool.
  3. Especifica objetivos de inferencia: Especifica objetivos de inferencia con el recurso personalizado InferenceObjective
  4. Crea la puerta de enlace: Expón el servicio de inferencia con la API de Gateway.
  5. Crea el HTTPRoute: Define cómo se enruta el tráfico HTTP al servicio de inferencia.
  6. Envía solicitudes de inferencia: Realiza solicitudes al modelo implementado.

Crea la puerta de enlace

El recurso Gateway es el punto de entrada para el tráfico externo en tu clúster de Kubernetes. Define los objetos de escucha que aceptan conexiones entrantes.

GKE Inference Gateway funciona con las siguientes clases de Gateway:

  • gke-l7-rilb: Para balanceadores de cargas de aplicaciones internos regionales.
  • gke-l7-regional-external-managed: Para balanceadores de cargas de aplicaciones externos regionales.

Para obtener más información, consulta la documentación de clases de Gateway.

Para crear una puerta de enlace, sigue estos pasos:

  1. Guarda el siguiente manifiesto de muestra como gateway.yaml:

    apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: GATEWAY_NAME
spec:
  gatewayClassName: GATEWAY_CLASS
  listeners:
    - protocol: HTTP
      port: 80
      name: http

    Reemplaza lo siguiente:

    • GATEWAY_NAME: Es un nombre único para tu recurso de Gateway. Por ejemplo, inference-gateway
    • GATEWAY_CLASS: Es la clase de puerta de enlace que deseas usar. Por ejemplo, gke-l7-regional-external-managed

  2. Aplica el manifiesto al clúster:

    kubectl apply -f gateway.yaml

Nota: Para obtener más información sobre cómo configurar TLS para proteger tu puerta de enlace con HTTPS, consulta la documentación de GKE sobre la configuración de TLS.

Prepara el entorno

  1. Instala Helm.

  2. Crea un clúster de GKE:

    • Crea un clúster de GKE Autopilot o Standard con la versión 1.32.3 o posterior. Para ver una configuración de referencia de implementación con un clic, consulta el ejemplo de cluster-toolkit gke-a3-highgpu.
    • Configura los nodos con la familia de procesamiento y el acelerador que prefieras.
    • Usa la Guía de inicio rápido de GKE Inference para obtener manifiestos de implementación preconfigurados y probados, según el acelerador, el modelo y las necesidades de rendimiento que selecciones.

  3. Instala las definiciones de recursos personalizados (CRD) necesarias en tu clúster de GKE:

    • Para las versiones de GKE 1.34.0-gke.1626000 o posteriores, el CRD InferencePool se incluye de forma predeterminada. Por lo tanto, instala solo la CRD de InferenceObjective alfa:

      kubectl apply -f https://github.com/kubernetes-sigs/gateway-api-inference-extension/raw/v1.4.0/config/crd/bases/inference.networking.x-k8s.io_inferenceobjectives.yaml

    • En las versiones de GKE anteriores a 1.34.0-gke.1626000, instala las CRD de InferencePool v1 y InferenceObjective alfa:

      kubectl apply -f  https://github.com/kubernetes-sigs/gateway-api-inference-extension/releases/download/v1.4.0/manifests.yaml

      Para obtener más información, consulta la matriz de compatibilidad.

  4. Si usas una versión de GKE anterior a v1.32.2-gke.1182001 y deseas usar Model Armor con GKE Inference Gateway, debes instalar los CRD de extensión de tráfico y enrutamiento:

    kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcptrafficextensions.yaml
kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcproutingextensions.yaml

  5. Configura las siguientes variables de entorno:

    export GAIE_VERSION=v1.5.0
export GUIDE_NAME="optimized-baseline"
export NAMESPACE=llm-d-optimized-baseline
export INFRA_PROVIDER=gke   # gke | base

  6. Instala las definiciones de recursos personalizados (CRD) de la extensión de inferencia de la API de Gateway que requiere el selector de extremos (EPP) de llm-d:

    kubectl apply -k \
  "https://github.com/kubernetes-sigs/gateway-api-inference-extension/config/crd?ref=${GAIE_VERSION}"

  7. Crea el espacio de nombres de destino:

    kubectl create namespace ${NAMESPACE}

Crea un servidor de modelos y una implementación de modelos

En esta sección, se muestra cómo implementar un servidor de modelos y un modelo. En el ejemplo, se usa un servidor de modelos vLLM con un modelo Llama3. La implementación se etiqueta como app:vllm-llama3-8b-instruct. Esta implementación también usa dos adaptadores de LoRA llamados food-review y cad-fabricator de Hugging Face.

Puedes adaptar este ejemplo con tu propio contenedor de servidor de modelos y modelo, puerto de entrega y nombre de implementación. También puedes configurar adaptadores LoRA en la implementación o implementar el modelo base. En los siguientes pasos, se describe cómo crear los recursos de Kubernetes necesarios.

  1. Crea un Secret de Kubernetes para almacenar tu token de Hugging Face. Este token se usa para acceder al modelo base y a los adaptadores de LoRA:

    kubectl create secret generic hf-token --from-literal=token=HF_TOKEN

    Reemplaza HF_TOKEN por tu token de Hugging Face.

  2. Implementa el servidor de modelos de vLLM con la superposición de Kustomize específica de GKE de la guía de referencia optimizada de llm-d. El parámetro de configuración INFRA_PROVIDER=gke aplica configuraciones específicas de GKE, incluida la integración de Cloud Monitoring:

    kubectl apply -n ${NAMESPACE} \
  -k guides/${GUIDE_NAME}/modelserver/gpu/vllm/${INFRA_PROVIDER}/

Nota: GKE proporciona supervisión automática de aplicaciones de forma predeterminada. La pila de supervisión de llm-d no es obligatoria para GKE, pero está disponible si prefieres usarla.

Si tu servidor de modelos requiere varios puertos, asegúrate de que la especificación del contenedor exponga cada puerto. En el siguiente ejemplo, se define una Deployment en la que el contenedor expone tres puertos:

Ejemplo de implementación en varios puertos

apiVersion: apps/v1
kind: Deployment
metadata:
  name: multiport-model-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: multiport-model-server
  template:
    metadata:
      labels:
        app: multiport-model-server
    spec:
      containers:
      - name: model-server
        image: your-model-server-image
        ports:
        - containerPort: 8080
        - containerPort: 8081
        - containerPort: 9000

Crea un grupo de inferencia

El recurso personalizado de Kubernetes InferencePool define un grupo de Pods con un modelo de lenguaje grande (LLM) base y una configuración de procesamiento comunes. El campo selector especifica qué Pods pertenecen a este grupo. Las etiquetas de este selector deben coincidir exactamente con las etiquetas aplicadas a los Pods del servidor del modelo. El campo targetPorts define los puertos que usa el servidor del modelo dentro de los Pods. Puedes especificar hasta ocho puertos. El campo extensionRef hace referencia a un servicio de extensión que proporciona capacidad adicional para el grupo de inferencia. InferencePool permite que GKE Inference Gateway enrute el tráfico a los Pods del servidor de tu modelo.

El siguiente manifiesto de InferencePool especifica varios targetPorts que corresponden a los puertos expuestos por la Deployment del servidor de modelos:

Ejemplo de InferencePool con varios puertos

apiVersion: inference.networking.k8s.io/v1
kind: InferencePool
metadata:
  name: my-multiport-pool
  namespace: default
spec:
  selector:
    matchLabels:
      app: multiport-model-server
  targetPorts:
    - number: 8080
    - number: 8081
    - number: 9000

Antes de crear el InferencePool, asegúrate de que los Pods que selecciona el InferencePool ya se estén ejecutando.

Para crear un InferencePool con Helm, sigue estos pasos:

helm install ${GUIDE_NAME} \
  -f guides/recipes/scheduler/base.values.yaml \
  -f guides/${GUIDE_NAME}/scheduler/${GUIDE_NAME}.values.yaml \
  --set provider.name=gke \
  --set inferenceExtension.monitoring.gke.enabled=true \
  -n ${NAMESPACE} \
  --version ${GAIE_VERSION} \
  oci://LLM_D_REGISTRY_PATH

Reemplaza lo siguiente:

  • GAIE_VERSION: Es la versión del gráfico de Helm. Por ejemplo, v1.5.0.
  • LLM_D_REGISTRY_PATH: Es la ruta de acceso al registro de OCI del gráfico de Helm. Por ejemplo, us-central1-docker.pkg.dev/cloud-ai-gke/gke-inference-gateway/charts/inferencepool

Cambia el siguiente campo para que coincida con tu Deployment:

  • inferencePool.modelServers.matchLabels.app: Es la clave de la etiqueta que se usa para seleccionar los Pods del servidor del modelo.

Para la supervisión, la extracción de métricas de Google Cloud Managed Service para Prometheus está habilitada de forma predeterminada.

  • Para inhabilitar esta función, agrega la marca --set inferenceExtension.monitoring.prometheus.enabled=false al comando.
  • Si usas la supervisión predeterminada en un clúster de Autopilot de GKE, también debes agregar la marca --set provider.gke.autopilot=true.

La instalación de Helm instala automáticamente la política de tiempo de espera necesaria, el selector de extremos y los Pods necesarios para la observabilidad.

Esto crea un objeto InferencePool: vllm-llama3-8b-instruct que hace referencia a los servicios de extremos del modelo dentro de los Pods. También crea una implementación del selector de extremos llamado app:vllm-llama3-8b-instruct-epp para este InferencePool creado.

Crea el HTTPRoute

El recurso HTTPRoute define cómo la puerta de enlace de GKE enruta las solicitudes HTTP entrantes a los servicios de backend, como tu InferencePool. El recurso HTTPRoute especifica reglas de coincidencia (por ejemplo, encabezados o rutas de acceso) y el backend al que se debe reenviar el tráfico.

  1. Para crear un HTTPRoute, guarda el siguiente manifiesto de muestra como httproute.yaml:

    apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: HTTPROUTE_NAME
spec:
  parentRefs:
  - name: GATEWAY_NAME
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: PATH_PREFIX
    backendRefs:
    - name: INFERENCE_POOL_NAME
      group: "inference.networking.k8s.io"
      kind: InferencePool

    Reemplaza lo siguiente:

    • HTTPROUTE_NAME: Es un nombre único para tu recurso HTTPRoute. Por ejemplo, my-route.
    • GATEWAY_NAME: Es el nombre del recurso Gateway que creaste. Por ejemplo, inference-gateway.
    • PATH_PREFIX: Es el prefijo de ruta de acceso que usas para hacer coincidir las solicitudes entrantes. Por ejemplo, / para que coincida con todo.
    • INFERENCE_POOL_NAME: Es el nombre del recurso InferencePool al que deseas enrutar el tráfico. Por ejemplo, vllm-llama3-8b-instruct

  2. Aplica el manifiesto al clúster:

    kubectl apply -f httproute.yaml

Especifica los objetivos de la inferencia

El recurso personalizado InferenceObjective te permite especificar la prioridad de las solicitudes.

El campo metadata.name del recurso InferenceObjective especifica el nombre del objetivo de inferencia, el campo Priority especifica su criticidad de servicio y el campo poolRef especifica el InferencePool en el que se publica el modelo.

apiVersion: inference.networking.x-k8s.io/v1alpha2
kind: InferenceObjective
metadata:
  name: NAME
spec:
  priority: VALUE
  poolRef:
    name: INFERENCE_POOL_NAME
    group: "inference.networking.k8s.io"

Reemplaza lo siguiente:

  • NAME: Es el nombre de tu objetivo de inferencia. Por ejemplo, food-review
  • VALUE: Es la prioridad del objetivo de inferencia. Es un número entero en el que un valor más alto indica una solicitud más crítica. Por ejemplo, 10.
  • INFERENCE_POOL_NAME: Es el nombre del InferencePool que creaste en el paso anterior. Por ejemplo, vllm-llama3-8b-instruct.

Para crear un InferenceObjective, sigue estos pasos:

  1. Guarda el siguiente manifiesto como inference-objectives.yaml. En este manifiesto, se crean dos recursos InferenceObjective. La primera configura el objetivo de inferencia food-review en InferencePool vllm-llama3-8b-instruct con una prioridad de 10. La segunda configura el objetivo de inferencia llama3-base-model para que se publique con una prioridad más alta de 20.

    apiVersion: inference.networking.x-k8s.io/v1alpha2
kind: InferenceObjective
metadata:
  name: food-review
spec:
  priority: 10
  poolRef:
    name: vllm-llama3-8b-instruct
    group: "inference.networking.k8s.io"
---
apiVersion: inference.networking.x-k8s.io/v1alpha2
kind: InferenceObjective
metadata:
  name: llama3-base-model
spec:
  priority: 20 # Higher priority
  poolRef:
    name: vllm-llama3-8b-instruct

  2. Aplica el manifiesto de muestra a tu clúster:

    kubectl apply -f inference-objectives.yaml

Verifica la implementación

Para verificar que todos los componentes se estén ejecutando, ejecuta los siguientes comandos:

kubectl get inferencepool
kubectl get inferenceobjective
kubectl get pods -l app=vllm-llama3-8b-instruct-epp

Envía la solicitud de inferencia

Después de configurar GKE Inference Gateway, puedes enviar solicitudes de inferencia a tu modelo implementado. Esto te permite generar texto según la instrucción de entrada y los parámetros especificados.

Para enviar solicitudes de inferencia, sigue estos pasos:

  1. Configura las siguientes variables de entorno:

    export GATEWAY_NAME=GATEWAY_NAME
export PORT_NUMBER=PORT_NUMBER # Use 80 for HTTP

    Reemplaza lo siguiente:

    • GATEWAY_NAME: Es el nombre de tu recurso de Gateway.
    • PORT_NUMBER: Es el número de puerto que configuraste en la puerta de enlace.

  2. Para obtener el extremo de la puerta de enlace, ejecuta el siguiente comando:

    echo "Waiting for the Gateway IP address..."
IP=""
while [ -z "$IP" ]; do
  IP=$(kubectl get gateway/${GATEWAY_NAME} -o jsonpath='{.status.addresses[0].value}' 2>/dev/null)
  if [ -z "$IP" ]; then
    echo "Gateway IP not found, waiting 5 seconds..."
    sleep 5
  fi
done

echo "Gateway IP address is: $IP"
PORT=${PORT_NUMBER}

  3. Para enviar una solicitud al extremo /v1/completions con curl, ejecuta el siguiente comando:

    curl -i -X POST ${IP}:${PORT}/v1/completions \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $(gcloud auth application-default print-access-token)' \
-d '{
    "model": "MODEL_NAME",
    "prompt": "PROMPT_TEXT",
    "max_tokens": MAX_TOKENS,
    "temperature": "TEMPERATURE"
}'

    Reemplaza lo siguiente:

    • MODEL_NAME: Es el nombre del modelo o del adaptador de LoRA que se usará.
    • PROMPT_TEXT: Es la instrucción de entrada para el modelo.
    • MAX_TOKENS: Es la cantidad máxima de tokens que se pueden generar en la respuesta.
    • TEMPERATURE: Controla la aleatoriedad del resultado. Usa el valor 0 para obtener un resultado determinístico o un número más alto para obtener un resultado más creativo.

En el siguiente ejemplo, se muestra cómo enviar una solicitud de muestra a GKE Inference Gateway:

curl -i -X POST ${IP}:${PORT}/v1/completions -H 'Content-Type: application/json' -H 'Authorization: Bearer $(gcloud auth application-default print-access-token)' -d '{
    "model": "food-review-1",
    "prompt": "What is the best pizza in the world?",
    "max_tokens": 2048,
    "temperature": 0
}'

Ten en cuenta los siguientes comportamientos:

  • Cuerpo de la solicitud: El cuerpo de la solicitud puede incluir parámetros adicionales, como stop y top_p. Consulta la especificación de la API de OpenAI para obtener una lista completa de opciones.
  • Manejo de errores: implementa un manejo de errores adecuado en el código del cliente para controlar los posibles errores en la respuesta. Por ejemplo, verifica el código de estado HTTP en la respuesta curl. Por lo general, un código de estado que no es 200 indica un error.
  • Autenticación y autorización: Para las implementaciones de producción, protege tu extremo de API con mecanismos de autenticación y autorización. Incluye los encabezados adecuados (por ejemplo, Authorization) en tus solicitudes.

Matriz de compatibilidad

En la siguiente tabla, se describe la matriz de compatibilidad y asistencia para las definiciones de recursos personalizados (CRD) de la extensión de inferencia de la API de Gateway. Detalla qué versiones de CustomResourceDefinition son compatibles con GKE en comparación con el proyecto de extensión de inferencia de la API de Gateway de código abierto (OSS), incluidos los requisitos de versión específicos y las notas de instalación.

Nombre de CustomResourceDefinition Versión de la API de CustomResourceDefinition Asistencia administrada de GKE Compatibilidad con OSS (extensión de inferencia de la API de Gateway)
InferencePool de la versión 1 inference.networking.k8s.io/v1 Es compatible con GKE 1.32.3 o versiones posteriores, y CustomResourceDefinition se instala de forma predeterminada en GKE 1.34.0-gke.1626000 o versiones posteriores. Compatible a partir de la versión 1.0.0 de la extensión de inferencia de la API de Gateway
InferencePool alfa (se recomienda que los usuarios comiencen con InferencePool v1, ya que la versión alfa de InferencePool dejó de estar disponible) inference.networking.x-k8s.io/v1alpha2 Es compatible con GKE 1.32.3 o versiones posteriores. Sin embargo, CustomResourceDefinition no se instala de forma predeterminada en GKE. Los usuarios deben instalar manualmente el CustomResourceDefinition desde la extensión de inferencia de la API de Gateway. Compatible a partir de la extensión de inferencia de la API de Gateway v0.2.0
Alpha InferenceObjective inference.networking.x-k8s.io/v1alpha2 GKE no administra InferenceObjective Compatible a partir de la versión 1.0.0 de la extensión de inferencia de la API de Gateway
Modelo InferenceModel alfa (se recomienda que los usuarios comiencen con InferenceObjective, ya que InferenceModel dejó de estar disponible) inference.networking.x-k8s.io/v1alpha2 GKE no administra InferenceModel Se admite a partir de la versión 0.2.0 de la extensión de inferencia de la API de Gateway.

¿Qué sigue?