Esegui agenti con i modelli Gemma 4 su Cloud Run

Questa guida descrive come eseguire il deployment dei modelli aperti Gemma 4 su Cloud Run utilizzando un container predefinito 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 capacità di ragionamento e agentiche.

Contesto lungo, multimodalità, ragionamento e chiamate di strumenti consentono a Gemma 4 di gestire logica complessa, pianificazione in più passaggi, programmazione e workflow agentici.

Prima di iniziare

  1. 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

  2. Verify that billing is enabled for your Google Cloud project.

  3. Configura l'ambiente di sviluppo di Cloud Runnel tuo progetto Google Cloud .
  4. Installa e inizializza gcloud CLI.
  5. Assicurati che al tuo account siano stati concessi i seguenti ruoli IAM:

    6. Scopri come concedere i ruoli

    Console

    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 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 al tuo account i ruoli IAM richiesti nel tuo progetto:

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

    Sostituisci:

    • PROJECT_NUMBER con il numero del tuo progetto Google Cloud .
    • PROJECT_ID con l'ID progetto Google Cloud .
    • PRINCIPAL con l'account per cui stai aggiungendo l'associazione. In genere si tratta dell'indirizzo email utilizzato per eseguire il deployment del servizio Cloud Run.
    • ROLE con il ruolo che stai aggiungendo all'account deployer.
  6. 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.
  7. 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 funzione, generazione di codice e output strutturato.

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

Utilizza vLLM per gestire Gemma come endpoint API OpenAI. vLLM fornisce una gestione rapida ed efficiente dei modelli generativi su larga scala, con un throughput di gestione all'avanguardia, una gestione della memoria efficiente con PagedAttention, un raggruppamento continuo delle richieste in entrata, il supporto della quantizzazione e kernel CUDA ottimizzati.

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 progetto Google Cloud .

  • REGION con una regione Google Cloud 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 abilitati per 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. Consulta Imposta la contemporaneità per prestazioni ottimali per i consigli sulla latenza ottimale delle richieste.
--cpu

La quantità di CPU allocata per il tuo 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 tuo 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 tuo servizio, ad esempio 1.
--memory

La quantità di memoria allocata per il tuo servizio, ad esempio 80Gi.
--no-invoker-iam-check

Disabilita i controlli IAM dell'invoker. Consulta il tutorial sui servizi Cloud Run sicuri per suggerimenti su come proteggere meglio la tua app.
--no-cpu-throttling

Questa impostazione disabilita 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 virgole per il probe di avvio nel formato CHIAVE=VALORE. Per maggiori dettagli, consulta Probe di avvio di Cloud Run. Con dimensioni del modello di Gemma 4, se non utilizzi il traffico VPC diretto in uscita, 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 tuo 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 .

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 a essere chiamata da altri servizi, ad esempio un'applicazione di frontend. Per saperne di più sull'autenticazione tra servizi su Cloud Run, consulta Autenticazione tra servizi.

Per inviare richieste al servizio Gemma, aggiungi alle richieste un'intestazione con un token OIDC valido, 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 questo comando per inviare una richiesta in una scheda del terminale separata, lasciando il proxy in esecuzione. 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
 }
}

Imposta la contemporaneità per prestazioni ottimali

Questa sezione fornisce il contesto per le impostazioni di contemporaneità 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 contemporaneamente.
  • --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 più richieste a un'istanza vLLM rispetto agli slot di richiesta disponibili. Ciò comporta l'accodamento delle 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 l'accodamento delle 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 del tempo necessario per le 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 l'accodamento delle 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 l'Agent Development Kit, assicurati che le richieste in entrata trasmettano 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 l'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",
)

Esegui la pulizia

Elimina le seguenti risorse Google Cloud create:

Passaggi successivi