קריאה לפונקציות באמצעות 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 אובייקט כן שם העיר והמדינה שבה רוצים לקבל את תחזית מזג האוויר.
יש תמיכה רק בערים בארה"ב. תמיד חייב להיות אובייקט בתצוגת עץ של 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 חדש או קיים, כולל שימוש בתוכנית התמחור והתשלומים של Bllaze ומפעילים את ממשקי ה-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