Gemma mit Hugging Face-Transformern ausführen

Auf ai.google.dev ansehen In Google Colab ausführen In Kaggle ausführen In Vertex AI öffnen Quellcode auf GitHub ansehen

Mit offenen Gemma-Modellen können Sie unter anderem Text generieren, Inhalte zusammenfassen und analysieren. In dieser Anleitung erfahren Sie, wie Sie Gemma mit Hugging Face Transformers ausführen und Textinhalte sowohl mit Text- als auch mit Bildeingabe generieren. Die Transformers-Python-Bibliothek bietet eine API für den Zugriff auf vortrainierte Modelle für generative KI, einschließlich Gemma. Weitere Informationen finden Sie in der Transformer-Dokumentation.

Einrichtung

Führen Sie die folgenden Schritte aus, bevor Sie mit dieser Anleitung beginnen:

  • Melden Sie sich bei Hugging Face an und wählen Sie für ein Gemma-Modell Lizenz bestätigen aus, um Zugriff auf Gemma zu erhalten.
  • Wählen Sie eine Colab-Laufzeit mit ausreichenden Ressourcen für die Ausführung der gewünschten Gemma-Modellgröße aus. Weitere Informationen
  • Generieren Sie ein Hugging Face-Zugriffstoken und fügen Sie es Ihrer Colab-Umgebung hinzu.

Zugriffstoken konfigurieren

Fügen Sie Colab Ihr Zugriffstoken hinzu, um das Herunterladen von Gemma-Modellen von der Hugging Face-Website zu ermöglichen. Verwenden Sie die Secrets-Funktion von Colab, um Ihr Token sicher zu speichern, ohne es in Ihren Arbeitscode aufzunehmen.

So fügen Sie Ihr Hugging Face-Zugriffstoken als Secret hinzu:

  1. Öffnen Sie den Tab „Secrets“, indem Sie das Schlüsselsymbol auf der linken Seite der Benutzeroberfläche auswählen. Sie können auch Tools > Befehlspalette auswählen, secrets eingeben und die Eingabetaste drücken.
  2. Wählen Sie Neues Secret hinzufügen aus, um einen neuen Secret-Eintrag hinzuzufügen.
  3. Geben Sie im Feld Name HF_TOKEN ein.
  4. Geben Sie im Feld Wert den Text Ihres Hugging Face-Zugriffstokens ein.
  5. Aktivieren Sie im Feld Notebookzugriff den Schalter, um den Zugriff zu aktivieren.

Nachdem Sie Ihr Zugriffstoken als HF_TOKEN und Wert eingegeben haben, können Sie mit dem folgenden Code darauf zugreifen und es in Ihrer Colab-Notebook-Umgebung festlegen:

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)

Python-Pakete installieren

Installieren Sie die Hugging Face-Bibliotheken, die zum Ausführen des Gemma-Modells und zum Senden von Anfragen erforderlich sind.

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

Text aus Text generieren

Die einfachste Methode, Gemma zu verwenden, ist, ein Gemma-Modell mit Text zu füttern, um eine Textantwort zu erhalten. Diese Methode funktioniert mit fast allen Gemma-Varianten. In diesem Abschnitt wird gezeigt, wie Sie mit der Hugging Face Transformers-Bibliothek ein Gemma-Modell für die Text-zu-Text-Generierung laden und konfigurieren.

Modell laden

Verwenden Sie die Bibliotheken torch und transformers, um mit Gemma eine Instanz der Klasse pipeline für die Modellausführung zu erstellen. Wenn Sie ein Modell zum Generieren von Ausgabe oder zum Befolgen von Anweisungen verwenden, wählen Sie ein modelloptimiertes Modell aus. Dieses enthält normalerweise it im Modell-ID-String. Mit dem pipeline-Objekt geben Sie die gewünschte Gemma-Variante und die Art der Aufgabe an, die Sie ausführen möchten, z. B. "text-generation" für die Text-zu-Text-Generierung, wie im folgenden Codebeispiel gezeigt:

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 unterstützt nur wenige task-Einstellungen für die Generierung. Weitere Informationen zu den verfügbaren task-Einstellungen finden Sie in der Dokumentation zu task() von Hugging Face Pipelines. Mit dem Torch-Datentyp torch.bfloat16 können Sie die Genauigkeit des Modells und die erforderlichen Rechenressourcen reduzieren, ohne die Ausgabequalität des Modells erheblich zu beeinträchtigen. Für die Einstellung device können Sie "cuda" für Colab oder "msu" für iOS-Geräte verwenden. Sie können sie auch einfach auf 0 (null) setzen, um die erste GPU auf Ihrem System anzugeben. Weitere Informationen zur Verwendung der Pipeline-Klasse finden Sie in der Pipelines-Dokumentation von Hugging Face.

Textgenerierung ausführen

Nachdem Sie das Gemma-Modell in einem pipeline-Objekt geladen und konfiguriert haben, können Sie Prompts an das Modell senden. Der folgende Beispielcode zeigt eine einfache Anfrage mit dem Parameter 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'}]

