קריאה לפונקציות באמצעות Gemini API


מודלים גנרטיביים יעילים בפתרון סוגים רבים של בעיות. עם זאת, הן מוגבלות על ידי מגבלות כמו:

  • הם קופאים אחרי האימון, וכתוצאה מכך הידע לא מעודכן.
  • הם לא יכולים לשלוח שאילתות לנתונים חיצוניים או לשנות אותם.

קריאה לפונקציות יכולה לעזור לכם להתגבר על חלק מהמגבלות האלה. לפעמים קוראים לקריאה לפונקציה שימוש בכלים כי היא מאפשרת למודל להשתמש בכלים חיצוניים כמו ממשקי API ופונקציות כדי ליצור את התגובה הסופית שלו.

מידע נוסף על קריאה לפונקציות זמין במסמכי העזרה של Google Cloud, כולל רשימה מועילה של תרחישים לדוגמה לקריאה לפונקציות.

יש תמיכה בקריאה לפונקציות ב-Gemini 1.0 Pro, ב-Gemini 1.5 Pro וב-Gemini 1.5 Flash.

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

  1. כותבים פונקציה שיכולה לספק למודל את המידע הדרוש לו כדי ליצור את התגובה הסופית (לדוגמה, הפונקציה יכולה להפעיל API חיצוני).

  2. יוצרים הצהרת פונקציה שמתארת את הפונקציה ואת הפרמטרים שלה.

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

  4. מגדירים את האפליקציה כך שהמודל יוכל לשלוח את המידע הנדרש כדי שהאפליקציה תוכל לבצע קריאה לפונקציה.

  5. מעבירים את התשובה של הפונקציה בחזרה למודל כדי שהמודל יוכל ליצור את התשובה הסופית שלו.

מעבר להטמעת הקוד

סקירה כללית של דוגמה לקריאה לפונקציה

כששולחים בקשה למודל, אפשר גם לספק לו קבוצה של "כלים" (כמו פונקציות) שבהם הוא יכול להשתמש כדי ליצור את התשובה הסופית. כדי להשתמש בפונקציות האלה ולקרוא להן ('קריאה לפונקציה'), המודל והאפליקציה צריכים להעביר מידע זה לזה, ולכן הדרך המומלצת להשתמש בקריאה לפונקציה היא דרך ממשק הצ'אט עם מספר סבבים.

נניח שיש לכם אפליקציה שבה משתמש יכול להזין הנחיה כמו: What was the weather in Boston on October 17, 2024?.

יכול להיות שהמודלים של Gemini לא יודעים את המידע הזה על מזג האוויר. עם זאת, נניח שאתם מכירים ממשק API חיצוני של שירות מזג אוויר שיכול לספק אותם. אפשר להשתמש בקריאה לפונקציה כדי לתת למודל של Gemini מסלול ל-API הזה ומידע על מזג האוויר בו.

קודם כל, כותבים באפליקציה פונקציה fetchWeather שמקיימת אינטראקציה עם ה-API החיצוני ההיפותטי הזה, שיש לו את הקלט והפלט הבאים:

פרמטר סוג חובה תיאור
קלט
location אובייקט כן שם העיר והמדינה (State) שלגביהם ניתן לקבל את תחזית מזג האוויר.
יש תמיכה רק בערים בארה"ב. תמיד חייב להיות אובייקט בתצוגת עץ של city ו-state.
date String כן התאריך שבו רוצים לאחזר את מזג האוויר (הפורמט חייב להיות YYYY-MM-DD).
פלט
temperature מספר שלם כן טמפרטורה (בפרנהייט)
chancePrecipitation String כן סיכוי למשקעים (באחוזים)
cloudConditions String כן תנאים ב-Cloud (אחד מתוך clear, partlyCloudy, mostlyCloudy, cloudy)

