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 riassunto e l'analisi dei contenuti sono solo alcune delle attività che puoi svolgere con i modelli aperti di Gemma. Questo tutorial mostra come iniziare a utilizzare Gemma con Hugging Face Transformers utilizzando input di testo e immagini per generare contenuti di testo. La libreria Python Transformers fornisce un'API per accedere ai modelli di IA generativa preaddestrati, tra cui Gemma. Per saperne di più, consulta la documentazione di Transformers.

Configurazione

Prima di iniziare questo tutorial, completa i seguenti passaggi:

  • Accedi a Gemma accedendo a Hugging Face e selezionando Accetta licenza per un modello Gemma.
  • Seleziona un runtime Colab con risorse sufficienti per eseguire la dimensione del modello Gemma che vuoi eseguire. Ulteriori informazioni.
  • Genera un token di accesso Hugging Face e aggiungilo al tuo ambiente Colab.

Configura il token di accesso

Aggiungi il tuo token di accesso a Colab per consentire il download dei modelli Gemma dal sito web di Hugging Face. Utilizza la funzionalità Secret di Colab per salvare il token in modo sicuro 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 a forma di chiave sul lato sinistro dell'interfaccia oppure seleziona Strumenti > Tavolozza dei comandi, digita secrets e premi Invio.
  2. Seleziona Aggiungi nuovo secret per aggiungere una nuova voce del secret.
  3. Nel campo Nome, inserisci HF_TOKEN.
  4. Nel campo Valore, inserisci il testo del token di accesso di Hugging Face.
  5. Nel campo Accesso al notebook, seleziona l'opzione per attivare l'accesso.

Dopo aver inserito il token di accesso come HF_TOKEN e il 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 e inviare 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

Chiedere a un modello Gemma di rispondere con un testo è il modo più semplice per utilizzare Gemma e funziona con quasi tutte le varianti di Gemma. Questa sezione mostra come utilizzare il caricamento della libreria Hugging Face Transformers e configurare un modello Gemma per la generazione di testo da testo.

Carica 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 indicazioni, seleziona un modello ottimizzato per le istruzioni (IT), che in genere contiene it nella stringa dell'ID modello. Utilizzando l'oggetto pipeline, specifichi la variante di Gemma che vuoi utilizzare, il tipo di attività che vuoi eseguire, in particolare "text-generation" per la generazione di testo in 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 task() di Hugging Face Pipelines. 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 o "msu" per i dispositivi iOS oppure impostare il valore su 0 (zero) per specificare la prima GPU del sistema. Per ulteriori informazioni sull'utilizzo della classe Pipeline, consulta la documentazione relativa alle pipeline di Hugging Face.

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_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'}]

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 ti consente di specificare input da ruoli specifici, come user o model, ed è un formato obbligatorio per gestire le interazioni di chat con più turni con i modelli Gemma. Il seguente codice di esempio 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 dai dati delle immagini

A partire da Gemma 3, per le dimensioni dei modelli pari o superiori a 4 miliardi, puoi utilizzare i dati immagine all'interno del prompt. Questa sezione mostra come utilizzare la libreria Transformers per caricare e configurare un modello Gemma in modo da utilizzare i dati delle immagini e l'input di testo per generare un output di testo.

Carica modello

Quando carichi un modello Gemma da utilizzare con i dati delle immagini, configura l'istanza Transformer pipeline specificamente per l'utilizzo con le immagini. In particolare, devi selezionare una configurazione della pipeline che possa 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 codice di esempio 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'}]

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 ti consente di specificare input da ruoli specifici, ad esempio user o model, ed è un formato obbligatorio per gestire le interazioni di chat con più turni con i modelli Gemma. Il seguente codice di esempio 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 inserendo voci "type": "image", aggiuntive nell'elenco content.

Generare 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 modello

Quando carichi un modello Gemma da utilizzare con i dati audio, configura l'istanza Transformer specificamente 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")

Utilizzare 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 input da ruoli specifici, come user o model, ed è un formato obbligatorio per gestire le interazioni di chat con 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:

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ù immagini nel prompt inserendo voci "type": "audio", aggiuntive nell'elenco content. Se fornisci 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 codice di esempio 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: