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 w GitHubie

Generowanie tekstu, podsumowywanie 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 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 Pythona Transformers udostępnia interfejs API do uzyskiwania dostępu do wstępnie wytrenowanych modeli generatywnej AI, w tym Gemmy. Więcej informacji znajdziesz w dokumentacji Transformerów.

Konfiguracja

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

  • Aby uzyskać dostęp do Gemmy, zaloguj się w Hugging Face i wybierz Potwierdź licencję dla modelu Gemma.
  • 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 ze strony 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 tajny, 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 za pomocą Gemy. Jeśli używasz modelu do generowania danych wyjściowych lub wykonywania instrukcji, wybierz model dostrojony do instrukcji (IT), który zwykle ma symbol it w ciągu identyfikatora modelu. 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 Colab lub "msu" na urządzeniach 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. Poniższy 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

Podczas generowania 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 wieloetapowymi interakcjami na czacie 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 pokazujemy, 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. Aby dodać obraz do tekstu promptu, użyj tokena <start_of_image>. Poniższy 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

Podczas generowania 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 wieloetapowymi interakcjami na czacie 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ć wejścia audio z Gammą, 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 wieloetapowymi interakcjami na czacie 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 promptu z danymi audio za pomocą szablonu promptu możesz wysłać prompt, 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 odkrywaj więcej dzięki modelom Gemma: