Implantar o GKE Inference Gateway com tecnologia llm-d

Autopilot Standard

Neste documento, descrevemos como implantar o GKE Inference Gateway.

Este documento é destinado a especialistas em rede responsáveis por gerenciar a infraestrutura do GKE e administradores de plataforma que gerenciam cargas de trabalho de IA.

Antes de ler esta página, confira se você conhece os seguintes conceitos:

• Sobre o GKE Inference Gateway.
• Orquestração de IA/ML no GKE.
• Glossário de IA generativa.
• Balanceamento de carga em Google Cloud, principalmente como os balanceadores de carga interagem com o GKE.
• Extensões de serviço do GKE. Para mais informações, consulte a documentação do controlador do gateway do GKE.
• Personalizar o tráfego do gateway do GKE usando Service Extensions.

O GKE Inference Gateway aprimora o gateway do Google Kubernetes Engine (GKE) para otimizar a disponibilização de aplicativos e cargas de trabalho de IA generativa no GKE. Ele oferece gerenciamento e escalonamento eficientes de cargas de trabalho de IA, permite objetivos de performance específicos da carga de trabalho, como latência, e melhora a utilização de recursos, a observabilidade e a segurança da IA.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

• Ative a API Google Kubernetes Engine.
Ativar a API Google Kubernetes Engine
• Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando o comando gcloud components update. Talvez as versões anteriores da CLI gcloud não sejam compatíveis com a execução dos comandos neste documento.
  Observação:em instalações prévias da CLI gcloud, defina a propriedade compute/region. Se você usa principalmente clusters zonais, defina compute/zone. Ao definir um local padrão, é possível evitar erros na CLI gcloud como: One of [--zone, --region] must be supplied: Please specify location. Talvez seja necessário especificar o local em determinados comandos se o local do cluster for diferente do padrão definido.

• Ative a API Compute Engine, API Kubernetes Engine, Network Services e Model Armor, se necessário.

  Acesse Ativar acesso a APIs e siga as instruções.

• Verifique se você tem os seguintes papéis no projeto: roles/container.admin, roles/iam.serviceAccountAdmin.

• Verifique se o projeto tem cota suficiente para GPUs H100. Para saber mais, consulte Planejar a cota de GPU e Cotas de alocação.

• Crie uma conta do Hugging Face caso ainda não tenha uma. Você vai precisar disso para acessar os recursos do modelo deste tutorial.

• Solicite acesso ao modelo Llama 3.1 e gere um token de acesso. O acesso a esse modelo exige uma solicitação aprovada no Hugging Face, e a implantação vai falhar se o acesso não for concedido.

  • Assine o contrato de consentimento de licença:é necessário assinar o contrato de consentimento para usar o modelo Llama 3.1. Acesse a página do modelo no Hugging Face, verifique sua conta e aceite os termos.
  • Gere um token de acesso:para acessar o modelo, você precisa de um token do Hugging Face. Na sua conta do Hugging Face, acesse Seu perfil > Configurações > Tokens de acesso, crie um novo token com pelo menos permissões de leitura e copie para a área de transferência.

Requisitos do GKE Gateway Controller

• GKE versão 1.32.3 ou mais recente.
• Google Cloud CLI versão 407.0.0 ou mais recente.
• A API Gateway é compatível apenas com clusters nativos de VPC.
• É necessário ativar uma sub-rede somente proxy.
• O cluster precisa ter o complemento HttpLoadBalancing ativado.
• Se você estiver usando o Istio, será necessário fazer upgrade do Istio para uma das seguintes versões:
  • 1.15.2 ou mais recente
  • 1.14.5 ou mais recente
  • 1.13.9 ou mais recente
• Se você estiver usando a VPC compartilhada, será necessário atribuir o papel Compute Network User à conta de serviço do GKE referente ao projeto de serviço no projeto host.

Restrições e limitações

As seguintes restrições e limitações são aplicáveis:

• Não há suporte para gateways de vários clusters.
• O GKE Inference Gateway só é compatível com os recursos gke-l7-regional-external-managed e gke-l7-rilb GatewayClass.
• Os balanceadores de carga de aplicativo internos entre regiões não são compatíveis.
• Um InferencePool pode ter no máximo oito targetPorts.

Configurar o GKE Inference Gateway

Para configurar o GKE Inference Gateway, considere este exemplo. Uma equipe executa modelos vLLM e Llama3 e testa ativamente dois adaptadores distintos com ajuste fino de LoRA: "food-review" e "cad-fabricator".

O fluxo de trabalho de alto nível para configurar o GKE Inference Gateway é o seguinte:

