Esegui Gemma con Hugging Face Transformers

Visualizza su ai.google.dev Esegui in Google Colab Esegui in Kaggle Apri in Vertex AI Visualizza il codice sorgente su GitHub

Generare testo, riassumere e analizzare i contenuti sono solo alcune delle attività che puoi svolgere con i modelli open Gemma. Questo tutorial mostra come iniziare a eseguire Gemma utilizzando Hugging Face Transformers con input di testo e immagini per generare contenuti di testo. La libreria Python Transformers fornisce un'API per accedere a modelli di AI generativa preaddestrati, tra cui Gemma. Per saperne di più, consulta la documentazione relativa ai Transformer.

Installa i pacchetti Python

Installa le librerie Hugging Face necessarie per eseguire il modello Gemma ed effettuare richieste.

# Install Pytorch
%pip install torch

# Install a transformers
%pip install transformers

Generare testo da testo

Richiedere a un modello Gemma di generare una risposta di testo è il modo più semplice per utilizzare Gemma e funziona con quasi tutte le varianti di Gemma. Questa sezione mostra come utilizzare la libreria Hugging Face Transformers per caricare e configurare un modello Gemma per la generazione di testo.

Carica modello

Utilizza le librerie torch e transformers per creare un'istanza di una classe di esecuzione del modello pipeline con Gemma. Quando utilizzi un modello per generare output o seguire indicazioni, seleziona un modello con istruzioni ottimizzate (IT), che in genere include it nella stringa dell'ID modello. Utilizzando l'oggetto pipeline, specifica la variante di Gemma che vuoi utilizzare, il tipo di attività che vuoi eseguire, in particolare "any-to-any" per la generazione multimodale, come mostrato nel seguente esempio di codice:

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 supporta solo alcune impostazioni task per la generazione. Per ulteriori informazioni sulle impostazioni task disponibili, consulta la documentazione di Hugging Face Pipelines task(). Per saperne di più sull'utilizzo della classe Pipeline, consulta la documentazione di Hugging Face Pipelines.

Esegui la generazione di testo

Una volta caricato e configurato il modello Gemma in un oggetto pipeline, puoi inviare prompt al modello. Il seguente codice di esempio mostra una richiesta di base che utilizza il parametro text:

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?**'}]

Utilizzare un modello di prompt

Quando generi contenuti con prompt più complessi, utilizza un modello di prompt per strutturare la richiesta. Un modello di prompt consente di specificare l'input di ruoli specifici, ad esempio user o model, ed è un formato obbligatorio per la gestione delle interazioni di chat a più turni con i modelli Gemma. Il seguente codice di esempio mostra come creare un modello di prompt per 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.'}]

Generare testo dai dati delle immagini

A partire da Gemma 3, per le dimensioni del modello 4B e superiori, puoi utilizzare i dati immagine come parte del prompt. Questa sezione mostra come utilizzare la libreria Transformers per caricare e configurare un modello Gemma in modo che utilizzi dati delle immagini e input di testo per generare output di testo.

Utilizzare un modello di prompt

Quando generi contenuti con prompt più complessi, utilizza un modello di prompt per strutturare la richiesta. Un modello di prompt consente di specificare l'input di ruoli specifici, ad esempio user o model, ed è un formato obbligatorio per la gestione delle interazioni di chat a più turni con i modelli Gemma. Il seguente codice di esempio mostra come creare un modello di prompt per 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."}]

Puoi includere più immagini nel prompt aggiungendo ulteriori voci "type": "image", all'elenco content.

Generare testo dai dati audio

Con Gemma 4 e Gemma 3n, puoi utilizzare i dati audio come parte del prompt. Questa sezione mostra come utilizzare la libreria Transformers per caricare e configurare un modello Gemma in modo che utilizzi dati audio e input di testo per generare output di testo.

Utilizzare un modello di prompt

Quando generi contenuti con audio, utilizza un modello di prompt per strutturare la richiesta. Un modello di prompt consente di specificare l'input di ruoli specifici, ad esempio user o model, ed è un formato obbligatorio per la gestione delle interazioni di chat a più turni con i modelli Gemma. Il seguente codice di esempio mostra come creare un modello di prompt per Gemma con input di dati 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.'}]

Puoi includere più file audio nel prompt aggiungendo ulteriori voci "type": "audio", all'elenco content.

Passaggi successivi

Crea ed esplora di più con i modelli Gemma: