Exécuter Gemma 3 sur Cloud Run

Ce guide explique comment déployer des modèles ouverts Gemma 3 sur Cloud Run à l'aide d'un conteneur prédéfini. Il fournit également des conseils sur l'utilisation du service Cloud Run déployé avec le SDK Google Gen AI.

Avant de commencer

Si vous avez utilisé Google AI Studio pour déployer sur Cloud Run, passez à la section Interagir de manière sécurisée avec le SDK Gen AI de Google.

Si vous n'avez pas utilisé Google AI Studio, suivez ces étapes avant d'utiliser Cloud Run pour créer un service.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure 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.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

1. Configurez votre environnement de développement Cloud Run dans votre projet Google Cloud .
2. Installez et initialisez gcloud CLI.
3. Assurez-vous que les rôles IAM suivants sont attribués à votre compte :
   • Administrateur Cloud Run (roles/run.admin)
   • Administrateur de projet IAM (roles/resourcemanager.projectIamAdmin)
   • Consommateur Service Usage (roles/serviceusage.serviceUsageConsumer)

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 person_add 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 du compte Google utilisé 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 add Ajouter un autre rôle et ajoutez chaque rôle supplémentaire.
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 Google Cloud projet.
• 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 du compte Google utilisé pour déployer le service Cloud Run.
• ROLE par le rôle que vous ajoutez au compte du déployeur.
4. Demandez le quota Total Nvidia L4 GPU allocation, per project per region sous l'API Cloud Run Admin sur la page Quotas et limites du système.
5. Consultez la page des 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 avec un conteneur prédéfini

Cloud Run fournit un conteneur prédéfini pour diffuser des modèles ouverts Gemma sur Cloud Run.

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

gcloud run deploy SERVICE_NAME \
   --image us-docker.pkg.dev/cloudrun/container/gemma/GEMMA_PARAMETER \
   --concurrency 4 \
   --cpu 8 \
   --set-env-vars OLLAMA_NUM_PARALLEL=4 \
   --gpu 1 \
   --gpu-type nvidia-l4 \
   --max-instances 1 \
   --memory 32Gi \
   --no-allow-unauthenticated \
   --no-cpu-throttling \
   --timeout=600 \
   --region REGION

Remplacez :

• SERVICE_NAME par un nom unique pour le service Cloud Run.

• GEMMA_PARAMETER avec le modèle Gemma que vous avez utilisé :

  • Gemma 3 1B (gemma-3-1b-it) : gemma3-1b
  • Gemma 3 4B (gemma-3-4b-it) : gemma3-4b
  • Gemma 3 12B (gemma-3-12b-it) : gemma3-12b
  • Gemma 3 27B (gemma-3-27b-it) : gemma3-27b

  Vous pouvez également remplacer l'intégralité de l'URL de l'image par une image Docker que vous avez créée à partir du dépôt GitHub Gemma-on-Cloudrun.

• REGION par la région Google Cloud dans laquelle votre service Cloud Run sera déployé, par exemple europe-west1. Si vous devez modifier la région, consultez la section Configuration des GPU pour en savoir plus sur les régions compatibles avec les déploiements utilisant des GPU.

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 4. 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 8.
--set-env-vars	Les variables d'environnement définies pour votre service. Exemple :OLLAMA_NUM_PARALLEL=4 Pour obtenir des recommandations sur la latence optimale des requêtes, consultez Définir la simultanéité pour des performances optimales.
--gpu	La valeur de GPU pour votre service, par exemple 1.
--gpu-type	Le type de GPU à utiliser pour votre service, tel que nvidia-l4.
--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 32Gi.
--no-invoker-iam-check	Désactivez les vérifications IAM du demandeur. Consultez Interagir de manière sécurisée avec le SDK Google Gen AI pour obtenir des recommandations sur la façon de mieux sécuriser votre application.
--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.

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 d'interface utilisateur. 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 ollama-gemma --port=9090

2. Envoyez-lui une requête dans un onglet de terminal distinct, en laissant le proxy en cours d'exécution. Notez que le proxy s'exécute sur localhost:9090 :

   curl http://localhost:9090/api/generate -d '{
     "model": "gemma3:4b",
     "prompt": "Why is the sky blue?"
   }'

   Cette commande devrait fournir un flux de sortie semblable à celui-ci :

   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.641492408Z","response":"That","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.687529153Z","response":"'","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.753284927Z","response":"s","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.812957381Z","response":" a","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.889102649Z","response":" fantastic","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.925748116Z","response":",","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.958391572Z","response":" decept","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.971035028Z","response":"ively","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.989678484Z","response":" tricky","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.999321940Z","response":" question","done":false}
   ...
   