1. Prepare o ambiente: configure a infraestrutura e os componentes necessários.
2. Criar um pool de inferência: defina um pool de servidores de modelo usando o recurso personalizado InferencePool.
3. Especificar objetivos de inferência: especifique objetivos de inferência usando o recurso personalizado InferenceObjective.
4. Crie o gateway: exponha o serviço de inferência usando a API Gateway.
5. Crie o HTTPRoute: defina como o tráfego HTTP é roteado para o serviço de inferência.
6. Enviar solicitações de inferência: faça solicitações ao modelo implantado.

Criar o gateway

O recurso Gateway é o ponto de entrada do tráfego externo no seu cluster do Kubernetes. Ele define os listeners que aceitam conexões de entrada.

O GKE Inference Gateway funciona com as seguintes classes de gateway:

• gke-l7-rilb: para balanceadores de carga de aplicativo internos regionais.
• gke-l7-regional-external-managed: para balanceadores de carga de aplicativo externos regionais.

Para mais informações, consulte a documentação Classes de gateway.

Para criar um gateway, siga estas etapas:

1. Salve o seguinte manifesto de amostra 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
   

   Substitua:

   • GATEWAY_NAME: um nome exclusivo para o recurso de gateway. Por exemplo, inference-gateway.
   • GATEWAY_CLASS: a classe de gateway que você quer usar. Por exemplo, gke-l7-regional-external-managed.

2. Aplique o manifesto ao cluster:

   kubectl apply -f gateway.yaml
   

Observação: para mais informações sobre como configurar o TLS para proteger seu gateway com HTTPS, consulte a documentação do GKE sobre configuração do TLS.

Preparar o ambiente

1. Instale o Helm.

2. Crie um cluster do GKE:

   • Crie um cluster do GKE Autopilot ou Standard com a versão 1.32.3 ou mais recente. Para uma configuração de referência de implantação com um clique, consulte o exemplo de cluster-toolkit gke-a3-highgpu.
   • Configure os nós com a família de computação e o acelerador de sua preferência.
   • Use o Guia de início rápido de inferência do GKE para manifestos de implantação pré-configurados e testados, com base no acelerador, modelo e necessidades de desempenho selecionados.

3. Instale as definições de recursos personalizados (CRDs) necessárias no cluster do GKE:

   • Para versões do GKE 1.34.0-gke.1626000 ou mais recentes, o CRD InferencePool é incluído por padrão. Portanto, instale apenas o CRD alfa InferenceObjective:

     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
     

   • Para versões do GKE anteriores a 1.34.0-gke.1626000, instale os CRDs v1 InferencePool e alfa InferenceObjective:

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

     Para mais informações, consulte a matriz de compatibilidade.

4. Se você estiver usando uma versão do GKE anterior a v1.32.2-gke.1182001 e quiser usar o Model Armor com o GKE Inference Gateway, será necessário instalar os CRDs de extensão de tráfego e roteamento:

   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. Configure as variáveis de ambiente a seguir:

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

6. Instale as definições de recursos personalizados (CRDs) da extensão de inferência da API Gateway necessárias para o seletor de endpoints (EPP) llm-d:

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

7. Crie o namespace de destino:

   kubectl create namespace ${NAMESPACE}
   

Criar um servidor de modelo e uma implantação de modelo

Esta seção mostra como implantar um servidor e um modelo. O exemplo usa um servidor de modelo vLLM com um modelo Llama3. A implantação é rotulada como app:vllm-llama3-8b-instruct. Essa implantação também usa dois adaptadores LoRA chamados food-review e cad-fabricator do Hugging Face.

É possível adaptar este exemplo com seu próprio contêiner do servidor de modelo e modelo, porta de serviço e nome de implantação. Também é possível configurar adaptadores LoRA na implantação ou implantar o modelo de base. As etapas a seguir descrevem como criar os recursos necessários do Kubernetes.

1. Crie um secret do Kubernetes para armazenar seu token do Hugging Face. Esse token é usado para acessar o modelo de base e os adaptadores LoRA:

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

   Substitua HF_TOKEN pelo seu token do Hugging Face.

2. Implante o servidor de modelo vLLM usando a sobreposição Kustomize específica do GKE do guia de base otimizada llm-d. A definição de INFRA_PROVIDER=gke aplica configurações específicas do GKE, incluindo a integração do Cloud Monitoring:

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

Observação:o GKE oferece monitoramento automático de aplicativos por padrão. A pilha de monitoramento llm-d não é necessária para o GKE, mas está disponível se você preferir usá-la.

Se o servidor de modelo exigir várias portas, verifique se a especificação do contêiner expõe cada uma delas. O exemplo a seguir define uma implantação em que o contêiner expõe três portas:

Exemplo de implantação multiporta

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

Criar um pool de inferência

O recurso personalizado do Kubernetes InferencePool define um grupo de pods com um modelo de linguagem grande (LLM) de base comum e uma configuração de computação. O campo selector especifica quais pods pertencem a esse pool. Os rótulos nesse seletor precisam corresponder exatamente aos rótulos aplicados aos pods do servidor de modelo. O campo targetPorts define as portas que o servidor de modelo usa nos pods. É possível especificar até oito portas. O campo extensionRef faz referência a um serviço de extensão que oferece mais recursos para o pool de inferência. O InferencePool permite que o GKE Inference Gateway roteie o tráfego para os pods do servidor de modelo.

Observação: cada entrada no campo targetPorts resulta em um grupo de endpoints de rede (NEG) dedicado, mas todos os NEGs do InferencePool são anexados a um único serviço de back-end Google Cloud .

O manifesto do InferencePool a seguir especifica várias targetPorts que correspondem às portas expostas pela implantação do servidor de modelos:

Exemplo de Multiport InferencePool

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 criar o InferencePool, verifique se os pods selecionados por ele já estão em execução.

Para criar um InferencePool usando o Helm, siga estas etapas:

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

Substitua:

• GAIE_VERSION: a versão do gráfico do Helm. Por exemplo, v1.5.0.
• LLM_D_REGISTRY_PATH: o caminho do registro OCI para o gráfico Helm. Por exemplo, us-central1-docker.pkg.dev/cloud-ai-gke/gke-inference-gateway/charts/inferencepool.

Mude o seguinte campo para corresponder à sua implantação:

• inferencePool.modelServers.matchLabels.app: a chave do rótulo usado para selecionar os pods do servidor de modelo.

Para monitoramento, a extração de métricas do Google Cloud Managed Service para Prometheus é ativada por padrão.

• Para desativar esse recurso, adicione a flag --set inferenceExtension.monitoring.prometheus.enabled=false ao comando.
• Se você usa o monitoramento padrão em um cluster do GKE Autopilot, também precisa adicionar a flag --set provider.gke.autopilot=true.

A instalação do Helm instala automaticamente a política de tempo limite necessária, o seletor de endpoints e os pods necessários para a observabilidade.

Isso cria um objeto InferencePool: vllm-llama3-8b-instruct que faz referência aos serviços de endpoint do modelo nos pods. Ele também cria uma implantação do seletor de endpoints chamado app:vllm-llama3-8b-instruct-epp para o InferencePool criado.

Criar o HTTPRoute

O recurso HTTPRoute define como o GKE Gateway encaminha solicitações HTTP recebidas para serviços de back-end, como o InferencePool. O recurso HTTPRoute especifica regras de correspondência (por exemplo, cabeçalhos ou caminhos) e o backend para onde o tráfego precisa ser encaminhado.

1. Para criar um HTTPRoute, salve o seguinte manifesto de exemplo 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
   

   Substitua:

   • HTTPROUTE_NAME: um nome exclusivo para o recurso HTTPRoute. Por exemplo, my-route.
   • GATEWAY_NAME: o nome do recurso Gateway que você criou. Por exemplo, inference-gateway.
   • PATH_PREFIX: o prefixo de caminho usado para corresponder a solicitações recebidas. Por exemplo, / para corresponder a tudo.
   • INFERENCE_POOL_NAME: o nome do recurso InferencePool para onde você quer encaminhar o tráfego. Por exemplo, vllm-llama3-8b-instruct.

2. Aplique o manifesto ao cluster:

   kubectl apply -f httproute.yaml
   

Especificar objetivos de inferência

O recurso personalizado InferenceObjective permite especificar a prioridade das solicitações.

O campo metadata.name do recurso InferenceObjective especifica o nome do objetivo de inferência. O campo Priority especifica a criticidade de serviço dele, e o campo poolRef especifica o InferencePool em que o modelo é veiculado.

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"

Substitua:

• NAME: o nome do objetivo de inferência. Por exemplo, food-review.
• VALUE: a prioridade do objetivo de inferência. É um número inteiro em que um valor maior indica uma solicitação mais crítica. Por exemplo, 10.
• INFERENCE_POOL_NAME: o nome do InferencePool que você criou na etapa anterior. Por exemplo, vllm-llama3-8b-instruct.

Para criar um InferenceObjective, siga estas etapas:

