Gestisci LLM aperti su GKE con un'architettura preconfigurata

Autopilot Standard

Questa pagina mostra come eseguire rapidamente il deployment e la pubblicazione di modelli linguistici di grandi dimensioni (LLM) open source su GKE per l'inferenza utilizzando un'architettura di riferimento per l'inferenza GKE preconfigurata e pronta per la produzione. pronta per la produzione architettura di riferimento per l'inferenza GKE. Questo approccio utilizza Infrastructure as Code (IaC), con Terraform racchiuso in 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 ed eroghi LLM utilizzando nodi GPU a host singolo su GKE con il framework di pubblicazione vLLM. Questa guida fornisce istruzioni e configurazioni per il deployment dei seguenti modelli open source:

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

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

Questa guida è destinata agli ingegneri di machine learning (ML) e agli specialisti di dati e AI interessati a esplorare le funzionalità di orchestrazione dei container Kubernetes per la pubblicazione di modelli open source per l'inferenza. Per scoprire di più sui ruoli comuni e sulle attività di esempio a cui si fa riferimento nel Google Cloud contenuto, consulta Ruoli e attività utente GKE comuni.

Per un'analisi dettagliata delle prestazioni e dei costi di erogazione del modello per questi modelli open source, puoi anche utilizzare lo strumento GKE Inference Quickstart. Per saperne di più, consulta la guida rapida di inferenza GKE e il notebook di Colab di accompagnamento.

Prima di iniziare

Accedi al tuo Google Cloud account. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

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

• Assicurati di avere il seguente ruolo o i seguenti ruoli nel progetto: 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

  Controlla i ruoli

  1. Nella Google Cloud console vai alla pagina IAM.

     Vai a IAM
  2. Seleziona il progetto.

  3. Nella colonna Entità, trova tutte le righe che identificano te o un gruppo di cui fai parte. Per scoprire i gruppi di cui fai parte, contatta l' amministratore.

  4. Per tutte le righe che ti specificano o ti includono, controlla la colonna Ruolo per verificare se l'elenco dei ruoli include i ruoli richiesti.

  Concedi i ruoli

  1. Nella Google Cloud console vai alla pagina IAM.

     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. Fai clic su Seleziona un ruolo, quindi cerca il 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 abbia una quota GPU sufficiente GPU. Per saperne di più, consulta Quote di allocazione.

Accedi al modello

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

Per accedere al modello tramite Hugging Face, devi avere 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 di almeno Lettura.
4. Seleziona Genera un token.
5. Copia il token generato negli appunti.

Provisioning dell'ambiente di inferenza GKE

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

Avvia Cloud Shell

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

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

Apri Cloud Shell

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

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-gpu-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 che hai 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 il seguente script. Questo script installa lo tfswitch strumento e Terraform v1.8.0 nella tua home directory. Segui le istruzioni dello script per impostare la variabile di ambiente necessaria o passare 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 lo script di deployment seguente. 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 alcuni minuti.

   Puoi erogare 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 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 il comando seguente 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. Prima di eseguire il deployment del cluster, devi aggiungere manualmente il token a questo secret. 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 open source

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 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 accelerated-platforms repository GitHub.

Scarica 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 lo script seguente per configurare le risorse di download del modello Hugging Face 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"
   

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 il nome del modello Hugging Face sia impostato.

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

Verifica il deployment

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

   until kubectl --namespace=${ira_online_gpu_kubernetes_namespace_name} wait deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --for=condition=available --timeout=10s >/dev/null; do
       clear
       kubectl --namespace=${ira_online_gpu_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_gpu_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_gpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=inference-server --tail 10
   done
   

1. Verifica che il deployment del carico di lavoro di inferenza sia disponibile.

   kubectl --namespace=${ira_online_gpu_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_gpu_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_gpu_kubernetes_namespace_name} logs deployment/vllm-${ACCELERATOR_TYPE}-${HF_MODEL_NAME} --container=inference-server --tail 10
   

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

   kubectl --namespace=${ira_online_gpu_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 in formato JSON del modello che risponde alla domanda.

Libera spazio

Per evitare che ti vengano addebitati dei costi, elimina tutte le risorse che hai creato.

1. Elimina il carico di lavoro 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. Libera spazio dalle risorse:

   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ù su l'inferenza dei modelli di AI/ML su GKE.
• Analizza le prestazioni e i costi dell'inferenza dei modelli con lo strumento GKE Inference Quickstart.
• Esplora il repository GitHub accelerated-platforms utilizzato per creare questa architettura.