Gestisci LLM aperti su GKE con un'architettura preconfigurata

Autopilot Standard

---

Questa pagina mostra come eseguire rapidamente il deployment e l'hosting di modelli linguistici di grandi dimensioni (LLM) open source popolari su GKE per l'inferenza utilizzando un'architettura di riferimento 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 GPU a host singolo su GKE con il framework di gestione vLLM. Questa guida fornisce istruzioni e configurazioni per il deployment dei seguenti modelli aperti:

• Google Gemma 3 27B-it
• Meta Llama 4 Scout 17B-16E-Instruct
• Qwen3 32-B
• OpenAI gpt-oss-20b

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 utente e attività comuni di 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.

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.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

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.

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 aggiuntivo.
  7. Fai clic su Salva.
  • Crea un account Hugging Face.
  • Assicurati che il tuo progetto disponga di una quota GPU sufficiente. Per ulteriori informazioni, consulta Quote di allocazione.

  Ottenere l'accesso al modello

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

  Per accedere al modello tramite Hugging Face, devi disporre di 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 di Hugging Face, segui questi passaggi:

  1. In Cloud Shell, clona il seguente repository:

     git clone https://github.com/GoogleCloudPlatform/accelerated-platforms --branch hf-model-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 terraform-switcher e apporta modifiche all'ambiente shell.

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

  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 GPU in un cluster GKE Autopilot o Standard. Un cluster Autopilot offre 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-gpu-model/deploy-ap.sh"
     

     Standard

     "${ACP_REPO_DIR}/platforms/gke/base/tutorials/hf-gpu-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}
     

  Esegui il deployment di un modello aperto

  Ora puoi scaricare ed eseguire il deployment del modello.

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

     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"
     

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

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

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

  3. Esegui lo script seguente per configurare il job Kubernetes che scarica il modello in Cloud Storage:

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

  4. Esegui il deployment del job di download del modello:

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

  5. Attendi il completamento del download. Monitora lo stato del job e quando COMPLETIONS è 1/1, premi Ctrl+C per uscire.

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

  Testare il deployment

  1. Attendi che il pod del server di inferenza sia pronto. Quando la colonna READY è 1/1, premi Ctrl+C per uscire.

     watch --color --interval 5 --no-title "kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} get deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
     

  2. Esegui lo script seguente per configurare il port forwarding e inviare una richiesta di esempio al modello. Questo esempio utilizza il formato del payload per un modello 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}
     

     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-gpu/vllm/${ACCELERATOR_TYPE}-${HF_MODEL_NAME}"
     

  2. Rimuovi il cluster GKE di base:

     Autopilot

     "${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"
     

  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 altri casi d'uso e pattern su GitHub basati su questa architettura.