Esegui agenti con i modelli Gemma 4 su Cloud Run

Questa guida descrive come eseguire il deployment dei modelli open Gemma 4 su Cloud Run utilizzando un container precompilato con la libreria di inferenza vLLM e fornisce indicazioni sull'utilizzo del servizio Cloud Run di cui è stato eseguito il deployment con gli agenti AI creati utilizzando Agent Development Kit.

Gemma 4 è la famiglia di modelli open-weight più efficiente di Google, che offre solide funzionalità di ragionamento e agentiche.

Il contesto lungo, la multimodalità, il ragionamento e la chiamata di strumenti consentono a Gemma 4 di gestire logiche complesse, pianificazione in più passaggi, programmazione e workflow agentici.

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 carichi di lavoro.

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.

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.

1. Configura l'ambiente di sviluppo di Cloud Run nel tuo Google Cloud progetto.
2. Installa e inizializza gcloud CLI.
3. Assicurati di aver concesso i seguenti ruoli IAM al tuo account:
   • Cloud Run Admin (roles/run.admin)
   • Project IAM Admin (roles/resourcemanager.projectIamAdmin)
   • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

Scopri come concedere i ruoli

Console

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 utilizzato per eseguire il deployment del servizio Cloud Run.

5. Nell'elenco Seleziona un ruolo, seleziona un ruolo.
6. Per concedere altri ruoli, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo successivo.
7. Fai clic su Salva.

gcloud

Per concedere i ruoli IAM richiesti al tuo account nel tuo progetto:

        gcloud projects add-iam-policy-binding PROJECT_ID \
            --member=PRINCIPAL \
            --role=ROLE
        

Sostituisci:

• PROJECT_NUMBER con il numero del tuo Google Cloud progetto
• PROJECT_ID con l'ID del tuo Google Cloud progetto.
• PRINCIPAL con l'account a cui stai aggiungendo l' associazione. In genere si tratta dell'indirizzo email che è utilizzato per eseguire il deployment del servizio Cloud Run.
• ROLE con il ruolo che stai aggiungendo all'account del deployer.
4. Per impostazione predefinita, ai nuovi progetti viene concessa automaticamente una quota di 3000 milliGPU al momento del deployment iniziale. Se hai bisogno di una quota aggiuntiva, richiedi la quota Total Nvidia RTX Pro 6000 GPU allocation, in milli GPU, without zonal redundancy, per project per region nell'API Cloud Run Admin nella pagina Quote e limiti di sistema.
5. Consulta la pagina dei prezzi di Cloud Run. Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi.

Esegui il deployment di un modello Gemma 4 con un container vLLM

Gemma 4 offre funzionalità agentiche avanzate, tra cui ragionamento, chiamata di funzioni, generazione di codice e output strutturato.

Agent Development Kit (ADK) ti aiuta a creare agenti AI completamente funzionali con Gemma 4.

Utilizza vLLM per erogare Gemma come endpoint API OpenAI. vLLM fornisce un'erogazione rapida ed efficiente per i modelli generativi su larga scala, con un throughput di erogazione allo stato dell'arte, una gestione efficiente della memoria con PagedAttention, batching continuo delle richieste in entrata, supporto della quantizzazione e kernel CUDA ottimizzati.

Nota: Gemma 4 26B e 31B richiedono una configurazione più avanzata di Cloud Run e vLLM con traffico in uscita VPC diretto e Run:ai Model Streamer.

Per eseguire il deployment dei modelli Gemma su Cloud Run, utilizza il seguente comando gcloud CLI con le impostazioni consigliate:

CONTAINER_ARGS=(
    "serve"
    "MODEL_NAME"
    "--enable-chunked-prefill"
    "--enable-prefix-caching"
    "--generation-config=auto"
    "--enable-auto-tool-choice"
    "--tool-call-parser=gemma4"
    "--reasoning-parser=gemma4"
    "--dtype=bfloat16"
    "--max-num-seqs=64"
    "--gpu-memory-utilization=0.95"
    "--tensor-parallel-size=1"
    "--port=8080"
    "--host=0.0.0.0"
)
gcloud beta run deploy SERVICE_NAME \
    --image "us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4" \
    --project PROJECT \
    --region REGION \
    --execution-environment gen2 \
    --no-allow-unauthenticated \
    --cpu 20 \
    --memory 80Gi \
    --gpu 1 \
    --gpu-type nvidia-rtx-pro-6000 \
    --no-gpu-zonal-redundancy \
    --no-cpu-throttling \
    --max-instances 3 \
    --concurrency 64 \
    --timeout 600 \
    --startup-probe tcpSocket.port=8080,initialDelaySeconds=240,failureThreshold=1,timeoutSeconds=240,periodSeconds=240 \
    --command "vllm" \
    --args=$(IFS=','; echo "${CONTAINER_ARGS[*]}")

Sostituisci:

• SERVICE_NAME con un nome univoco per il servizio Cloud Run.
• PROJECT con l'ID del tuo Google Cloud progetto.

• REGION con una Google Cloud regione in cui le GPU nvidia-rtx-pro-6000 sono supportate per Cloud Run, ad esempio us-central1. Per un elenco completo delle regioni supportate per i deployment con GPU, consulta Configurazione GPU.

• MODEL_NAME con il nome completo di una variante di Gemma 4.

  • Gemma 4 2B: google/gemma-4-E2B-it
  • Gemma 4 4B: google/gemma-4-E4B-it

Le altre impostazioni sono le seguenti:

Opzione	Descrizione
--concurrency	Il numero massimo di richieste che possono essere elaborate contemporaneamente da una determinata istanza, ad esempio 8. Per suggerimenti sulla latenza ottimale delle richieste, consulta Imposta la concorrenza per prestazioni ottimali.
--cpu	La quantità di CPU allocata per il servizio, ad esempio 20.
--set-env-vars	Le variabili di ambiente impostate per il servizio. Ad esempio, HF_TOKEN="..."
--gpu	Il valore della GPU per il servizio, ad esempio 1.
--gpu-type	Il tipo di GPU da utilizzare per il servizio, ad esempio nvidia-rtx-pro-6000.
--max-instances	Il numero massimo di istanze di container per il servizio, ad esempio 1.
--memory	La quantità di memoria allocata per il servizio, ad esempio 80Gi.
--no-invoker-iam-check	Disattiva i controlli IAM dell'invoker. Per suggerimenti su come proteggere meglio l'app, consulta il tutorial Proteggi i servizi Cloud Run.
--no-cpu-throttling	Questa impostazione disattiva la limitazione della CPU quando il container non gestisce attivamente le richieste.
--timeout	Il tempo entro il quale deve essere restituita una risposta, ad esempio 600 secondi.
--startup-probe	Impostazioni separate da virgola per il probe di avvio nel formato KEY=VALUE. Per maggiori dettagli, consulta Probe di avvio di Cloud Run. Con le dimensioni dei modelli di Gemma 4, se non utilizzi il traffico in uscita VPC diretto Direct VPC Egress, ti consigliamo di impostare il timeout del probe di avvio su almeno 240 secondi.

Se devi modificare le impostazioni predefinite o aggiungere impostazioni più personalizzate al servizio Cloud Run, consulta Configura i servizi.

Al termine del servizio di cui è stato eseguito il deployment, viene visualizzato un messaggio di operazione riuscita insieme all' URL dell'endpoint Cloud Run che termina con run.app.

Testa il servizio Gemma di cui è stato eseguito il deployment con curl

Ora che hai eseguito il deployment del servizio Gemma, puoi inviargli richieste. Tuttavia, se invii una richiesta direttamente, Cloud Run risponde con HTTP 401 Unauthorized. Questo è intenzionale, perché un'API di inferenza LLM è destinata ad altri servizi da chiamare, ad esempio un'applicazione frontend. Per ulteriori informazioni sull'autenticazione da servizio a servizio su Cloud Run, consulta Autenticazione da servizio a servizio.

Per inviare richieste al servizio Gemma, aggiungi un'intestazione con un token OIDC valido alle richieste, ad esempio utilizzando il proxy per sviluppatori di Cloud Run:

1. Avvia il proxy e, quando ti viene chiesto di installare il componente cloud-run-proxy, scegli Y:

   gcloud run services proxy SERVICE_NAME \
     --project PROJECT \
     --region REGION \
     --port=9090

