Eroga LLM aperti su GKE utilizzando TPU con un'architettura preconfigurata

Autopilot Standard

Questa pagina mostra come eseguire rapidamente il deployment e pubblicare modelli linguistici di grandi dimensioni (LLM) open source popolari su GKE con TPU per l'inferenza utilizzando un'architettura di riferimento per l'inferenza di GKE preconfigurata e pronta per la produzione. Questo approccio utilizza Infrastructure as Code (IaC), con Terraform incluso negli script CLI, per creare un ambiente GKE standardizzato, sicuro e scalabile progettato per i carichi di lavoro di inferenza AI.

In questa guida, esegui il deployment e la gestione di LLM utilizzando nodi TPU single-host su GKE con il framework di gestione vLLM. Questa guida fornisce istruzioni e configurazioni per il deployment dei seguenti modelli aperti:

• Google Gemma 3 1B-it
• Google Gemma 3 4B-it
• Google Gemma 3 27B-it

Nota: devi accettare i termini di licenza per tutti i modelli con accesso controllato che vuoi utilizzare (come Gemma) nella rispettiva pagina del modello Hugging Face.

Questa guida è rivolta a ML engineer e specialisti di dati e AI interessati a esplorare le funzionalità di orchestrazione dei container Kubernetes per la gestione di modelli aperti per l'inferenza. Per scoprire di più sui ruoli comuni e sulle attività di esempio a cui viene fatto riferimento nei contenuti di Google Cloud , consulta Ruoli e attività comuni degli utenti GKE.

Prima di iniziare

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 role (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 role (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.

     Vai a IAM
  2. Seleziona il progetto.
  3. Fai clic su Concedi l'accesso.

  4. Nel campo Nuove entità, inserisci il tuo identificatore dell'utente. In genere si tratta dell'indirizzo email di un Account Google.

  5. Nell'elenco Seleziona un ruolo, seleziona un ruolo.
  6. Per concedere altri ruoli, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo successivo.
  7. Fai clic su Salva.
  • Crea un account Hugging Face.
  • Assicurati che il tuo progetto disponga di una quota TPU (GKE Standard) o di una quota TPU (GKE Autopilot) sufficiente. Per ulteriori informazioni, consulta la sezione Pianificare le TPU in GKE.

  Ottenere l'accesso al modello

  Accetta i termini di licenza per tutti i modelli con accesso limitato che vuoi utilizzare (ad esempio Gemma) nella rispettiva pagina del modello Hugging Face.

  Per accedere al modello tramite Hugging Face, è necessario un token Hugging Face.

  Segui questi passaggi per generare un nuovo token se non ne hai già uno:

  1. Fai clic su Il tuo profilo > Impostazioni > Token di accesso.
  2. Seleziona Nuovo token.
  3. Specifica un Nome a tua scelta e un Ruolo con almeno l'autorizzazione Lettura.
  4. Seleziona Genera un token.
  5. Copia il token generato negli appunti.

  Esegui il provisioning dell'ambiente di inferenza GKE

  In questa sezione, esegui il deployment dell'infrastruttura necessaria per pubblicare il modello.

  Avvia Cloud Shell

  Questa guida utilizza Cloud Shell per eseguire i comandi. Cloud Shell viene fornito con gli strumenti necessari preinstallati, tra cui gcloud, kubectl e git.

  Nella console Google Cloud , avvia un'istanza di Cloud Shell:

  Apri Cloud Shell

  Questa azione avvia una sessione nel riquadro inferiore della console Google Cloud .

  Esegui il deployment dell'architettura di base

  Per eseguire il provisioning del cluster GKE e delle risorse necessarie per accedere ai modelli da Hugging Face, segui questi passaggi:

  1. In Cloud Shell, clona il seguente repository:

     git clone https://github.com/GoogleCloudPlatform/accelerated-platforms --branch hf-model-vllm-tpu-tutorial && \
     cd accelerated-platforms && \
     export ACP_REPO_DIR="$(pwd)"
     

  2. Imposta le variabili di ambiente:

     export TF_VAR_platform_default_project_id=PROJECT_ID
     export HF_TOKEN_READ=HF_TOKEN
     

     Sostituisci i seguenti valori:

     • PROJECT_ID: il tuo Google Cloud ID progetto.
     • HF_TOKEN: il token Hugging Face generato in precedenza.

  3. Questa guida richiede Terraform versione 1.8.0 o successive. Cloud Shell ha Terraform v1.5.7 installato per impostazione predefinita.

     Per aggiornare la versione di Terraform in Cloud Shell, puoi eseguire questo script. Questo script installa lo strumento tfswitch e Terraform v1.8.0 nella home directory. Segui le istruzioni dello script per impostare la variabile di ambiente necessaria o trasmetti il flag --modify-rc-file allo script.

     "${ACP_REPO_DIR}/tools/bin/install_terraform.sh" && \
     export PATH=${HOME}/bin:${HOME}/.local/bin:${PATH}
     

  4. Esegui il seguente script di deployment. Lo script di deployment abilita le API Google Cloud richieste e esegue il provisioning dell'infrastruttura necessaria per questa guida. Sono inclusi una nuova rete VPC, un cluster GKE con nodi privati e altre risorse di supporto. Il completamento dello script può richiedere diversi minuti.

     Puoi gestire i modelli utilizzando le TPU in un cluster GKE Autopilot o Standard. Un cluster Autopilot fornisce un'esperienza Kubernetes completamente gestita. Per saperne di più sulla scelta della modalità operativa GKE più adatta ai tuoi workload, consulta Informazioni sulle modalità operative di GKE.

     Autopilot

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

     Standard

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

     Al termine dello script, avrai un cluster GKE pronto per i carichi di lavoro di inferenza.

  5. Esegui questo comando per impostare le variabili di ambiente dalla configurazione condivisa:

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

  6. Lo script di deployment crea un secret in Secret Manager per archiviare il token Hugging Face. Devi aggiungere manualmente il token a questo secret prima di eseguire il deployment del cluster. In Cloud Shell, esegui questo comando per aggiungere il token a 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}
     

  Eseguire il deployment di un modello aperto

  Ora puoi scaricare ed eseguire il deployment del modello.

  Seleziona un modello

  1. Imposta le variabili di ambiente per il modello di cui vuoi eseguire il deployment:

     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"
     

     Per altre configurazioni, tra cui altre varianti di modello e tipi di TPU, consulta i manifest disponibili nel repository GitHub accelerated-platforms.

  Scaricare il modello

  1. Recupera le variabili di ambiente dal deployment. Queste variabili di ambiente contengono i dettagli di configurazione necessari dell'infrastruttura di cui hai eseguito il provisioning.

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

  2. Esegui il seguente script per configurare le risorse di download del modello Hugging Face che scaricano il modello in Cloud Storage:

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

  3. Applica le risorse di download del modello Hugging Face:

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

  4. Monitora il job di download del modello Hugging Face fino al completamento.

     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
     

  5. Verifica che il job di download del modello Hugging Face sia completato.

     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'
     

  6. Elimina le risorse di download del modello Hugging Face.

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

  Esegui il deployment del modello

  1. Recupera le variabili di ambiente dal deployment.

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

  2. Verifica che sia impostato il nome del modello Hugging Face.

     echo "HF_MODEL_NAME=${HF_MODEL_NAME}"
     

  3. Configura le risorse vLLM.

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

  4. Esegui il deployment del carico di lavoro di inferenza nel cluster 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}"
     

  Testa il deployment

  1. Monitora il deployment del carico di lavoro di inferenza finché non è disponibile.

     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
     

  2. Verifica che il deployment del workload di inferenza sia disponibile.

     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
     

  3. Esegui lo script seguente per configurare il port forwarding e inviare una richiesta di esempio al modello.

     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}
     

     Dovresti visualizzare una risposta JSON del modello che risponde alla domanda.

  Esegui la pulizia

  Per evitare addebiti, elimina tutte le risorse che hai creato.

  1. Elimina il workload di inferenza:

     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}"
     

  2. Esegui la pulizia delle risorse:

     Autopilot

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

     Standard

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

  Passaggi successivi

  • Scopri di più sull'inferenza del modello di AI/ML su GKE.
  • Analizza le prestazioni e i costi dell'inferenza del modello con lo strumento GKE Inference Quickstart.
  • Esplora il repository GitHub accelerated-platforms utilizzato per creare questa architettura.