הפעלת 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, בוחרים את המתג כדי להפעיל את הגישה.

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

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

אחרי שמטעינים את מודל 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 לשימוש עם נתוני תמונות, אתם צריכים להגדיר את מופע ה-Transformer 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. כדי להריץ את מודל Gemma ולשלוח בקשות עם נתוני אודיו, מתקינים את ספריות Hugging Face כפי שמתואר בהמשך.

# 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
• ביצוע התאמה אישית מדויקת (fine-tuning) והסקה מבוזרת במודלים של Gemma
• שימוש במודלים הפתוחים של Gemma עם Vertex AI
• ביצוע שיפורים ועדכונים ב-Gemma באמצעות Keras ופריסה ב-Vertex AI