Exécuter des agents avec les modèles Gemma 4 sur Cloud Run

Ce guide explique comment déployer des modèles ouverts Gemma 4 sur Cloud Run à l'aide d'un conteneur préconfiguré avec la bibliothèque d'inférence vLLM. Il fournit également des conseils sur l'utilisation du service Cloud Run déployé avec des agents d'IA créés à l'aide de l'Agent Development Kit.

Gemma 4 est la famille de modèles ouverts la plus efficace de Google. Elle offre de solides capacités de raisonnement et d'agentivité.

Le contexte long, la multimodalité, le raisonnement et l'appel d'outils permettent à Gemma 4 de gérer la logique complexe, la planification en plusieurs étapes, le codage et les workflows agentifs.

Avant de commencer

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  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. Configurez votre environnement de développement Cloud Run dans votre projet Google Cloud .
  7. Installez et initialisez la gcloud CLI.
  8. Assurez-vous que les rôles IAM suivants sont attribués à votre compte :

    9. Découvrez comment attribuer les rôles.

    Console

    1. Dans la console Google Cloud , accédez à la page IAM.

      Accéder à IAM
    2. Sélectionnez le projet.
    3. Cliquez sur  Accorder l'accès.

    4. Dans le champ Nouveaux comptes principaux, saisissez votre identifiant utilisateur. Il s'agit généralement de l'adresse e-mail utilisée pour déployer le service Cloud Run.

    5. Dans la liste Sélectionner un rôle, sélectionnez un rôle.
    6. Pour attribuer des rôles supplémentaires, cliquez sur  Ajouter un autre rôle et ajoutez tous les rôles supplémentaires.
    7. Cliquez sur Enregistrer.

    gcloud

    Pour attribuer les rôles IAM requis à votre compte dans votre projet :

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

    Remplacez :

    • PROJECT_NUMBER par le numéro de votre projet Google Cloud .
    • PROJECT_ID par l'ID de votre projet Google Cloud .
    • PRINCIPAL par le compte pour lequel vous ajoutez la liaison. Il s'agit généralement de l'adresse e-mail utilisée pour déployer le service Cloud Run.
    • ROLE par le rôle que vous ajoutez au compte du déployeur.
  9. Si nécessaire, demandez un quota Total Nvidia RTX Pro 6000 GPU allocation, in milli GPU, without zonal redundancy, per project per region sous l'API Cloud Run Admin sur la page Quotas et limites du système.
  10. Consultez la page des tarifs de Cloud Run. Pour obtenir une estimation des coûts en fonction de votre utilisation prévue, utilisez le simulateur de coût.

Déployer un modèle Gemma 4 avec un conteneur vLLM

Gemma 4 offre des fonctionnalités agentives avancées, y compris le raisonnement, l'appel de fonction, la génération de code et la sortie structurée.

Agent Development Kit (ADK) vous aide à créer des agents IA entièrement fonctionnels avec Gemma 4.

Utilisez vLLM pour diffuser Gemma en tant que point de terminaison de l'API OpenAI. vLLM permet de diffuser des modèles génératifs à grande échelle de manière rapide et efficace. Il offre un débit de diffusion de pointe, une gestion efficace de la mémoire avec PagedAttention, le traitement par lot continu des requêtes entrantes, la prise en charge de la quantification et des kernels CUDA optimisés.

Pour déployer des modèles Gemma sur Cloud Run, utilisez la commande gcloud CLI suivante avec les paramètres recommandés :

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[*]}")

Remplacez :

  • SERVICE_NAME par un nom unique pour le service Cloud Run.
  • PROJECT par l'ID de votre projet Google Cloud .

  • REGION par une région Google Cloud où les GPU nvidia-rtx-pro-6000 sont compatibles avec Cloud Run, comme us-central1. Pour obtenir la liste complète des régions acceptant les déploiements compatibles avec les GPU, consultez Configuration des GPU.

  • MODEL_NAME par le nom complet d'une variante Gemma 4.

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

Voici les autres paramètres :

Option Description
--concurrency

Le nombre maximal de requêtes pouvant être traitées simultanément par une instance donnée, par exemple 8. Pour obtenir des recommandations sur la latence optimale des requêtes, consultez Définir la simultanéité pour des performances optimales.
--cpu

La quantité de processeurs alloués à votre service, par exemple 20.
--set-env-vars

Les variables d'environnement définies pour votre service. Par exemple, HF_TOKEN="...".
--gpu

La valeur de GPU pour votre service, par exemple 1.
--gpu-type

Le type de GPU à utiliser pour votre service, tel que nvidia-rtx-pro-6000.
--max-instances

Le nombre maximal d'instances de conteneur pour votre service, par exemple 1.
--memory

