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

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

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

דוגמה לקריאה לפונקציה זמינה במחברות 'light bot'.

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

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

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

הצהרות על פונקציות

כשמטמיעים קריאה לפונקציה בהנחיה, יוצרים אובייקט tools שמכיל function declarations אחד או יותר. מגדירים פונקציות באמצעות JSON, במיוחד באמצעות קבוצת משנה נבחרת של הפורמט OpenAPI schema. הצהרת פונקציה אחת יכולה לכלול את הפרמטרים הבאים:

  • name (מחרוזת): המזהה הייחודי של הפונקציה בקריאת ה-API.
  • description (מחרוזת): הסבר מקיף על המטרה והיכולות של הפונקציה.
  • parameters (אובייקט): מגדיר את נתוני הקלט הנדרשים לפונקציה.
    • type (מחרוזת): מציין את סוג הנתונים הכולל, למשל object.
    • properties (אובייקט): רשימה של פרמטרים נפרדים, כל אחד עם:
      • type (מחרוזת): סוג הנתונים של הפרמטר, למשל string, ‏ integer, ‏ boolean.
      • description (מחרוזת): הסבר ברור על המטרה של הפרמטר ועל הפורמט הצפוי.
    • required (מערך): מערך של מחרוזות שמציג את שמות הפרמטרים שחייבים להופיע כדי שהפונקציה תפעל.

דוגמאות לקוד של הצהרת פונקציה באמצעות פקודות cURL מפורטות בקטע דוגמאות לקריאה לפונקציות. דוגמאות ליצירת הצהרות על פונקציות באמצעות ערכות ה-SDK של Gemini API מפורטות במדריך בנושא קריאה לפונקציות.

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

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

  • name: עדיף להשתמש בשמות ברורים ותיאורים ללא רווחים, נקודות (.) או מקפים (-). במקום זאת, כדאי להשתמש בתווים של קו תחתון (_) או באותיות קטנות ואז גדולות (camel case).

  • description: יש לספק תיאורים מפורטים, ברורים וספציפיים של הפונקציות, ולצרף דוגמאות לפי הצורך. לדוגמה, במקום find theaters, צריך להשתמש ב-find theaters based on location and optionally movie title that is currently playing in theaters. הימנעות מתיאורים רחבים מדי או לא ברורים.

  • properties > type: שימוש בפרמטרים עם סוג מוגדר כדי לצמצם את ההזיות של המודל. לדוגמה, אם ערכי הפרמטרים הם מקבוצה מוגבלת, צריך להשתמש בשדה enum במקום לרשום את הערכים בתיאור (למשל, "type": "enum", "values": ["now_playing", "upcoming"]). אם הערך של הפרמטר הוא תמיד מספר שלם, צריך להגדיר את הסוג כ-integer במקום כ-number.

  • properties > description: יש לספק דוגמאות והגבלות קונקרטיות. לדוגמה, במקום the location to search, צריך להשתמש ב-The city and state, e.g. San Francisco, CA or a zip code e.g. 95616.

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

מצב קריאה של פונקציה

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

  • AUTO: התנהגות ברירת המחדל של המודל. המודל מחליט אם לחזות קריאה לפונקציה או תגובה בשפה טבעית.
  • ANY: המודל מוגבל תמיד לחזות קריאה לפונקציה. אם הערך של allowed_function_names לא מסופק, המודל בוחר מבין כל ההצהרות הזמינות על פונקציות. אם הערך allowed_function_names מוזן, המודל בוחר מתוך קבוצת הפונקציות המותרות.
  • NONE: המודל לא יחזה קריאה לפונקציה. במקרה כזה, התנהגות המודל זהה לזו שמתקבלת אם לא מעבירים הצהרות על פונקציות.

השימוש במצב ANY ('קריאה בכפייה לפונקציה') נתמך רק במודלים Gemini 1.5 Pro ו-Gemini 1.5 Flash.

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

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

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

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

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

כשמשתמשים בפקודות cURL עם התכונה הזו, פרטי הפונקציה והפרמטר כלולים ברכיב tools. כל הצהרת פונקציה ברכיב tools מכילה את שם הפונקציה, ומציינים את הפרמטרים באמצעות סכימה תואמת ל-OpenAPI ותיאור של הפונקציה.

דוגמה לפנייה אחת

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

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

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

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "Which theaters in Mountain View show Barbie movie?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ]
}'

התגובה לדוגמה הזו של curl עשויה להיראות כך:

תגובה לדוגמה של קריאה לפונקציה ב-curl בשלב אחד

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_theaters",
              "args": {
                "movie": "Barbie",
                "location": "Mountain View, CA"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "totalTokenCount": 9
  }
}]

דוגמה לפנייה אחת בכל מצב

דוגמת ה-curl הבאה דומה לדוגמה עם צעד אחד, אבל בה מוגדר הערך ANY ל-mode:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY"
  },
}

קריאה לפונקציה בפעולה אחת באמצעות כל מצב (בקשה)

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "What movies are showing in North Seattle tonight?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY"
    },
  }
}'

