你可以使用函式定義自訂函式,並提供給 Gemini 模型 通話功能。模型不會直接叫用這些函式,而是 產生結構化資料輸出內容,指定函式名稱和 引數。這個輸出內容可讓您編寫採用 然後產生 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
。定義函式
尤其是在內含特定資料
選取子集
的
OpenAPI 結構定義
格式。單一函式宣告可包含下列參數:
name
(字串):API 中函式的專屬 ID 呼叫。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 city and state, e.g. San Francisco, CA or a zip code e.g. 95616
,而非the location to search
。
如需有關使用函式呼叫的更多最佳做法,請參閱 最佳做法一節。
函式呼叫模式
您可以使用函式呼叫 mode
參數修改執行作業
功能的運作方式共有三種模式:
AUTO
:預設模型行為。模型決定 函式呼叫或自然語言回應ANY
:模型受到侷限,只能預測函式呼叫。如果allowed_function_names
未提供,模型會從所有 可用的函式宣告如果「提供」allowed_function_names
, 模型會從允許的函式集中挑選。NONE
:模型不會預測函式呼叫。在本例中 如果您未傳遞任何函式宣告,行為就會相同。
ANY
模式 (「強制函式呼叫」) 的用量:
僅支援 Gemini 1.5 Pro
模型。
您也可以傳遞一組 allowed_function_names
,如果有提供,就會限制
模型將會呼叫的函式您可以只將
如果模式為 ANY
,則為 allowed_function_names
。函式名稱應相符
函式宣告名稱。模式設為 ANY
且
已設定 allowed_function_names
,模型將根據
提供的函式名稱組合。
下列程式碼片段是從
範例要求說明如何
將 mode
設為 ANY
,並指定允許的函式清單:
"tool_config": {
"function_calling_config": {
"mode": "ANY",
"allowed_function_names": ["find_theaters", "get_showtimes"]
},
}
函式呼叫範例
本節提供使用 cURL 指令呼叫函式的提示範例。 相關例子包括單輪和多輪迴轉情形,且 不同的函式呼叫模式
搭配這項功能使用 cURL 指令時,函式和參數
資訊包含在 tools
元素中。文件中每個函式宣告
tools
元素包含函式名稱,而您使用以下參數指定參數:
與 OpenAPI 相容的結構定義
以及函式說明
單輪範例
「單輪」是指一次呼叫語言模型一次。運用函式呼叫 若是以自然語言提供模型,則適合處理這類單輪用途 和函式清單在這種情況下,模型會使用 宣告,其中包含函式名稱、參數和說明 預測要呼叫的函式和呼叫該函式的引數
以下 curl 範例為將說明傳入
函式,傳回電影播放位置相關資訊。數個
請求中包含函式宣告,例如 find_movies
和
find_theaters
。
單輪函式呼叫範例要求
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": { "role": "user", "parts": { "text": "Which theaters in Mountain View show Barbie movie?" } }, "tools": [ { "function_declarations": [ { "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "string", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": [ "description" ] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" } }, "required": [ "location" ] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" }, "theater": { "type": "string", "description": "Name of the theater" }, "date": { "type": "string", "description": "Date for requested showtime" } }, "required": [ "location", "movie", "theater", "date" ] } } ] } ] }'
這個 curl 範例的回應可能與以下內容類似。
呼叫 curl 回應的單輪函式範例
[{ "candidates": [ { "content": { "parts": [ { "functionCall": { "name": "find_theaters", "args": { "movie": "Barbie", "location": "Mountain View, CA" } } } ] }, "finishReason": "STOP", "safetyRatings": [ { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } ], "usageMetadata": { "promptTokenCount": 9, "totalTokenCount": 9 } }]
使用「任一」模式的單輪範例
以下的 curl 範例與
將模式轉換為 ANY
:
"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" } ] } }
採用任一模式和允許函式的單輪範例
以下的 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" } ] } }
多輪範例
如要實作多輪函式呼叫情境,請按照下列步驟操作:
- 呼叫語言模型以取得函式呼叫回應。這是第一個 旋轉。
- 使用第一輪的函式呼叫回應來呼叫語言模型 以及呼叫該函式得到的函式回應這是 第二次。
第二輪的回覆就會總結結果 或是包含第二個函式呼叫,以便取得 請提供更多資訊
本主題包含兩個多輪 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 範例多次呼叫生成式 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 叫用
如果模型提議叫用會傳送訂單的函式, 更新資料庫,或產生重大結果 函式呼叫再執行。