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