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

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

הסבר על שליחת פונקציות

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

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

מודלים נתמכים

יש תמיכה בתכונה 'שליחת פונקציות' במודלים הבאים:

  • gemini-1.0-pro
  • gemini-1.0-pro-001
  • gemini-1.5-flash-latest
  • gemini-1.5-pro-latest

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

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

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

דוגמאות לקוד של הצהרת פונקציה באמצעות פקודות cURL דוגמאות לקריאה לפונקציות. לדוגמאות ומידע על יצירת הצהרות לגבי פונקציות בפלטפורמות אחרות: מדריך בנושא פלטפורמות לקריאה לפונקציות.

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

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

אפשר גם להעביר קבוצה של 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
  }
}]

דוגמה לפנייה אחת באמצעות מצב Any (Any)

הדוגמה הבאה ל-curl דומה ל- דוגמה לפנייה אחת, אבל היא מגדירה המצב אל ANY:

"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 (תשובה)

{
  "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": "function",
    "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 הזו כוללת את התוצאה של קריאה ל אמצעי תשלום אחד (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": "function",
    "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

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