1. Introduzione
I modelli linguistici di grandi dimensioni (LLM) stanno cambiando il modo in cui creiamo applicazioni intelligenti. Tuttavia, preparare questi potenti modelli per l'uso nel mondo reale può essere complicato. Hanno bisogno di molta potenza di calcolo, in particolare schede grafiche (GPU), e di modi intelligenti per gestire molte richieste contemporaneamente. Inoltre, vuoi contenere i costi e far funzionare la tua applicazione senza problemi e ritardi.
Questo codelab ti mostrerà come affrontare queste sfide. Utilizzeremo due strumenti chiave:
- vLLM: consideralo un motore super veloce per gli LLM. Consente di eseguire i modelli in modo molto più efficiente, gestendo più richieste contemporaneamente e riducendo l'utilizzo della memoria.
- Google Cloud Run: questa è la piattaforma serverless di Google. È ideale per il deployment delle applicazioni perché gestisce tutta la scalabilità per te, da zero a migliaia di utenti e viceversa. La cosa migliore è che Cloud Run ora supporta le GPU, essenziali per l'hosting di LLM.
Insieme, vLLM e Cloud Run offrono un modo potente, flessibile ed economicamente vantaggioso per pubblicare i tuoi LLM. In questa guida, eseguirai il deployment di un modello aperto, rendendolo disponibile come API web standard.
Obiettivi didattici
- Come scegliere la dimensione e la variante del modello giuste per la pubblicazione.
- Come configurare vLLM per pubblicare endpoint API compatibili con OpenAI.
- Come containerizzare il server vLLM con Docker.
- Come eseguire il push dell'immagine container in Google Artifact Registry.
- Come eseguire il deployment del container in Cloud Run con l'accelerazione GPU.
- Come testare il modello di cui è stato eseguito il deployment.
Che cosa ti serve
- Un browser, ad esempio Chrome, per accedere alla console Google Cloud
- Una connessione a internet affidabile
- Un progetto Google Cloud con la fatturazione abilitata
- Un token di accesso a Hugging Face (creane uno qui se non lo hai ancora)
- Conoscenza di base di Python, Docker e dell'interfaccia a riga di comando
- Una mente curiosa e la voglia di imparare
2. Prima di iniziare
Configura il progetto Google Cloud
Questo codelab richiede un progetto Google Cloud con un account di fatturazione attivo.
- Per le sessioni guidate dall'insegnante:se ti trovi in un corso, l'insegnante ti fornirà le informazioni necessarie sul progetto e sulla fatturazione. Segui le istruzioni dell'istruttore per completare la configurazione.
- Per gli studenti indipendenti:se stai lavorando in autonomia e non hai un account di fatturazione attivo, dovrai configurarne uno utilizzando i tuoi dati di pagamento. Consulta la documentazione sulla fatturazione Google Cloud per creare un nuovo account di fatturazione e abilitarlo per il tuo progetto.
Crea un progetto Google Cloud
Per mantenere tutto il lavoro per questo codelab organizzato e separato dagli altri progetti, inizierai creando un nuovo progetto Google Cloud.
Per aprire la pagina di creazione del progetto, fai clic su:
Inserisci le informazioni richieste nella pagina di creazione del progetto:
- Nome progetto: puoi inserire il nome che preferisci (ad es. genai-workshop)
- Località: lascia Nessuna organizzazione
- Account di fatturazione: se viene visualizzata questa opzione, seleziona "Account di fatturazione di prova di Google Cloud Platform" o il tuo account di fatturazione, se preferisci. Se non vedi questa opzione, puoi procedere al passaggio successivo.
Copia l'ID progetto generato, ti servirà in un secondo momento. 
Se è tutto a posto, fai clic sul pulsante Crea.
Configurare Cloud Shell
Cloud Shell è un ambiente preconfigurato con tutti gli strumenti necessari per questo codelab. Una volta creato il progetto, segui questi passaggi per configurare Cloud Shell.
Avvia Cloud Shell
Per avviare Cloud Shell, fai clic su:
Se viene visualizzato un popup che richiede l'autorizzazione, fai clic su Autorizza.
Imposta ID progetto
Sostituisci replace-with-your-project-id con l'ID progetto effettivo del passaggio di creazione del progetto riportato sopra. Esegui questo comando nel terminale Cloud Shell per impostare l'ID progetto corretto.
gcloud config set project replace-with-your-project-id
Ora dovresti vedere che nel terminale Cloud Shell è selezionato il progetto corretto. L'ID progetto selezionato è evidenziato in giallo.
Abilita le API necessarie
Per utilizzare i servizi Google Cloud come Cloud Run, devi prima attivare le rispettive API per il tuo progetto. Esegui questi comandi in Cloud Shell per abilitare i servizi necessari per questo Codelab:
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable artifactregistry.googleapis.com
3. Scegliere il modello giusto
Puoi trovare molti modelli open source su siti web come Hugging Face Hub e Kaggle. Quando vuoi utilizzare uno di questi modelli su un servizio come Google Cloud Run, devi sceglierne uno adatto alle risorse che hai a disposizione (ad es. GPU NVIDIA L4).
Oltre alle dimensioni, ricorda di considerare cosa può fare effettivamente il modello. I modelli non sono tutti uguali: ognuno ha i suoi vantaggi e svantaggi. Ad esempio, alcuni modelli possono gestire diversi tipi di input (come immagini e testo, funzionalità multimodali), mentre altri possono memorizzare ed elaborare più informazioni contemporaneamente (il che significa che hanno finestre contestuali più grandi). Spesso, i modelli più grandi hanno funzionalità più avanzate come la chiamata di funzione e il pensiero.
È anche importante verificare se il modello che ti interessa è supportato dallo strumento di pubblicazione (in questo caso vLLM). Puoi controllare tutti i modelli supportati dal vLLM qui.
Ora esploriamo Gemma 3, la nuova famiglia di modelli linguistici di grandi dimensioni (LLM) di Google disponibili pubblicamente. Gemma 3 è disponibile in quattro scale diverse in base alla complessità, misurata in parametri: 1 miliardo, 4 miliardi, 12 miliardi e 27 miliardi.
Per ciascuna di queste dimensioni, troverai due tipi principali:
- Una versione di base (preaddestrata): questo è il modello di base che ha appreso da un'enorme quantità di dati.
- Una versione ottimizzata per le istruzioni: questa versione è stata ulteriormente perfezionata per comprendere e seguire meglio istruzioni o comandi specifici.
I modelli più grandi (4 miliardi, 12 miliardi e 27 miliardi di parametri) sono multimodali, il che significa che possono comprendere e lavorare sia con le immagini che con il testo. La variante più piccola da 1 miliardo di parametri, tuttavia, si concentra esclusivamente sul testo.
Per questo codelab, utilizzeremo 1 miliardo di varianti di Gemma 3: gemma-3-1b-it. L'utilizzo di un modello più piccolo ti aiuta anche a imparare a lavorare con risorse limitate, il che è importante per contenere i costi e garantire che la tua app funzioni senza problemi nel cloud.
4. Variabili di ambiente e secret
Creare un file di ambiente
Prima di procedere, è buona norma avere tutte le configurazioni che utilizzerai in questo codelab in un unico posto. Per iniziare, apri il terminale e segui questi passaggi:
- Crea una nuova cartella per questo progetto.
- Vai alla cartella appena creata.
- Crea un file .env vuoto all'interno di questa cartella (questo file conterrà in seguito le variabili di ambiente)
Ecco il comando per eseguire questi passaggi:
mkdir vllm-gemma3 && cd vllm-gemma3 && cloudshell edit .env
Successivamente, copia le variabili elencate di seguito e incollale nel file.env che hai appena creato.
PROJECT_ID=your_project_id
REGION=your_region
MODEL_PROVIDER=google
MODEL_VARIANT=gemma-3-1b-it
MODEL_NAME=${MODEL_PROVIDER}/${MODEL_VARIANT}
AR_REPO_NAME=vllm-gemma3-repo
SERVICE_NAME=${MODEL_VARIANT}-service
IMAGE_NAME=${REGION}-docker.pkg.dev/${PROJECT_ID}/${AR_REPO_NAME}/${SERVICE_NAME}
SERVICE_ACC_NAME=${SERVICE_NAME}-sa
SERVICE_ACC_EMAIL=${SERVICE_ACC_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
Ricorda di sostituire i valori segnaposto (your_project_id e your_region) con le informazioni specifiche del tuo progetto. Ad esempio, PROJECT_ID=unique-ai-project e REGION=us-central1. Consulta l'elenco delle regioni che supportano le GPU su Cloud Run qui.
Una volta modificato e salvato il file.env, digita questo comando per caricare le variabili di ambiente nella sessione del terminale:
source .env
Puoi verificare se le variabili vengono caricate correttamente o meno eseguendo l'echo di una delle variabili. Ad esempio:
echo $SERVICE_NAME
Se ottieni lo stesso valore che hai assegnato nel file.env, le variabili vengono caricate correttamente.
Archivia un secret in Secret Manager
Per tutti i dati sensibili, inclusi codici di accesso, credenziali e password, l'approccio consigliato è l'utilizzo di un gestore dei secret.
Prima di utilizzare i modelli Gemma 3, devi prima accettare i termini e condizioni, in quanto sono protetti. Puoi accettare i termini e le condizioni tramite la scheda del modello Gamma 3 su Hugging Face Hub.
Una volta ottenuto il token di accesso a Hugging Face, vai alla pagina Secret Manager e crea un secret seguendo queste istruzioni
- Vai alla console Google Cloud
- Seleziona il progetto dalla barra del menu a discesa in alto a sinistra.
- Cerca Secret Manager nella barra di ricerca e fai clic su questa opzione quando viene visualizzata.
Quando ti trovi nella pagina Secret Manager:
- Fai clic sul pulsante +Crea secret.
- Compila queste informazioni:
- Name: HF_TOKEN
- Valore secret: <your_hf_access_token>
- Al termine, fai clic sul pulsante Crea secret.
Ora dovresti avere il token di accesso Hugging Face come secret in Google Cloud Secret Manager.
Puoi testare l'accesso al secret eseguendo il comando riportato di seguito nel terminale, che lo recupererà da Secret Manager:
gcloud secrets versions access latest --secret=HF_TOKEN
Dovresti vedere il token di accesso recuperato e mostrato nella finestra del terminale.
Concedi l'accesso al secret al service account Cloud Build
Poiché il secret ora è archiviato in modo sicuro in Secret Manager,
Per farlo, esegui questi comandi nel terminale:
# Get the project number
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
# Grant Cloud Build access to the Hugging Face Token secret
gcloud secrets add-iam-policy-binding HF_TOKEN \
--member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \
--role="roles/secretmanager.secretAccessor"
5. Crea un account di servizio
Per migliorare la sicurezza e gestire l'accesso in modo efficace in un ambiente di produzione, i servizi devono operare con service account dedicati strettamente limitati alle autorizzazioni necessarie per le loro attività specifiche.
Esegui questo comando per creare un service account
gcloud iam service-accounts create $SERVICE_ACC_NAME --display-name='Cloud Run vLLM Model Serving SA'
Il seguente comando associa l'autorizzazione necessaria
gcloud secrets add-iam-policy-binding HF_TOKEN \
--member="serviceAccount:${SERVICE_ACC_EMAIL}" \
--role="roles/secretmanager.secretAccessor"
6. Crea un'immagine su Artifact Registry
Questo passaggio prevede la creazione di un'immagine Docker che include i pesi del modello e vLLM preinstallato.
1. Crea un repository Docker su Artifact Registry
Creiamo un repository Docker in Artifact Registry per eseguire il push delle immagini create. Esegui questo comando nel terminale:
gcloud artifacts repositories create ${AR_REPO_NAME} \
--repository-format docker \
--location ${REGION}
2. Memorizzazione del modello
In base alla documentazione sulle best practice per le GPU, puoi archiviare i modelli ML all'interno delle immagini container o ottimizzare il caricamento da Cloud Storage.
Naturalmente, ogni approccio presenta pro e contro. Per saperne di più, consulta la documentazione. Per semplicità, archivieremo il modello nell'immagine container. Lo farai nella sessione successiva.
3. Crea un file Docker
Crea un file denominato Dockerfile e copia al suo interno i contenuti riportati di seguito:
FROM vllm/vllm-openai:v0.16.0
ARG MODEL_NAME
ARG HF_TOKEN
ENV HF_HOME=/model-cache
ENV MODEL_NAME=${MODEL_NAME}
# Use the HF_TOKEN argument to log in and download the model
RUN huggingface-cli login --token ${HF_TOKEN} && \
huggingface-cli download ${MODEL_NAME}
# Prevent vLLM from trying to download the model again at runtime
ENV HF_HUB_OFFLINE=1
EXPOSE 8080
ENTRYPOINT python3 -m vllm.entrypoints.openai.api_server \
--port ${PORT:-8080} \
--model ${MODEL_NAME} \
--gpu-memory-utilization 0.90 \
${MAX_MODEL_LEN:+--max-model-len "$MAX_MODEL_LEN"}
4. Crea un file YAML per il deployment
Poi, crea un file denominato cloudbuild.yaml nella stessa directory. Questo file definisce i passaggi che Cloud Build deve seguire. Copia e incolla i seguenti contenuti in cloudbuild.yaml:
steps:
- name: 'gcr.io/cloud-builders/docker'
entrypoint: 'bash'
args:
- '-c'
- |
docker build \
--build-arg MODEL_NAME=${_MODEL_NAME} \
--build-arg HF_TOKEN=$$HF_TOKEN_SECRET \
-t ${_IMAGE_NAME} .
secretEnv: ['HF_TOKEN_SECRET']
images:
- '${_IMAGE_NAME}'
availableSecrets:
secretManager:
- versionName: projects/${PROJECT_ID}/secrets/HF_TOKEN/versions/latest
env: 'HF_TOKEN_SECRET'
5. Invia la build a Cloud Build
Copia e incolla il seguente codice ed eseguilo nel terminale:
gcloud builds submit . \
--config=cloudbuild.yaml \
--region=${REGION} \
--substitutions=_MODEL_NAME=${MODEL_NAME},_IMAGE_NAME=${IMAGE_NAME}
Questo comando carica il codice (Dockerfile e cloudbuild.yaml), passa le variabili della shell come sostituzioni (_MODEL_NAME e _IMAGE_NAME) e avvia la build.
Cloud Build eseguirà ora i passaggi definiti in cloudbuild.yaml. Puoi seguire i log nel terminale o facendo clic sul link ai dettagli della build in Cloud Console. Al termine, l'immagine container sarà disponibile nel repository Artifact Registry, pronta per il deployment.
6. Esegui il deployment in Cloud Run
Ora puoi eseguire il deployment del servizio su Cloud Run. Esegui questo comando nel terminale:
gcloud run deploy ${SERVICE_NAME} \
--image ${IMAGE_NAME} \
--region ${REGION} \
--service-account ${SERVICE_ACC_EMAIL} \
--gpu 1 \
--gpu-type nvidia-l4 \
--cpu 4 \
--memory 16Gi \
--max-instances 3 \
--concurrency 80 \
--no-allow-unauthenticated
7. Testare il servizio
Esegui questo comando nel terminale per creare un proxy, in modo da poter accedere al servizio mentre è in esecuzione in localhost:
gcloud run services proxy ${SERVICE_NAME} --region ${REGION}
In una nuova finestra del terminale, esegui questo comando curl nel terminale per testare la connessione
curl -X POST http://localhost:8080/v1/completions \
-H "Authorization: Bearer $(gcloud auth print-identity-token)" \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemma-3-1b-it",
"prompt": "Cloud Run is a ",
"max_tokens": 128,
"temperature": 0.90
}'
Se vedi un output simile al seguente:
{"id":"cmpl-e96d05d2893d42939c1780d44233defa","object":"text_completion","created":1746870778,"model":"google/gemma-3-1b-it","choices":[{"index":0,"text":"100% managed Kubernetes service. It's a great option for many use cases.\n\nHere's a breakdown of key features and considerations:\n\n* **Managed Kubernetes:** This means Google handles the underlying infrastructure, including scaling, patching, and maintenance. You don't need to worry about managing Kubernetes clusters.\n* **Serverless:** You only pay for the compute time your application actually uses. No charges when your code isn't running.\n* **Scalability:** Cloud Run automatically scales your application based on demand. You can easily scale up or down to handle fluctuating traffic.\n*","logprobs":null,"finish_reason":"length","stop_reason":null,"prompt_logprobs":null}],"usage":{"prompt_tokens":6,"total_tokens":134,"completion_tokens":128,"prompt_tokens_details":null}}
8. Conclusione
Complimenti! Hai completato correttamente questo codelab. Hai imparato a:
- Scegli una dimensione del modello appropriata per un deployment di destinazione.
- Configura vLLM per pubblicare un'API compatibile con OpenAI.
- Containerizza in modo sicuro il server vLLM e i pesi del modello con Docker.
- Esegui il push di un'immagine container in Google Artifact Registry.
- Esegui il deployment di un servizio con accelerazione GPU in Cloud Run.
- Testa un modello autenticato di cui è stato eseguito il deployment.
Continua il tuo percorso di apprendimento esplorando il deployment di altri modelli interessanti come Llama, Mistral o Qwen.
9. Esegui la pulizia
Per evitare addebiti futuri, è importante eliminare le risorse che hai creato. Esegui questi comandi per pulire il progetto.
1. Elimina il servizio Cloud Run:
gcloud run services delete ${SERVICE_NAME} --region=${REGION} --quiet
2. Elimina il repository Artifact Registry:
gcloud artifacts repositories delete ${AR_REPO_NAME} --location=${REGION} --quiet
3. Elimina il service account:
gcloud iam service-accounts delete ${SERVICE_ACC_EMAIL} --quiet
4. Elimina il secret da Secret Manager:
gcloud secrets delete HF_TOKEN --quiet