התגובה עשויה להיראות כך:

קריאה לפונקציה בסבב אחד באמצעות כל מצב (תגובה)

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_movies",
              "args": {
                "description": "",
                "location": "North Seattle, WA"
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}

דוגמה לתור יחיד עם מצב ANY והפונקציות המותרות

הדוגמה הבאה ל-curl דומה לדוגמה עם צעד אחד, אבל היא מגדירה את ה-mode לערך ANY וכוללת רשימה של הפונקציות המותרות:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

קריאה לפונקציה בפעולה אחת באמצעות כל מצב ופונקציות מותרות (בקשה)

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "What movies are showing in North Seattle tonight?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY",
      "allowed_function_names": ["find_theaters", "get_showtimes"]
    },
  }
}'

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

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

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_theaters",
              "args": {
                "location": "North Seattle, WA",
                "movie": null
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}

דוגמאות לשיחות עם כמה תורנים

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

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

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

הנושא הזה כולל שתי דוגמאות ל-curl עם כמה שלבים:

שימוש בתגובה מתור קודף

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

"functionCall": {
  "name": "find_theaters",
  "args": {
    "movie": "Barbie",
    "location": "Mountain View, CA"
  }
}

בקשה לדוגמה של קריאה של פונקציה בכמה שלבים ל-curl

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "user",
    "parts": [{
      "functionResponse": {
        "name": "find_theaters",
        "response": {
          "name": "find_theaters",
          "content": {
            "movie": "Barbie",
            "theaters": [{
              "name": "AMC Mountain View 16",
              "address": "2000 W El Camino Real, Mountain View, CA 94040"
            }, {
              "name": "Regal Edwards 14",
              "address": "245 Castro St, Mountain View, CA 94040"
            }]
          }
        }
      }
    }]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "find_movies",
      "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "description": {
            "type": "STRING",
            "description": "Any kind of description including category or genre, title words, attributes, etc."
          }
        },
        "required": ["description"]
      }
    }, {
      "name": "find_theaters",
      "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          }
        },
        "required": ["location"]
      }
    }, {
      "name": "get_showtimes",
      "description": "Find the start times for movies playing in a specific theater",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          },
          "theater": {
            "type": "STRING",
            "description": "Name of the theater"
          },
          "date": {
            "type": "STRING",
            "description": "Date for requested showtime"
          }
        },
        "required": ["location", "movie", "theater", "date"]
      }
    }]
  }]
}'

התגובה לדוגמה הזו של curl כוללת את התוצאה של הקריאה ל-method‏ find_theaters. התגובה עשויה להיראות כך:

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

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 27,
    "totalTokenCount": 36
  }
}

קריאה למודל כמה פעמים

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

בקשה לדוגמה של קריאה של פונקציה בכמה שלבים ל-curl

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "user",
    "parts": [{
      "functionResponse": {
        "name": "find_theaters",
        "response": {
          "name": "find_theaters",
          "content": {
            "movie": "Barbie",
            "theaters": [{
              "name": "AMC Mountain View 16",
              "address": "2000 W El Camino Real, Mountain View, CA 94040"
            }, {
              "name": "Regal Edwards 14",
              "address": "245 Castro St, Mountain View, CA 94040"
            }]
          }
        }
      }
    }]
  },
  {
    "role": "model",
    "parts": [{
      "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
    }]
  },{
    "role": "user",
    "parts": [{
      "text": "Can we recommend some comedy movies on show in Mountain View?"
    }]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "find_movies",
      "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "description": {
            "type": "STRING",
            "description": "Any kind of description including category or genre, title words, attributes, etc."
          }
        },
        "required": ["description"]
      }
    }, {
      "name": "find_theaters",
      "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          }
        },
        "required": ["location"]
      }
    }, {
      "name": "get_showtimes",
      "description": "Find the start times for movies playing in a specific theater",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          },
          "theater": {
            "type": "STRING",
            "description": "Name of the theater"
          },
          "date": {
            "type": "STRING",
            "description": "Date for requested showtime"
          }
        },
        "required": ["location", "movie", "theater", "date"]
      }
    }]
  }]
}'

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

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_movies",
              "args": {
                "description": "comedy",
                "location": "Mountain View, CA"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 48,
    "totalTokenCount": 48
  }
}
]

שיטות מומלצות

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

הנחיה למשתמש

כדי לקבל את התוצאות הטובות ביותר, מומלץ להוסיף לשאילתת המשתמש את הפרטים הבאים:

  • הקשר נוסף למודל. לדוגמה: You are a movie API assistant to help users find movies and showtimes based on their preferences.
  • פרטים או הוראות לגבי האופן והמועד שבהם משתמשים בפונקציות. לדוגמה, Don't make assumptions on showtimes. Always use a future date for showtimes.
  • הוראות לשאול שאלות הבהרה אם שאילתות של משתמשים לא ברורות. לדוגמה, Ask clarifying questions if not enough information is available to complete the request.

פרמטרים של דגימה

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

קריאה ל-API

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