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

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

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

לדוגמה, לקריאה של פונקציות, אפשר לעיין "בוט קל" notebook.

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

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

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

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

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

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

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

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

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

  • name: עדיף להשתמש בשמות ברורים ותיאורים ללא רווחים, נקודות (.) או מקפים (-). במקום זאת, צריך להשתמש בקו תחתון (_) תווים או קאמל קייס.

  • 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"
  },
}

שליחת פונקציות פנייה אחת באמצעות מצב 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"
    },
  }
}'

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

שליחת פונקציות פנייה חד-פעמית באמצעות מצב Any mode (תשובה)

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

דוגמה לבקשת 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

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