Este tutorial mostra como implementar e publicar um modelo de linguagem (conteúdo extenso) (MDL/CE) Gemma 3 usando GPUs no Google Kubernetes Engine (GKE) com a framework de publicação vLLM. Isto fornece uma base para compreender e explorar a implementação prática de MDIs/CEs para inferência num ambiente Kubernetes gerido. Implementa um contentor pré-criado que executa o vLLM no GKE. Também configura o GKE para carregar os pesos do Gemma 1B, 4B, 12B e 27B do Hugging Face.
Este tutorial destina-se a engenheiros de aprendizagem automática (AA), administradores e operadores de plataformas, e especialistas em dados e IA que tenham interesse em usar capacidades de orquestração de contentores do Kubernetes para publicar cargas de trabalho de IA/AA em hardware de GPU H200, H100, A100 e L4. Para saber mais acerca das funções comuns e das tarefas de exemplo que referimos no Google Cloud conteúdo, consulte Funções e tarefas comuns do utilizador do GKE.
Se precisar de uma plataforma de IA gerida unificada concebida para criar e apresentar rapidamente modelos de ML de forma económica, recomendamos que experimente a nossa solução de implementação do Vertex AI.
Antes de ler esta página, certifique-se de que conhece o seguinte:
Contexto
Esta secção descreve as principais tecnologias usadas neste guia.
Gemma
O Gemma é um conjunto de modelos multimodais de inteligência artificial (IA) generativa, leves e disponíveis abertamente, lançados ao abrigo de uma licença aberta. Estes modelos de IA estão disponíveis para execução nas suas aplicações, hardware, dispositivos móveis ou serviços alojados. O Gemma 3 introduz a multimodalidade e suporta a entrada de linguagem visual e as saídas de texto. Processa janelas de contexto de até 128 000 tokens e suporta mais de 140 idiomas. O Gemma 3 também oferece capacidades melhoradas de matemática, raciocínio e chat, incluindo resultados estruturados e chamadas de funções.
Pode usar os modelos Gemma para geração de texto ou também pode ajustar estes modelos para tarefas especializadas.
Para mais informações, consulte a documentação do Gemma.
GPUs
As GPUs permitem-lhe acelerar cargas de trabalho específicas executadas nos seus nós, como a aprendizagem automática e o processamento de dados. O GKE oferece uma variedade de opções de tipos de máquinas para a configuração de nós, incluindo tipos de máquinas com GPUs NVIDIA H200, H100, L4 e A100.
vLLM
O vLLM é uma framework de publicação de LLMs de código aberto altamente otimizada que pode aumentar a taxa de transferência de publicação em GPUs, com funcionalidades como as seguintes:
- Implementação do transformador otimizada com PagedAttention
- Processamento em lote contínuo para melhorar o débito geral da publicação
- Paralelismo de tensores e publicação distribuída em várias GPUs
Para mais informações, consulte a documentação do vLLM.
Aceda ao modelo
Para aceder ao modelo através do Hugging Face, precisa de um token do Hugging Face.
Siga estes passos para gerar um novo token se ainda não tiver um:
- Clique em O seu perfil > Definições > Tokens de acesso.
- Selecione Novo token.
- Especifique um nome à sua escolha e uma função de, pelo menos,
Read. - Selecione Gerar um token.
- Copie o token gerado para a área de transferência.
Prepare o seu ambiente
Neste tutorial, vai usar o Cloud Shell para gerir recursos alojados no
Google Cloud. O Cloud Shell é pré-instalado com o software necessário
para este tutorial, incluindo
kubectl e
CLI gcloud.
Para configurar o seu ambiente com o Cloud Shell, siga estes passos:
Na Google Cloud consola, inicie uma sessão do Cloud Shell clicando em
Ativar Cloud Shell na Google Cloud consola. Esta ação inicia uma sessão no painel inferior da consola. Google Cloud Defina as variáveis de ambiente predefinidas:
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_NAME export HF_TOKEN=HF_TOKENSubstitua os seguintes valores:
PROJECT_ID: o seu Google Cloud ID do projeto.REGION: uma região que suporta o tipo de acelerador que quer usar, por exemplo,us-central1para a GPU L4.CLUSTER_NAME: o nome do cluster.HF_TOKEN: o token do Hugging Face que gerou anteriormente.
Crie e configure Google Cloud recursos
Siga estas instruções para criar os recursos necessários.
Crie um cluster e um node pool do GKE
Pode publicar o Gemma em GPUs num cluster do GKE Autopilot ou Standard. Recomendamos que use um cluster do Autopilot para uma experiência do Kubernetes totalmente gerida. Para escolher o modo de funcionamento do GKE mais adequado às suas cargas de trabalho, consulte o artigo Escolha um modo de funcionamento do GKE.
Piloto automático
No Cloud Shell, execute o seguinte 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 seu Google Cloud ID do projeto.CONTROL_PLANE_LOCATION: a região do Compute Engine do plano de controlo do seu cluster. Indique uma região que suporte o tipo de acelerador que quer usar, por exemplo,us-central1para a 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 implementadas.
Standard
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 seu Google Cloud ID do projeto.CONTROL_PLANE_LOCATION: a região do Compute Engine do plano de controlo do seu cluster. Indique uma região que suporte o tipo de acelerador que quer usar, por exemplo,us-central1para a GPU L4.CLUSTER_NAME: o nome do cluster.
A criação do cluster pode demorar vários minutos.
Para criar um node pool para o seu cluster com o tamanho do 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 node pool que contém 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 node pool que contém 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 node pool com 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 node pool que contém uma GPU A100 de 80 GB.
Crie um segredo do Kubernetes para as credenciais do Hugging Face
No Cloud Shell, faça o seguinte:
Configure o
kubectlpara que possa comunicar com o seu cluster:gcloud container clusters get-credentials CLUSTER_NAME \ --location=REGIONSubstitua os seguintes valores:
REGION: uma região que suporta o tipo de acelerador que quer usar, por exemplo,us-central1para a GPU L4.CLUSTER_NAME: o nome do cluster.
Crie um segredo 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 gerou anteriormente.
Implemente o vLLM
Nesta secção, implementa o contentor vLLM para publicar o modelo Gemma que quer usar. Para implementar o modelo, este tutorial usa implementações do Kubernetes. Uma implementação é um objeto da API Kubernetes que lhe permite executar várias réplicas de pods distribuídas entre os nós num cluster.
Gemma 3 1B-it
Siga estas instruções para implementar o modelo ajustado de instruções Gemma 3 1B (entrada apenas 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 implementar o modelo otimizado para instruções 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 capacidade de resposta a 32 mil tokens usando a opção vLLM
--max-model-len=32768. Se quiser um tamanho da capacidade de resposta maior (até 128 K), ajuste o manifesto e a configuração do conjunto de nós com mais capacidade de GPU.
Gemma 3 12B-it
Siga estas instruções para implementar o modelo ajustado de instruções 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 capacidade de resposta em 16 K usando a opção vLLM
--max-model-len=16384. Se quiser um tamanho da capacidade de resposta maior (até 128 K), ajuste a configuração do manifesto e do conjunto de nós com mais capacidade de GPU.
Gemma 3 27B-it
Siga estas instruções para implementar o modelo otimizado para instruções 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 capacidade de resposta a 32 mil usando a opção vLLM
--max-model-len=32768. Se quiser um tamanho da capacidade de resposta maior (até 128 mil), ajuste o manifesto e a configuração do conjunto de nós com mais capacidade de GPU.
Um pod no cluster transfere os pesos do modelo do Hugging Face e inicia o motor de publicação.
Aguarde até que a implementação esteja disponível:
kubectl wait --for=condition=Available --timeout=1800s deployment/vllm-gemma-deployment
Veja os registos da implementação em execução:
kubectl logs -f -l app=gemma-server
O recurso de implementação transfere os dados do modelo. Este processo pode demorar alguns minutos. O resultado é semelhante ao 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.
Certifique-se de que o modelo é totalmente transferido antes de avançar para a secção seguinte.
Publique o modelo
Nesta secção, interage com o modelo.
Configure 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 é semelhante ao seguinte:
Forwarding from 127.0.0.1:8000 -> 8000
Interaja com o modelo através do curl
Esta secção mostra como pode realizar um teste rápido básico para validar os seus modelos Gemma 3 otimizados para instruções implementados.
Para outros modelos, substitua gemma-3-4b-it pelo nome do modelo respetivo.
Este exemplo mostra como testar o modelo ajustado Gemma 3 4B com entrada apenas de texto.
Numa nova sessão de terminal, use curl para conversar com o 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?"
}
]
}'
O resultado tem um aspeto semelhante ao seguinte:
{
"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 através de uma interface de chat do Gradio
Nesta secção, vai criar uma aplicação de chat Web que lhe permite interagir com o seu modelo ajustado por instruções. Para simplificar, esta secção descreve apenas a abordagem de teste com o modelo de 4 bits.
O Gradio é uma biblioteca Python que tem um wrapper ChatInterface que cria interfaces do utilizador para chatbots.
Implemente a interface do chat
No Cloud Shell, guarde o seguinte manifesto como
gradio.yaml. Alteregoogle/gemma-2-9b-itparagoogle/gemma-3-4b-itou para outro nome do modelo Gemma 3 que usou na sua implementação.Aplique o manifesto:
kubectl apply -f gradio.yamlAguarde até que a implementação esteja disponível:
kubectl wait --for=condition=Available --timeout=900s deployment/gradio
Use a interface de chat
No Cloud Shell, execute o seguinte comando:
kubectl port-forward service/gradio 8080:8080Isto cria um encaminhamento de porta do Cloud Shell para o serviço Gradio.
Clique no botão
Pré-visualização Web, que se encontra na parte superior direita da barra de tarefas do Cloud Shell. Clique em Pré-visualizar na porta 8080. É aberto um novo separador no navegador.Interaja com o Gemma através da interface de chat do Gradio. Adicione um comando e clique em Enviar.
Resolver problemas
- Se receber a mensagem
Empty reply from server, é possível que o contentor não tenha terminado de transferir os dados do modelo. Verifique novamente os registos do Pod para ver a mensagemConnected, que indica que o modelo está pronto para publicação. - Se vir
Connection refused, verifique se o encaminhamento de portas está ativo.
Observe o desempenho do modelo
Para ver os painéis de controlo das métricas de observabilidade de um modelo, siga estes passos:
Na Google Cloud consola, aceda à página Modelos implementados.
Para ver detalhes sobre a implementação específica, incluindo as respetivas métricas, registos e painéis de controlo, clique no nome do modelo na lista.
Na página de detalhes do modelo, clique no separador Observabilidade para ver os seguintes painéis de controlo. Se lhe for pedido, clique em Ativar para ativar a recolha de métricas para o cluster.
- O painel de controlo Utilização da infraestrutura apresenta métricas de utilização.
- O painel de controlo do DCGM apresenta métricas do DCGM.
- Se estiver a usar o vLLM, o painel de controlo Desempenho do modelo está disponível e apresenta métricas para o desempenho do modelo vLLM.
Também pode ver métricas na integração do painel de controlo do vLLM no Cloud Monitoring. Estas métricas são agregadas para todas as implementações de vLLM sem filtros predefinidos
Para usar o painel de controlo no Cloud Monitoring, tem de ativar o Google Cloud Managed Service for Prometheus, que recolhe as métricas do vLLM, no seu cluster do GKE. Por predefinição, o vLLM expõe métricas no formato Prometheus; não precisa de instalar um exportador adicional. Para obter informações sobre a utilização do serviço gerido do Google Cloud para Prometheus para recolher métricas do seu modelo, consulte as orientações de observabilidade da vLLM na documentação do Cloud Monitoring.