כשמפעילים את המודל, צריך להודיע לו על קיומה של הפונקציה fetchWeather ואיך אפשר להשתמש בה כדי לעבד בקשות נכנסות, במקרה הצורך. התהליך הזה נקרא 'הצהרת פונקציה'. המודל לא קורא לפונקציה ישירות. במקום זאת, כשהמודל מעבד את הבקשה הנכנסת, הוא מחליט אם הפונקציה fetchWeather יכולה לעזור לו להשיב לבקשה. אם המודל מחליט שהפונקציה אכן יכולה להיות מועילה, המודל יוצר נתונים מובְנים שיעזרו לאפליקציה לקרוא לפונקציה.

בודקים שוב את הבקשה הנכנסת: What was the weather in Boston on October 17, 2024?. סביר להניח שהמודל יחליט שהפונקציה fetchWeather יכולה לעזור לו ליצור תשובה. המודל יבדוק אילו פרמטרים של קלט נדרשים ל-fetchWeather, ולאחר מכן ייצור נתוני קלט מובְנים לפונקציה שנראים בערך כך:

{
  functionName: fetchWeather,
  location: {
    city: Boston,
    state: Massachusetts  // the model can infer the state from the prompt
  },
  date: 2024-10-17
}

המודל מעביר את נתוני הקלט המובְנים האלה לאפליקציה כדי שהאפליקציה תוכל להפעיל את הפונקציה fetchWeather. כשהתנאים המטאורולוגיים מגיעים לאפליקציה מה-API, היא מעבירה את המידע למודל. נתוני מזג האוויר האלה מאפשרים למודל להשלים את העיבוד הסופי וליצור את התגובה לבקשה הראשונית של What was the weather in Boston on October 17, 2024?

המודל עשוי לספק תשובה סופית בשפה טבעית, כמו: On October 17, 2024, in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

תרשים שבו מוצג איך קריאה לפונקציה כוללת אינטראקציה של המודל עם פונקציה באפליקציה 

הטמעת קריאה לפונקציות

לפני שמתחילים

אם עדיין לא עשיתם זאת, כדאי לעיין במדריך למתחילים בנושא ערכות ה-SDK של Vertex AI in Firebase. חשוב לוודא שכל הפעולות הבאות בוצעו:

  1. מגדירים פרויקט Firebase חדש או קיים, כולל שימוש בתוכנית התמחור Blaze והפעלת ממשקי ה-API הנדרשים.

  2. קישור האפליקציה ל-Firebase, כולל רישום האפליקציה והוספת הגדרות Firebase לאפליקציה.

  3. מוסיפים את ה-SDK ומפעילים את השירות Vertex AI ואת המודל הגנרטיבי באפליקציה.

אחרי שמחברים את האפליקציה ל-Firebase, מוסיפים את ה-SDK ומפעילים את השירות Vertex AI ואת המודל הגנרטיבי, אפשר לבצע קריאה ל-Gemini API.

השלבים הנותרים במדריך הזה מראים איך להטמיע הגדרה של קריאה לפונקציה, בדומה לתהליך העבודה שמתואר במאמר סקירה כללית של דוגמה לקריאה לפונקציה (עיינו בחלק העליון בדף הזה).

דוגמת הקוד המלאה של הקריאה לפונקציה הזו מופיעה בהמשך הדף.

שלב 1: כותבים את הפונקציה

נניח שיש לכם אפליקציה שבה משתמש יכול להזין הנחיה כמו: What was the weather in Boston on October 17, 2024?. יכול להיות שהמודלים של Gemini לא יודעים את המידע הזה על מזג האוויר. עם זאת, נניח שאתם מכירים API של שירות מזג אוויר חיצוני שיכול לספק אותו. הדוגמה במדריך הזה מבוססת על ה-API החיצוני ההיפותטי הזה.

כותבים באפליקציה את הפונקציה שתהיה בקשר עם ה-API החיצוני ההיפותטי ותספק למודל את המידע הדרוש כדי ליצור את הבקשה הסופית. בדוגמה הזו של תחזית מזג האוויר, זו תהיה פונקציית fetchWeather שתפעיל את הקריאה לממשק ה-API החיצוני ההיפותטי הזה.