Vorlage für Prompts verwenden

Wenn Sie Inhalte mit komplexeren Prompts erstellen, verwenden Sie eine Promptvorlage, um Ihre Anfrage zu strukturieren. Mit einer Promptvorlage können Sie Eingaben von bestimmten Rollen wie user oder model angeben. Dieses Format ist erforderlich, um mehrstufige Chatinteraktionen mit Gemma-Modellen zu verwalten. Im folgenden Beispielcode wird gezeigt, wie eine Prompt-Vorlage für Gemma erstellt wird:

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)

Text aus Bilddaten generieren

Ab Gemma 3 können Sie bei Modellgrößen ab 4 Billiarden Bilddaten als Teil des Prompts verwenden. In diesem Abschnitt wird gezeigt, wie Sie mit der Transformers-Bibliothek ein Gemma-Modell laden und konfigurieren, um mithilfe von Bilddaten und Texteingaben Textausgaben zu generieren.

Modell laden

Wenn Sie ein Gemma-Modell für die Verwendung mit Bilddaten laden, konfigurieren Sie die Transformer-Instanz pipeline speziell für die Verwendung mit Bildern. Sie müssen insbesondere eine Pipelinekonfiguration auswählen, die visuelle Daten verarbeiten kann. Dazu müssen Sie den Parameter task auf "image-text-to-text" festlegen, wie im folgenden Codebeispiel gezeigt:

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
)

Textgenerierung ausführen

Sobald Sie das Gemma-Modell so konfiguriert haben, dass es Bildeingaben mit einer pipeline-Instanz verarbeitet, können Sie dem Modell Prompts mit Bildern senden. Verwenden Sie das Token <start_of_image>, um das Bild dem Text Ihres Prompts hinzuzufügen. Der folgende Beispielcode zeigt eine einfache Anfrage mit dem Parameter 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'}]

Vorlage für Prompts verwenden

Wenn Sie Inhalte mit komplexeren Prompts erstellen, verwenden Sie eine Promptvorlage, um Ihre Anfrage zu strukturieren. Mit einer Promptvorlage können Sie Eingaben von bestimmten Rollen wie user oder model angeben. Dieses Format ist erforderlich, um mehrstufige Chatinteraktionen mit Gemma-Modellen zu verwalten. Im folgenden Beispielcode wird gezeigt, wie eine Prompt-Vorlage für Gemma erstellt wird:

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)

Sie können mehrere Bilder in Ihren Prompt aufnehmen, indem Sie der Liste content zusätzliche "type": "image",-Einträge hinzufügen.

Text aus Audiodaten generieren

Mit Gemma 3n können Sie Audiodaten als Teil Ihres Prompts verwenden. In diesem Abschnitt wird gezeigt, wie Sie mit der Transformers-Bibliothek ein Gemma-Modell laden und konfigurieren, um Audiodaten und Texteingaben für die Textausgabe zu verwenden.

Python-Pakete installieren

Für die Verwendung des Audioinputs mit Gemma ist eine aktuelle Version der Transformers-Bibliotheken erforderlich. Installieren Sie die Hugging Face-Bibliotheken, um das Gemma-Modell auszuführen und Anfragen mit Audiodaten zu senden, wie unten gezeigt.

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

Modell laden

Wenn Sie ein Gemma-Modell für die Verwendung mit Audiodaten laden, konfigurieren Sie die Transformer-Instanz speziell für die Verwendung mit Audiodaten. Insbesondere müssen Sie ein processor- und ein model-Objekt mit den Klassen AutoProcessor und AutoModelForImageTextToText definieren, wie im folgenden Codebeispiel gezeigt:

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

Vorlage für Prompts verwenden

Wenn Sie Inhalte mit Audio generieren, verwenden Sie eine Promptvorlage, um Ihre Anfrage zu strukturieren. Mit einer Promptvorlage können Sie Eingaben von bestimmten Rollen wie user oder model angeben. Dieses Format ist erforderlich, um mehrstufige Chatinteraktionen mit Gemma-Modellen zu verwalten. Im folgenden Beispielcode wird gezeigt, wie eine Promptvorlage für Gemma mit Audiodaten erstellt wird:

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

Sie können mehrere Bilder in Ihren Prompt aufnehmen, indem Sie der Liste content zusätzliche "type": "audio",-Einträge hinzufügen. Wenn Sie Prompts mit Audiodaten, aber ohne Vorlage erstellen, verwenden Sie die <audio_soft_token>-Syntax im Text des Prompts.

Textgenerierung ausführen

Nachdem Sie das Gemma-Modell mit einem processor- und einem model-Objekt konfiguriert und mithilfe einer Promptvorlage einen Prompt mit Audiodaten erstellt haben, können Sie den Prompt senden, um eine Ausgabe zu generieren. Im folgenden Beispielcode wird eine Anfrage mit einer Chatvorlage, die Ausgabegenerierung und die Dekodierung der Antwort gezeigt:

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

Nächste Schritte

Mit Gemma-Modellen können Sie noch mehr entwickeln und entdecken: