הפעלת Gemma עם Hugging Face Transformers

לצפייה ב-ai.google.dev

הרצה ב-Google Colab

הרצה ב-Kaggle

פתיחה ב-Vertex AI

צפייה במקור ב-GitHub

יצירת טקסט, סיכום וניתוח תוכן הם רק חלק מהמשימות שאפשר לבצע באמצעות מודלים פתוחים של Gemma. במדריך הזה נסביר איך להתחיל להריץ את Gemma באמצעות Hugging Face Transformers, תוך שימוש בקלט של טקסט ותמונות כדי ליצור תוכן טקסטואלי. ספריית ה-Transformers Python מספקת API לגישה למודלים של AI גנרטיבי שעברו אימון מראש, כולל Gemma. מידע נוסף מופיע במאמר בנושא Transformers.

הגדרה

לפני שמתחילים את המדריך הזה, צריך לבצע את השלבים הבאים:

• כדי לקבל גישה ל-Gemma, צריך להתחבר ל-Hugging Face ולבחור באפשרות Acknowledge license (אישור רישיון) עבור מודל Gemma.
• בוחרים זמן ריצה של Colab עם מספיק משאבים להרצת מודל Gemma בגודל שרוצים להריץ. מידע נוסף
• יוצרים טוקן גישה ל-Hugging Face ומוסיפים אותו לסביבת Colab.

הגדרת טוקן גישה

מוסיפים את אסימון הגישה ל-Colab כדי להוריד מודלים של Gemma מאתר האינטרנט של Hugging Face. כדי לשמור את האסימון בצורה מאובטחת בלי להוסיף אותו לקוד הפעיל, אפשר להשתמש בתכונה Secrets ב-Colab.

כדי להוסיף את טוקן הגישה של Hugging Face כסוד:

1. פותחים את הכרטיסייה 'סודות' על ידי לחיצה על סמל המפתח בצד ימין של הממשק, או בוחרים באפשרות כלים > לוח פקודות, מקלידים secrets ומקישים על Enter.
2. בוחרים באפשרות הוספת סוד חדש כדי להוסיף רשומה חדשה של סוד.
3. בשדה שם מזינים HF_TOKEN.
4. בשדה Value (ערך), מזינים את הטקסט של אסימון הגישה של Hugging Face.
5. בשדה Notebook access (גישה ל-Notebook), מעבירים את המתג למצב מופעל כדי לאפשר גישה.

אחרי שמזינים את טוקן הגישה כ-HF_TOKEN ואת הערך, אפשר לגשת אליו ולהגדיר אותו בסביבת notebook של Colab באמצעות הקוד הבא:

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

מתקינים את הספריות של Hugging Face שנדרשות להרצת מודל Gemma ולשליחת בקשות.

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

יצירת טקסט מטקסט

הדרך הכי פשוטה להשתמש ב-Gemma היא להזין טקסט להנחיה של מודל Gemma כדי לקבל תגובה טקסטואלית. השיטה הזו פועלת כמעט עם כל הווריאציות של Gemma. בקטע הזה נראה איך להשתמש בספריית Hugging Face Transformers כדי לטעון ולהגדיר מודל Gemma ליצירת טקסט מטקסט.

טעינת מודל

משתמשים בספריות torch ו-transformers כדי ליצור מופע של מחלקת pipeline להרצת מודל עם Gemma. כשמשתמשים במודל כדי ליצור פלט או לבצע הוראות, כדאי לבחור במודל שעבר כוונון להוראות (IT), שבדרך כלל כולל את המחרוזת it במזהה המודל. באמצעות האובייקט pipeline, מציינים את הווריאציה של Gemma שבה רוצים להשתמש, את סוג המשימה שרוצים לבצע, ובאופן ספציפי "text-generation" ליצירת טקסט על סמך טקסט, כמו שמוצג בדוגמת הקוד הבאה:

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 תומך רק בכמה הגדרות של task ליצירה. מידע נוסף על ההגדרות הזמינות של task זמין במאמרי העזרה בנושא Hugging Face Pipelines task(). אפשר להשתמש בסוג הנתונים torch torch.bfloat16 כדי לצמצם את הדיוק של המודל ואת משאבי המחשוב שנדרשים, בלי להשפיע באופן משמעותי על איכות הפלט של המודל. בהגדרה device, אפשר להשתמש ב-"cuda" ל-Colab, ב-"msu" למכשירי iOS או פשוט להגדיר את הערך 0 (אפס) כדי לציין את ה-GPU הראשון במערכת. מידע נוסף על השימוש במחלקת Pipeline זמין במסמכי העזרה של Hugging Face בנושא Pipelines.

הרצת יצירת טקסט

אחרי שמעמיסים את מודל Gemma ומגדירים אותו באובייקט pipeline, אפשר לשלוח הנחיות למודל. בדוגמת הקוד הבאה מוצגת בקשה בסיסית באמצעות הפרמטר 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'}]

שימוש בתבנית של הנחיה

