Implemente o GKE Inference Gateway

Autopilot Padrão

Esta página descreve como implementar o GKE Inference Gateway.

Esta página destina-se a especialistas em redes responsáveis pela gestão da infraestrutura do GKE e a administradores da plataforma que gerem cargas de trabalho de IA.

Antes de ler esta página, certifique-se de que conhece o seguinte:

• Acerca do GKE Inference Gateway.
• Orquestração de IA/ML no GKE.
• Glossário de IA generativa.
• Balanceamento de carga no Google Cloud, especialmente 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 GKE Gateway.
• Personalize o tráfego do GKE Gateway através das extensões de serviço.

O GKE Inference Gateway melhora o Gateway do Google Kubernetes Engine (GKE) para otimizar a publicação de aplicações e cargas de trabalho de IA generativa no GKE. Oferece uma gestão e um dimensionamento eficientes das cargas de trabalho de IA, permite objetivos de desempenho específicos da carga de trabalho, como a 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, certifique-se de que realizou as seguintes tarefas:

• Ative a API Google Kubernetes Engine.
Ative a API Google Kubernetes Engine
• Se quiser usar a CLI gcloud para esta tarefa, instale-a e, em seguida, inicialize-a. Se instalou anteriormente a CLI gcloud, execute o comando gcloud components update para obter a versão mais recente. As versões anteriores da CLI gcloud podem não suportar a execução dos comandos neste documento.
  Nota: para instalações existentes da CLI gcloud, certifique-se de que define a compute/region propriedade. Se usar principalmente clusters zonais, defina o compute/zone. Ao definir uma localização predefinida, pode evitar erros na CLI gcloud, como os seguintes: One of [--zone, --region] must be supplied: Please specify location. Pode ter de especificar a localização em determinados comandos se a localização do seu cluster for diferente da predefinição que definiu.

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

  Aceda a Ativar acesso às APIs e siga as instruções.

• Certifique-se de que tem as seguintes funções no projeto: roles/container.admin, roles/iam.serviceAccountAdmin.

• Certifique-se de que o seu projeto tem quota suficiente para GPUs H100. Para saber mais, consulte os artigos Planeie a quota de GPU e Quotas de atribuição.

• Crie uma conta Hugging Face, se ainda não tiver uma. Vai precisar desta opção para aceder aos recursos do modelo para este tutorial.

• Peça acesso ao modelo Llama 3.1 e gere um token de acesso. O acesso a este modelo requer um pedido aprovado no Hugging Face e a implementação falha se o acesso não tiver sido concedido.

  • Assine o contrato de consentimento de licença: tem de assinar o contrato de consentimento para usar o modelo Llama 3.1. Aceda à página do modelo no Hugging Face, valide a sua conta e aceite os termos.
  • Gerar uma chave de acesso: para aceder ao modelo, precisa de uma chave do Hugging Face. Na sua conta do Hugging Face, aceda a O seu perfil > Definições > Tokens de acesso, crie um novo token com, pelo menos, autorizações de leitura e copie-o para a área de transferência.

Requisitos do GKE Gateway Controller

• Versão 1.32.3 ou posterior do GKE.
• Versão 407.0.0 ou posterior da CLI Google Cloud.
• A API Gateway só é suportada em clusters nativos de VPC.
• Tem de ativar uma sub-rede só de proxy.
• O seu cluster tem de ter o suplemento HttpLoadBalancing ativado.
• Se estiver a usar o Istio, tem de atualizar o Istio para uma das seguintes versões:
  • 1.15.2 ou posterior
  • 1.14.5 ou posterior
  • 1.13.9 ou posterior
• Se estiver a usar a VPC partilhada, no projeto anfitrião, tem de atribuir a função Compute Network User à conta de serviço do GKE para o projeto de serviço.

Restrições e limitações

Aplicam-se as seguintes restrições e limitações:

• Os gateways de vários clusters não são suportados.
• O GKE Inference Gateway só é suportado nos recursos GatewayClass gke-l7-regional-external-managed e gke-l7-rilb.
• Os equilibradores de carga de aplicações internos entre regiões não são suportados.

Configure o GKE Inference Gateway

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

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

1. Prepare o seu ambiente: configure a infraestrutura e os componentes necessários.
2. Crie um conjunto de inferência: defina um conjunto de servidores de modelos usando o InferencePool recurso personalizado.
3. Especifique objetivos de inferência: especifique objetivos de inferência através do InferenceObjective recurso personalizado
4. Crie o gateway: exponha o serviço de inferência através da API Gateway.
5. Crie o HTTPRoute: define como o tráfego HTTP é encaminhado para o serviço de inferência.
6. Enviar pedidos de inferência: fazer pedidos ao modelo implementado.

Prepare o seu 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 posterior. Para uma implementação com um clique de configuração de referência, consulte o cluster-toolkit gke-a3-highgpu exemplo.
   • Configure os nós com a família de computação e o acelerador preferidos.
   • Use o GKE Inference Quickstart para manifestos de implementação pré-configurados e testados, com base no acelerador, no modelo e nas necessidades de desempenho selecionados.

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

   • Para versões do GKE 1.34.0-gke.1626000 ou posteriores, instale apenas o CRD alfa InferenceObjective:

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

   • Para versões do GKE anteriores à 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.0.0/manifests.yaml
     

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

