您可以使用函式呼叫定義自訂函式,並提供給生成式 AI 模型。模型不會直接叫用這些函式,而是產生結構化資料輸出,指定函式名稱和建議的引數。此輸出內容可以呼叫外部 API,所產生的 API 輸出內容也可以整合回模型中,以便取得更全面的查詢回應。函式呼叫可讓 LLM 與即時資訊和各種服務 (例如資料庫、客戶關係管理系統和文件存放區) 互動,藉此提升提供相關且符合情境的答案。
函式呼叫的運作方式
函式會使用函式宣告來描述。您將查詢中的函式宣告清單傳遞至語言模型之後,模型會以 OpenAPI 相容結構定義格式傳回物件,其中包含函式名稱和函式引數,並嘗試用其中一個傳回的函式回答使用者查詢。語言模型透過分析函式宣告來瞭解函式的用途。模型實際上並未呼叫函式。而是開發人員改為在回應中使用 OpenAPI 相容結構定義物件,呼叫模型傳回的函式。
實作函式呼叫時,您可以建立一或多個函式宣告,然後將函式宣告新增至傳遞至模型的 tools
物件。每個函式宣告都包含與一個函式相關的資訊,包含下列項目:
- 函式名稱
- 採用 OpenAPI 相容結構定義格式的函式參數。系統支援特定子集。使用 curl 時,系統會以 JSON 指定結構定義。
- 函式說明 (選填),為獲得最佳結果,建議您加入說明。
Gemini API 也支援平行函式呼叫,在這裡您可以一次呼叫多個函式。
本文件包含 curl 範例,使用 GenerativeModel
類別及其方法進行 REST 呼叫。
支援的模型
下列模型支援函式呼叫:
gemini-1.0-pro
gemini-1.0-pro-001
gemini-1.5-flash-latest
gemini-1.5-pro-latest
函式呼叫模式
您可以使用呼叫 mode 的函式定義函式呼叫的執行行為,共有三種模式:
AUTO
:預設模型行為。模型決定預測函式呼叫或自然語言回應ANY
:模型會受到限制,無法一律預測函式呼叫。如果「未」提供allowed_function_names
,模型會從所有可用的函式宣告中挑選。如果提供allowed_function_names
,模型會從允許的函式組合中挑選。NONE
:模型不會預測函式呼叫。在這種情況下,模型行為會與傳遞任何函式宣告時相同。
您也可以傳遞一組 allowed_function_names
,如果提供此值,就會限制模型呼叫的函式。模式為 ANY
時,您只能加入 allowed_function_names
。函式名稱應與函式宣告名稱相符。當模式設為 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 範例
「單輪」是指一次性呼叫語言模型。透過函式呼叫,當您提供自然語言查詢和函式清單時,單輪用途可能是供給模型使用。在此情況下,模型會使用函式宣告,其中包括函式名稱、參數和說明,藉此預測要呼叫的函式,以及要呼叫哪個函式。
以下 curl 範例示範如何傳入函式說明,該函式會傳回電影播放位置的相關資訊。要求中包含多個函式宣告,例如 find_movies
和 find_theaters
。
呼叫 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?" } }, "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 模式的單輪範例
以下 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"]
},
}
使用 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", "allowed_function_names": ["find_theaters", "get_showtimes"] }, } }'
這個模型不在許可函式清單中,因此無法預測 find_movies
函式,因此會改為預測其他函式。回應內容大致如下:
使用 ANY 模式和允許的函式 (回應) 的單輪函式呼叫
{ "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 範例:
使用前一個回合回應的 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": "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 範例
以下 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"] } }] }] }'
呼叫 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 } } ]
最佳做法
請按照下列最佳做法,提高函式呼叫的準確度和可靠性。
函式鍵欄位
如要將函式整合至要求,請務必精確定義函式。每個函式都必須仰賴特定參數,以引導其行為及與模型的互動。以下細分 functions_declarations
陣列內使用的重要參數。
function_declarations
(陣列):
- 包含一或多個 物件,每個物件都代表不同的函式。
在每個 function_declarations
物件中:
name
(字串):API 呼叫中函式的專屬 ID。- 最佳做法:使用清楚易懂的名稱,且不含空格、句號 (
.
) 或破折號 (-
) 字元。請改用底線 (_
) 字元或駝峰式大小寫。
- 最佳做法:使用清楚易懂的名稱,且不含空格、句號 (
description
(字串):函式用途和功能的完整說明。- 最佳做法:函式說明應清楚詳盡且具體,並在必要時提供範例。舉例來說,應使用
find theaters based on location and optionally movie title that is currently playing in theaters.
,不要使用find theaters
,避免使用過於廣泛或模糊的說明。
- 最佳做法:函式說明應清楚詳盡且具體,並在必要時提供範例。舉例來說,應使用
parameters
(物件):定義函式所需的輸入資料。type
(字串):指定整體資料類型 (例如object
).properties
(物件):- 列出個別參數,每個參數都包含:
type
(字串):參數的資料類型 (例如string
、integer
、boolean
)。- 最佳做法:使用強類型的參數來減少模型幻覺。舉例來說,如果參數值來自有限組合,請使用
enum
欄位,不要在說明中列出值 (例如"type": "enum", "values": ["now_playing", "upcoming"]
)。如果參數值一律為整數,請將類型設為integer
(而非number
)。
- 最佳做法:使用強類型的參數來減少模型幻覺。舉例來說,如果參數值來自有限組合,請使用
description
(字串):清楚說明參數的用途和預期格式。- 最佳做法:提供具體的範例和限制。例如,使用
The city and state, e.g. San Francisco, CA or a zip code e.g. 95616
,而不使用the location to search
。
- 最佳做法:提供具體的範例和限制。例如,使用
- 列出個別參數,每個參數都包含:
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 叫用
如果模型提議叫用可傳送訂單、更新資料庫或其他造成重大結果的函式,請在執行函式前與使用者驗證函式呼叫。