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:
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_TOKENSubstitua 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-switchere faz mudanças no ambiente shell."${ACP_REPO_DIR}/tools/bin/install_terraform.sh" source ~/.bashrcExecute 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-platformsdo 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
COMPLETIONSfor1/1, pressioneCtrl+Cpara sair.watch --color --interval 5 --no-title "kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcsImplante 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
READYfor1/1, pressioneCtrl+Cpara 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.