Questo tutorial mostra come eseguire il deployment e l'hosting di un modello linguistico di grandi dimensioni (LLM) Gemma 3 utilizzando le GPU su Google Kubernetes Engine (GKE) con il framework di gestione vLLM. Questo fornisce una base per comprendere ed esplorare il deployment pratico di LLM per l'inferenza in un ambiente Kubernetes gestito. Esegui il deployment di un container predefinito che esegue vLLM su GKE. Configura anche GKE per caricare i pesi di Gemma 1B, 4B, 12B e 27B da Hugging Face.
Questo tutorial è destinato a ingegneri di machine learning (ML), amministratori e operatori di piattaforme e specialisti di dati e AI interessati a utilizzare le funzionalità di orchestrazione dei container Kubernetes per la gestione dei carichi di lavoro di AI/ML su hardware GPU H200, H100, A100 e L4. Per scoprire di più sui ruoli comuni e sulle attività di esempio a cui facciamo riferimento nei contenuti, consulta Ruoli e attività comuni degli utenti di GKE Enterprise. Google Cloud
Se hai bisogno di una piattaforma di AI gestita e unificata progettata per creare e pubblicare rapidamente modelli ML in modo economicamente vantaggioso, ti consigliamo di provare la nostra soluzione di deployment Vertex AI.
Prima di leggere questa pagina, assicurati di avere familiarità con quanto segue:
Sfondo
Questa sezione descrive le tecnologie chiave utilizzate in questa guida.
Gemma
Gemma è un insieme di modelli multimodali di intelligenza artificiale (AI) generativa, leggeri e disponibili pubblicamente, rilasciati con una licenza aperta. Questi modelli di AI sono disponibili per l'esecuzione nelle tue applicazioni, hardware, dispositivi mobili o servizi ospitati. Gemma 3 introduce la multimodalità e supporta l'input di visione-linguaggio e gli output di testo. Gestisce finestre contestuali fino a 128.000 token e supporta oltre 140 lingue. Gemma 3 offre anche funzionalità migliorate per matematica, ragionamento e chat, tra cui output strutturati e chiamate di funzioni.
Puoi utilizzare i modelli Gemma per la generazione di testo oppure puoi anche ottimizzarli per attività specializzate.
Per saperne di più, consulta la documentazione di Gemma.
GPU
Le GPU ti consentono di accelerare carichi di lavoro specifici in esecuzione sui tuoi nodi, come machine learning ed elaborazione di dati. GKE offre una gamma di opzioni di tipo di macchina per la configurazione dei nodi, inclusi i tipi di macchine con GPU NVIDIA H200, H100, L4 e A100.
vLLM
vLLM è un framework di gestione degli LLM open source altamente ottimizzato che può aumentare la velocità effettiva di gestione sulle GPU, con funzionalità come le seguenti:
- Implementazione ottimizzata di Transformer con PagedAttention
- Batch continuo per migliorare la velocità effettiva complessiva della pubblicazione
- Parallelismo dei tensori e pubblicazione distribuita su più GPU
Per saperne di più, consulta la documentazione di vLLM.
Obiettivi
- Prepara l'ambiente con un cluster GKE in modalità Autopilot o Standard.
- Esegui il deployment di un container vLLM nel tuo cluster.
- Utilizza vLLM per distribuire il modello Gemma 3 tramite curl e un'interfaccia di chat web.
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.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the required API.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the required API.
-
Make sure that you have the following role or roles on the project: roles/container.admin, roles/iam.serviceAccountAdmin
Check for the roles
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
-
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.
- 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
-
In the Google Cloud console, go to the IAM page.
Vai a IAM - Seleziona il progetto.
- Fai clic su Concedi l'accesso.
-
Nel campo Nuove entità, inserisci il tuo identificatore utente. In genere si tratta dell'indirizzo email di un Account Google.
- Nell'elenco Seleziona un ruolo, seleziona un ruolo.
- Per concedere altri ruoli, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo aggiuntivo.
- Fai clic su Salva.
-
- Crea un account Hugging Face, se non ne hai già uno.
- Assicurati che il tuo progetto disponga di una quota sufficiente per le GPU L4. Per ulteriori informazioni, consulta Informazioni sulle GPU e Quote di allocazione.
Ottenere l'accesso al modello
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 di almeno
Read. - Seleziona Genera un token.
- Copia il token generato negli appunti.
prepara l'ambiente
In questo tutorial utilizzerai Cloud Shell per gestire le risorse ospitate su
Google Cloud. Cloud Shell include il software necessario
per questo tutorial, tra cui
kubectl e
gcloud CLI.
Per configurare l'ambiente con Cloud Shell:
Nella console Google Cloud , avvia una sessione di Cloud Shell facendo clic su
Attiva Cloud Shell nella consoleGoogle Cloud . Viene avviata una sessione nel riquadro inferiore della console Google Cloud .Imposta le variabili di ambiente predefinite:
gcloud config set project PROJECT_ID gcloud config set billing/quota_project PROJECT_ID export PROJECT_ID=$(gcloud config get project) export REGION=REGION export CLUSTER_NAME=CLUSTER_NAME export HF_TOKEN=HF_TOKENSostituisci i seguenti valori:
PROJECT_ID: il tuo Google Cloud ID progetto.REGION: una regione che supporta il tipo di acceleratore che vuoi utilizzare, ad esempious-central1per la GPU L4.CLUSTER_NAME: il nome del tuo cluster.HF_TOKEN: il token Hugging Face che hai generato in precedenza.
Creare e configurare risorse Google Cloud
Segui queste istruzioni per creare le risorse richieste.
Crea un cluster GKE e un pool di nodi
Puoi gestire Gemma su GPU in un cluster GKE Autopilot o Standard. Ti consigliamo di utilizzare un cluster Autopilot per un'esperienza Kubernetes completamente gestita. Per scegliere la modalità operativa GKE più adatta ai tuoi carichi di lavoro, consulta Scegliere una modalità operativa GKE.
Autopilot
In Cloud Shell, esegui questo comando:
gcloud container clusters create-auto CLUSTER_NAME \
--project=PROJECT_ID \
--region=REGION \
--release-channel=rapid
Sostituisci i seguenti valori:
PROJECT_ID: il tuo Google Cloud ID progetto.REGION: una regione che supporta il tipo di acceleratore che vuoi utilizzare, ad esempious-central1per la GPU L4.CLUSTER_NAME: il nome del tuo cluster.
GKE crea un cluster Autopilot con nodi CPU e GPU come richiesto dai carichi di lavoro di cui è stato eseguito il deployment.
Standard
In Cloud Shell, esegui questo comando per creare un cluster Standard:
gcloud container clusters create CLUSTER_NAME \ --project=PROJECT_ID \ --region=REGION \ --workload-pool=PROJECT_ID.svc.id.goog \ --release-channel=rapid \ --num-nodes=1Sostituisci i seguenti valori:
PROJECT_ID: il tuo Google Cloud ID progetto.REGION: una regione che supporta il tipo di acceleratore che vuoi utilizzare, ad esempious-central1per la GPU L4.CLUSTER_NAME: il nome del tuo cluster.
La creazione del cluster potrebbe richiedere diversi minuti.
Per creare un node pool per il tuo cluster con le dimensioni del disco appropriate, esegui questo comando:
Gemma 3 1B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-8 \ --num-nodes=1GKE crea un singolo pool di nodi contenente una GPU L4 per ogni nodo.
Gemma 3 4B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-8 \ --num-nodes=1GKE crea un singolo pool di nodi contenente una GPU L4 per ogni nodo.
Gemma 3 12B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-l4,count=4,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=g2-standard-48 \ --num-nodes=1GKE crea un singolo pool di nodi contenente quattro GPU L4 per ogni nodo.
Gemma 3 27B
gcloud container node-pools create gpupool \ --accelerator type=nvidia-a100-80gb,count=1,gpu-driver-version=latest \ --project=PROJECT_ID \ --location=REGION \ --node-locations=REGION-a \ --cluster=CLUSTER_NAME \ --machine-type=a2-ultragpu-1g \ --disk-type=pd-ssd \ --num-nodes=1 \ --disk-size=256GKE crea un singolo pool di nodi contenente una GPU A100 da 80 GB.
Crea un secret Kubernetes per le credenziali di Hugging Face
In Cloud Shell:
Configura
kubectlin modo che possa comunicare con il tuo cluster:gcloud container clusters get-credentials CLUSTER_NAME \ --location=REGIONSostituisci i seguenti valori:
REGION: una regione che supporta il tipo di acceleratore che vuoi utilizzare, ad esempious-central1per la GPU L4.CLUSTER_NAME: il nome del tuo cluster.
Crea un secret di Kubernetes che contenga il token Hugging Face:
kubectl create secret generic hf-secret \ --from-literal=hf_api_token=${HF_TOKEN} \ --dry-run=client -o yaml | kubectl apply -f -Sostituisci
HF_TOKENcon il token Hugging Face che hai generato in precedenza.
Esegui il deployment di vLLM
In questa sezione, esegui il deployment del container vLLM per pubblicare il modello Gemma che vuoi utilizzare. Per eseguire il deployment del modello, questo tutorial utilizza i deployment Kubernetes. Un deployment è un oggetto API Kubernetes che consente di eseguire più repliche di pod distribuite tra i nodi di un cluster.
Gemma 3 1B-it
Segui queste istruzioni per eseguire il deployment del modello Gemma 3 1B ottimizzato per le istruzioni (input solo di testo).
Crea il seguente manifest
vllm-3-1b-it.yaml:Applica il manifest:
kubectl apply -f vllm-3-1b-it.yaml
Gemma 3 4B-it
Segui queste istruzioni per eseguire il deployment del modello Gemma 3 4B ottimizzato per le istruzioni.
Crea il seguente manifest
vllm-3-4b-it.yaml:Applica il manifest:
kubectl apply -f vllm-3-4b-it.yamlNel nostro esempio, limitiamo la finestra contestuale a 32 K utilizzando l'opzione vLLM
--max-model-len=32768. Se vuoi una dimensione della finestra contestuale più grande (fino a 128 K), modifica il manifest e la configurazione del pool di nodi con una maggiore capacità della GPU.
Gemma 3 12B-it
Segui queste istruzioni per eseguire il deployment del modello Gemma 3 12B ottimizzato per le istruzioni.
Crea il seguente manifest
vllm-3-12b-it.yaml:Applica il manifest:
kubectl apply -f vllm-3-12b-it.yamlNel nostro esempio, limitiamo la dimensione della finestra contestuale a 16 K utilizzando l'opzione vLLM
--max-model-len=16384. Se vuoi una dimensione della finestra contestuale più grande (fino a 128 K), modifica la configurazione del manifest e del pool di nodi con una maggiore capacità della GPU.
Gemma 3 27B-it
Segui queste istruzioni per eseguire il deployment del modello Gemma 3 27B ottimizzato per le istruzioni.
Crea il seguente manifest
vllm-3-27b-it.yaml:Applica il manifest:
kubectl apply -f vllm-3-27b-it.yamlNel nostro esempio, limitiamo le dimensioni della finestra contestuale a 32 K utilizzando l'opzione vLLM
--max-model-len=32768. Se vuoi una finestra contestuale più grande (fino a 128.000), modifica il manifest e la configurazione del pool di nodi con una maggiore capacità della GPU.
Un pod nel cluster scarica i pesi del modello da Hugging Face e avvia il motore di pubblicazione.
Attendi che il deployment sia disponibile:
kubectl wait --for=condition=Available --timeout=1800s deployment/vllm-gemma-deployment
Visualizza i log del deployment in esecuzione:
kubectl logs -f -l app=gemma-server
La risorsa Deployment scarica i dati del modello. Questo processo può richiedere alcuni minuti. L'output è simile al seguente:
INFO: Automatically detected platform cuda.
...
INFO [launcher.py:34] Route: /v1/chat/completions, Methods: POST
...
INFO: Started server process [13]
INFO: Waiting for application startup.
INFO: Application startup complete.
Default STARTUP TCP probe succeeded after 1 attempt for container "vllm--google--gemma-3-4b-it-1" on port 8080.
Assicurati che il modello sia stato scaricato completamente prima di procedere alla sezione successiva.
Pubblica il modello
In questa sezione, interagisci con il modello.
Configurare il port forwarding
Esegui questo comando per configurare il port forwarding al modello:
kubectl port-forward service/llm-service 8000:8000
L'output è simile al seguente:
Forwarding from 127.0.0.1:8000 -> 8000
Interagisci con il modello utilizzando curl
Questa sezione mostra come eseguire un test di base per verificare i modelli Gemma 3 ottimizzati per le istruzioni che hai implementato.
Per gli altri modelli, sostituisci gemma-3-4b-it con il nome del modello corrispondente.
Questo esempio mostra come testare il modello Gemma 3 4B ottimizzato per le istruzioni con input di solo testo.
In una nuova sessione del terminale, utilizza curl per chattare con il tuo modello:
curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemma-3-4b-it",
"messages": [
{
"role": "user",
"content": "Why is the sky blue?"
}
]
}'
L'output è simile al seguente:
{
"id": "chatcmpl-e4a2e624bea849d9b09f838a571c4d9e",
"object": "chat.completion",
"created": 1741763029,
"model": "google/gemma-3-4b-it",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"reasoning_content": null,
"content": "Okay, let's break down why the sky appears blue! It's a fascinating phenomenon rooted in physics, specifically something called **Rayleigh scattering**. Here's the explanation: ...",
"tool_calls": []
},
"logprobs": null,
"finish_reason": "stop",
"stop_reason": 106
}
],
"usage": {
"prompt_tokens": 15,
"total_tokens": 668,
"completion_tokens": 653,
"prompt_tokens_details": null
},
"prompt_logprobs": null
}
(Facoltativo) Interagisci con il modello tramite un'interfaccia di chat Gradio
In questa sezione, creerai un'applicazione di chat web che ti consente di interagire con il modello ottimizzato per le istruzioni. Per semplicità, questa sezione descrive solo l'approccio di test utilizzando il modello 4B-it.
Gradio è una libreria Python che ha un wrapper ChatInterface che crea interfacce utente per chatbot.
Implementare l'interfaccia di chat
In Cloud Shell, salva il seguente manifest come
gradio.yaml. Modificagoogle/gemma-2-9b-itingoogle/gemma-3-4b-ito in un altro nome del modello Gemma 3 che hai utilizzato nel deployment.Applica il manifest:
kubectl apply -f gradio.yamlAttendi che il deployment sia disponibile:
kubectl wait --for=condition=Available --timeout=900s deployment/gradio
Utilizzare l'interfaccia di chat
In Cloud Shell, esegui questo comando:
kubectl port-forward service/gradio 8080:8080In questo modo viene creato un port forwarding da Cloud Shell al servizio Gradio.
Fai clic sul pulsante
Anteprima web, che si trova in alto a destra nella barra delle app di Cloud Shell. Fai clic su Anteprima sulla porta 8080. Nel browser si apre una nuova scheda.Interagisci con Gemma utilizzando l'interfaccia di chat di Gradio. Aggiungi un prompt e fai clic su Invia.
Risoluzione dei problemi
- Se visualizzi il messaggio
Empty reply from server, è possibile che il container non abbia completato il download dei dati del modello. Controlla di nuovo i log del pod per il messaggioConnectedche indica che il modello è pronto per essere pubblicato. - Se visualizzi
Connection refused, verifica che il port forwarding sia attivo.
Osserva le prestazioni del modello
Per osservare le prestazioni del modello, puoi utilizzare l'integrazione della dashboard vLLM in Cloud Monitoring. Con questa dashboard puoi visualizzare metriche sul rendimento critiche come il throughput dei token, la latenza delle richieste e i tassi di errore.
Per utilizzare la dashboard vLLM, devi abilitare Google Cloud Managed Service per Prometheus, che raccoglie le metriche da vLLM, nel tuo cluster GKE. vLLM espone le metriche nel formato Prometheus per impostazione predefinita; non è necessario installare un esportatore aggiuntivo.
Puoi quindi visualizzare le metriche utilizzando la dashboard vLLM. Per informazioni sull'utilizzo di Google Cloud Managed Service per Prometheus per raccogliere metriche dal tuo modello, consulta le indicazioni sull'osservabilità di vLLM nella documentazione di Cloud Monitoring.Esegui la pulizia
Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.
Elimina le risorse di cui è stato eseguito il deployment
Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse che hai creato in questa guida, esegui questo comando:
gcloud container clusters delete CLUSTER_NAME \
--region=REGION
Sostituisci i seguenti valori:
REGION: una regione che supporta il tipo di acceleratore che vuoi utilizzare, ad esempious-central1per la GPU L4.CLUSTER_NAME: il nome del tuo cluster.
Passaggi successivi
- Scopri di più sulle GPU in GKE.
- Scopri come utilizzare Gemma con vLLM su altri acceleratori, tra cui le GPU A100 e H100, visualizzando il codice campione in GitHub.
- Scopri come eseguire il deployment dei carichi di lavoro GPU in Autopilot.
- Scopri come eseguire il deployment dei carichi di lavoro delle GPU in Standard.
- Esplora il repository GitHub e la documentazione di vLLM.
- Esplora Vertex AI Model Garden.
- Scopri come eseguire carichi di lavoro di AI/ML ottimizzati con le funzionalità di orchestrazione della piattaforma GKE.