Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Disponibilizar LLMs abertos no GKE usando TPUs com uma arquitetura pré-configurada

Autopilot Padrão

Nesta página, mostramos como implantar e disponibilizar rapidamente modelos de linguagem grandes (LLMs) abertos e populares no GKE com TPUs para inferência usando uma arquitetura de referência de inferência do GKE pré-configurada e pronta para produção. GKE inference reference architecture. Essa abordagem usa a infraestrutura como código (IaC, na sigla em inglês), com o Terraform encapsulado em scripts da CLI, para criar um ambiente do GKE padronizado, seguro e escalonável projetado para cargas de trabalho de inferência de IA.

Neste guia, você vai implantar e disponibilizar LLMs usando nós de TPU de host único no GKE com o framework de veiculaçã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 explorar 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 tarefas de exemplo referenciados no Google Cloud content, consulte Tarefas e funções de usuário comuns do GKE.

Antes de começar

Faça login nasua Google Cloud conta. Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho dos 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 the resourcemanager.projects.create permission. Learn how to grant roles.

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

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

Verifique se você tem os seguintes papéis no projeto: roles/artifactregistry.admin, roles/browser, roles/compute.networkAdmin, roles/container.clusterAdmin, roles/iam.roleAdmin, roles/iam.serviceAccountAdmin, roles/resourcemanager.projectIamAdmin, roles/serviceusage.serviceUsageAdmin e roles/secretmanager.secretVersionManager
Verificar os papéis
1. No Google Cloud console, acesse a página IAM.
  Acessar IAM
2. Selecione o projeto.
3. 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.
4. 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
1. No Google Cloud console, acesse a página IAM.
  Acessar IAM
2. Selecione o projeto.
3. Clique em Conceder acesso.
4. No campo Novos principais, digite seu identificador de usuário. Normalmente, é o endereço de e-mail de uma Conta do Google.
5. Clique em Selecionar um papel e pesquise o papel.
6. Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
7. Clique em Salvar.

Crie uma conta do Hugging Face.
Verifique se o projeto tem cota de TPU suficiente (cota do GKE Standard ou do GKE Autopilot). Para mais informações, consulte Planejar TPUs no GKE.

Receber acesso ao modelo

Aceite os termos de licença de todos os modelos restritos que você quiser usar (como o Gemma) na página de modelo do Hugging Face.

Para acessar o modelo usando o 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 um Papel 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ê vai implantar a infraestrutura necessária para disponibilizar o modelo.

Iniciar o Cloud Shell

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

No Google Cloud console, inicie uma instância do Cloud Shell:

Abra o Cloud Shell

Essa ação inicia uma sessão no painel inferior de Google Cloud console.