4. Se estiver a usar uma versão do GKE anterior à v1.32.2-gke.1182001 e quiser usar o Model Armor com o GKE Inference Gateway, tem de instalar os CRDs de tráfego e encaminhamento:

   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
   

Crie um servidor de modelos e uma implementação de modelos

Esta secção mostra como implementar um servidor de modelos e um modelo. O exemplo usa um servidor de modelos vLLM com um modelo Llama3. A implementação é etiquetada como app:vllm-llama3-8b-instruct. Esta implementação também usa dois adaptadores LoRA denominados food-review e cad-fabricator da Hugging Face.

Pode adaptar este exemplo com o seu próprio contentor do servidor do modelo e modelo, porta de publicação e nome de implementação. Também pode configurar adaptadores LoRA na implementação ou implementar o modelo base. Os passos seguintes descrevem como criar os recursos do Kubernetes necessários.

1. Crie um segredo do Kubernetes para armazenar o seu token do Hugging Face. Este token é usado para aceder ao modelo base e aos adaptadores LoRA:

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

   Substitua HF_TOKEN pelo seu token do Hugging Face.

2. Implemente o servidor de modelos e o modelo. O comando seguinte aplica um manifesto que define uma implementação do Kubernetes para um servidor de modelos vLLM com um modelo Llama3:

   kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api-inference-extension/release-1.0/config/manifests/vllm/gpu-deployment.yaml
   

   Nota: se estiver a usar o Autopilot, tem de adicionar manualmente um nodeSelector ao manifesto gpu-deployment.yaml predefinido para agendar cargas de trabalho da GPU. Para mais informações, consulte o artigo Peça GPUs nos seus contentores.

Crie um conjunto de inferências

O recurso personalizado do Kubernetes define um grupo de pods com um modelo de linguagem (conteúdo extenso) (MDL/CE) base comum e uma configuração de computação.InferencePool O campo selector especifica a que pods este conjunto pertence. As etiquetas neste seletor têm de corresponder exatamente às etiquetas aplicadas aos pods do servidor do modelo. O campo targetPort define as portas que o servidor do modelo usa nos pods. O campo extensionRef faz referência a um serviço de extensão que oferece capacidade adicional para o conjunto de inferências. O InferencePool permite ao GKE Inference Gateway encaminhar o tráfego para os pods do servidor de modelos.

Antes de criar o InferencePool, certifique-se de que os pods que o InferencePool seleciona já estão em execução.

Para criar um InferencePool com o Helm, siga estes passos:

helm install vllm-llama3-8b-instruct \
  --set inferencePool.modelServers.matchLabels.app=vllm-llama3-8b-instruct \
  --set provider.name=gke \
  --set inferenceExtension.monitoring.gke.enabled=true \
  --version v1.0.1 \
  oci://registry.k8s.io/gateway-api-inference-extension/charts/inferencepool

Altere o campo seguinte para corresponder à sua implementação:

• inferencePool.modelServers.matchLabels.app: a chave da etiqueta usada para selecionar os pods do servidor do modelo.

Para a monitorização, a recolha de métricas para o Google Cloud Managed Service for Prometheus está ativada por predefinição.

• Para desativar esta funcionalidade, adicione a flag --set inferenceExtension.monitoring.gke.enabled=false ao comando.
• Se usar a monitorização predefinida num cluster do GKE Autopilot, também tem de adicionar a flag --set provider.gke.autopilot=true.

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

Isto cria um objeto InferencePool: vllm-llama3-8b-instruct que faz referência aos serviços de ponto final do modelo nos pods. Também cria uma implementação do seletor de pontos finais denominado app:vllm-llama3-8b-instruct-epp para este InferencePool criado.

Especifique objetivos de inferência

O recurso personalizado InferenceObjective permite-lhe especificar a prioridade dos pedidos.

O campo metadata.name do recurso InferenceObjective especifica o nome do objetivo de inferência, o campo Priority especifica a respetiva criticidade de publicação e o campo poolRef especifica o InferencePool no qual o modelo é publicado.

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

Substitua o seguinte:

• NAME: o nome do seu objetivo de inferência. Por exemplo, food-review.
• VALUE: a prioridade para o objetivo de inferência. Este é um número inteiro em que um valor mais elevado indica um pedido mais crítico. Por exemplo, 10.
• INFERENCE_POOL_NAME: o nome do InferencePool que criou no passo anterior. Por exemplo, vllm-llama3-8b-instruct.

Para criar um InferenceObjective, siga estes passos:

1. Guarde o seguinte manifesto como inference-objectives.yaml. Este manifesto cria dois recursos InferenceObjective. A primeira configura o food-review objetivo de inferência no vllm-llama3-8b-instruct InferencePool com uma prioridade de 10. A segunda configuração configura o llama3-base-modelobjetivo de inferência a ser publicado com uma prioridade mais elevada 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 exemplo ao seu cluster:

   kubectl apply -f inference-objectives.yaml
   

