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

La génération de texte, la synthèse et l'analyse de contenu ne sont que quelques-unes des tâches que vous pouvez effectuer 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 à des modèles d'IA générative pré-entraînés, y compris Gemma. Pour en savoir plus, consultez la documentation de Transformers.

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
%pip install torch

# Install a transformers
%pip install transformers

Générer du texte à partir de texte

Demander à un modèle Gemma de générer une réponse textuelle est le moyen le plus simple d'utiliser Gemma et 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 à partir de 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 adapté aux instructions (IT), qui comporte 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 "any-to-any" pour la génération multimodale, comme illustré dans l'exemple de code suivant :

from transformers import pipeline

MODEL_ID = "google/gemma-4-E2B-it"

pipe = pipeline(
    task="any-to-any",
    model=MODEL_ID,
    device_map="auto",
    dtype="auto"
)

config.json: 0.00B [00:00, ?B/s]
model.safetensors:   0%|          | 0.00/10.2G [00:00<?, ?B/s]
Loading weights:   0%|          | 0/2011 [00:00<?, ?it/s]
generation_config.json:   0%|          | 0.00/208 [00:00<?, ?B/s]
processor_config.json: 0.00B [00:00, ?B/s]
chat_template.jinja: 0.00B [00:00, ?B/s]
tokenizer_config.json: 0.00B [00:00, ?B/s]
tokenizer.json:   0%|          | 0.00/32.2M [00:00<?, ?B/s]

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 la tâche Pipelines de Hugging Face. Pour en savoir plus sur l'utilisation de la classe Pipeline, consultez la documentation de Pipelines de Hugging Face.

Exécuter 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 montre une requête de base utilisant le text paramètre :

pipe(text="<|turn>user\nroses are red<turn|>\n<|turn>model\n")

Both `max_new_tokens` (=256) and `max_length`(=20) seem to have been set. `max_new_tokens` will take precedence. Please refer to the documentation for more information. (https://huggingface.co/docs/transformers/main/en/main_classes/text_generation)
[{'input_text': '<|turn>user\nroses are red<turn|>\n<|turn>model\n',
  'generated_text': '<|turn>user\nroses are red<turn|>\n<|turn>model\nThat\'s a classic phrase, often used to highlight a contrast or a truth.\n\n**"Roses are red"** is a very popular, simple, and sweet arrangement.\n\nWhat would you like to do with this phrase? Are you looking for:\n\n1. **More rhymes or phrases?**\n2. **A continuation of a thought?**\n3. **Just appreciating the simplicity?**'}]

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 requête. 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, et constitue un format obligatoire pour gérer les interactions de chat en plusieurs tours avec les modèles Gemma. L'exemple de code suivant montre comment construire un modèle de requête pour Gemma :

from transformers import GenerationConfig
config = GenerationConfig.from_pretrained(MODEL_ID)
config.max_new_tokens = 512
gen_kwargs = dict(generation_config=config)

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

pipe(messages, return_full_text=False, generate_kwargs=gen_kwargs)

[{'input_text': [{'role': 'system',
    'content': [{'type': 'text', 'text': 'You are a helpful assistant.'}]},
   {'role': 'user',
    'content': [{'type': 'text', 'text': 'Roses are red...'}]}],
  'generated_text': 'Roses are red,\nViolets are blue,\nHow lovely to see\nA beautiful view.'}]

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

À partir de Gemma 3, pour les tailles de modèle de 4B et plus, 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 des entrées de texte pour générer une sortie de texte.

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 requête. 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, et constitue un format obligatoire pour gérer les interactions de chat en plusieurs tours avec les modèles Gemma. L'exemple de code suivant montre comment construire un modèle de requête pour Gemma :

from transformers import GenerationConfig
config = GenerationConfig.from_pretrained(MODEL_ID)
config.max_new_tokens = 512
gen_kwargs = dict(generation_config=config)

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"},
        ],
    },
]

pipe(text=messages, return_full_text=False, generate_kwargs=gen_kwargs)

[{'input_text': [{'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'}]}],
  'generated_text': " a platter of Indian food, likely a meal or an assortment of dishes.\n\nHere's a breakdown of what is visible:\n\n*   **Flatbread:** There is a large, golden-brown flatbread (possibly naan or roti) dominating the center of the platter.\n*   **Dips/Sides:** There are several small bowls containing various accompaniments:\n    *   A bowl of **yellow/mustard-colored dip** (perhaps a chutney or sauce).\n    *   A bowl of **white creamy dip** (like raita or yogurt sauce).\n    *   A portion of **white rice**.\n    *   Several bowls of **curries or sauces** in different colors:\n        *   An **orange/brown curry**.\n        *   A **deep yellow/orange sauce**.\n        *   A **green sauce** (likely a chutney).\n*   **Garnish/Side Item:** In the upper right corner, there appears to be some darker, textured items, possibly fried pieces or spices.\n*   **Platter:** The food is served on a metal platter.\n\nOverall, it looks like a traditional Indian meal setup featuring bread, rice, and various flavorful sauces/curries."}]

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

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

Avec Gemma 4 et 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 des entrées de texte pour générer une sortie de texte.

Utiliser un modèle de requête

Lorsque vous générez du contenu audio, utilisez un modèle de requête pour structurer votre requête. 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, et constitue un format obligatoire pour gérer les interactions de chat en plusieurs tours avec les modèles Gemma. L'exemple de code suivant montre comment construire un modèle de requête pour Gemma avec une entrée de données audio :

from transformers import GenerationConfig
config = GenerationConfig.from_pretrained(MODEL_ID)
config.max_new_tokens = 512
gen_kwargs = dict(generation_config=config)

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Transcribe the following speech segment in its original language. Follow these specific instructions for formatting the answer:\n* Only output the transcription, with no newlines.\n* When transcribing numbers, write the digits, i.e. write 1.7 and not one point seven, and write 3 instead of three."},
            {"type": "audio", "audio": "https://ai.google.dev/gemma/docs/audio/roses-are.wav"},
        ]
    }
]

pipe(text=messages, return_full_text=False, generate_kwargs=gen_kwargs)

[{'input_text': [{'role': 'user',
    'content': [{'type': 'text',
      'text': 'Transcribe the following speech segment in its original language. Follow these specific instructions for formatting the answer:\n* Only output the transcription, with no newlines.\n* When transcribing numbers, write the digits, i.e. write 1.7 and not one point seven, and write 3 instead of three.'},
     {'type': 'audio',
      'audio': 'https://ai.google.dev/gemma/docs/audio/roses-are.wav'}]}],
  'generated_text': 'Roses are red, violets are blue.'}]

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

Étapes suivantes

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