Uruchom Gemma z użyciem funkcji Hugging Face Transformers

Wyświetl na ai.google.dev Uruchom w Google Colab Uruchom w Kaggle Otwórz w Vertex AI Wyświetl źródło na GitHubie

Generowanie tekstu, tworzenie podsumowań i analizowanie treści to tylko niektóre z zadań, które możesz wykonać za pomocą otwartych modeli Gemma. Z tego samouczka dowiesz się, jak zacząć korzystać z modelu Gemma za pomocą Hugging Face Transformers, używając zarówno tekstu, jak i obrazu jako danych wejściowych do generowania treści tekstowych. Biblioteka Transformers w języku Python udostępnia interfejs API do uzyskiwania dostępu do wstępnie wytrenowanych modeli generatywnej AI, w tym Gemmy. Więcej informacji znajdziesz w dokumentacji Transformers.

Konfiguracja

Zanim rozpoczniesz wykonywanie zadań z tego samouczka, wykonaj te czynności:

  • Aby uzyskać dostęp do Gemy, zaloguj się w Hugging Face i kliknij Potwierdź licencję w przypadku modelu Gemy.
  • Wybierz środowisko wykonawcze Colab z zasobami wystarczającymi do uruchomienia modelu Gemma o wybranym rozmiarze. Więcej informacji
  • Wygeneruj token dostępu Hugging Face i dodaj go do środowiska Colab.

Konfigurowanie tokena dostępu

Dodaj token dostępu do Colab, aby umożliwić pobieranie modeli Gemma z witryny Hugging Face. Użyj funkcji Secrets w Colab, aby bezpiecznie zapisać token bez dodawania go do kodu roboczego.

Aby dodać token dostępu Hugging Face jako obiekt tajny:

  1. Otwórz kartę wpisów tajnych, klikając ikonę klucza po lewej stronie interfejsu, lub wybierz Narzędzia > Paleta poleceń, wpisz secrets i naciśnij Enter.
  2. Aby dodać nowy wpis obiektu tajnego, kliknij Dodaj nowy obiekt tajny.
  3. W polu Nazwa wpisz HF_TOKEN.
  4. W polu Value (Wartość) wpisz tekst tokena dostępu Hugging Face.
  5. W polu Dostęp do notatnika wybierz przełącznik, aby włączyć dostęp.

Po wpisaniu tokena dostępu jako HF_TOKEN i wartości możesz uzyskać do niego dostęp i ustawić go w środowisku notatnika Colab za pomocą tego kodu:

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)

Instalowanie pakietów Pythona

Zainstaluj biblioteki Hugging Face wymagane do uruchomienia modelu Gemma i wysyłania żądań.

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

Generowanie tekstu na podstawie tekstu

Wysyłanie do modelu Gemma promptów tekstowych w celu uzyskania odpowiedzi tekstowej to najprostszy sposób korzystania z Gemma, który działa w przypadku niemal wszystkich wariantów tego modelu. W tej sekcji dowiesz się, jak za pomocą biblioteki Hugging Face Transformers wczytać i skonfigurować model Gemma do generowania tekstu na podstawie tekstu.

Wczytaj model

Użyj bibliotek torch i transformers, aby utworzyć instancję klasy pipeline wykonania modelu z Gemma. Jeśli używasz modelu do generowania danych wyjściowych lub wykonywania instrukcji, wybierz model dostrojony pod kątem instrukcji (IT), który zwykle ma w ciągu identyfikatora modelu symbol it. Za pomocą obiektu pipeline możesz określić wariant modelu Gemma, którego chcesz użyć, oraz typ zadania, które chcesz wykonać, a konkretnie "text-generation" w przypadku generowania tekstu na podstawie tekstu, jak pokazano w tym przykładzie kodu:

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
)

Model Gemma obsługuje tylko kilka task ustawień generowania. Więcej informacji o dostępnych ustawieniach task znajdziesz w dokumentacji funkcji task() w Hugging Face Pipelines. Użyj typu danych torch torch.bfloat16, aby zmniejszyć precyzję modelu i potrzebne zasoby obliczeniowe bez znaczącego wpływu na jakość danych wyjściowych modelu. W przypadku ustawienia device możesz użyć wartości "cuda" w przypadku Colab lub "msu" w przypadku urządzeń z iOS albo po prostu ustawić wartość 0 (zero), aby określić pierwszy procesor GPU w systemie. Więcej informacji o korzystaniu z klasy Pipeline znajdziesz w dokumentacji Hugging Face Pipelines.

Uruchamianie generowania tekstu

Gdy model Gemma zostanie wczytany i skonfigurowany w obiekcie pipeline, możesz wysyłać do niego prompty. Ten przykładowy kod pokazuje podstawowe żądanie z użyciem parametru 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'}]

Używanie szablonu prompta

Gdy generujesz treści za pomocą bardziej złożonych promptów, użyj szablonu promptu, aby uporządkować żądanie. Szablon promptu umożliwia określanie danych wejściowych z określonych ról, takich jak user lub model, i jest wymaganym formatem do zarządzania czatem wieloetapowym z modelami Gemma. Poniższy przykładowy kod pokazuje, jak utworzyć szablon prompta dla modelu 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)

Generowanie tekstu na podstawie danych obrazu

Od modelu Gemma 3 w przypadku modeli o rozmiarze 4B i większym możesz używać danych obrazów w ramach promptu. W tej sekcji dowiesz się, jak używać biblioteki Transformers do wczytywania i konfigurowania modelu Gemma, aby używać danych obrazu i tekstu wejściowego do generowania tekstu wyjściowego.

Wczytaj model

Podczas wczytywania modelu Gemma do użycia z danymi obrazu konfigurujesz instancję Transformer pipeline specjalnie do użycia z obrazami. Musisz w szczególności wybrać konfigurację potoku, która może obsługiwać dane wizualne, ustawiając parametr task na "image-text-to-text", jak pokazano w tym przykładzie kodu:

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
)

Uruchamianie generowania tekstu

Gdy model Gemma będzie skonfigurowany do obsługi danych wejściowych w postaci obrazów za pomocą instancji pipeline, możesz wysyłać do niego prompty z obrazami. Użyj tokena <start_of_image>, aby dodać obraz do tekstu prompta. Ten przykładowy kod pokazuje podstawowe żądanie z użyciem parametru 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'}]

Używanie szablonu prompta

Gdy generujesz treści za pomocą bardziej złożonych promptów, użyj szablonu promptu, aby uporządkować żądanie. Szablon promptu umożliwia określanie danych wejściowych z określonych ról, takich jak user lub model, i jest wymaganym formatem do zarządzania czatem wieloetapowym z modelami Gemma. Poniższy przykładowy kod pokazuje, jak utworzyć szablon prompta dla modelu 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)

W prompcie możesz uwzględnić wiele obrazów, dodając kolejne wpisy "type": "image", do listy content.

Generowanie tekstu na podstawie danych audio

Dzięki Gemma 3n możesz używać danych audio w ramach promptu. W tej sekcji dowiesz się, jak za pomocą biblioteki Transformers wczytać i skonfigurować model Gemma, aby używać danych audio i tekstowych do generowania tekstu wyjściowego.

Instalowanie pakietów Pythona

Aby używać danych wejściowych audio w przypadku Gemy, musisz mieć najnowszą wersję bibliotek Transformers. Zainstaluj biblioteki Hugging Face do uruchamiania modelu Gemma i wysyłania żądań z danymi audio, jak pokazano poniżej.

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

Wczytaj model

Podczas wczytywania modelu Gemma do użycia z danymi audio konfigurujesz instancję Transformer specjalnie do użycia z danymi audio. W szczególności musisz zdefiniować obiekty processor i model za pomocą klas AutoProcessor i AutoModelForImageTextToText, jak pokazano w tym przykładzie kodu:

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

Używanie szablonu prompta

Podczas generowania treści z dźwiękiem użyj szablonu prompta, aby uporządkować żądanie. Szablon promptu umożliwia określanie danych wejściowych z określonych ról, takich jak user lub model, i jest wymaganym formatem do zarządzania czatem wieloetapowym z modelami Gemma. Poniższy przykładowy kod pokazuje, jak utworzyć szablon prompta dla modelu Gemma z danymi 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"},
        ]
    }
]

Możesz dodać do prompta wiele plików audio, umieszczając dodatkowe wpisy "type": "audio", na liście content. Jeśli używasz promptu z danymi audio, ale bez szablonu, użyj w tekście promptu składni <audio_soft_token>.

Uruchamianie generowania tekstu

Po skonfigurowaniu modelu Gemma z obiektami processor i model oraz utworzeniu prompta z danymi audio za pomocą szablonu prompta możesz wysłać prompta, aby wygenerować dane wyjściowe. Poniższy przykładowy kod pokazuje żądanie z użyciem szablonu czatu, generowanie danych wyjściowych i dekodowanie odpowiedzi:

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

Dalsze kroki

Twórz i eksploruj więcej dzięki modelom Gemma: