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

Esta página mostra como implementar e publicar rapidamente modelos de linguagem (conteúdo extenso) (MDIs/CEs) populares de código aberto 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:

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 referidas no conteúdo, consulte o artigo Funções e tarefas comuns do utilizador do GKE. Google Cloud

Para uma análise detalhada do desempenho e dos custos da publicação de modelos para estes modelos abertos, também pode usar a ferramenta de início rápido do GKE Inference. Para saber mais, consulte o guia de início rápido da inferência do GKE e o notebook do Colab que o acompanha.

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:

  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á tem tudo pronto para 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?