Interagir de manière sécurisée avec le SDK Google Gen AI

Une fois votre service Cloud Run déployé, vous pouvez utiliser le point de terminaison Cloud Run avec le SDK Google Gen AI.

Avant d'utiliser le SDK Gen AI de Google, 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 Authentification de service à service.

Les exemples suivants montrent comment utiliser le SDK Google Gen AI avec l'authentification IAM.

JavaScript ou TypeScript

Si vous utilisez le SDK Google Gen AI pour JavaScript et TypeScript, le code peut se présenter comme suit :

import { GoogleGenAI, setDefaultBaseUrls } from "@google/genai";
import { GoogleAuth} from 'google-auth-library'

const cloudrunurl = 'https://CLOUD_RUN_SERVICE_URL';
const targetAudience = url;

const auth = new GoogleAuth();

async function main() {

  const client = await auth.getIdTokenClient(targetAudience);
  const headers = await client.getRequestHeaders(targetAudience);
  const idToken = headers['Authorization']

const ai = new GoogleGenAI({
  apiKey:"placeholder",
  httpOptions: { baseUrl: url, headers: {'Authorization': idToken}  },
});

  const response = await ai.models.generateContent({
    model: "gemma-3-1b-it",
    contents: "I want a pony",
  });
  console.log(response.text);
}

main();

curl

Si vous utilisez curl, exécutez les commandes suivantes pour accéder aux points de terminaison du SDK Google Gen AI :

• Pour "Générer du contenu", utilisez /v1beta/{model=models/*}:generateContent : génère une réponse du modèle à partir d'une entrée GenerateContentRequest.

  curl "<cloud_run_url>/v1beta/models/<model>:generateContent" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -X POST \
  -d '{
    "contents": [{
      "parts":[{"text": "Write a story about a magic backpack. You are the narrator of an interactive text adventure game."}]
      }]
      }'
  

• Pour Stream Generate Content, utilisez /v1beta/{model=models/*}:streamGenerateContent : génère une réponse en streaming à partir de l'entrée GenerateContentRequest.

  curl "<cloud_run_url>/v1beta/models/<model>:streamGenerateContent" \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
    -X POST \
    -d '{
      "contents": [{
        "parts":[{"text": "Write a story about a magic backpack. You are the narrator of an interactive text adventure game."}]
        }]
        }'
  

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 à la variable d'environnement OLLAMA_NUM_PARALLEL d'Ollama.

• OLLAMA_NUM_PARALLEL détermine le nombre d'emplacements de requête disponibles pour chaque modèle afin de gérer les requêtes d'inférence simultanément.
• --concurrency détermine le nombre de requêtes que Cloud Run envoie simultanément à une instance Ollama.

Si --concurrency dépasse OLLAMA_NUM_PARALLEL, Cloud Run peut envoyer plus de requêtes à un modèle dans Ollama que le nombre d'emplacements de requêtes disponibles. Cela entraîne la mise en file d'attente des requêtes dans Ollama, ce qui augmente la latence des requêtes 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.

Ollama permet également de diffuser plusieurs modèles à partir d'un seul GPU. Pour éviter complètement la mise en file d'attente des requêtes sur l'instance Ollama, vous devez toujours définir --concurrency pour qu'il corresponde à OLLAMA_NUM_PARALLEL.

Il est important de noter que l'augmentation de OLLAMA_NUM_PARALLEL allonge également la durée des requêtes parallèles.

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 OLLAMA_NUM_PARALLEL. Bien que cela entraîne une mise en file d'attente des requêtes dans Ollama, cela peut contribuer à améliorer l'utilisation : les instances Ollama peuvent traiter immédiatement les requêtes de leur file d'attente, et les files d'attente aident à absorber les pics de trafic.

Effectuer un nettoyage

Supprimez les ressources Google Cloud créées :

• Service Cloud Run
• Image du conteneur

Étapes suivantes

• Configurer le GPU
• Bonnes pratiques : inférence de l'IA sur Cloud Run avec des GPU
• Exécuter des modèles Gemma 3 avec différents frameworks d'exécution d'IA