2. Esegui il seguente comando per inviare una richiesta in una scheda del terminale separata, lasciando in esecuzione il proxy. Il proxy viene eseguito su localhost:9090. Specifica il modello Gemma che hai utilizzato in precedenza:

   curl http://localhost:9090/v1/chat/completions \
     -H "Content-Type: application/json" \
     -d '{
       "model": "MODEL_NAME",
       "messages": [{"role": "user", "content": "Why is the sky blue?"}],
       "chat_template_kwargs": {
            "enable_thinking": true
        },
        "skip_special_tokens": false
     }'

   Questo comando dovrebbe fornire un output simile al seguente:

   {
    "id": "chatcmpl-9cf1ab1450487047",
    "object": "chat.completion",
    "created": 1774904187,
    "model": "google/gemma-4-E2B-it",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "The short answer is a phenomenon called **Rayleigh scattering**...",
          "function_call": null,
          "tool_calls": [],
          "reasoning": "*   Question: \"Why is the sky blue?\"\n..."
        },
        "finish_reason": "stop",
        "stop_reason": 106
      }
    ],
    "usage": {
      "prompt_tokens": 21,
      "total_tokens": 877,
      "completion_tokens": 856
    }
   }
   

   Operazione riuscita: hai eseguito il deployment di un servizio Cloud Run con GPU con Gemma 4 e gli hai inviato una richiesta di inferenza.

Imposta la concorrenza per prestazioni ottimali

Questa sezione fornisce il contesto delle impostazioni di concorrenza consigliate. Per una latenza delle richieste ottimale, assicurati che l'impostazione --concurrency sia uguale all'argomento della riga di comando --max-num-seqs di vLLM.

• --max-num-seqs determina il numero di sequenze (richieste) disponibili per ogni istanza vLLM per gestire l'inferenza in parallelo.
• --concurrency determina il numero di richieste che Cloud Run invia contemporaneamente a un'istanza vLLM.

Se --concurrency supera --max-num-seqs, Cloud Run può inviare a un'istanza vLLM più richieste di quelle per cui ha slot di richiesta disponibili. Ciò comporta la creazione di code di richieste all'interno di vLLM, aumentando la latenza delle richieste in coda. Inoltre, la scalabilità automatica è meno reattiva, poiché le richieste in coda non attivano lo scale out di Cloud Run e l'avvio di nuove istanze.

Per evitare completamente la creazione di code di richieste nell'istanza vLLM, devi impostare --concurrency in modo che corrisponda a --max-num-seqs.

È importante notare che l'aumento di --max-num-seqs comporta anche un aumento della durata delle richieste parallele e richiede più memoria GPU per la cache KV.

Ottimizza l'utilizzo

Per un utilizzo ottimale della GPU, aumenta --concurrency, mantenendolo entro il doppio del valore di --max-num-seqs. Sebbene ciò comporti la creazione di code di richieste in vLLM, può contribuire a migliorare l'utilizzo: le istanze vLLM possono elaborare immediatamente le richieste dalla coda e le code aiutano ad assorbire i picchi di traffico.

Crea agenti AI con Agent Development Kit utilizzando Gemma 4

Dopo aver eseguito il deployment del servizio Cloud Run, puoi utilizzare l'endpoint Cloud Run con Gemma 4 per creare agenti AI con l' Agent Development Kit.

Prima di utilizzare Agent Development Kit, assicurati che le richieste in entrata passino il token di identità appropriato. Per saperne di più sull'utilizzo dell'autenticazione IAM e di Cloud Run, consulta Autenticazione da servizio a servizio.

L'esempio seguente mostra come utilizzare Agent Development Kit in Python con l'autenticazione IAM:

import subprocess
from google.adk.models.lite_llm import LiteLlm
from google.adk.agents import Agent

# Get the identity token using gcloud
id_token = subprocess.run(
    ["gcloud", "auth", "print-identity-token"],
    capture_output=True, text=True
).stdout.strip()

gemma_model = LiteLlm(
    model=f'openai/MODEL_NAME',
    base_url='https://YOUR_CLOUD_RUN_SERVICE_URL/v1',
    extra_body={
        "chat_template_kwargs": {
            "enable_thinking": True
        },
        "skip_special_tokens": False
    },
    extra_headers={
        "Authorization": f"Bearer {id_token}",
    },
)

root_agent = Agent(
    model=gemma_model,
    name='assistant',
    instruction="You are a helpful assistant",
)

Libera spazio

Elimina le seguenti Google Cloud risorse create:

• Servizio Cloud Run

Passaggi successivi

• Per modelli più grandi e tempi di avvio più rapidi con Run:ai Model Streamer, utilizza il codelab Esegui l'inferenza del modello Gemma 4 su Cloud Run con GPU RTX 6000 Pro con vLLM
• Configura la GPU
• Best practice: inferenza AI su Cloud Run con GPU
• Esegui i modelli Gemma 4 con vari framework di runtime AI