Crie o gateway

O recurso Gateway é o ponto de entrada para o tráfego externo no seu cluster do Kubernetes. Define os ouvintes que aceitam ligações recebidas.

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

• gke-l7-rilb: para balanceadores de carga de aplicações internos regionais.
• gke-l7-regional-external-managed: para balanceadores de carga de aplicações externos regionais.

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

Para criar um gateway, siga estes passos:

1. Guarde o seguinte manifesto de exemplo 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 o seguinte:

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

2. Aplique o manifesto ao cluster:

   kubectl apply -f gateway.yaml
   

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

Crie o HTTPRoute

O recurso HTTPRoute define como o GKE Gateway encaminha os pedidos HTTP recebidos para serviços de back-end, como o seu InferencePool. O recurso HTTPRoute especifica regras de correspondência (por exemplo, cabeçalhos ou caminhos) e o back-end para o qual o tráfego deve ser encaminhado.

1. Para criar um HTTPRoute, guarde 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 o seguinte:

   • HTTPROUTE_NAME: um nome exclusivo para o seu recurso HTTPRoute. Por exemplo, my-route.
   • GATEWAY_NAME: o nome do recurso Gateway que criou. Por exemplo, inference-gateway.
   • PATH_PREFIX: o prefixo do caminho que usa para fazer corresponder pedidos recebidos. Por exemplo, / para corresponder a tudo.
   • INFERENCE_POOL_NAME: o nome do recurso InferencePool para o qual quer encaminhar o tráfego. Por exemplo, vllm-llama3-8b-instruct.

2. Aplique o manifesto ao cluster:

   kubectl apply -f httproute.yaml
   

Enviar pedido de inferência

Depois de configurar o GKE Inference Gateway, pode enviar pedidos de inferência para o modelo implementado. Isto permite-lhe gerar texto com base no comando de entrada e nos parâmetros especificados.

Para enviar pedidos de inferência, siga estes passos:

1. Defina as seguintes variáveis de ambiente:

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

   Substitua o seguinte:

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

2. Para obter o ponto final 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 um pedido para o ponto final /v1/completions através do curl, execute o seguinte 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"
   }'
   

   Substitua o seguinte:

   • MODEL_NAME: o nome do modelo ou do adaptador LoRA a usar.
   • PROMPT_TEXT: o comando de entrada para o modelo.
   • MAX_TOKENS: o número máximo de tokens a gerar na resposta.
   • TEMPERATURE: controla a aleatoriedade do resultado. Use o valor 0 para uma saída determinística ou um número superior para uma saída mais criativa.

O exemplo seguinte mostra como enviar um pedido de amostra para o GKE Inference Gateway:

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

Tenha em atenção os seguintes comportamentos:

• Corpo do pedido: o corpo do pedido pode incluir parâmetros adicionais, como stop e top_p. Consulte a especificação da API OpenAI para ver uma lista completa de opções.
• Processamento de erros: implemente o processamento de erros adequado no código do cliente para processar potenciais erros na resposta. Por exemplo, verifique o código de estado HTTP na resposta curl. Um código de estado que não seja 200 indica geralmente um erro.
• Autenticação e autorização: para implementações de produção, proteja o seu ponto final da API com mecanismos de autenticação e autorização. Inclua os cabeçalhos adequados (por exemplo, Authorization) nos seus pedidos.

Matriz de compatibilidade

Nota: a partir da versão 1.34.0-gke.1626000 do GKE, o Google Kubernetes Engine gere automaticamente o CRD InferencePool v1. A tentativa de instalar o CRD v1 InferencePool pode causar problemas inesperados e resulta num 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. Detalha as versões de CRD suportadas pelo 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 notas de instalação.

Nome do CRD	Versão da API CRD	Apoio técnico gerido do GKE	Suporte de OSS (extensão de inferência da API Gateway)
V1 InferencePool	inference.networking.k8s.io/v1	Suportado no GKE 1.32.3 ou posterior e CRD instalado por predefinição no GKE 1.34.0-gke.1626000 ou posterior	Suportado a partir da extensão de inferência da API Gateway v1.0.0
Alpha InferencePool (Recomendamos que os utilizadores comecem com a versão v1 do InferencePool, uma vez que a versão alfa do InferencePool foi descontinuada)	inference.networking.x-k8s.io/v1alpha2	Suportado no GKE 1.32.3 ou posterior. No entanto, o CRD não está instalado por predefinição no GKE. Os utilizadores têm de instalar manualmente o CRD a partir da extensão de inferência da API Gateway.	Suportado 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 gere o InferenceObjective	Suportado a partir da extensão de inferência da API Gateway v1.0.0
Alpha InferenceModel (Recomendamos que os utilizadores comecem com InferenceObjective, uma vez que InferenceModel foi descontinuado)	inference.networking.x-k8s.io/v1alpha2	O GKE não gere o InferenceModel	Suportado a partir da extensão de inferência da API Gateway v0.2.0.

O que se segue?

• Personalize a configuração do GKE Inference Gateway
• Configure o encaminhamento baseado no corpo
• Publique um MDG com o GKE Inference Gateway