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 di Gemma. Questo tutorial mostra come iniziare a eseguire Gemma utilizzando Hugging Face Transformers utilizzando sia l'input di testo che quello di 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 di Transformers.

Configurazione

Prima di iniziare questo tutorial, completa i seguenti passaggi:

  • Accedi a Gemma effettuando l'accesso 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 utilizzare. Ulteriori informazioni.
  • Genera un token di accesso Hugging Face e aggiungilo al tuo ambiente Colab.

Configurare il token di accesso

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

Una volta inserito il token di accesso come HF_TOKEN e valore, puoi accedervi e impostarlo nell'ambiente del notebook 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"

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 pipeline di esecuzione del modello 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 "text-generation" per la generazione di 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 relativa a task() di Hugging Face Pipelines. Utilizza il tipo di dati torcia 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 questo 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.

Eseguire 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 consente di specificare l'input di ruoli specifici, ad esempio user o model, ed è un formato obbligatorio per la gestione delle interazioni di chat multi-turn 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)

Generare testo dai dati delle immagini

A partire da Gemma 3, per i modelli di dimensioni pari o superiori a 4 miliardi di parametri, 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 dati delle immagini e input di testo per generare output di testo.

Carica modello

Quando carichi un modello Gemma da utilizzare con i dati delle immagini, configuri l'istanza Transformer pipeline specificamente 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
)

Eseguire la generazione di testo

Una volta 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 consente di specificare l'input di ruoli specifici, ad esempio user o model, ed è un formato obbligatorio per la gestione delle interazioni di chat multi-turn 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 aggiungendo altre voci "type": "image", all'elenco content.

Generare testo dai 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 che utilizzi dati audio e 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, configuri l'istanza 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")

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 multi-turn 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ù file audio nel prompt aggiungendo ulteriori voci "type": "audio", all'elenco content. Se utilizzi dati audio come prompt, ma senza un modello, utilizza la sintassi <audio_soft_token> nel testo del prompt.

Eseguire la generazione di testo

Una volta configurato il modello Gemma con un oggetto processor e model e 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: