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 ed eroghi 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 open source:

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 si fa riferimento nei contenuti di Google Cloud , consulta Ruoli utente e attività comuni di GKE.

Prima di iniziare

Accedi al tuo account Google Cloud . 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.

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

Assicurati di disporre dei seguenti ruoli nel progetto: roles/artifactregistry.admin, roles/browser, roles/compute.networkAdmin, roles/container.clusterAdmin, roles/iam.roleAdmin, roles/iam.serviceAccountAdmin, roles/resourcemanager.projectIamAdmin e roles/serviceusage.serviceUsageAdmin, roles/secretmanager.secretVersionManager
Controlla i ruoli
1. Nella console Google Cloud 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 a quali gruppi appartieni, contatta il tuo 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 console Google Cloud 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 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:

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

Esegui il 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 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:

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

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.
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 tua home directory. Segui le istruzioni dello script per impostare la variabile di ambiente necessaria o passa il flag --modify-rc-file allo script.
```
"${ACP_REPO_DIR}/tools/bin/install_terraform.sh" && \
export PATH=${HOME}/bin:${HOME}/.local/bin:${PATH}
```
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.

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"

Lo script di deployment crea un secret in Secret Manager per archiviare il tuo 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

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

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

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"

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

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'

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

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"

Verifica che sia impostato il nome del modello Hugging Face.
```
echo "HF_MODEL_NAME=${HF_MODEL_NAME}"
```

Configura le risorse vLLM.

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

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

Monitora il deployment del workload 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

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

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.

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

Libera spazio dalle 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 dei modelli 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.

Eroga LLM aperti su GKE utilizzando TPU con un'architettura preconfigurata Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Controlla i ruoli

Concedi i ruoli

Ottenere l'accesso al modello

Esegui il provisioning dell'ambiente di inferenza GKE

Avvia Cloud Shell

Esegui il deployment dell'architettura di base

Autopilot

Standard

Eseguire il deployment di un modello aperto

Seleziona un modello

Gemma 3 1B-it

Gemma 3 4B-it

Gemma 3 27B-it

Scaricare il modello

Esegui il deployment del modello

Testa il deployment

Esegui la pulizia

Autopilot

Standard

Passaggi successivi

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