Esta página foi traduzida pela API Cloud Translation.

Implantar o gateway de inferência do GKE

Autopilot Standard

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 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 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 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 gcloud CLI, 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 gcloud CLI 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, 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:

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

Preparar o ambiente

Instale o Helm.
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.
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.

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.

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.
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
```
Observação: se você estiver usando o Autopilot, adicione manualmente um nodeSelector ao manifesto gpu-deployment.yaml padrão para programar cargas de trabalho de GPU. Para mais informações, consulte Solicitar GPUs nos seus contêineres.

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:

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

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:

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

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

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.

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}

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.

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.

Nome do CRD	Versão da API CRD	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 o CRD instalado por padrão no GKE 1.34.0-gke.1626000 ou mais recente	Com suporte 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 alfa do InferencePool foi descontinuada)	inference.networking.x-k8s.io/v1alpha2	Compatível com o GKE 1.32.3 ou versões mais recentes. No entanto, a CRD não é instalada por padrão no GKE. Os usuários precisam instalar manualmente o CRD 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	Com suporte 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.