Quantité de mémoire allouée à votre service, par exemple 80Gi.
--no-invoker-iam-check

Désactivez les vérifications IAM du demandeur. Pour obtenir des recommandations sur la façon de mieux sécuriser votre application, consultez le tutoriel sur la sécurisation des services Cloud Run.
--no-cpu-throttling

Ce paramètre désactive la limitation du processeur lorsque le conteneur ne traite pas activement les requêtes.
--timeout

Le délai au cours duquel une réponse doit être renvoyée, par exemple 600 secondes.
--startup-probe

Paramètres séparés par une virgule pour la vérification de démarrage au format KEY=VALUE. Pour en savoir plus, consultez Sonde de démarrage Cloud Run. Avec les tailles de modèle Gemma 4, si vous n'utilisez pas la sortie VPC directe, il est recommandé de définir le délai avant expiration de votre sonde de démarrage sur au moins 240 secondes.

Si vous devez modifier les paramètres par défaut ou ajouter des paramètres plus personnalisés à votre service Cloud Run, consultez Configurer des services.

Une fois le service déployé, un message de réussite s'affiche avec l'URL du point de terminaison Cloud Run se terminant par run.app.

Tester le service Gemma déployé avec curl

Maintenant que vous avez déployé le service Gemma, vous pouvez lui envoyer des requêtes. Toutefois, si vous envoyez une requête directement, Cloud Run répond avec HTTP 401 Unauthorized. C'est normal, car une API d'inférence LLM est destinée à être appelée par d'autres services, tels qu'une application frontend. Pour en savoir plus sur l'authentification de service à service sur Cloud Run, consultez Authentification de service à service.

Pour envoyer des requêtes au service Gemma, ajoutez un en-tête avec un jeton OIDC valide aux requêtes, par exemple à l'aide du proxy de développement Cloud Run :

  1. Démarrez le proxy et, lorsque vous êtes invité à installer le composant cloud-run-proxy, sélectionnez Y :

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

  2. Exécutez la commande suivante pour envoyer une requête dans un onglet de terminal distinct, en laissant le proxy en cours d'exécution. Le proxy s'exécute sur localhost:9090. Spécifiez le modèle Gemma que vous avez utilisé précédemment :

    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
  }'

    Cette commande devrait produire un résultat semblable à celui-ci :

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

Définir la simultanéité pour des performances optimales

Cette section fournit des informations sur les paramètres de simultanéité recommandés. Pour une latence des requêtes optimale, assurez-vous que le paramètre --concurrency est égal à l'argument de ligne de commande --max-num-seqs de vLLM.

  • --max-num-seqs détermine le nombre de séquences (requêtes) disponibles par instance vLLM pour gérer l'inférence simultanément.
  • --concurrency détermine le nombre de requêtes que Cloud Run envoie simultanément à une instance vLLM.

Si --concurrency dépasse --max-num-seqs, Cloud Run peut envoyer plus de requêtes à une instance vLLM que le nombre d'emplacements de requêtes disponibles. Cela entraîne la mise en file d'attente des requêtes dans vLLM, ce qui augmente la latence des requêtes mises en file d'attente. Cela entraîne également un autoscaling moins réactif, car les requêtes mises en file d'attente ne déclenchent pas le effectuer un scaling horizontal de Cloud Run ni le démarrage de nouvelles instances.

Pour éviter complètement la mise en file d'attente des requêtes sur l'instance vLLM, vous devez définir --concurrency pour qu'il corresponde à --max-num-seqs.

Il est important de noter que l'augmentation de --max-num-seqs allonge également la durée des requêtes parallèles et nécessite plus de mémoire GPU pour le cache KV.

Utilisation optimale

Pour une utilisation optimale du GPU, augmentez --concurrency, en veillant à ce qu'il reste dans la limite du double de la valeur de --max-num-seqs. Bien que cela entraîne une mise en file d'attente des requêtes dans vLLM, cela peut contribuer à améliorer l'utilisation : les instances vLLM peuvent traiter immédiatement les requêtes de leur file d'attente, et les files d'attente aident à absorber les pics de trafic.

Créer des agents IA avec Agent Development Kit à l'aide de Gemma 4

Une fois votre service Cloud Run déployé, vous pouvez utiliser le point de terminaison Cloud Run avec Gemma 4 pour créer des agents d'IA avec le kit de développement d'agent.

Avant d'utiliser le kit de développement de l'agent, assurez-vous que les requêtes entrantes transmettent le jeton d'identité approprié. Pour en savoir plus sur l'utilisation de l'authentification IAM et de Cloud Run, consultez Authentifier de service à service.

L'exemple suivant montre comment utiliser le kit de développement d'agent en Python avec l'authentification 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",
)

Effectuer un nettoyage

Supprimez les ressources Google Cloud créées :

Étapes suivantes