Esta página foi traduzida pela API Cloud Translation.

Disponibilizar LLMs abertos no GKE com uma arquitetura pré-configurada

Nesta página, mostramos como implantar e disponibilizar rapidamente modelos de linguagem grandes (LLMs) abertos e conhecidos no GKE para inferência usando uma arquitetura de referência pré-configurada e pronta para produção. Essa abordagem usa a infraestrutura como código (IaC), com o Terraform encapsulado em scripts da CLI, para criar um ambiente do GKE padronizado, seguro e escalonável projetado para cargas de trabalho de inferência de IA.

Neste guia, você vai implantar e disponibilizar LLMs usando nós de GPU de host único no GKE com o framework de disponibilização vLLM. Este guia fornece instruções e configurações para implantar os seguintes modelos abertos:

Este guia é destinado a engenheiros de machine learning (ML) e especialistas em dados e IA interessados em conhecer os recursos de orquestração de contêineres do Kubernetes para disponibilizar modelos abertos para inferência. Para saber mais sobre papéis comuns e exemplos de tarefas referenciados no conteúdo do Google Cloud , consulte Tarefas e funções de usuário comuns do GKE.

Para uma análise detalhada do desempenho e dos custos de disponibilização de modelos para esses modelos abertos, use a ferramenta de início rápido de inferência do GKE. Para saber mais, consulte o guia de início rápido da inferência do GKE e o notebook do Colab.

Receber acesso ao modelo

Para acessar o modelo pelo Hugging Face, você vai precisar de um token do Hugging Face.

Siga as etapas abaixo para gerar um novo token, caso ainda não tenha um:

Clique em Seu perfil > Configurações > Tokens de acesso.
Selecione Novo token.
Especifique um Nome de sua escolha e uma Função de pelo menos Leitura.
Selecione Gerar um token.
Copie o token gerado para a área de transferência.

Provisionar o ambiente de inferência do GKE

Nesta seção, você implanta a infraestrutura necessária para veicular seu modelo.

Iniciar o Cloud Shell

Este guia usa o Cloud Shell para executar comandos. O Cloud Shell vem pré-instalado com as ferramentas necessárias, incluindo gcloud, kubectl e git.

No console Google Cloud , inicie uma instância do Cloud Shell:

Abra o Cloud Shell

Essa ação inicia uma sessão no painel inferior do console Google Cloud .

Implantar a arquitetura de base

Para provisionar o cluster do GKE e os recursos necessários para acessar modelos do Hugging Face, siga estas etapas:

No Cloud Shell, clone o seguinte repositório:

git clone https://github.com/GoogleCloudPlatform/accelerated-platforms --branch hf-model-tutorial && \
cd accelerated-platforms && \
export ACP_REPO_DIR="$(pwd)"

Defina as variáveis de ambiente:
```
export TF_VAR_platform_default_project_id=PROJECT_ID
export HF_TOKEN_READ=HF_TOKEN
```
Substitua os seguintes valores:
- PROJECT_ID: o Google Cloud ID do projeto.
- HF_TOKEN: o token do Hugging Face que você gerou anteriormente.
Este guia requer o Terraform versão 1.8.0 ou mais recente. O Cloud Shell tem o Terraform v1.5.7 instalado por padrão.

Para atualizar a versão do Terraform no Cloud Shell, execute o script a seguir. Esse script instala a ferramenta terraform-switcher e faz mudanças no ambiente shell.
```
"${ACP_REPO_DIR}/tools/bin/install_terraform.sh"
source ~/.bashrc
```
Execute o script de implantação a seguir. O script de implantação ativa as APIs Google Cloud necessárias e provisiona a infraestrutura necessária para este guia. Isso inclui uma nova rede VPC, um cluster do GKE com nós particulares e outros recursos de suporte. O script pode levar alguns minutos para ser concluído.

