באמצעות התכונה של קריאת פונקציות ב-Gemini API, אפשר לספק למדגם הגדרות פונקציות בהתאמה אישית. המודל לא מפעיל את הפונקציות האלה באופן ישיר, אלא יוצר פלט מובנה שמציין את שם הפונקציה ואת ההצעות לארגומנטים. לאחר מכן תוכלו להשתמש בשם הפונקציה ובארגומנטים שלה כדי לבצע קריאה ל-API חיצוני, וגם לשלב את הפלט של ה-API שנוצר בשאילתה נוספת למודל, כדי לאפשר למודל לספק תגובה מקיפה יותר ולבצע פעולות נוספות.
קריאה לפונקציות מאפשרת למשתמשים לקיים אינטראקציה עם מידע ושירותים בזמן אמת, כמו מסדי נתונים, מערכות לניהול קשרי לקוחות ומאגרי מסמכים. התכונה גם משפרת את היכולת של המודל לספק תשובות רלוונטיות ובהקשר. קריאה לפונקציה מתאימה במיוחד לאינטראקציה עם מערכות חיצוניות. אם בתרחיש לדוגמה שלכם המודלים צריכים לבצע חישובים אבל לא מעורבים בו מערכות חיצוניות או ממשקי API, כדאי להשתמש במקום זאת בהרצת קוד.
דוגמה לקריאה לפונקציה זמינה במחברות 'light bot'.
איך פועלת קריאה לפונקציה
כדי להשתמש בתכונה של קריאת פונקציות, מוסיפים להנחיה של מודל נתוני שאילתות מובְנים שמתארים ממשקי תכנות, שנקראים הצהרות פונקציה. בהצהרות על הפונקציות מופיע שם פונקציית ה-API, הסבר על המטרה שלה, הפרמטרים שהיא תומכת בהם ותיאורים של הפרמטרים האלה. אחרי שמעבירים רשימה של הצהרות פונקציה בשאילתה למודל, הוא מנתח את הצהרות הפונקציה ואת שאר השאילתה כדי לקבוע איך להשתמש ב-API המוצהר בתגובה לבקשה.
לאחר מכן, המודל מחזיר אובייקט בסכימה תואמת ל-OpenAPI שמציין איך לקרוא לפונקציה אחת או יותר מהפונקציות המוצגות כדי לענות על השאלה של המשתמש. לאחר מכן תוכלו להשתמש בפרמטרים המומלצים לקריאה לפונקציה, לקרוא ל-API בפועל, לקבל תשובה ולספק אותה למשתמש או לבצע פעולה נוספת. חשוב לזכור שהמודל לא קורא בפועל לפונקציות המוצגות. במקום זאת, משתמשים בפרמטרים של אובייקט הסכימה שהוחזרו כדי להפעיל את הפונקציה. ממשק ה-API של Gemini תומך גם בקריאות פונקציה במקביל, שבהן המודל ממליץ על מספר קריאות לפונקציות 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"]
},
}
קריאה לפונקציות מורכבות
Gemini 2.0 תומך ביכולת חדשה של קריאת פונקציות: קריאת פונקציות מורכבות. קריאה לפונקציות מורכבות מאפשרת ל-Gemini API להפעיל אוטומטית כמה פונקציות מוגדרות-משתמש בתהליך יצירת התגובה. לדוגמה, כדי להגיב להנחיה "Get the temperature in my current location"
, יכול להיות ש-Gemini API יפעיל גם פונקציית get_current_location()
וגם פונקציית get_weather()
שמקבלת את המיקום כפרמטר.
כדי לבצע קריאה לפונקציה מורכבת עם ביצוע קוד, נדרש סטרימינג דו-כיווני, והאפשרות הזו נתמכת רק ב-Multimodal Live API החדש. בדוגמה הבאה מוסבר איך משתמשים יחד בקריאה לפונקציות מורכבות, בהרצת קוד וב-Multimodal Live API:
turn_on_the_lights_schema = {'name': 'turn_on_the_lights'}
turn_off_the_lights_schema = {'name': 'turn_off_the_lights'}
prompt = """
Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
"""
tools = [
{'code_execution': {}},
{'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]}
]
await run(prompt, tools=tools, modality="AUDIO")
מפתחי Python יכולים לנסות את זה במחברת הקוד של השימוש בכלי ה-API.
שימוש בכלי רב-תכליתיים
ב-Gemini 2.0 אפשר להפעיל כמה כלים בו-זמנית, והמודל יחליט מתי להפעיל אותם. בדוגמה הבאה מופיעים שני כלים, 'התאמה לאינטראקציה' עם חיפוש Google והרצת קוד, בבקשה באמצעות Multimodal Live API.
prompt = """
Hey, I need you to do three things for me.
1. Turn on the lights.
2. Then compute the largest prime palindrome under 100000.
3. Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024.
Thanks!
"""
tools = [
{'google_search': {}},
{'code_execution': {}},
{'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]}
]
await run(prompt, tools=tools, modality="AUDIO")
מפתחי Python יכולים לנסות את זה במחברת הקוד של השימוש בכלי ה-API.
דוגמאות לקריאה לפונקציות
בקטע הזה מפורטות הנחיות לדוגמה לקריאה לפונקציות באמצעות פקודות 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" } ] } }
דוגמאות לשיחות עם כמה תורנים
כדי להטמיע תרחיש של קריאה לפונקציה בכמה סבבים, מבצעים את הפעולות הבאות:
- קריאה למודל השפה כדי לקבל תשובה לקריאה לפונקציה. זוהי הפניה הראשונה.
- קוראים למודל השפה באמצעות התשובה לקריאה של הפונקציה מהתור הראשון, והתשובה של הפונקציה שמתקבלת מהקריאה לפונקציה הזו. זהו תורו השני.
התגובה מהתור השני היא סיכום של התוצאות כדי לענות לשאילתה שלכם מהתור הראשון, או שהיא מכילה קריאה שנייה לפונקציה שאפשר להשתמש בה כדי לקבל מידע נוסף על השאילתה.
הנושא הזה כולל שתי דוגמאות ל-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, מודל ה-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
אם המודל מציע להפעיל פונקציה ששולחת הזמנה, מעדכנת מסד נתונים או גורמת לתוצאות משמעותיות אחרות, צריך לאמת את הקריאה לפונקציה עם המשתמש לפני שמפעילים אותה.