Esegui il deployment di GKE Inference Gateway basato su llm-d

Questo documento descrive come eseguire il deployment di GKE Inference Gateway.

Questo documento è destinato agli specialisti di networking responsabili della gestione dell'infrastruttura GKE e agli amministratori della piattaforma che gestiscono i carichi di lavoro AI.

Prima di leggere questa pagina, assicurati di avere familiarità con quanto segue:

• Informazioni su GKE Inference Gateway.
• Orchestrazione di AI/ML su GKE.
• Glossario dell'AI generativa.
• Bilanciamento del carico in Cloud de Confiance, in particolare come i bilanciatori del carico interagiscono con GKE.
• Service Extensions di GKE. Per saperne di più, consulta la documentazione relativa al controller GKE Gateway.
• Personalizza il traffico del gateway GKE utilizzando Service Extensions.

GKE Inference Gateway migliora Google Kubernetes Engine (GKE) Gateway per ottimizzare l'erogazione di applicazioni e workload di AI generativa su GKE. Consente la gestione e lo scaling efficienti dei workload AI, consente obiettivi di rendimento specifici per il workload, come la latenza, e migliora l'utilizzo delle risorse, l'osservabilità e la sicurezza dell'AI.

Prima di iniziare

Prima di iniziare, assicurati di aver eseguito le seguenti operazioni:

• Attiva l'API Google Kubernetes Engine.
Attiva l'API Google Kubernetes Engine
• Se vuoi utilizzare Google Cloud CLI per questa attività, installala e poi inizializza gcloud CLI. Se hai già installato gcloud CLI, scarica l'ultima versione eseguendo il comando gcloud components update. Le versioni precedenti di gcloud CLI potrebbero non supportare l'esecuzione dei comandi in questo documento.

• Se necessario, abilita l'API Compute Engine, l'API Kubernetes Engine, l'API Network Services e l'API Model Armor.

  Vai ad Abilita l'accesso alle API e segui le istruzioni.

• Assicurati di disporre dei seguenti ruoli nel progetto: roles/container.admin, roles/iam.serviceAccountAdmin.

• Assicurati che il tuo progetto disponga di una quota sufficiente per le GPU H100. Per saperne di più, consulta Pianificare la quota di GPU e Quote di allocazione.

• Crea un account Hugging Face se non ne hai già uno. Ti servirà per accedere alle risorse del modello per questo tutorial.

• Richiedi l'accesso al modello Llama 3.1 e genera un token di accesso. L'accesso a questo modello richiede una richiesta approvata su Hugging Face e il deployment non andrà a buon fine se l'accesso non è stato concesso.

  • Firma il contratto di consenso alla licenza:devi firmare il contratto di consenso per utilizzare il modello Llama 3.1. Vai alla pagina del modello su Hugging Face, verifica il tuo account e accetta i termini.
  • Genera un token di accesso:per accedere al modello, devi disporre di un token Hugging Face. Nel tuo account Hugging Face, vai a Il tuo profilo > Impostazioni > Token di accesso, crea un nuovo token con almeno autorizzazioni di lettura e copialo negli appunti.

Requisiti del controller GKE Gateway

• GKE 1.32.3 o versioni successive.
• Google Cloud CLI versione 407.0.0 o successive.
• L'API Gateway è supportata solo sui cluster VPC nativi.
• Devi abilitare una subnet solo proxy.
• Il cluster deve avere il componente aggiuntivo HttpLoadBalancing abilitato.
• Se utilizzi Istio, devi eseguire l'upgrade a una delle seguenti versioni:
  • 1.15.2 o versioni successive
  • 1.14.5 o versioni successive
  • 1.13.9 o versioni successive
• Se utilizzi un VPC condiviso, nel progetto host devi assegnare il ruolo Compute Network User al service account GKE per il progetto di servizio.

Limitazioni e restrizioni

Si applicano le seguenti limitazioni:

• I gateway multicluster non sono supportati.
• GKE Inference Gateway è supportato solo sulle risorse GatewayClass gke-l7-regional-external-managed e gke-l7-rilb.
• I bilanciatori del carico delle applicazioni interni tra regioni non sono supportati.
• Un InferencePool può avere un massimo di otto targetPorts.

Configura GKE Inference Gateway

Per configurare GKE Inference Gateway, considera questo esempio. Un team esegue i modelli vLLM e Llama3 e sperimenta attivamente due adattatori LoRA ottimizzati distinti: "food-review" e "cad-fabricator".

Il flusso di lavoro di alto livello per la configurazione di GKE Inference Gateway è il seguente:

