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

La generazione di testo, il riepilogo e l'analisi dei contenuti sono solo alcune delle attività che puoi svolgere con i modelli open di 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 ai modelli di AI generativa preaddestrati, inclusi i modelli Gemma. Per ulteriori informazioni, consulta la documentazione di Transformers.

Configurazione

Prima di iniziare questo tutorial, completa i seguenti passaggi:

  • Accedi a Gemma accedendo a Hugging Face e selezionando Acknowledge license per un modello Gemma.
  • Seleziona un runtime Colab con risorse sufficienti per eseguire le dimensioni del modello Gemma che vuoi eseguire. Scopri di più.
  • Genera un token di accesso a Hugging Face e aggiungilo al tuo ambiente Colab.

Configura il token di accesso

Aggiungi il token di accesso a Colab per consentire il download dei modelli Gemma dal sito web di Hugging Face. Utilizza la funzionalità Secrets di Colab per salvare in modo sicuro il token senza aggiungerlo al codice di lavoro.

Per aggiungere il token di accesso a Hugging Face come secret:

  1. Apri la scheda dei secret selezionando l'icona della chiave sul lato sinistro dell'interfaccia oppure seleziona Strumenti > Tavolozza comandi , digita secrets e premi Invio.
  2. Seleziona Add new secret (Aggiungi nuovo secret) per aggiungere una nuova voce secret.
  3. Nel campo Name (Nome), inserisci HF_TOKEN.
  4. Nel campo Value (Valore), inserisci il testo del token di accesso a Hugging Face.
  5. Nel campo Notebook access (Accesso al notebook), seleziona l'opzione per attivare l'accesso.

Dopo aver inserito il token di accesso come HF_TOKEN e valore, puoi accedervi e impostarlo nell'ambiente del notebook di Colab utilizzando il seguente codice:

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)

Installa i pacchetti Python

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

# 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"

Genera testo da testo

Il modo più semplice per utilizzare Gemma è fornire un prompt di testo a un modello Gemma per ottenere una risposta di testo, ed è compatibile 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 da testo.

Carica il modello

Utilizza le librerie torch e transformers per creare un'istanza di una classe pipeline di esecuzione del modello con Gemma. Quando utilizzi un modello per generare output o seguire le indicazioni, seleziona un modello ottimizzato per le istruzioni (IT), che in genere ha 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 "text-generation" per la generazione da testo a testo, come mostrato nel seguente esempio di codice:

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 supporta solo alcune impostazioni task per la generazione. Per ulteriori informazioni sulle impostazioni task disponibili, consulta la documentazione di Hugging Face Pipelines task(). Utilizza il tipo di dati torch torch.bfloat16 per ridurre la precisione del modello e le risorse di calcolo necessarie, senza influire in modo significativo sulla qualità dell'output del modello. Per l'impostazione device, puoi utilizzare "cuda" per Colab, "msu" per i dispositivi iOS o semplicemente impostare questo valore su 0 (zero) per specificare la prima GPU del sistema. Per ulteriori informazioni sull'utilizzo della classe Pipeline, consulta la documentazione di Hugging Face Pipelines.

Esegui la generazione di testo

Dopo aver caricato e configurato il modello Gemma in un oggetto pipeline, puoi inviare prompt al modello. Il seguente esempio di codice mostra una richiesta di base che utilizza il parametro 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'}]

Utilizza un modello di prompt

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

Genera testo da dati immagine

A partire da Gemma 3, per le dimensioni dei modelli 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 da utilizzare i dati immagine e l'input di testo per generare output di testo.

Carica il modello

Quando carichi un modello Gemma da utilizzare con i dati immagine, configuri l'istanza pipeline di Transformer in modo specifico per l'utilizzo con le immagini. In particolare, devi selezionare una configurazione della pipeline in grado di gestire i dati visivi impostando il parametro task su "image-text-to-text", come mostrato nel seguente esempio di codice:

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
)

Esegui la generazione di testo

Dopo aver configurato il modello Gemma per gestire l'input di immagini con un'istanza pipeline, puoi inviare prompt con immagini al modello. Utilizza il token <start_of_image> per aggiungere l'immagine al testo del prompt. Il seguente esempio di codice mostra una richiesta di base che utilizza il parametro 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'}]

Utilizza un modello di prompt

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

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

Genera testo da dati audio

Con 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 da utilizzare i dati audio e l'input di testo per generare output di testo.

Installa i pacchetti Python

Per utilizzare l'input audio con Gemma è necessaria una versione recente delle librerie Transformers. Installa le librerie Hugging Face per eseguire il modello Gemma ed effettuare richieste con dati audio come mostrato di seguito.

# 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"

Carica il modello

Quando carichi un modello Gemma da utilizzare con i dati audio, configuri l'istanza di Transformer in modo specifico per l'utilizzo con i dati audio. In particolare, devi definire un oggetto processor e model utilizzando le classi AutoProcessor e AutoModelForImageTextToText, come mostrato nel seguente esempio di codice:

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")

Utilizza un modello di prompt

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

Puoi includere più file audio nel prompt includendo ulteriori "type": "audio", voci nell'elenco content. Se fornisci un prompt con dati audio, ma senza un modello, utilizza la sintassi <audio_soft_token> nel testo del prompt.

Esegui la generazione di testo

Dopo aver configurato il modello Gemma con un oggetto processor e model e aver creato un prompt con dati audio utilizzando un modello di prompt, puoi inviare il prompt per generare l'output. Il seguente esempio di codice mostra una richiesta che utilizza un modello di chat, la generazione dell'output e la decodifica della risposta:

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])

Passaggi successivi

Crea ed esplora di più con i modelli Gemma: