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 agenti di 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 capacità agentiche.

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

Prima di iniziare

  1. Accedi al tuo account Google Cloud . 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 workload.

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

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

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

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

  6. Configura l'ambiente di sviluppo Cloud Run nel tuo progetto Google Cloud .
  7. Installa e inizializza gcloud CLI.
  8. Assicurati di aver concesso al tuo account i seguenti ruoli IAM:

    9. 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 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 progetto Google Cloud .
    • PROJECT_ID con l'ID progetto Google Cloud .
    • PRINCIPAL con l'account per il quale 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.
  9. Se necessario, 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.
  10. Consulta la pagina 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 all'avanguardia, una gestione efficiente della memoria con PagedAttention, il batch continuo delle richieste in entrata, il supporto della quantizzazione e i 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 sono supportate le GPU nvidia-rtx-pro-6000 per Cloud Run, ad esempio us-central1. Per un elenco completo delle regioni supportate per i deployment abilitati per la 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 la sezione Imposta la concorrenza per un rendimento ottimale per suggerimenti sulla latenza ottimale delle richieste.
--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 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 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 di sicurezza di Cloud Run 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 KEY=VALUE. Per i dettagli, vedi Probe di avvio di Cloud Run. Con le dimensioni del modello Gemma 4, se non utilizzi l'uscita VPC diretta, 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 Configurare 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. Ciò è intenzionale, perché un'API di inferenza LLM è pensata per essere chiamata da altri servizi, ad esempio un'applicazione frontend. Per ulteriori informazioni sull'autenticazione tra servizi su Cloud Run, consulta Autenticazione tra servizi.

Per inviare richieste al servizio Gemma, aggiungi un'intestazione con un token OIDC valido alle richieste, ad esempio utilizzando il proxy per sviluppatori 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 a questo:

    {
 "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
 }
}

Impostare 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 contemporaneamente.
  • --concurrency determina il numero di richieste che Cloud Run invia a un'istanza vLLM contemporaneamente.

Se --concurrency supera --max-num-seqs, Cloud Run può inviare più richieste a un'istanza vLLM rispetto agli 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 Cloud Run per fare lo scale out e avviare nuove istanze.

Per evitare completamente la coda delle richieste sull'istanza vLLM, devi impostare --concurrency in modo che corrisponda a --max-num-seqs.

È importante notare che l'aumento di --max-num-seqs allunga anche i tempi di esecuzione delle richieste parallele e richiede più memoria GPU per la cache KV.

Ottimizza l'utilizzo

Per un utilizzo della GPU ottimale, 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 Agent Development Kit.

Prima di utilizzare l'Agent Development Kit, assicurati che le richieste in entrata superino il token di identità appropriato. Per scoprire 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