1. Prepara l'ambiente: configura l'infrastruttura e i componenti necessari.
2. Crea un pool di inferenza: definisci un pool di server di modelli utilizzando la risorsa personalizzata InferencePool.
3. Specifica gli obiettivi di inferenza: specifica gli obiettivi di inferenza utilizzando la risorsa personalizzata InferenceObjective
4. Crea il gateway: esponi il servizio di inferenza utilizzando l'API Gateway.
5. Crea HTTPRoute: definisci come viene instradato il traffico HTTP al servizio di inferenza.
6. Invia richieste di inferenza: invia richieste al modello di cui è stato eseguito il deployment.

Crea il gateway

La risorsa Gateway è il punto di ingresso per il traffico esterno nel tuo cluster Kubernetes. Definisce i listener che accettano le connessioni in entrata.

GKE Inference Gateway funziona con le seguenti classi Gateway:

• gke-l7-rilb: per i bilanciatori del carico delle applicazioni interni regionali.
• gke-l7-regional-external-managed: per i bilanciatori del carico delle applicazioni esterni regionali.

Per saperne di più, consulta la documentazione relativa alle classi Gateway.

Per creare un gateway, segui questi passaggi:

1. Salva il seguente manifest di esempio come 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
   

   Sostituisci quanto segue:

   • GATEWAY_NAME: un nome univoco per la risorsa Gateway. Ad esempio, inference-gateway.
   • GATEWAY_CLASS: la classe gateway che vuoi utilizzare. Ad esempio, gke-l7-regional-external-managed.

2. Applica il manifest al cluster:

   kubectl apply -f gateway.yaml
   

Nota: per saperne di più sulla configurazione di TLS per proteggere il gateway con HTTPS, consulta la documentazione di GKE sulla configurazione TLS.

prepara l'ambiente

1. Installa Helm.

2. Crea un cluster GKE:

   • Crea un cluster GKE Autopilot o Standard con la versione 1.32.3 o successive. Per una configurazione di riferimento per il deployment con un solo clic, consulta l'cluster-toolkit gke-a3-highgpu esempio.
   • Configura i nodi con la famiglia di computing e l'acceleratore che preferisci.
   • Utilizza la guida rapida all'inferenza di GKE per manifest di deployment preconfigurati e testati, in base all'acceleratore, al modello e alle esigenze di prestazioni selezionati.

3. Installa le definizioni di risorse personalizzate (CRD) necessarie nel tuo cluster GKE:

   • Per le versioni di GKE 1.34.0-gke.1626000 o successive, la CRD InferencePool è inclusa per impostazione predefinita. Pertanto, installa solo la CRD alpha InferenceObjective:

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

   • Per le versioni di GKE precedenti alla 1.34.0-gke.1626000, installa sia le CRD v1 InferencePool sia alpha InferenceObjective:

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

     Per saperne di più, consulta la matrice di compatibilità.

4. Se utilizzi una versione di GKE precedente alla v1.32.2-gke.1182001 e vuoi utilizzare Model Armor con GKE Inference Gateway, devi installare i CRD dell'estensione di gestione del traffico e del routing:

   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. Imposta le seguenti variabili di ambiente:

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

6. Installa le definizioni di risorse personalizzate (CRD) dell'estensione di inferenza dell'API Gateway richieste dal selettore di endpoint (EPP) llm-d:

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

7. Crea lo spazio dei nomi di destinazione:

   kubectl create namespace ${NAMESPACE}
   

Crea un server di modelli ed esegui il deployment del modello

Questa sezione mostra come eseguire il deployment di un server di modelli e di un modello. L'esempio utilizza un server di modelli vLLM con un modello Llama3. Il deployment è etichettato come app:vllm-llama3-8b-instruct. Questo deployment utilizza anche due adattatori LoRA denominati food-review e cad-fabricator di Hugging Face.

Puoi adattare questo esempio con il tuo contenitore del server del modello e il tuo modello, la porta di pubblicazione e il nome del deployment. Puoi anche configurare gli adattatori LoRA nel deployment o eseguire il deployment del modello di base. I passaggi seguenti descrivono come creare le risorse Kubernetes necessarie.

1. Crea un secret di Kubernetes per archiviare il token Hugging Face. Questo token viene utilizzato per accedere al modello base e agli adattatori LoRA:

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

   Sostituisci HF_TOKEN con il tuo token Hugging Face.

2. Esegui il deployment del server di modelli vLLM utilizzando l'overlay Kustomize specifico per GKE dalla guida di base ottimizzata per llm-d. L'impostazione di INFRA_PROVIDER=gke applica configurazioni specifiche per GKE, inclusa l'integrazione di Cloud Monitoring:

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

