Disponibilizar um LLM com o gateway de inferência do GKE

Neste tutorial, descrevemos como implantar um modelo de linguagem grande (LLM) no Google Kubernetes Engine (GKE) com o GKE Inference Gateway. O tutorial inclui etapas para configuração do cluster, implantação do modelo, configuração do GKE Inference Gateway e processamento de solicitações de LLM.

Este tutorial é destinado a engenheiros de machine learning (ML), administradores e operadores de plataforma e especialistas em dados e IA que querem implantar e gerenciar aplicativos de LLM no GKE com o GKE Inference Gateway.

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

O GKE Inference Gateway aprimora o GKE Gateway para otimizar a veiculaçã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:

  • Ativar a API Google Kubernetes Engine.
    • Ativar a API Google Kubernetes Engine
  • Se você quiser usar a CLI do Google Cloud para essa tarefa, instale e inicialize a gcloud CLI. 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.

  • Ative a API Compute 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 válidas:

  • 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.

Configurar o gateway de inferência do GKE

Para configurar o gateway de inferência do GKE, considere este exemplo. Uma equipe executa modelos vLLM e Llama3 e faz experimentos ativos com dois adaptadores distintos de ajuste fino do 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. Crie 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.

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 do GKE Inference 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, instale apenas o CRD InferenceObjective Alfa:

      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 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.0.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

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.

Adapte este exemplo com seu próprio contêiner e modelo de servidor de 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 e o modelo. O comando a seguir aplica um manifesto que define uma implantação do Kubernetes para um servidor de modelo 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

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 targetPort define as portas que o servidor de modelo usa nos pods. 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 gateway de inferência do GKE encaminhe o tráfego para os pods do servidor de modelo.

Antes de criar o InferencePool, verifique se os pods selecionados pelo InferencePool já estão em execução.

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

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

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 raspagem de métricas do Google Cloud Managed Service para Prometheus é ativada por padrão.

  • Para desativar esse recurso, adicione a flag --set inferenceExtension.monitoring.gke.enabled=false ao comando.
  • Se você usar o monitoramento padrão em um cluster do GKE Autopilot, também precisará 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 capacidade de observação.

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 Endpoint Picker chamado app:vllm-llama3-8b-instruct-epp para o InferencePool criado.

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 importância da veiculação e o campo poolRef especifica o InferencePool em que o modelo é veiculado.

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:

  • 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 vllm-llama3-8b-instruct InferencePool 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

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 gateway de inferência do GKE 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.

Criar o HTTPRoute

O recurso HTTPRoute define como o GKE Gateway encaminha solicitações HTTP recebidas para serviços de back-end, como seu InferencePool. O recurso HTTPRoute especifica regras de correspondência (por exemplo, cabeçalhos ou caminhos) e o back-end 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

Enviar solicitação de inferência

Depois de configurar o gateway de inferência do GKE, é possível enviar solicitações de inferência para o modelo implantado. Assim, você pode 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 gateway de inferência do GKE:

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

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.

A seguir