É possível disponibilizar modelos usando GPUs em um cluster do GKE Autopilot ou Standard. Um cluster do Autopilot oferece uma experiência totalmente gerenciada do Kubernetes. Para mais informações sobre como escolher o modo de operação do GKE mais adequado para suas cargas de trabalho, consulte Sobre os modos de operação do GKE.
Piloto automático
```
"${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/deploy-ap.sh"
```
Padrão
```
"${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/deploy-standard.sh"
```
Depois que o script for concluído, você terá um cluster do GKE pronto para cargas de trabalho de inferência.

Execute o comando a seguir para definir variáveis de ambiente da configuração compartilhada:

source "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/terraform/_shared_config/scripts/set_environment_variables.sh"

O script de implantação cria um secret no Secret Manager para armazenar seu token do Hugging Face. Você precisa adicionar manualmente seu token a esse secret antes de implantar o cluster. No Cloud Shell, execute este comando para adicionar o token ao Secret Manager.
```
echo ${HF_TOKEN_READ} | gcloud secrets versions add ${huggingface_hub_access_token_read_secret_manager_secret_name} \
    --data-file=- \
    --project=${huggingface_secret_manager_project_id}
```

Implantar um modelo aberto

Agora você pode baixar e implantar o modelo.

Defina as variáveis de ambiente do modelo que você quer implantar:

Gemma 3 27B-it

export ACCELERATOR_TYPE="h100"
export HF_MODEL_ID="google/gemma-3-27b-it"

Llama 4 Scout 17B-16E-Instruct

export ACCELERATOR_TYPE="h100"
export HF_MODEL_ID="meta-llama/llama-4-scout-17b-16e-instruct"

Qwen3 32B

export ACCELERATOR_TYPE="h100"
export HF_MODEL_ID="qwen/qwen3-32b"

gpt-oss 20B

export ACCELERATOR_TYPE="h100"
export HF_MODEL_ID="openai/gpt-oss-20b"

Para outras configurações, incluindo outras variantes de modelo e tipos de GPU, consulte os manifestos disponíveis no repositório accelerated-platforms do GitHub.

Crie as variáveis de ambiente da sua implantação. Essas variáveis de ambiente contêm os detalhes de configuração necessários da infraestrutura provisionada.
```
source "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/terraform/_shared_config/scripts/set_environment_variables.sh"
```

Execute o script a seguir para configurar o job do Kubernetes que faz o download do modelo para o Cloud Storage:

"${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/configure_huggingface.sh"

Implante o job de download do modelo:

kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/huggingface"

Aguarde a conclusão do download. Monitore o status do job e, quando COMPLETIONS for 1/1, pressione Ctrl+C para sair.

watch --color --interval 5 --no-title "kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs

Implante a carga de trabalho de inferência no cluster do GKE.

"${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/configure_deployment.sh"

kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"

Testar a implantação

Aguarde até que o pod do servidor de inferência esteja pronto. Quando a coluna READY for 1/1, pressione Ctrl+C para sair.

watch --color --interval 5 --no-title "kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"

Execute o script a seguir para configurar o encaminhamento de portas e enviar uma solicitação de amostra ao modelo. Este exemplo usa o formato de payload para um modelo Gemma 3 27b-it.

kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} port-forward service/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} 8000:8000 >/dev/null &
PF_PID=$!
curl http://127.0.0.1:8000/v1/chat/completions \
  --data '{
    "model": "/gcs/'${HF_MODEL_ID}'",
    "messages": [ { "role": "user", "content": "What is GKE?" } ]
  }' \
  --header "Content-Type: application/json" \
  --request POST \
  --show-error \
  --silent | jq
kill -9 ${PF_PID}

Você vai receber uma resposta JSON do modelo respondendo à pergunta.

Limpar

Para evitar cobranças, exclua todos os recursos criados.

Exclua a carga de trabalho de inferência:

kubectl delete --ignore-not-found --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-gpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"

Remova o cluster do GKE fundamental:

Piloto automático

"${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/teardown-ap.sh"

Padrão

"${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-model/teardown-standard.sh"

A seguir

Saiba mais sobre a inferência de modelos de IA/ML no GKE.
Analise o desempenho e os custos da inferência de modelo com a ferramenta de início rápido de inferência do GKE.
Confira outros casos de uso e padrões no GitHub criados com base nessa arquitetura.