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 du texte et des images pour générer du contenu textuel. La bibliothèque Python Transformers fournit une API permettant d'accéder à des modèles d'IA générative pré-entraînés, y compris Gemma. Pour en savoir plus, consultez la documentation sur les transformateurs.

Configuration

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

  • Pour accéder à Gemma, connectez-vous à Hugging Face et sélectionnez Acknowledge license (Accepter la licence) pour un modèle Gemma.
  • Sélectionnez un environnement d'exécution Colab disposant de ressources suffisantes pour exécuter la taille de modèle Gemma que vous souhaitez exécuter. 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 des modèles Gemma depuis le site Web de 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 bloc-notes, activez l'accès en activant le bouton bascule.

Une fois que vous avez saisi votre jeton d'accès en tant que HF_TOKEN et valeur, vous pouvez y accéder et le définir dans l'environnement de votre 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 envoyer 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

Demander à un modèle Gemma de répondre à un texte est le moyen le plus simple d'utiliser Gemma. 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 une sortie ou suivre des instructions, sélectionnez un modèle réglé en suivant les instructions (IT), qui contient généralement it dans la chaîne d'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 à texte, comme illustré 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 affecter de manière significative la qualité de sortie du modèle. Pour le paramètre device, vous pouvez utiliser "cuda" pour Colab ou "msu" pour les appareils iOS, ou simplement définir cette 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 sur les pipelines de Hugging Face.

Lancer la génération de texte

Une fois le modèle Gemma chargé et configuré dans un objet pipeline, vous pouvez envoyer des requêtes au modèle. L'exemple de code suivant illustre 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 invites plus complexes, utilisez un modèle d'invite pour structurer votre requête. Un modèle d'invite vous permet de spécifier les entrées de rôles spécifiques, tels que user ou model. Il s'agit d'un format obligatoire pour gérer les interactions de chat multi-tours avec les modèles Gemma. L'exemple de code suivant montre comment créer 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 de 4 Go et plus, vous pouvez utiliser des données d'image dans votre requête. Cette section montre 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 textuelle pour générer une sortie textuelle.

Charger le modèle

Lorsque vous chargez un modèle Gemma à utiliser avec des données d'image, vous configurez l'instance pipeline Transformer spécifiquement pour l'utiliser avec des images. Plus précisément, 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 illustré 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
)

Lancer la génération de texte

Une fois le modèle Gemma configuré pour gérer l'entrée d'images 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 illustre 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 invites plus complexes, utilisez un modèle d'invite pour structurer votre requête. Un modèle d'invite vous permet de spécifier les entrées de rôles spécifiques, tels que user ou model. Il s'agit d'un format obligatoire pour gérer les interactions de chat multi-tours avec les modèles Gemma. L'exemple de code suivant montre comment créer 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 textuelle pour générer une sortie textuelle.

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 à 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 illustré 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 du contenu audio, utilisez un modèle de requête pour structurer votre demande. Un modèle d'invite vous permet de spécifier les entrées de rôles spécifiques, tels que user ou model. Il s'agit d'un format obligatoire pour gérer les interactions de chat multi-tours avec les modèles Gemma. L'exemple de code suivant montre comment créer un modèle de requête pour Gemma avec une entrée de données audio :

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 images dans votre requête en ajoutant des entrées "type": "audio", supplémentaires à la liste content. Si vous utilisez des données audio pour votre requête, mais sans modèle, utilisez la syntaxe <audio_soft_token> dans le texte de votre requête.

Lancer la génération de texte

Une fois que vous avez configuré le modèle Gemma avec un objet processor et model, et créé une invite avec des données audio à l'aide d'un modèle d'invite, vous pouvez envoyer l'invite pour générer une sortie. L'exemple de code suivant montre une requête à l'aide d'un modèle de chat, la génération de 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 plus avec les modèles Gemma :