Nota:GKE fornisce il monitoraggio automatico delle applicazioni per impostazione predefinita. Lo stack di monitoraggio llm-d non è obbligatorio per GKE, ma è disponibile se preferisci utilizzarlo.

Se il server del modello richiede più porte, assicurati che la specifica del contenitore esponga ogni porta. L'esempio seguente definisce un deployment in cui il container espone tre porte:

Esempio di implementazione multi-porta

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 pool di inferenza

La risorsa personalizzata Kubernetes InferencePool definisce un gruppo di pod con una configurazione di calcolo e un modello linguistico di grandi dimensioni (LLM) di base comune. Il campo selector specifica i pod che appartengono a questo pool. Le etichette in questo selettore devono corrispondere esattamente alle etichette applicate ai pod del server di modelli. Il campo targetPorts definisce le porte utilizzate dal server di modelli all'interno dei pod. Puoi specificare fino a otto porte. Il campo extensionRef fa riferimento a un servizio di estensione che fornisce funzionalità aggiuntive per il pool di inferenza. InferencePool consente a GKE Inference Gateway di instradare il traffico ai pod del server di modelli.

Il seguente manifest InferencePool specifica più targetPort che corrispondono alle porte esposte dal deployment del server di modelli:

Esempio di InferencePool multiporta

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

Prima di creare InferencePool, assicurati che i pod del server di modelli selezionati da InferencePool siano già in esecuzione.

Clona le ricette e i suggerimenti per InferencePool dal repository GitHub llm-d. Questo passaggio è obbligatorio:

git clone https://github.com/llm-d/llm-d -b v0.7.0 && cd llm-d

Per creare un InferencePool utilizzando Helm:

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

Sostituisci quanto segue:

• GAIE_VERSION: la versione del grafico Helm. Ad esempio, v1.5.0.
• LLM_D_REGISTRY_PATH: il percorso del registro OCI per il grafico Helm. Ad esempio, registry.k8s.io/gateway-api-inference-extension/charts/inferencepool.

Nel file guides/recipes/scheduler/base.values.yaml, modifica il seguente campo in modo che corrisponda all'etichetta del pod di deployment del modello:

• inferencePool.modelServers.matchLabels: la chiave e il valore dell'etichetta utilizzata per selezionare i pod del server del modello.

  Nota: la chiave e il valore sono in linea con l'esempio della guida optimized-baseline, quindi li sostituiamo in modo che corrispondano alle etichette del pod di deployment.

Per il monitoraggio, lo scraping delle metriche per Google Cloud Managed Service per Prometheus è abilitato per impostazione predefinita.

• Per disattivare questa funzionalità, aggiungi il flag --set inferenceExtension.monitoring.prometheus.enabled=false al comando.
• Se utilizzi il monitoraggio predefinito su un cluster GKE Autopilot, devi aggiungere anche il flag --set provider.gke.autopilot=true.

L'installazione di Helm installa automaticamente il criterio di timeout necessario, il selettore di endpoint e i pod necessari per l'osservabilità.

Viene creato un oggetto InferencePool: vllm-llama3-8b-instruct che fa riferimento ai servizi endpoint del modello all'interno dei pod. Viene inoltre creato un deployment di Endpoint Picker denominato app:vllm-llama3-8b-instruct-epp per questo InferencePool creato.

Crea il HTTPRoute

La risorsa HTTPRoute definisce il modo in cui GKE Gateway instrada le richieste HTTP in entrata ai servizi di backend, ad esempio InferencePool. La risorsa HTTPRoute specifica le regole di corrispondenza (ad esempio intestazioni o percorsi) e il backend a cui deve essere inoltrato il traffico.

1. Per creare un HTTPRoute, salva il seguente manifest di esempio come 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
   

   Sostituisci quanto segue:

   • HTTPROUTE_NAME: un nome univoco per la risorsa HTTPRoute. Ad esempio: my-route.
   • GATEWAY_NAME: il nome della risorsa Gateway che hai creato. Ad esempio: inference-gateway.
   • PATH_PREFIX: il prefisso del percorso che utilizzi per trovare corrispondenze con le richieste in entrata. Ad esempio, / per la corrispondenza con tutti.
   • INFERENCE_POOL_NAME: il nome della risorsa InferencePool a cui vuoi indirizzare il traffico. Ad esempio, vllm-llama3-8b-instruct.

2. Applica il manifest al cluster:

   kubectl apply -f httproute.yaml
   

Specifica gli obiettivi dell'inferenza

La risorsa personalizzata InferenceObjective consente di specificare la priorità delle richieste.

Il campo metadata.name della risorsa InferenceObjective specifica il nome dell'obiettivo di inferenza, il campo Priority specifica la sua criticità di pubblicazione e il campo poolRef specifica l'InferencePool su cui viene pubblicato il modello.

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"

Sostituisci quanto segue:

• NAME: il nome dell'obiettivo di inferenza. Ad esempio, food-review.
• VALUE: la priorità per l'obiettivo di inferenza. Si tratta di un numero intero in cui un valore più elevato indica una richiesta più critica. Ad esempio, 10.
• INFERENCE_POOL_NAME: il nome di InferencePool creato nel passaggio precedente. Ad esempio, vllm-llama3-8b-instruct.

Per creare un InferenceObjective, segui questi passaggi:

1. Salva il seguente manifest come inference-objectives.yaml. Questo manifest crea due risorse InferenceObjective. La prima configura l'food-reviewobiettivo di inferenza nel vllm-llama3-8b-instruct InferencePool con una priorità di 10. La seconda configura l'obiettivo di inferenza llama3-base-model in modo che venga pubblicato con una priorità più elevata di 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. Applica il manifest di esempio al cluster:

   kubectl apply -f inference-objectives.yaml
   

Verifica il deployment

Per verificare che tutti i componenti siano in esecuzione, esegui questi comandi:

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

Inviare una richiesta di inferenza

Dopo aver configurato GKE Inference Gateway, puoi inviare richieste di inferenza al modello di cui è stato eseguito il deployment. In questo modo puoi generare testo in base al prompt di input e ai parametri specificati.

Per inviare richieste di inferenza:

1. Imposta le seguenti variabili di ambiente:

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

   Sostituisci quanto segue:

   • GATEWAY_NAME: il nome della risorsa Gateway.
   • PORT_NUMBER: il numero di porta che hai configurato nel gateway.

2. Per ottenere l'endpoint del gateway, esegui il comando seguente:

   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. Per inviare una richiesta all'endpoint /v1/completions utilizzando curl, esegui questo 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"
   }'
   

   Sostituisci quanto segue:

   • MODEL_NAME: il nome del modello o dell'adattatore LoRA da utilizzare.
   • PROMPT_TEXT: il prompt di input per il modello.
   • MAX_TOKENS: il numero massimo di token da generare nella risposta.
   • TEMPERATURE: controlla la casualità dell'output. Utilizza il valore 0 per un output deterministico o un numero più alto per un output più creativo.

L'esempio seguente mostra come inviare una richiesta di esempio 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
}'

Tieni presente i seguenti comportamenti:

• Corpo della richiesta: il corpo della richiesta può includere parametri aggiuntivi come stop e top_p. Per un elenco completo delle opzioni, consulta la specifica dell'API OpenAI.
• Gestione degli errori: implementa una gestione degli errori corretta nel codice client per gestire i potenziali errori nella risposta. Ad esempio, controlla il codice di stato HTTP nella risposta curl. Un codice di stato diverso da 200 indica in genere un errore.
• Autenticazione e autorizzazione: per le implementazioni di produzione, proteggi l'endpoint API con meccanismi di autenticazione e autorizzazione. Includi le intestazioni appropriate (ad esempio Authorization) nelle richieste.

Matrice di compatibilità

La tabella descrive la matrice di compatibilità e supporto per le definizioni di risorse personalizzate (CRD) dell'estensione di inferenza dell'API Gateway. Specifica le versioni di CustomResourceDefinition supportate da GKE rispetto al progetto di estensione di inferenza dell'API Gateway open source (OSS), inclusi requisiti di versione specifici e note di installazione.

Proteggi il backend di inferenza con TLS del backend

TLS backend consente al bilanciatore del carico GKE Gateway di verificare l'identità dei backend di inferenza a cui si connette. TLS del backend aggiunge un passaggio di verifica esplicito durante l'handshake TLS tra il gateway e il pod backend. Questa verifica contribuisce a garantire che il gateway comunichi solo con server di modelli attendibili.

Per configurare TLS di backend per i tuoi workload di inferenza, collega un oggetto BackendTLSPolicy a una risorsa InferencePool o GCPInferencePoolImport.

Per saperne di più, consulta Configura TLS di backend.

Passaggi successivi

• Personalizza la configurazione di GKE Inference Gateway
• Configurare il routing basato sul corpo
• Servire un LLM con GKE Inference Gateway
• Utilizzare il routing basato sulla latenza prevista con GKE Inference Gateway