Implantar o gateway de inferência do GKE

Nesta página, descrevemos como implantar o GKE Inference Gateway.

Esta página é destinada a especialistas 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 Trusted Cloud, principalmente como os balanceadores de carga interagem com o GKE.
• Extensões de serviço do GKE. Para mais informações, leia a documentação do controlador do gateway do GKE.
• Personalizar o tráfego do gateway do GKE usando extensões de serviço.

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 gcloud CLI anteriormente, instale a versão mais recente executando gcloud components update.

• Ative as APIs 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.

Matriz de compatibilidade

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 de CRD 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.

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 instruções, consulte Criar um cluster do GKE.
   • 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 anteriores a 1.34.0-gke.1626000, execute o comando a seguir para instalar os CRDs v1 InferencePool e alfa InferenceObjective:

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

   • Para versões do GKE 1.34.0-gke.1626000 ou mais recentes, instale apenas a CRD alfa InferenceObjective executando o seguinte comando:

   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
   

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. Para configurar a autorização para coletar métricas, crie o secret inference-gateway-sa-metrics-reader-secret:

   kubectl apply -f - <<EOF
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: inference-gateway-metrics-reader
   rules:
   - nonResourceURLs:
     - /metrics
     verbs:
     - get
   ---
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: inference-gateway-sa-metrics-reader
     namespace: default
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: inference-gateway-sa-metrics-reader-role-binding
     namespace: default
   subjects:
   - kind: ServiceAccount
     name: inference-gateway-sa-metrics-reader
     namespace: default
   roleRef:
     kind: ClusterRole
     name: inference-gateway-metrics-reader
     apiGroup: rbac.authorization.k8s.io
   ---
   apiVersion: v1
   kind: Secret
   metadata:
     name: inference-gateway-sa-metrics-reader-secret
     namespace: default
     annotations:
       kubernetes.io/service-account.name: inference-gateway-sa-metrics-reader
   type: kubernetes.io/service-account-token
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: inference-gateway-sa-metrics-reader-secret-read
   rules:
   - resources:
     - secrets
     apiGroups: [""]
     verbs: ["get", "list", "watch"]
     resourceNames: ["inference-gateway-sa-metrics-reader-secret"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name: gmp-system:collector:inference-gateway-sa-metrics-reader-secret-read
     namespace: default
   roleRef:
     name: inference-gateway-sa-metrics-reader-secret-read
     kind: ClusterRole
     apiGroup: rbac.authorization.k8s.io
   subjects:
   - name: collector
     namespace: gmp-system
     kind: ServiceAccount
   EOF
   

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 capacidade adicional para o pool de inferência. O InferencePool permite que o gateway de inferência do GKE roteie 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 \
  --version v1.0.0 \
  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.

A instalação do Helm instala automaticamente a política de tempo limite, 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.

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.

```yaml
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 inferenceobjective.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

• Personalizar a configuração do GKE Inference Gateway
• Configurar o roteamento com base no corpo
• Disponibilizar um LLM com o GKE Inference Gateway