הפעלת 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 ולבחור באפשרות אישור רישיון עבור מודל Gemma.
• בוחרים סביבת ריצה של Colab עם מספיק משאבים להרצת מודל Gemma בגודל הרצוי. מידע נוסף
• יוצרים טוקן גישה של Hugging Face ומוסיפים אותו לסביבת Colab.

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

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

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

1. פותחים את הכרטיסייה 'סודות' על ידי לחיצה על סמל המפתח בצד ימין של הממשק, או בוחרים באפשרות כלים > לוח פקודות, מקלידים secrets ומקישים על Enter.
2. בוחרים באפשרות הוספת סוד חדש כדי להוסיף רשומה חדשה של סוד.
3. בשדה שם מזינים HF_TOKEN.
4. בשדה ערך, מזינים את הטקסט של אסימון הגישה של 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 זמין במאמרי העזרה בנושא 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
• איך מבצעים Fine-tuning של Gemma באמצעות Keras ופורסים אותו ב-Vertex AI