Exécuter Gemma avec Hugging Face Transformers

 Afficher sur ai.google.dev Exécuter dans Google Colab  Exécuter dans Kaggle  Ouvrir dans Vertex AI Afficher la source sur GitHub

Générer du texte, résumer et analyser du contenu ne sont que quelques-unes des tâches que vous pouvez accomplir avec les modèles ouverts Gemma. Ce tutoriel vous explique comment commencer à exécuter Gemma à l'aide de Hugging Face Transformers en utilisant à la fois des entrées de texte et d'image pour générer du contenu textuel. La bibliothèque Python Transformers fournit une API permettant d'accéder aux modèles d'IA générative pré-entraînés, y compris Gemma. Pour en savoir plus, consultez la documentation Transformers.

Configuration

Avant de commencer ce tutoriel, effectuez les étapes suivantes :

  • Pour accéder à Gemma, connectez-vous à Hugging Face et sélectionnez Accepter la licence pour un modèle Gemma.
  • Sélectionnez un environnement d'exécution Colab avec suffisamment de ressources pour exécuter la taille du modèle Gemma que vous souhaitez utiliser. En savoir plus
  • Générez un jeton d'accès Hugging Face et ajoutez-le à votre environnement Colab.

Configurer le jeton d'accès

Ajoutez votre jeton d'accès à Colab pour pouvoir télécharger les modèles Gemma depuis le site Web Hugging Face. Utilisez la fonctionnalité Secrets de Colab pour enregistrer votre jeton de manière sécurisée sans l'ajouter à votre code de travail.

Pour ajouter votre jeton d'accès Hugging Face en tant que secret :

  1. Ouvrez l'onglet "Secrets" en sélectionnant l'icône en forme de clé sur le côté gauche de l'interface, ou sélectionnez Outils > Palette de commandes, saisissez secrets, puis appuyez sur Entrée.
  2. Sélectionnez Ajouter un secret pour ajouter une entrée de secret.
  3. Dans le champ Nom, saisissez HF_TOKEN.
  4. Dans le champ Valeur, saisissez le texte de votre jeton d'accès Hugging Face.
  5. Dans le champ Accès au notebook, sélectionnez le bouton bascule pour activer l'accès.

Une fois que vous avez saisi votre jeton d'accès en tant que HF_TOKEN et sa valeur, vous pouvez y accéder et le définir dans votre environnement de notebook Colab à l'aide du code suivant :

from google.colab import userdata
from huggingface_hub import login

# Login into Hugging Face Hub
hf_token = userdata.get('HF_TOKEN') # If you are running inside a Google Colab
login(hf_token)

Installer des packages Python

Installez les bibliothèques Hugging Face requises pour exécuter le modèle Gemma et effectuer des requêtes.

# Install Pytorch & other libraries
%pip install "torch>=2.4.0"

# Install a transformers version that supports Gemma 3 (>= 4.51.3)
%pip install "transformers>=4.51.3"

Générer du texte à partir de texte

La façon la plus simple d'utiliser Gemma consiste à envoyer une requête textuelle à un modèle Gemma pour obtenir une réponse textuelle. Cette méthode fonctionne avec presque toutes les variantes de Gemma. Cette section explique comment utiliser la bibliothèque Hugging Face Transformers pour charger et configurer un modèle Gemma pour la génération de texte à texte.

Charger le modèle

Utilisez les bibliothèques torch et transformers pour créer une instance d'une classe pipeline d'exécution de modèle avec Gemma. Lorsque vous utilisez un modèle pour générer des résultats ou suivre des instructions, sélectionnez un modèle réglé en suivant les instructions (IT), qui comporte généralement it dans la chaîne de l'ID du modèle. À l'aide de l'objet pipeline, vous spécifiez la variante Gemma que vous souhaitez utiliser, le type de tâche que vous souhaitez effectuer, en particulier "text-generation" pour la génération de texte à partir de texte, comme indiqué dans l'exemple de code suivant :

import torch
from transformers import pipeline