שלב 2: יצירת הצהרה לגבי פונקציה

יוצרים את הצהרת הפונקציה שתספקו בהמשך למודל (השלב הבא במדריך הזה).

בהצהרה, כדאי לכלול כמה שיותר פרטים בתיאורים של הפונקציה והפרמטרים שלה.

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

חשוב לשים לב לנקודות הבאות לגבי הסכימה שאתם מספקים:

  • אתם צריכים לספק הצהרות על פונקציות בפורמט סכימה שתואם לסכימת OpenAPI. Vertex AI תומך בסכימה של OpenAPI באופן מוגבל.

    • המאפיינים הבאים נתמכים: type, nullable, required, format, description, properties, items, enum.

    • המאפיינים הבאים לא נתמכים: default, ‏ optional,‏ maximum, ‏ oneOf.

  • כברירת מחדל, ב-SDKs של Vertex AI in Firebase, כל השדות נחשבים חובה, אלא אם מציינים אותם כאופציונליים במערך optionalProperties. בשדות האופציונליים האלה, המודל יכול לאכלס את השדות או לדלג עליהם. חשוב לזכור שההתנהגות הזו שונה מהתנהגות ברירת המחדל של Vertex AI Gemini API.

לשיטות מומלצות שקשורות להצהרות על פונקציות, כולל טיפים לשמות ותיאורים, תוכלו לעיין בקטע שיטות מומלצות במסמכי התיעוד של Google Cloud.

כך כותבים הצהרת פונקציה:

שלב 3: מציינים את הצהרת הפונקציה במהלך האינטוליזציה של המודל

המספר המקסימלי של הצהרות פונקציה שאפשר לציין בבקשה הוא 128. בקטע התנהגויות ואפשרויות נוספות בהמשך הדף מוסבר איך המודל יכול לבחור מבין הפונקציות, ואיך אפשר לשלוט בבחירה הזו (באמצעות toolConfig כדי להגדיר את מצב הקריאה של הפונקציה).

איך בוחרים מודל Gemini, ואם רוצים גם מיקום, שמתאימים לתרחיש לדוגמה ולאפליקציה.

שלב 4: קריאה לפונקציה כדי להפעיל את ה-API החיצוני

אם המודל יחליט שהפונקציה fetchWeather יכולה לעזור לו ליצור תשובה סופית, האפליקציה צריכה לבצע את הקריאה בפועל לפונקציה הזו באמצעות נתוני הקלט המובְנים שסופקו על ידי המודל.

מאחר שצריך להעביר מידע הלוך ושוב בין המודל לאפליקציה, הדרך המומלצת להשתמש בקריאה לפונקציה היא דרך ממשק הצ'אט עם מספר סבבים.

בקטע הקוד הבא מוצג איך האפליקציה מקבלת הודעה שהמודל רוצה להשתמש בפונקציה fetchWeather. בנוסף, אפשר לראות שהמודל סיפק את ערכי הפרמטרים הנדרשים של הקלט לקריאה לפונקציה (ול-API החיצוני שמבוסס עליה).

בדוגמה הזו, הבקשה הנכנסת הכילה את ההנחיה What was the weather in Boston on October 17, 2024?. מההנחיה הזו, המודל הסיק מהם הפרמטרים של הקלט שנדרשים על ידי הפונקציה fetchWeather (כלומר city, state ו-date).

שלב 5: מעבירים את הפלט של הפונקציה למודל כדי ליצור את התגובה הסופית

אחרי שפונקציית fetchWeather מחזירה את נתוני מזג האוויר, האפליקציה צריכה להעביר אותם חזרה למודל.

לאחר מכן, המודל מבצע את העיבוד הסופי ומפיק תשובה סופית בשפה טבעית, כמו: On October 17, 2024 in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

התנהגויות ואפשרויות נוספות

בהמשך מפורטות כמה התנהגויות נוספות של קריאות לפונקציות שצריך להתאים לקוד ואפשרויות שאפשר לשלוט בהן.