כשיוצרים תוכן באמצעות הנחיות מורכבות יותר, כדאי להשתמש בתבנית הנחיה כדי לבנות את הבקשה. תבנית הנחיה מאפשרת לכם לציין קלט מתפקידים ספציפיים, כמו user או model, והיא פורמט חובה לניהול שיחה עם זיכרון עם מודלים של Gemma. בדוגמת הקוד הבאה אפשר לראות איך יוצרים תבנית של הנחיה ל-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)

יצירת טקסט מנתוני תמונה

החל מ-Gemma 3, לגבי גדלי מודלים של 4B ומעלה, אפשר להשתמש בנתוני תמונות כחלק מההנחיה. בקטע הזה מוסבר איך להשתמש בספריית Transformers כדי לטעון ולהגדיר מודל Gemma לשימוש בנתוני תמונות ובקלט טקסט כדי ליצור פלט טקסט.

טעינת מודל

כשמעלים מודל Gemma לשימוש עם נתוני תמונות, צריך להגדיר את מופע הטרנספורמר pipeline במיוחד לשימוש עם תמונות. בפרט, צריך לבחור הגדרת צינור שיכולה לטפל בנתונים חזותיים על ידי הגדרת הפרמטר task לערך "image-text-to-text", כמו בדוגמה הבאה של קוד:

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
)

הרצת יצירת טקסט

אחרי שמגדירים את מודל Gemma לטיפול בקלט של תמונות באמצעות מופע pipeline, אפשר לשלוח למודל הנחיות עם תמונות. משתמשים בטוקן <start_of_image> כדי להוסיף את התמונה לטקסט של ההנחיה. בדוגמת הקוד הבאה מוצגת בקשה בסיסית באמצעות הפרמטר 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'}]

שימוש בתבנית של הנחיה

כשיוצרים תוכן באמצעות הנחיות מורכבות יותר, כדאי להשתמש בתבנית הנחיה כדי לבנות את הבקשה. תבנית הנחיה מאפשרת לכם לציין קלט מתפקידים ספציפיים, כמו user או model, והיא פורמט חובה לניהול שיחה עם זיכרון עם מודלים של Gemma. בדוגמת הקוד הבאה אפשר לראות איך יוצרים תבנית של הנחיה ל-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)

אפשר לכלול כמה תמונות בהנחיה על ידי הוספת עוד רשומות "type": "image", לרשימה content.

יצירת טקסט מנתוני אודיו

עם Gemma 3n, אתם יכולים להשתמש בנתוני אודיו כחלק מההנחיה. בקטע הזה מוסבר איך להשתמש בספריית Transformers כדי לטעון ולהגדיר מודל Gemma לשימוש בנתוני אודיו ובקלט טקסט כדי ליצור פלט טקסט.

התקנת חבילות Python

כדי להשתמש בקלט אודיו עם Gemma, צריך גרסה עדכנית של ספריות Transformers. מתקינים את הספריות של Hugging Face כדי להריץ את מודל Gemma ולשלוח בקשות עם נתוני אודיו, כמו בדוגמה שלמטה.

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

טעינת מודל

כשמעלים מודל Gemma לשימוש עם נתוני אודיו, מגדירים את מופע ה-Transformer במיוחד לשימוש עם נתוני אודיו. בפרט, אתם צריכים להגדיר אובייקט processor ואובייקט model באמצעות המחלקות AutoProcessor ו-AutoModelForImageTextToText, כמו שמוצג בדוגמת הקוד הבאה:

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

שימוש בתבנית של הנחיה

כשיוצרים תוכן עם אודיו, כדאי להשתמש בתבנית של הנחיה כדי לבנות את הבקשה. תבנית הנחיה מאפשרת לכם לציין קלט מתפקידים ספציפיים, כמו user או model, והיא פורמט חובה לניהול שיחה עם זיכרון עם מודלים של Gemma. בדוגמת הקוד הבאה אפשר לראות איך יוצרים תבנית הנחיה ל-Gemma עם קלט של נתוני אודיו:

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

אפשר לכלול כמה קובצי אודיו בהנחיה על ידי הוספת עוד רשומות "type": "audio", לרשימה content. אם אתם מזינים הנחיה עם נתוני אודיו, אבל בלי תבנית, צריך להשתמש בתחביר <audio_soft_token> בטקסט של ההנחיה.

הרצת יצירת טקסט

אחרי שמגדירים את מודל Gemma עם אובייקט processor ואובייקט model, ויוצרים הנחיה עם נתוני אודיו באמצעות תבנית הנחיה, אפשר לשלוח את ההנחיה כדי ליצור פלט. בדוגמת הקוד הבאה מוצגת בקשה באמצעות תבנית צ'אט, יצירת פלט ופענוח של התגובה:

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

השלבים הבאים

אפשר ליצור ולחקור עוד באמצעות מודלים של Gemma:

• ביצוע התאמה עדינה של Gemma למשימות שקשורות לטקסט באמצעות Hugging Face Transformers
• איך מבצעים כוונון עדין של Gemma למשימות שקשורות לראייה באמצעות Hugging Face Transformers
• ביצוע התאמה עדינה והסקת מסקנות מבוזרות במודלים של Gemma
• שימוש במודלים פתוחים של Gemma עם Vertex AI
• כוונון של Gemma באמצעות Keras והטמעה ב-Vertex AI