Implantar a arquitetura 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-vllm-tpu-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_TOKEN
```
Substitua os seguintes valores:
- PROJECT_ID: ID do projeto. Google Cloud
- HF_TOKEN: o token do Hugging Face gerado 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 tfswitch ferramenta e o Terraform v1.8.0 no seu diretório pessoal. Siga as instruções do script para definir a variável de ambiente necessária ou transmitir a flag --modify-rc-file para o script.
```
"${ACP_REPO_DIR}/tools/bin/install_terraform.sh" && \
export PATH=${HOME}/bin:${HOME}/.local/bin:${PATH}
```
Execute 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 vários minutos para ser concluído.

É possível disponibilizar modelos usando TPUs 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.
Autopilot
"${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-tpu-model/deploy-ap.sh"
Padrão
"${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-tpu-model/deploy-standard.sh"
Depois que esse 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 as 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. Adicione o token manualmente 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ê já pode baixar e implantar o modelo.

Selecione um modelo

Defina as variáveis de ambiente do modelo que você quer implantar:
Gemma 3 1B-it
export ACCELERATOR_TYPE="v5e" export HF_MODEL_ID="google/gemma-3-1b-it"
Gemma 3 4B-it
export ACCELERATOR_TYPE="v5e" export HF_MODEL_ID="google/gemma-3-4b-it"
Gemma 3 27B-it
export ACCELERATOR_TYPE="v5e" export HF_MODEL_ID="google/gemma-3-27b-it"
Para outras configurações, incluindo outras variantes de modelo e tipos de TPU, consulte os manifestos disponíveis no accelerated-platforms repositório do GitHub.

Baixar o modelo

Extraia as variáveis de ambiente da 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 os recursos de download do modelo do Hugging Face que baixa o modelo para o Cloud Storage:
```
"${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/model-download/configure_huggingface.sh"
```

Aplique os recursos de download do modelo do Hugging Face:

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

Monitore o job de download do modelo do Hugging Face até que ele seja concluído.

until kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} wait job/${HF_MODEL_ID_HASH}-hf-model-to-gcs --for=condition=complete --timeout=10s >/dev/null; do
    clear
    kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e 'Complete'
    echo -e "\nhf-model-to-gcs logs(last 10 lines):"
    kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} logs job/${HF_MODEL_ID_HASH}-hf-model-to-gcs --container=hf-model-to-gcs --tail 10
done

Verifique se o job de download do modelo do Hugging Face foi concluído.

kubectl --namespace=${huggingface_hub_downloader_kubernetes_namespace_name} get job/${HF_MODEL_ID_HASH}-hf-model-to-gcs | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e 'Complete'

Exclua os recursos de download do modelo do Hugging Face.

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

Implantar o modelo

Extraia as variáveis de ambiente da implantação.

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

Verifique se o nome do modelo do Hugging Face está definido.
```
echo "HF_MODEL_NAME=${HF_MODEL_NAME}"
```

Configure os recursos do vLLM.

"${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-tpu/vllm/configure_vllm.sh"

Implante a carga de trabalho de inferência no cluster do GKE.

kubectl apply --kustomize "${ACP_REPO_DIR}/platforms/gke/base/use-cases/inference-ref-arch/kubernetes-manifests/online-inference-tpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"

Testar a implantação

Monitore a implantação da carga de trabalho de inferência até que ela esteja disponível.

until kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} wait deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --for=condition=available --timeout=10s >/dev/null; do
    clear
    kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e '1/1     1            1'
    echo -e "\nfetch-safetensors logs(last 10 lines):"
    kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=fetch-safetensors --tail 10
    echo -e "\ninference-server logs(last 10 lines):"
    kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=inference-server --tail 10
done

Verifique se a implantação da carga de trabalho de inferência está disponível.

kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} | GREP_COLORS='mt=01;92' egrep --color=always -e '^' -e '1/1     1            1'
echo -e "\nfetch-safetensors logs(last 10 lines):"
kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=fetch-safetensors --tail 10
echo -e "\ninference-server logs(last 10 lines):"
kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=inference-server --tail 10

Execute o script a seguir para configurar o encaminhamento de portas e enviar uma solicitação de amostra ao modelo.

kubectl --namespace=${ira_online_tpu_kubernetes_namespace_name} port-forward service/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} 8000:8000 >/dev/null &
PF_PID=$!
while ! echo -e '\x1dclose\x0d' | telnet localhost 8000 >/dev/null 2>&1; do
    sleep 0.1
done
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-tpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"

Limpe os recursos:

Autopilot

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

Padrão

"${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-tpu-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 modelos com a ferramenta de início rápido de inferência do GKE.
Confira o repositório do GitHub accelerated-platforms usado para criar essa arquitetura.

Disponibilizar LLMs abertos no GKE usando TPUs com uma arquitetura pré-configurada Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Verificar os papéis

Conceder os papéis

Receber acesso ao modelo

Provisionar o ambiente de inferência do GKE

Iniciar o Cloud Shell

Implantar a arquitetura base

Autopilot

Padrão

Implantar um modelo aberto

Selecione um modelo

Gemma 3 1B-it

Gemma 3 4B-it

Gemma 3 27B-it

Baixar o modelo

Implantar o modelo

Testar a implantação

Limpar

Autopilot

Padrão

A seguir

Disponibilizar LLMs abertos no GKE usando TPUs com uma arquitetura pré-configurada