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

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

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

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

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

• שם פונקציה
• פרמטרים של פונקציות בפורמט סכימה תואמת ל-OpenAPI. יש תמיכה בקבוצת משנה נבחרת. כשמשתמשים ב-curl, הסכימה מצוינת באמצעות JSON.
• תיאור הפונקציה (אופציונלי). לקבלת התוצאות הטובות ביותר מומלץ לכלול תיאור.

במסמך הזה מפורטות דוגמאות ל-Curl לביצוע קריאות REST עם המחלקה GenerativeModel והשיטות שלה.

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

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

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

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

מצב התקשרות עם פונקציה

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

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

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

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

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

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

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

דגימה של סיבוב יחיד

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

דוגמת ה-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 לדוגמה הזו עשויה להיראות כך.

[{
  "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:

"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 הבאה דומה לדוגמה של סיבוב יחיד, אבל היא מגדירה את המצב ל-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 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 הזו כוללת את התוצאה של קריאה ל-method find_theaters. התשובה עשויה להיראות כך:

{
  "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": "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"]
      }
    }]
  }]
}'
    

[{
  "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
  }
}
]
    

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

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

השדות של מקשי הפונקציות

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

function_declarations (מערך):

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

בתוך כל אובייקט function_declarations:

• name (מחרוזת): המזהה הייחודי של הפונקציה בתוך הקריאה ל-API.
  • שיטה מומלצת: יש להשתמש בשמות ברורים ותיאוריים, ללא תווים של רווח, נקודה (.) או מקף (-). במקום זאת, צריך להשתמש בקו תחתון (_) או באותיות גמל.
• description (מחרוזת): הסבר מקיף של המטרה והיכולות של הפונקציה.
  • השיטה המומלצת: התיאורים של הפונקציות צריכים להיות ברורים, ברורים וספציפיים, ובמקרה הצורך כדאי לספק דוגמאות. לדוגמה: במקום find theaters, צריך להשתמש במדיניות find theaters based on location and optionally movie title that is currently playing in theaters.. מומלץ להימנע מתיאורים רחבים מדי או לא ברורים.
• parameters (אובייקט): מגדיר את נתוני הקלט שהפונקציה צריכה.
  • type (מחרוזת): מציין את סוג הנתונים הכולל (למשל, object).
  • properties (אובייקט):
    • בתיבת הדו-שיח הזו מפורטים פרמטרים ספציפיים, ולכל אחד מהם יש:
      • type (מחרוזת): סוג הנתונים של הפרמטר (למשל, string, integer, boolean).
        • שיטה מומלצת: השתמשו בפרמטרים מסוג כזה כדי להפחית תגובות לא תואמות נתונים (hallucination). לדוגמה, אם ערכי הפרמטר הם מקבוצה סופית, צריך להשתמש בשדה enum במקום לציין את הערכים בתיאור (למשל, "type": "enum", "values": ["now_playing", "upcoming"]). אם ערך הפרמטר הוא תמיד מספר שלם, צריך להגדיר את הסוג כ-integer ולא כ-number.
      • description (מחרוזת): הסבר ברור של מטרת הפרמטר והפורמט הצפוי.
        • שיטה מומלצת: ספקו דוגמאות ומגבלות מעשיות. לדוגמה, במקום the location to search, יש להשתמש ב-The city and state, e.g. San Francisco, CA or a zip code e.g. 95616.
  • required (מערך):
    • מערך של מחרוזות שמציינות את שמות הפרמטרים שחובה לבצע כדי שהפונקציה תפעל.

הנחיה למשתמש

לקבלת התוצאות הטובות ביותר, צריך להוסיף לפני השאילתה של המשתמש את הפרטים הבאים:

• הקשר נוסף עבור המודל. לדוגמה: 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

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