pipeline = pipeline(
    task="text-generation",
    model="google/gemma-3-4b-it",
    device=0, # "cuda" for Colab, "msu" for iOS devices
    torch_dtype=torch.bfloat16
)

Gemma n'accepte que quelques paramètres task pour la génération. Pour en savoir plus sur les paramètres task disponibles, consultez la documentation task() de Hugging Face Pipelines. Utilisez le type de données Torch torch.bfloat16 pour réduire la précision du modèle et les ressources de calcul nécessaires, sans impacter de manière significative la qualité de la sortie du modèle. Pour le paramètre device, vous pouvez utiliser "cuda" pour Colab, "msu" pour les appareils iOS ou simplement définir la valeur sur 0 (zéro) pour spécifier le premier GPU de votre système. Pour en savoir plus sur l'utilisation de la classe Pipeline, consultez la documentation Hugging Face Pipelines.

Exécuter la génération de texte

Une fois le modèle Gemma chargé et configuré dans un objet pipeline, vous pouvez lui envoyer des requêtes. L'exemple de code suivant montre une requête de base utilisant le paramètre text_inputs :

pipeline(text_inputs="roses are red")

[{'generated_text': 'roses are red, violets are blue, \ni love you more than you ever knew.\n\n**Explanation'}]

Utiliser un modèle de requête

Lorsque vous générez du contenu avec des requêtes plus complexes, utilisez un modèle de requête pour structurer votre demande. Un modèle de requête vous permet de spécifier des entrées provenant de rôles spécifiques, tels que user ou model. Il s'agit d'un format obligatoire pour gérer les interactions de chat multitours avec les modèles Gemma. L'exemple de code suivant montre comment construire un modèle de requête pour Gemma :

messages = [
    [
        {
            "role": "system",
            "content": [{"type": "text", "text": "You are a helpful assistant."},]
        },
        {
            "role": "user",
            "content": [{"type": "text", "text": "Roses are red..."},]
        },
    ],
]

pipeline(messages, max_new_tokens=50)

Générer du texte à partir de données d'image

À partir de Gemma 3, pour les tailles de modèle 4B et supérieures, vous pouvez utiliser des données d'image dans votre requête. Cette section explique comment utiliser la bibliothèque Transformers pour charger et configurer un modèle Gemma afin d'utiliser des données d'image et une entrée de texte pour générer une sortie de texte.

Charger le modèle

Lorsque vous chargez un modèle Gemma pour l'utiliser avec des données d'image, vous configurez l'instance Transformer pipeline spécifiquement pour les images. En particulier, vous devez sélectionner une configuration de pipeline capable de gérer les données visuelles en définissant le paramètre task sur "image-text-to-text", comme indiqué dans l'exemple de code suivant :

import torch
from transformers import pipeline

pipeline = pipeline(
    task="image-text-to-text", # required for image input
    model="google/gemma-3-4b-it",
    device=0,
    torch_dtype=torch.bfloat16
)

Exécuter la génération de texte

Une fois que vous avez configuré le modèle Gemma pour gérer les entrées d'image avec une instance pipeline, vous pouvez envoyer des requêtes avec des images au modèle. Utilisez le jeton <start_of_image> pour ajouter l'image au texte de votre requête. L'exemple de code suivant montre une requête de base utilisant le paramètre pipeline :

pipeline(
    "https://ai.google.dev/static/gemma/docs/images/thali-indian-plate.jpg",
    text="<start_of_image> What is shown in this image?"
)

[{'input_text': '<start_of_image> What is shown in this image?',
  'generated_text': '<start_of_image> What is shown in this image?\n\nThis image showcases a traditional Indian Thali. A Thali is a platter that contains a variety'}]

Utiliser un modèle de requête

