קריאה לפונקציות באמצעות 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.

  • כברירת מחדל, בערכות SDK של 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 המודל צריך להשתמש בקריאות לפונקציות ('קריאות לפונקציות מאולצות'). כדי להגביל את המודל לקבוצת משנה של פונקציות, צריך לציין את שמות הפונקציות המותרות ב-allowedFunctionNames.
NONE המודל לא יכול להשתמש בקריאות לפונקציות. ההתנהגות הזו מקבילה לבקשה של מודל ללא הצהרות על פונקציה כלשהי.

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

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

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

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

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

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

מידע על המודלים הזמינים לתרחישים שונים לדוגמה ועל המכסות והתמחור שלהם.


נשמח לקבל ממך משוב על החוויה שלך עם Vertex AI in Firebase