Para disponibilizar modelos de linguagem grandes (LLMs) Gemma 3 no Google Kubernetes Engine (GKE) usando o framework vLLM, é necessário provisionar um cluster do GKE com aceleradores compatíveis, como GPUs NVIDIA B200, H100 ou L4.
Para obter os pesos do modelo Gemma 3, configure o contêiner vLLM pré-criado para fazer o download deles no repositório do Hugging Face. Como alternativa, o contêiner pode carregar pesos de modelo do armazenamento persistente, como o armazenamento em cache dos buckets de modelo do Cloud Storage em uma instância do Google Cloud Managed Lustre.
Depois que os pesos são carregados, o contêiner vLLM expõe um endpoint de API compatível com OpenAI para inferência de alta capacidade de processamento.
Este tutorial é destinado a engenheiros de machine learning (ML), administradores e operadores de plataforma e especialistas em dados e IA interessados em usar os recursos de orquestração de contêineres do Kubernetes para veicular cargas de trabalho de IA/ML em hardwares de GPU H200, H100, A100 e L4. Para saber mais sobre papéis comuns e tarefas de exemplo referenciados no conteúdo do Google Cloud , consulte Tarefas e funções de usuário comuns do GKE.
Se você precisa de uma plataforma de IA gerenciada unificada projetada para criar e disponibilizar modelos de ML rapidamente e de maneira econômica, recomendamos que você teste nossa solução de implantação da Vertex AI.
Antes de ler esta página, confira se você conhece os seguintes conceitos:
Contexto
Esta seção descreve as principais tecnologias usadas neste guia.
Gemma
O Gemma é um conjunto de modelos multimodais de inteligência artificial (IA) generativa, leve e abertamente lançados sob licença aberta. Esses modelos de IA estão disponíveis para execução em aplicativos, hardware, dispositivos móveis ou serviços hospedados. O Gemma 3 apresenta multimodalidade e oferece suporte a entradas de linguagem de visão e saídas de texto. Ela lida com janelas de contexto de até 128.000 tokens e oferece suporte a mais de 140 idiomas. O Gemma 3 também oferece recursos aprimorados de matemática, raciocínio e chat, incluindo saídas estruturadas e chamadas de função.
É possível usar os modelos Gemma para geração de texto ou ajustá-los para tarefas especializadas.
Para mais informações, consulte a documentação do Gemma.
GPUs
As GPUs permitem acelerar cargas de trabalho específicas em execução nos nós, como machine learning e processamento de dados. O GKE oferece uma gama de opções de tipos de máquina para configuração de nós, incluindo tipos de máquinas com GPUs NVIDIA H200, H100, L4 e A100.
vLLM
O vLLM é um framework de disponibilização de LLM de código aberto altamente otimizado que pode aumentar a capacidade de processamento em GPUs, com recursos como:
- Otimização da implementação do transformador com PagedAttention
- Lotes contínuos para melhorar a capacidade geral de exibição
- Paralelismo de tensor e exibição distribuída em várias GPUs
Para mais informações, consulte a documentação do vLLM.
Objetivos
Este tutorial oferece uma base para entender e explorar a implantação prática de LLMs para inferência em um ambiente gerenciado do Kubernetes.
- Prepare seu ambiente com um cluster do GKE no modo Autopilot ou Standard.
- Implante um contêiner vLLM no seu cluster.
- Use o vLLM para disponibilizar o modelo Gemma 3 por meio de curl e de uma interface de chat na Web.
Antes de começar
- Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the required API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the required API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.-
Verifique se você tem os seguintes papéis no projeto: roles/container.admin, roles/iam.serviceAccountAdmin
Verificar os papéis
-
No console do Google Cloud , acesse a página IAM.
Acessar IAM - Selecione o projeto.
-
Na coluna Principal, encontre todas as linhas que identificam você ou um grupo no qual você está incluído. Para saber em quais grupos você está incluído, entre em contato com o administrador.
- Em todas as linhas que especificam ou incluem você, verifique a coluna Papel para ver se a lista de papéis inclui os papéis necessários.
Conceder os papéis
-
No console do Google Cloud , acesse a página IAM.
Acessar IAM - Selecione o projeto.
- Clique em Conceder acesso.
-
No campo Novos principais, digite seu identificador de usuário. Normalmente, é o endereço de e-mail de uma Conta do Google.
- Clique em Selecionar um papel e pesquise o papel.
- Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
- Clique em Salvar.
-
- Verifique se o projeto tem cota suficiente para GPUs L4. Para mais informações, consulte Sobre GPUs e Cotas de alocação.
Preparar o ambiente
Neste tutorial, você vai usar o Cloud Shell para gerenciar recursos hospedados no
Google Cloud. O Cloud Shell vem pré-instalado com o software necessário
para este tutorial, incluindo
kubectl e
a CLI gcloud.
Para configurar o ambiente com o Cloud Shell, siga estas etapas:
No console do Google Cloud , inicie uma sessão do Cloud Shell clicando em
Ativar o Cloud Shell no console doGoogle Cloud . Isso inicia uma sessão no painel inferior do console Google Cloud .Defina as variáveis de ambiente padrão:
gcloud config set project PROJECT_ID gcloud config set billing/quota_project PROJECT_ID export PROJECT_ID=$(gcloud config get project) export REGION=REGION export CLUSTER_NAME=CLUSTER_NAMESubstitua os seguintes valores:
PROJECT_ID: o Google Cloud ID do projeto.REGION: uma região compatível com o tipo de acelerador que você quer usar, por exemplo,us-central1para GPU L4.CLUSTER_NAME: o nome do cluster.
Criar e configurar recursos Google Cloud
Siga estas instruções para criar os recursos necessários.
Criar um cluster do GKE e um pool de nós
É possível disponibilizar o Gemma em GPUs em um cluster do GKE Autopilot ou Standard. Recomendamos que você use um cluster do Autopilot para ter uma experiência totalmente gerenciada do Kubernetes. Para escolher o modo de operação do GKE mais adequado para suas cargas de trabalho, consulte Escolher um modo de operação do GKE.
Piloto automático
No Cloud Shell, execute este comando:
gcloud container clusters create-auto CLUSTER_NAME \
--project=PROJECT_ID \
--location=CONTROL_PLANE_LOCATION \
--release-channel=rapid
Substitua os seguintes valores:
PROJECT_ID: o Google Cloud ID do projeto.CONTROL_PLANE_LOCATION: a região do Compute Engine do plano de controle do cluster. Forneça uma região compatível com o tipo de acelerador que você quer usar, por exemplo,us-central1para GPU L4.CLUSTER_NAME: o nome do cluster.
O GKE cria um cluster do Autopilot com nós de CPU e GPU conforme solicitado pelas cargas de trabalho implantadas.
Padrão
No Cloud Shell, execute o seguinte comando para criar um cluster Standard:
gcloud container clusters create CLUSTER_NAME \ --project=PROJECT_ID \ --location=CONTROL_PLANE_LOCATION \ --workload-pool=PROJECT_ID.svc.id.goog \ --release-channel=rapid \ --num-nodes=1Substitua os seguintes valores:
PROJECT_ID: o Google Cloud ID do projeto.CONTROL_PLANE_LOCATION: a região do Compute Engine do plano de controle do cluster. Forneça uma região compatível com o tipo de acelerador que você quer usar, por exemplo,us-central1para GPU L4.CLUSTER_NAME: o nome do cluster.
A criação do cluster pode levar vários minutos.
Para criar um pool de nós para o cluster com o tamanho de disco adequado, execute o seguinte comando:
Gemma 3 1B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-8 \ --num-nodes=1O GKE cria um único pool de nós contendo uma GPU L4 para cada nó.
Gemma 3 4B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-8 \ --num-nodes=1O GKE cria um único pool de nós contendo uma GPU L4 para cada nó.
Gemma 3 12B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=4,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-48 \ --num-nodes=1O GKE cria um único pool de nós contendo quatro GPUs L4 para cada nó.
Gemma 3 27B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-a100-80gb,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=a2-ultragpu-1g \ --disk-type=pd-ssd \ --num-nodes=1 \ --disk-size=256O GKE cria um único pool de nós contendo uma GPU A100 de 80 GB.
Implantar modelos do Gemma 3 no vLLM usando pesos do Hugging Face
Para implantar modelos do Gemma 3 usando pesos do Hugging Face, autentique seu cluster do GKE com um token da API Hugging Face e aplique um manifesto de implantação do Kubernetes. Esse manifesto extrai a imagem do contêiner vLLM, solicita uma GPU NVIDIA e monta seu token como um Secret para que o contêiner possa fazer o download dos pesos diretamente do repositório do Hugging Face durante a inicialização.
Procedimento
Para implantar o modelo, siga estas etapas:
- Acesse o modelo Gemma 3 e gere um token do Hugging Face.
- Crie um secret do Kubernetes no GKE para armazenar o token.
- Implante o manifesto do vLLM para o modelo Gemma 3 selecionado.
Receber acesso ao modelo
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 um Papel de pelo menos
Read. - Selecione Gerar um token.
- Copie o token gerado para a área de transferência.
Execute este comando para definir o token como uma variável de ambiente.
export HF_TOKEN=HF_TOKEN
Criar um secret do Kubernetes para as credenciais do Hugging Face
No Cloud Shell, faça o seguinte:
Configure
kubectlpara que ele possa se comunicar com o cluster:gcloud container clusters get-credentials CLUSTER_NAME \ --location=REGIONSubstitua os seguintes valores:
REGION: uma região compatível com o tipo de acelerador que você quer usar, por exemplo,us-central1para GPU L4.CLUSTER_NAME: o nome do cluster.
Crie um secret do Kubernetes que contenha o token do Hugging Face:
kubectl create secret generic hf-secret \ --from-literal=hf_api_token=${HF_TOKEN} \ --dry-run=client -o yaml | kubectl apply -f -Substitua
HF_TOKENpelo token do Hugging Face que você gerou anteriormente.
Faça o download dos pesos do modelo Gemma 3 do Hugging Face
Aplique o manifesto de implantação para o tamanho do modelo selecionado. Uma implantação é um objeto da API Kubernetes que permite executar várias réplicas de pods distribuídos entre os nós de um cluster.
A aplicação desse manifesto cria um pod no cluster que faz o download dos pesos do modelo Gemma 3 diretamente do Hugging Face e inicia o mecanismo de exibição do vLLM.
Gemma 3 1B-it
Siga estas instruções para implantar o modelo ajustado por instruções do Gemma 3 1B (entrada somente de texto).
Crie o seguinte manifesto
vllm-3-1b-it.yaml:Aplique o manifesto:
kubectl apply -f vllm-3-1b-it.yaml
Gemma 3 4B-it
Siga estas instruções para implantar o modelo ajustado por instruções do Gemma 3 4B.
Crie o seguinte manifesto
vllm-3-4b-it.yaml:Aplique o manifesto:
kubectl apply -f vllm-3-4b-it.yamlNo nosso exemplo, limitamos a janela de contexto em 32 K usando a opção
--max-model-len=32768do vLLM. Se você quiser um tamanho maior de janela de contexto (até 128 K), ajuste o manifesto e a configuração do pool de nós com mais capacidade de GPU.
Gemma 3 12B-it
Siga estas instruções para implantar o modelo ajustado por instruções do Gemma 3 12B.
Crie o seguinte manifesto
vllm-3-12b-it.yaml:Aplique o manifesto:
kubectl apply -f vllm-3-12b-it.yamlNo nosso exemplo, limitamos o tamanho da janela de contexto em 16 K usando a opção
--max-model-len=16384do vLLM. Se você quiser um tamanho maior de janela de contexto (até 128 K), ajuste o manifesto e a configuração do pool de nós com mais capacidade de GPU.
Gemma 3 27B-it
Siga estas instruções para implantar o modelo ajustado por instruções do Gemma 3 27B.
Crie o seguinte manifesto
vllm-3-27b-it.yaml:Aplique o manifesto:
kubectl apply -f vllm-3-27b-it.yamlNo nosso exemplo, limitamos o tamanho da janela de contexto em 32 K usando a opção
--max-model-len=32768do vLLM. Se você quiser um tamanho maior da janela de contexto (até 128 mil), ajuste o manifesto e a configuração do pool de nós com mais capacidade de GPU.
Verificação
Aguarde até que a implantação esteja disponível:
kubectl wait --for=condition=Available --timeout=1800s deployment/vllm-gemma-deploymentConfira os registros da implantação em execução:
kubectl logs -f -l app=gemma-serverO recurso de implantação faz o download dos dados do modelo Gemma. O processo pode levar alguns minutos. O resultado será o seguinte:
INFO: Automatically detected platform cuda. ... INFO [launcher.py:34] Route: /v1/chat/completions, Methods: POST ... INFO: Started server process [13] INFO: Waiting for application startup. INFO: Application startup complete. Default STARTUP TCP probe succeeded after 1 attempt for container "vllm--google--gemma-3-4b-it-1" on port 8080.
Depois que a implantação do Hugging Face estiver disponível, configure o encaminhamento de portas para interagir com o modelo.
Implantar o Gemma com ajuste fino do Managed Lustre
Para disponibilizar um modelo Gemma refinado (como o Gemma 3 27B) que já está armazenado em uma instância do Google Cloud Managed Lustre, é necessário montar o PersistentVolumeClaim (PVC) correspondente no contêiner vLLM.
Pré-requisitos
Verifique se você tem uma PVC no cluster do GKE que se conecta à instância do Lustre. Neste exemplo, o PVC é chamado de gemma-lustre-pvc.
Para saber como criar um PVC e um PersistentVolume (PV) para uma instância atual, consulte Acessar uma instância do Managed Lustre.
Procedimento
Salve o seguinte manifesto YAML como
vllm-lustre-gemma.yaml. Neste exemplo, o Deployment monta o PVC do Lustre em/datae instrui o vLLM a carregar os pesos do modelo desse caminho local.apiVersion: apps/v1 kind: Deployment metadata: name: vllm-gemma-lustre spec: replicas: 1 selector: matchLabels: app: gemma-server template: metadata: labels: app: gemma-server spec: containers: - name: vllm image: vllm/vllm-openai:latest command: ["python3", "-m", "vllm.entrypoints.openai.api_server"] args: - --model=/data/gemma-3-27b - --tensor-parallel-size=1 resources: limits: nvidia.com/gpu: "1" volumeMounts: - name: model-weights mountPath: /data volumes: - name: model-weights persistentVolumeClaim: claimName: gemma-lustre-pvc nodeSelector: cloud.google.com/gke-accelerator: nvidia-l4 cloud.google.com/gke-gpu-driver-version: latestAplique o manifesto ao cluster do GKE:
kubectl apply -f vllm-lustre-gemma.yaml
Verificação
Para confirmar se o modelo foi carregado do volume do Lustre, verifique os registros do pod na sequência de inicialização do vLLM:
kubectl logs -l app=gemma-server
Disponibilizar o modelo
Nesta seção, você vai interagir com o modelo. Verifique se o download do modelo foi concluído antes de prosseguir.
Configurar o encaminhamento de portas
Execute o seguinte comando para configurar o encaminhamento de portas para o modelo:
kubectl port-forward service/llm-service 8000:8000
O resultado será assim:
Forwarding from 127.0.0.1:8000 -> 8000
Interagir com o modelo usando curl
Nesta seção, mostramos como realizar um teste preliminar básico para verificar os modelos
ajustados por instruções do Gemma 3 implantados.
Para outros modelos, substitua gemma-3-4b-it pelo nome do modelo respectivo.
Este exemplo mostra como testar o modelo ajustado por instrução da Gemma 3 4B com entrada somente de texto.
Em uma nova sessão do terminal, use curl para conversar com seu modelo:
curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemma-3-4b-it",
"messages": [
{
"role": "user",
"content": "Why is the sky blue?"
}
]
}'
A saída será assim:
{
"id": "chatcmpl-e4a2e624bea849d9b09f838a571c4d9e",
"object": "chat.completion",
"created": 1741763029,
"model": "google/gemma-3-4b-it",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"reasoning_content": null,
"content": "Okay, let's break down why the sky appears blue! It's a fascinating phenomenon rooted in physics, specifically something called **Rayleigh scattering**. Here's the explanation: ...",
"tool_calls": []
},
"logprobs": null,
"finish_reason": "stop",
"stop_reason": 106
}
],
"usage": {
"prompt_tokens": 15,
"total_tokens": 668,
"completion_tokens": 653,
"prompt_tokens_details": null
},
"prompt_logprobs": null
}
(Opcional) Interagir com o modelo usando uma interface de chat do GRadio
Nesta seção, você criará um aplicativo de chat na Web que permite interagir com seu modelo ajustado por instruções. Para simplificar, esta seção descreve apenas a abordagem de teste usando o modelo 4B-it.
O Gradio é uma biblioteca Python que tem um
wrapper ChatInterface que cria interfaces de usuário para chatbots.
Implantar a interface de chat
No Cloud Shell, salve o seguinte manifesto como
gradio.yaml. Mudegoogle/gemma-2-9b-itparagoogle/gemma-3-4b-itou para outro nome de modelo da Gemma 3 usado na sua implantação.Aplique o manifesto:
kubectl apply -f gradio.yamlAguarde até que a implantação esteja disponível:
kubectl wait --for=condition=Available --timeout=900s deployment/gradio
Usar a interface de chat
No Cloud Shell, execute este comando:
kubectl port-forward service/gradio 8080:8080Isso cria um encaminhamento de porta do Cloud Shell para o serviço GRadio.
Clique no botão
Visualização da Web no canto superior direito da barra de tarefas do Cloud Shell. Clique em Visualizar na porta 8080. Uma nova guia será aberta no navegador.Interaja com Gemma usando a interface de chat do GRadio. Adicione uma solicitação e clique em Enviar.
Resolver problemas
- Se você receber a mensagem
Empty reply from server, é possível que o contêiner não tenha concluído o download dos dados do modelo. Verifique os registros do pod novamente para ver a mensagemConnected, que indica que o modelo está pronto para ser disponibilizado. - Se você vir
Connection refused, verifique se o encaminhamento de portas está ativo.
Observar o desempenho do modelo
Para conferir os painéis das métricas de observabilidade de um modelo, siga estas etapas:
No console do Google Cloud , acesse a página Modelos implantados.
Para ver detalhes sobre a implantação específica, incluindo métricas, registros e painéis, clique no nome do modelo na lista.
Na página de detalhes do modelo, clique na guia Observabilidade para conferir os seguintes painéis. Se solicitado, clique em Ativar para ativar a coleta de métricas do cluster.
- O painel Uso da infraestrutura mostra métricas de utilização.
- O painel DCGM mostra as métricas do DCGM.
- Se você estiver usando o vLLM, o painel Performance do modelo vai estar disponível e mostrará métricas de desempenho do modelo vLLM.
Também é possível conferir as métricas na integração do painel do vLLM no Cloud Monitoring. Essas métricas são agregadas para todas as implantações de vLLM sem filtros predefinidos.
Para usar o painel no Cloud Monitoring, ative o Google Cloud Managed Service para Prometheus, que coleta as métricas do vLLM no cluster do GKE. O vLLM expõe métricas no formato do Prometheus por padrão. Não é necessário instalar um exportador adicional. Para informações sobre como usar o Google Cloud Managed Service para Prometheus para coletar métricas do seu modelo, consulte as orientações de observabilidade do vLLM na documentação do Cloud Monitoring.
Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.
Excluir os recursos implantados
Para evitar cobranças na sua conta do Google Cloud pelos recursos criados neste guia, execute o seguinte comando:
gcloud container clusters delete CLUSTER_NAME \
--location=CONTROL_PLANE_LOCATION
Substitua os seguintes valores:
CONTROL_PLANE_LOCATION: a região do Compute Engine do plano de controle do cluster.CLUSTER_NAME: o nome do cluster.
A seguir
- Saiba mais sobre GPUs no GKE.
- Aprenda a usar o Gemma com o vLLM em outros aceleradores, incluindo GPUs A100 e H100, visualizando o exemplo de código no GitHub.
- Saiba mais como implantar cargas de trabalho de GPU no Autopilot.
- Aprenda a implantar cargas de trabalho de GPU no Standard.
- Conheça o repositório do GitHub e a documentação do vLLM.
- Conhecer o Model Garden da Vertex AI.
- Descubra como executar cargas de trabalho de IA/ML otimizadas com os recursos de orquestração da plataforma GKE.