您可以使用 Gemini API 函数调用功能向模型提供自定义函数定义。模型不会直接调用这些函数, 而是生成结构化输出,在其中指定函数名称 参数。然后,您可以使用函数名称和参数调用外部 API,并将生成的 API 输出纳入对模型的进一步查询中,以便模型提供更全面的回答并执行其他操作。
函数调用让用户能够与实时信息交互, 如数据库、客户关系管理系统和文档 代码库该功能还可以增强模型提供相关且符合上下文的回答的能力。函数调用最适合与外部系统交互。如果您的用例需要模型执行计算, 涉及外部系统或 API,则应考虑使用 代码执行。
如需查看函数调用的实际示例,请参阅“light bot”笔记本。
函数调用的工作原理
如需使用函数调用功能,您需要向模型提示添加描述编程接口的结构化查询数据(称为函数声明)。函数声明提供 API 函数的名称,说明其用途、支持的所有参数以及这些参数的说明。将查询中的函数声明列表传递给模型后,模型会分析函数声明和查询的其余部分,以确定如何使用声明的 API 来响应请求。
然后,模型会返回一个 OpenAPI 兼容架构中的对象,其中指定了如何调用一个或多个已声明的函数,以便回答用户的问题。然后,您可以采用建议的函数调用参数,调用实际 API,获取响应,并将该响应提供给用户或执行进一步操作。请注意,模型实际上并不会调用声明的函数。而是使用返回的架构对象参数来调用该函数。Gemini API 还支持并行函数调用,其中模型会根据单个请求推荐多个 API 函数调用。
函数声明
在提示中实现函数调用时,您需要创建一个 tools
对象,
其中包含一个或多个 function declarations
。你可以定义函数
尤其是使用
选择子集
的
OpenAPI 架构
格式。单个函数声明可以包含以下参数:
name
(字符串):API 调用中函数的唯一标识符。description
(字符串):全面说明函数的用途和功能。parameters
(对象):定义函数所需的输入数据。type
(字符串):指定整体数据类型,例如object
。properties
(对象):列出各个参数,每个参数均包含:type
(字符串):参数的数据类型,例如string
、integer
、boolean
。description
(字符串):清晰说明参数的用途和预期格式。
required
(数组):列出参数名称的字符串数组 它们是函数运行所必需的。
如需查看使用 cURL 命令的函数声明的代码示例,请参阅函数调用示例。如需查看使用 Gemini API SDK 创建函数声明的示例,请参阅函数调用教程。
函数声明最佳实践
在将函数集成到您的
请求。每个函数都依赖于特定参数,这些参数可指导其行为并与模型进行交互。以下列表提供了有关在 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
和 Gemini 1.5 Flash
模型。
您还可以传递一组 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"]
},
}
函数调用示例
本部分提供了有关使用 c网址 命令进行函数调用的示例提示。 这些示例包括单轮和多轮场景,以及启用不同的函数调用模式。
将 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 模式的单轮示例
以下 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 示例与
单轮示例,但它将
将 mode 设置为 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 示例调用上一个单轮示例返回的函数和参数以获取响应。方法和参数 单轮示例返回的 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 示例的响应包含调用 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 } }
多次调用模型
以下 c网址 示例多次调用生成式 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 调用
如果模型建议调用一个会发送订单、更新数据库或以其他方式产生重大后果的函数,请在执行之前先向用户验证该函数调用。