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édéfini 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 d'Agent Development Kit.

Gemma 4 est la famille de modèles ouverts la plus efficace de Google, offrant de solides capacités de raisonnement et d'agent.

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

Avant de commencer

  1. Connectez-vous à votre Google Cloud compte. Si vous n'avez jamais utilisé Google Cloud, créez un compte pour évaluer les performances de nos produits dans des scénarios réels. 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 Google Cloud projet.
  7. Installez et initialisez 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 votre Google Cloud numéro de projet.
    • PROJECT_ID par l'ID de votre Google Cloud projet.
    • 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 account.
  9. Par défaut, les nouveaux projets bénéficient automatiquement d'un quota de 3 000 milliGPU lors du déploiement initial. Si vous avez besoin d'un quota supplémentaire, demandez le 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 Tarifs de Cloud Run. Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût.

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

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

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

Utilisez vLLM pour diffuser Gemma en tant que point de terminaison de l'API OpenAI. vLLM fournit une diffusion rapide et efficace pour les modèles génératifs à grande échelle, avec un débit de diffusion de pointe, une gestion efficace de la mémoire avec PagedAttention, un traitement par lot continu des requêtes entrantes, une prise en charge de la quantification et des noyaux 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 Google Cloud projet.

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

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

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

Les autres paramètres sont les suivants :

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 la section Définir la simultanéité pour des performances optimales.
--cpu

Quantité de processeurs allouée à votre service, par exemple 20.
--set-env-vars

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

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

Le type de GPU à utiliser pour votre service, par exemple 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ésactiver les vérifications IAM de l'appelant. Pour obtenir des recommandations sur la façon de mieux sécuriser votre application, consultez le tutoriel Sécuriser les 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

Délai dans lequel une réponse doit être renvoyée, par exemple 600 secondes.
--startup-probe

Paramètres séparés par une virgule pour la sonde de démarrage au format KEY=VALUE. Pour en savoir plus, consultez la section Sonde de démarrage Cloud Run. Avec les tailles de modèle de Gemma 4, si vous n'utilisez pas la sortie VPC directe, il est recommandé de définir le délai d'inactivité de la 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 la section 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. Ce comportement est intentionnel, 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 la section Authentifier 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, puis lorsque vous êtes invité à installer le composant cloud-run-proxy, choisissez 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 doit fournir une sortie semblable à celle-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 le contexte des paramètres de simultanéité recommandés. Pour une latence de requête 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 une 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 davantage de mémoire GPU pour le cache KV.

Utilisation optimale

Pour une utilisation optimale du GPU, augmentez --concurrency, en le maintenant 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 permettent d'absorber les pics de trafic.

Créer des agents d'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 l' Agent Development Kit.

Avant d'utiliser Agent Development Kit, 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 la section Authentifier de service à service.

L'exemple suivant montre comment utiliser Agent Development Kit 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",
)

Libérer de l'espace

Supprimez les Google Cloud ressources suivantes créées :

Étape suivante