Lorsque vous générez du contenu avec des requêtes plus complexes, utilisez un modèle de requête pour structurer votre demande. Un modèle de requête vous permet de spécifier des entrées provenant de rôles spécifiques, tels que user ou model. Il s'agit d'un format obligatoire pour gérer les interactions de chat multitours avec les modèles Gemma. L'exemple de code suivant montre comment construire un modèle de requête pour Gemma :

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://ai.google.dev/static/gemma/docs/images/thali-indian-plate.jpg"},
            {"type": "text", "text": "What is shown in this image?"},
        ]
    },
    {
        "role": "assistant",
        "content": [
            {"type": "text", "text": "This image shows"},
        ],
    },
]

pipeline(text=messages, max_new_tokens=50, return_full_text=False)

Vous pouvez inclure plusieurs images dans votre requête en ajoutant des entrées "type": "image", supplémentaires à la liste content.

Générer du texte à partir de données audio

Avec Gemma 3n, vous pouvez utiliser des données audio dans votre requête. Cette section explique comment utiliser la bibliothèque Transformers pour charger et configurer un modèle Gemma afin d'utiliser des données audio et une entrée de texte pour générer une sortie de texte.

Installer des packages Python

Une version récente des bibliothèques Transformers est requise pour utiliser l'entrée audio avec Gemma. Installez les bibliothèques Hugging Face pour exécuter le modèle Gemma et effectuer des requêtes avec des données audio, comme indiqué ci-dessous.

# Install Pytorch & other libraries
%pip install "torch>=2.4.0"

# Install a transformers version that supports Gemma 3n (>= 4.53)
%pip install "transformers>=4.53.0"

Charger le modèle

Lorsque vous chargez un modèle Gemma pour l'utiliser avec des données audio, vous configurez l'instance Transformer spécifiquement pour l'utiliser avec des données audio. En particulier, vous devez définir un objet processor et model à l'aide des classes AutoProcessor et AutoModelForImageTextToText, comme indiqué dans l'exemple de code suivant :

import torch
from transformers import AutoProcessor, AutoModelForImageTextToText

GEMMA_MODEL_ID = "google/gemma-3n-E4B-it"

processor = AutoProcessor.from_pretrained(GEMMA_MODEL_ID, device_map="auto")
model = AutoModelForImageTextToText.from_pretrained(
            GEMMA_MODEL_ID, torch_dtype="auto", device_map="auto")

Utiliser un modèle de requête

Lorsque vous générez du contenu avec de l'audio, utilisez un modèle de requête pour structurer votre demande. Un modèle de requête vous permet de spécifier des entrées provenant de rôles spécifiques, tels que user ou model. Il s'agit d'un format obligatoire pour gérer les interactions de chat multitours avec les modèles Gemma. L'exemple de code suivant montre comment construire un modèle de prompt pour Gemma avec des données audio en entrée :

messages = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": "https://ai.google.dev/gemma/docs/audio/roses-are.wav"},
            {"type": "text", "text": "Transcribe this audio and complete the statement"},
        ]
    }
]

Vous pouvez inclure plusieurs fichiers audio dans votre requête en ajoutant des entrées "type": "audio", supplémentaires dans la liste content. Si vous créez un prompt avec des données audio, mais sans modèle, utilisez la syntaxe <audio_soft_token> dans le texte de votre prompt.

Exécuter la génération de texte

Une fois que vous avez configuré le modèle Gemma avec un objet processor et model, et que vous avez créé une requête avec des données audio à l'aide d'un modèle de requête, vous pouvez envoyer la requête pour générer une sortie. L'exemple de code suivant montre une requête utilisant un modèle de chat, la génération de la sortie et le décodage de la réponse :

input_ids = processor.apply_chat_template(
        messages,
        add_generation_prompt=True,
        tokenize=True, return_dict=True,
        return_tensors="pt",
)
input_ids = input_ids.to(model.device, dtype=model.dtype)

# Generate output from the model
outputs = model.generate(**input_ids, max_new_tokens=128)

# decode and print the output as text
text = processor.batch_decode(
    outputs,
    skip_special_tokens=False,
    clean_up_tokenization_spaces=False
)
print(text[0])

Étapes suivantes

Créez et explorez davantage avec les modèles Gemma :