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

Autopilot Standard

---

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:

• Google Gemma 3 27B-it
• Meta Llama 4 Scout 17B-16E-Instruct
• Qwen3 32-B
• OpenAI gpt-oss-20b

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.

Antes de começar

• In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

  Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

  Go to project selector

• Verify that billing is enabled for your Google Cloud project.

• Enable the required APIs.

  Enable the APIs

• Make sure that you have the following role or roles on the project: roles/artifactregistry.admin, roles/browser, roles/compute.networkAdmin, roles/container.clusterAdmin, roles/iam.serviceAccountAdmin, roles/resourcemanager.projectIamAdmin, and roles/serviceusage.serviceUsageAdmin

  Check for the roles

  1. In the Google Cloud console, go to the IAM page.

     Go to IAM
  2. Select the project.

  3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

  4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

  Grant the roles

  1. In the Google Cloud console, go to the IAM page.

     Acessar o IAM
  2. Selecione o projeto.
  3. Clique em Conceder acesso.

  4. No campo Novos principais, digite seu identificador de usuário. Normalmente, é o identificador de um usuário em um pool de identidades de força de trabalho. Saiba mais em Representar usuários do pool de força de trabalho nas políticas do IAM ou entre em contato com seu administrador.

  5. Na lista Selecionar papel, escolha um.
  6. Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
  7. Clique em Salvar.
  • Crie uma conta do Hugging Face.
  • Verifique se o projeto tem cota de GPU suficiente. Para mais informações, consulte Cotas de alocação.

  Receber acesso ao modelo

  Observação: é necessário aceitar os termos de licença de todos os modelos restritos que você quiser usar (como Gemma ou Llama) na página do modelo correspondente no Hugging Face.

  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:

  1. Clique em Seu perfil > Configurações > Tokens de acesso.
  2. Selecione Novo token.
  3. Especifique um Nome de sua escolha e uma Função de pelo menos Leitura.
  4. Selecione Gerar um token.
  5. 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:

  1. 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)"
     

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

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

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

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

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

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

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

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

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

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

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

  1. 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}"
     

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

  1. 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}"
     

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