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: pensa a questo modello come a un motore super veloce per i LLM. In questo modo i modelli vengono eseguiti 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 utenti a migliaia 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.
Cosa imparerai**:**
- 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)
- Familiarità di base con Python, Docker e l'interfaccia a riga di comando
- Una mente curiosa e la voglia di imparare
2. Prima di iniziare
Configurare 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 una classe, l'insegnante ti fornirà le informazioni necessarie sul progetto e sulla fatturazione. Segui le istruzioni dell'istruttore per completare la configurazione.
- Per chi studia in autonomia:se lo fai da solo, dovrai configurare un nuovo progetto e attivare un account di fatturazione di prova. Per iniziare, segui i passaggi riportati di seguito.
- Apri una finestra di navigazione in incognito premendo Ctrl + Maiusc + N o Cmd + Maiusc + N.
- Vai a questo portale di riscatto dalla finestra di navigazione in incognito
- Accedi e ottieni un account di fatturazione di prova con il tuo account Gmail personale
- Segui le istruzioni riportate in questo deck per completare la configurazione.
Configurare Cloud Shell
Ora configuriamo Cloud Shell, una pratica interfaccia a riga di comando direttamente nella console Google Cloud.
Avvia Cloud Shell
Nell'angolo in alto a destra della console Google Cloud, vedrai un'icona a forma di terminale (>_). Fai clic per attivare Cloud Shell.
Autorizza accesso
Se richiesto, fai clic su Autorizza per concedere a Cloud Shell le autorizzazioni necessarie per interagire con il tuo progetto Google Cloud.
Verifica l'ID progetto
Guarda Project ID nel terminale. Sarà scritto in giallo, come mostrato nell'immagine di seguito. Assicurati che sia lo stesso ID che hai registrato quando hai creato il progetto.
Se Project ID viene visualizzato correttamente nel terminale, vai al passaggio Abilita le API necessarie.
ID progetto corretto (se necessario)
Se Project ID è errato o non viene visualizzato, utilizza questo comando per correggerlo. Assicurati di sostituire il testo your-project-id con il tuo Project ID corretto prima di eseguire il comando.
gcloud config set project your-project-id
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 ricordare 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 diverse scale 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, è consigliabile 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
touch .env
Successivamente, copia le variabili elencate di seguito e incollale nel file.env che hai appena creato. 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)
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
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 ricevi 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. Vai alla scheda del modello Gamma3 sull'hub di Hugging Face e accetta i termini e le condizioni.
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 dal 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.
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.
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.9.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}
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. Creare un file cloudbuild.yaml
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 nella console Cloud. Al termine, l'immagine container sarà disponibile nel repository Artifact Registry, pronta per il deployment.
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 e sottoposto a deployment.
Continua il tuo percorso di apprendimento esplorando 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