יכול להיות שהמודל יבקש לקרוא שוב לפונקציה או לפונקציה אחרת.

אם התשובה מקריאה אחת של פונקציה לא מספיקה כדי שהמודל ייצור את התשובה הסופית שלו, יכול להיות שהמודל יבקש קריאה נוספת של פונקציה או קריאה לפונקציה שונה לגמרי. האפשרות השנייה יכולה לקרות רק אם מספקים יותר מפונקציה אחת למודל ברשימת הצהרות הפונקציה.

האפליקציה צריכה להתאים את עצמה לאפשרות שהמודל יבקש קריאות פונקציה נוספות.

יכול להיות שהמודל יבקש להפעיל כמה פונקציות בו-זמנית.

אפשר לספק עד 128 פונקציות ברשימה של הצהרות הפונקציות למודל. לכן, יכול להיות שהמודל יחליט שהוא זקוק למספר פונקציות כדי לעזור לו ליצור את התשובה הסופית. יכול להיות שהיא תחליט להפעיל חלק מהפונקציות האלה בו-זמנית – זה נקרא קריאה לפונקציות במקביל.

האפליקציה צריכה להתאים את עצמה לאפשרות שהמודל יבקש להריץ כמה פונקציות בו-זמנית, והיא צריכה לספק חזרה למודל את כל התגובות מהפונקציות.

אפשר להפעיל קריאות פונקציה במקביל ב-Gemini 1.5 Pro וב-Gemini 1.5 Flash.

אתם יכולים לקבוע איך ואם המודל יכול לבקש להפעיל פונקציות.

אפשר להציב אילוצים מסוימים על האופן שבו המודלים צריכים להשתמש בהצהרות הפונקציות שסופקו, ואם הם צריכים להשתמש בהן בכלל. הפעולה הזו נקראת הגדרת מצב הקריאה לפונקציה. הנה כמה דוגמאות:

  • במקום לאפשר למודל לבחור בין מענה מיידי של שפה טבעית לבין קריאה לפונקציה, אפשר לאלץ אותו להשתמש תמיד בקריאות לפונקציות. הפעולה הזו נקראת קריאה לפונקציה מאולצת.

  • אם מספקים כמה הצהרות על פונקציות, אפשר להגביל את המודל כך שישתמש רק בקבוצת משנה של הפונקציות שסופקו.

כדי להטמיע את האילוצים (או המצבים) האלה, מוסיפים הגדרת כלי (toolConfig) יחד עם ההנחיה והצהרות הפונקציות. בהגדרות הכלי אפשר לציין אחד מהמצבים הבאים. המצב השימושי ביותר הוא ANY.

מצב תיאור
AUTO התנהגות המודל שמוגדרת כברירת מחדל. המודל מחליט אם להשתמש בקריאה לפונקציה או בתגובה בשפה טבעית.
ANY המודל חייב להשתמש בקריאות פונקציה ('forced function calling'). כדי להגביל את המודל לקבוצת משנה של פונקציות, מציינים את שמות הפונקציות המותרות ב-allowedFunctionNames.
NONE אסור להשתמש בקריאות פונקציה במודל. ההתנהגות הזו זהה לבקשת מודל ללא הצהרות על פונקציות משויכות.

תמיכה במצב קריאה לפונקציה קיימת ב-Gemini 1.5 Pro וב-Gemini 1.5 Flash.

מה עוד אפשר לעשות?

יכולות נוספות של Gemini API

איך שולטים ביצירת תוכן

אפשר גם להתנסות בהנחיות ובהגדרות של מודלים באמצעות הפקודה Vertex AI Studio.

מידע נוסף על המודלים של Gemini

כאן תוכלו לקרוא מידע נוסף על המודלים הזמינים לתרחישי שימוש שונים, ועל המכסות והתמחור שלהם.


שליחת משוב על חוויית השימוש ב-Vertex AI in Firebase