1. Salve o seguinte manifesto inference-objectives.yaml como : Esse manifesto cria dois recursos InferenceObjective. A primeira configura o objetivo de inferência food-review no InferencePool vllm-llama3-8b-instruct com uma prioridade de 10. A segunda configura o objetivo de inferência llama3-base-model para ser veiculado com uma prioridade maior 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. Aplique o manifesto de amostra ao cluster:

   kubectl apply -f inference-objectives.yaml
   

Verificar a implantação

Para verificar se todos os componentes estão em execução, execute os seguintes comandos:

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

Enviar solicitação de inferência

Depois de configurar o GKE Inference Gateway, é possível enviar solicitações de inferência ao modelo implantado. Assim, é possível gerar texto com base no comando de entrada e nos parâmetros especificados.

Para enviar solicitações de inferência, siga estas etapas:

1. Configure as variáveis de ambiente a seguir:

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

   Substitua:

   • GATEWAY_NAME: o nome do recurso de gateway.
   • PORT_NUMBER: o número da porta que você configurou no gateway.

2. Para receber o endpoint do gateway, execute o seguinte 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 uma solicitação ao endpoint /v1/completions usando curl, execute o comando a seguir:

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

   Substitua:

   • MODEL_NAME: o nome do modelo ou adaptador LoRA a ser usado.
   • PROMPT_TEXT: o comando de entrada para o modelo.
   • MAX_TOKENS: o número máximo de tokens a serem gerados na resposta.
   • TEMPERATURE: controla a aleatoriedade da saída. Use o valor 0 para uma saída determinista ou um número maior para uma saída mais criativa.

O exemplo a seguir mostra como enviar uma solicitação de amostra ao 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
}'

Esteja ciente dos seguintes comportamentos:

• Corpo da solicitação: pode incluir outros parâmetros, como stop e top_p. Consulte a especificação da API da OpenAI para ver uma lista completa de opções.
• Tratamento de erros: implemente o tratamento de erros adequado no código do cliente para lidar com possíveis erros na resposta. Por exemplo, verifique o código de status HTTP na resposta curl. Um código de status diferente de 200 geralmente indica um erro.
• Autenticação e autorização: para implantações de produção, proteja seu endpoint de API com mecanismos de autenticação e autorização. Inclua os cabeçalhos apropriados (por exemplo, Authorization) nas suas solicitações.

Matriz de compatibilidade

Observação :a partir da versão 1.34.0-gke.1626000 do GKE, o Google Kubernetes Engine gerencia automaticamente a CustomResourceDefinition InferencePool v1. Tentar instalar a CustomResourceDefinition v1 InferencePool pode causar problemas inesperados e resultar em um aviso.

A tabela descreve a matriz de compatibilidade e suporte para as definições de recursos personalizados (CRDs) da extensão de inferência da API Gateway. Ele detalha quais versões do CustomResourceDefinition são compatíveis com o GKE em comparação com o projeto de extensão de inferência da API Gateway de código aberto (OSS), incluindo requisitos de versão específicos e observações de instalação.

Nome do CustomResourceDefinition	Versão da API CustomResourceDefinition	Suporte gerenciado do GKE	Suporte a OSS (extensão de inferência da API Gateway)
V1 InferencePool	inference.networking.k8s.io/v1	Compatível com o GKE 1.32.3 ou mais recente e CustomResourceDefinition instalado por padrão no GKE 1.34.0-gke.1626000 ou mais recente	Compatível a partir da extensão de inferência da API Gateway v1.0.0
Alpha InferencePool (recomenda-se que os usuários comecem com o InferencePool v1, já que a versão Alpha foi descontinuada)	inference.networking.x-k8s.io/v1alpha2	Compatível com o GKE 1.32.3 ou versões mais recentes. No entanto, CustomResourceDefinition não é instalado por padrão no GKE. Os usuários precisam instalar manualmente a CustomResourceDefinition da extensão de inferência da API Gateway.	Compatível a partir da extensão de inferência da API Gateway v0.2.0
Alpha InferenceObjective	inference.networking.x-k8s.io/v1alpha2	O GKE não gerencia o InferenceObjective.	Compatível a partir da extensão de inferência da API Gateway v1.0.0
Alpha InferenceModel (recomende aos usuários começar com InferenceObjective, já que InferenceModel está descontinuado)	inference.networking.x-k8s.io/v1alpha2	O GKE não gerencia o InferenceModel	Com suporte a partir da extensão de inferência da API Gateway v0.2.0.

A seguir

• Personalizar a configuração do GKE Inference Gateway
• Configurar o roteamento baseado no corpo
• Disponibilizar um LLM com o GKE Inference Gateway
• Usar o roteamento baseado em latência prevista com o GKE Inference Gateway