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 Quelle auf GitHub ansehen

Das Generieren von Text, das Zusammenfassen und Analysieren von Inhalten sind nur einige der Aufgaben, die Sie mit offenen Gemma-Modellen erledigen können. In dieser Anleitung erfahren Sie, wie Sie Gemma mit Hugging Face Transformers ausführen und sowohl Text- als auch Bildeingaben verwenden, um Textinhalte zu generieren. Die Transformers-Python-Bibliothek bietet eine API für den Zugriff auf vortrainierte generative KI-Modelle, einschließlich Gemma. Weitere Informationen finden Sie in der Dokumentation zu Transformers.

Einrichtung

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

  • Sie erhalten Zugriff auf Gemma, indem Sie sich bei Hugging Face anmelden und für ein Gemma-Modell Lizenz bestätigen auswählen.
  • Wählen Sie eine Colab-Laufzeit mit ausreichend Ressourcen aus, um die gewünschte Gemma-Modellgröße auszuführen. Weitere Informationen
  • Generieren Sie ein Hugging Face-Zugriffstoken und fügen Sie es Ihrer Colab-Umgebung hinzu.

Zugriffstoken konfigurieren

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

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

  1. Öffnen Sie den Tab „Secrets“, indem Sie auf der linken Seite der Benutzeroberfläche das Schlüsselsymbol auswählen oder Tools > Command Palette (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. Wählen Sie im Feld Notebook-Zugriff den Schalter aus, um den Zugriff zu aktivieren.

Nachdem Sie Ihr Zugriffstoken als HF_TOKEN und Wert eingegeben haben, können Sie mit dem folgenden Code in Ihrer Colab-Notebook-Umgebung darauf zugreifen und es 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 für die Ausführung des Gemma-Modells und das 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

Wenn Sie ein Gemma-Modell mit Text auffordern, eine Textantwort zu generieren, ist das die einfachste Methode, Gemma zu verwenden. Sie 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 eine Instanz der pipeline-Klasse für die Ausführung eines Modells mit Gemma zu erstellen. Wenn Sie ein Modell zum Generieren von Ausgaben oder zum Befolgen von Anweisungen verwenden, wählen Sie ein Instruction-Tuned-Modell (IT-Modell) aus, das in der Regel it im Modell-ID-String enthält. Mit dem pipeline-Objekt geben Sie die Gemma-Variante an, die Sie verwenden möchten, sowie den Typ der Aufgabe, die Sie ausführen möchten, insbesondere "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 Hugging Face Pipelines task(). Verwenden Sie den Torch-Datentyp torch.bfloat16, um die Genauigkeit des Modells und die benötigten Rechenressourcen zu 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 oder einfach 0 (Null) festlegen, um die erste GPU in Ihrem System anzugeben. Weitere Informationen zur Verwendung der Pipeline-Klasse finden Sie in der Hugging Face-Dokumentation zu Pipelines.

Text generieren

Sobald Sie das Gemma-Modell geladen und in einem pipeline-Objekt 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'}]

Eingabeaufforderungsvorlage verwenden

Wenn Sie Inhalte mit komplexeren Prompts generieren, verwenden Sie eine Prompt-Vorlage, um Ihre Anfrage zu strukturieren. Mit einer Prompt-Vorlage können Sie Eingaben von bestimmten Rollen wie user oder model angeben. Sie ist ein erforderliches Format für die Verwaltung von Chat-Interaktionen mit mehreren Durchgängen mit Gemma-Modellen. Das folgende Beispiel zeigt, wie Sie eine Prompt-Vorlage für Gemma erstellen:

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 für Modellgrößen ab 4B Bilddaten als Teil Ihres Prompts verwenden. In diesem Abschnitt wird gezeigt, wie Sie die Transformers-Bibliothek verwenden, um ein Gemma-Modell zu laden und zu konfigurieren, damit es mit Bilddaten und Texteingabe Textausgabe generiert.

Modell laden

Wenn Sie ein Gemma-Modell für die Verwendung mit Bilddaten laden, konfigurieren Sie die Transformer-pipeline-Instanz speziell für die Verwendung mit Bildern. Insbesondere müssen Sie eine Pipelinekonfiguration auswählen, die visuelle Daten verarbeiten kann. Dazu müssen Sie den Parameter task auf "image-text-to-text" setzen, 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
)

Text generieren

Sobald Sie das Gemma-Modell für die Verarbeitung von Bildeingaben mit einer pipeline-Instanz konfiguriert haben, können Sie Prompts mit Bildern an das Modell senden. Verwenden Sie das Token <start_of_image>, um das Bild in den Text Ihres Prompts einzufü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'}]

Eingabeaufforderungsvorlage verwenden

Wenn Sie Inhalte mit komplexeren Prompts generieren, verwenden Sie eine Prompt-Vorlage, um Ihre Anfrage zu strukturieren. Mit einer Prompt-Vorlage können Sie Eingaben von bestimmten Rollen wie user oder model angeben. Sie ist ein erforderliches Format für die Verwaltung von Chat-Interaktionen mit mehreren Durchgängen mit Gemma-Modellen. Das folgende Beispiel zeigt, wie Sie eine Prompt-Vorlage für Gemma erstellen:

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 einfügen, 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 mit Audiodaten und Texteingabe Textausgabe zu generieren.

Python-Pakete installieren

Für die Verwendung von Audioeingabe 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 stellen, 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 zur 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")

Eingabeaufforderungsvorlage verwenden

Wenn Sie Inhalte mit Audio generieren, verwenden Sie eine Prompt-Vorlage, um Ihre Anfrage zu strukturieren. Mit einer Prompt-Vorlage können Sie Eingaben von bestimmten Rollen wie user oder model angeben. Sie ist ein erforderliches Format für die Verwaltung von Chat-Interaktionen mit mehreren Durchgängen mit Gemma-Modellen. Im folgenden Beispielcode sehen Sie, wie Sie eine Prompt-Vorlage für Gemma mit Audioeingabe erstellen:

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 Audiodateien in Ihren Prompt einfügen, indem Sie der Liste content zusätzliche "type": "audio",-Einträge hinzufügen. Wenn Sie Audio-Daten ohne Vorlage als Prompt verwenden, nutzen Sie die <audio_soft_token>-Syntax im Text Ihres Prompts.

Text generieren

Sobald Sie das Gemma-Modell mit einem processor- und einem model-Objekt konfiguriert und einen Prompt mit Audiodaten mithilfe einer Promptvorlage erstellt haben, können Sie den Prompt senden, um eine Ausgabe zu generieren. Im folgenden Beispielcode wird eine Anfrage mit einer Chatvorlage, der Ausgabegenerierung und der Decodierung 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

Weitere Informationen zum Entwickeln und Erkunden mit Gemma-Modellen: