Publique MDIs abertos no GKE com uma arquitetura pré-configurada

Autopilot Padrão

---

Esta página mostra como implementar e publicar rapidamente modelos de linguagem (conteúdo extenso) (MDI/CE) abertos populares no GKE para inferência através de uma arquitetura de referência pré-configurada e pronta para produção. Esta abordagem usa a infraestrutura como código (IaC), com o Terraform integrado em scripts da CLI, para criar um ambiente do GKE padronizado, seguro e escalável concebido para cargas de trabalho de inferência de IA.

Neste guia, implementa e publica MDIs com nós de GPU de anfitrião único no GKE com a framework de publicação vLLM. Este guia fornece instruções e configurações para implementar 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 destina-se a engenheiros de aprendizagem automática (ML) e especialistas em dados e IA que tenham interesse em explorar as capacidades de orquestração de contentores do Kubernetes para publicar modelos abertos para inferência. Para saber mais sobre as funções comuns e as tarefas de exemplo referenciadas no conteúdo, consulte o artigo Funções e tarefas comuns do utilizador do GKE. Google Cloud

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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.

     Aceder ao IAM
  2. Selecione o projeto.
  3. Clique em Conceder acesso.

  4. No campo Novos responsáveis, introduza o identificador do utilizador. Normalmente, este é o endereço de email de uma Conta Google.

  5. Na lista Selecionar uma função, selecione uma função.
  6. Para conceder funções adicionais, clique em Adicionar outra função e adicione cada função adicional.
  7. Clique em Guardar.
  • Crie uma conta do Hugging Face.
  • Certifique-se de que o seu projeto tem uma quota de GPUs suficiente. Para mais informações, consulte o artigo Quotas de atribuição.

  Aceda ao modelo

  Nota: tem de aceitar os termos de licença de todos os modelos restritos que quer usar (como o Gemma ou o Llama) na respetiva página do modelo do Hugging Face.

  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:

  1. Clique em O seu perfil > Definições > Tokens de acesso.
  2. Selecione Novo token.
  3. Especifique um Nome à 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.

  Aprovisione o ambiente de inferência do GKE

  Nesta secção, implementa a infraestrutura necessária para publicar o seu modelo.

  Inicie o Cloud Shell

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

  Na Google Cloud consola, inicie uma instância do Cloud Shell:

  Abra o Cloud Shell

  Esta ação inicia uma sessão no painel inferior da consola Google Cloud .

  Implemente a arquitetura base

  Para aprovisionar o cluster do GKE e os recursos necessários para aceder aos modelos da Hugging Face, siga estes passos:

  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 seu Google Cloud ID do projeto.
     • HF_TOKEN: o token do Hugging Face que gerou anteriormente.

  3. Este guia requer a versão 1.8.0 ou posterior do Terraform. O Cloud Shell tem o Terraform v1.5.7 instalado por predefinição.

     Para atualizar a versão do Terraform no Cloud Shell, pode executar o seguinte script. Este script instala a ferramenta terraform-switcher e faz alterações ao seu ambiente de shell.

     "${ACP_REPO_DIR}/tools/bin/install_terraform.sh"
     source ~/.bashrc
     

  4. Execute o seguinte guião de implementação. O script de implementação ativa as APIs necessárias e aprovisiona a infraestrutura necessária para este guia. Google Cloud Isto inclui uma nova rede VPC, um cluster do GKE com nós privados e outros recursos de apoio. O script pode demorar vários minutos a ser concluído.

     Pode publicar modelos com GPUs num cluster padrão ou do GKE Autopilot. Um cluster do Autopilot oferece uma experiência do Kubernetes totalmente gerida. Para mais informações sobre como escolher o modo de funcionamento do GKE mais adequado para as suas cargas de trabalho, consulte o artigo Acerca dos modos de funcionamento do GKE.

     Piloto automático

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

     Standard

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

     Depois de este script ser concluído, tem um cluster do GKE pronto para cargas de trabalho de inferência.

  5. Execute o seguinte comando para definir variáveis de ambiente a partir da configuração partilhada:

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

  6. O script de implementação cria um segredo no Secret Manager para armazenar o seu token do Hugging Face. Tem de adicionar manualmente o seu token a este segredo antes de implementar 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}
     

  Implemente um modelo aberto

  Já pode transferir e implementar o modelo.

  1. Defina as variáveis de ambiente para o modelo que quer implementar:

     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 configurações adicionais, incluindo outras variantes de modelos e tipos de GPUs, consulte os manifestos disponíveis no accelerated-platforms repositório do GitHub.

  2. Obtenha as variáveis de ambiente da sua implementação. Estas variáveis de ambiente contêm os detalhes de configuração necessários da infraestrutura que aprovisionou.

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

  3. Execute o seguinte script para configurar a tarefa do Kubernetes que transfere o modelo para o Cloud Storage:

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

  4. Implemente a tarefa de transferência do modelo:

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

  5. Aguarde pela conclusão da transferência. Monitorize o estado da tarefa e, quando COMPLETIONS estiver 1/1, prima 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. Implemente a carga de trabalho de inferência no seu 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}"
     

  Teste a implementação

  1. Aguarde até que o pod do servidor de inferência esteja pronto. Quando a coluna READY for 1/1, prima 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 seguinte script para configurar o encaminhamento de portas e enviar um pedido de exemplo 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}
     

     Deve ver uma resposta JSON do modelo a responder à pergunta.

  Limpar

  Para evitar incorrer em custos, elimine todos os recursos que criou.

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

     Standard

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

  O que se segue?

  • Saiba mais sobre a inferência do modelo de IA/ML no GKE.
  • Analise o desempenho e os custos da inferência de modelos com a ferramenta de início rápido da inferência do GKE.
  • Explore outros exemplos de utilização e padrões no GitHub criados com base nesta arquitetura.