您可以使用 Gemini API 函数调用功能向模型提供自定义函数定义。模型不会直接调用这些函数，而是会生成结构化输出，其中指定了函数名称和建议的参数。然后，您可以使用函数名称和参数调用外部 API，并将生成的 API 输出纳入到对模型的进一步查询中，以便模型提供更全面的回答并执行其他操作。
借助函数调用，用户可以与实时信息和服务（例如数据库、客户关系管理系统和文档库）进行交互。该功能还可以增强模型提供相关且符合上下文的回答的能力。函数调用最适合与外部系统交互。如果您的用例需要模型执行计算，但不涉及外部系统或 API，您应考虑改用代码执行。
如需查看函数调用的实际示例，请参阅“light bot”笔记本。
函数调用的工作原理
如需使用函数调用功能，您需要向模型提示添加描述编程接口的结构化查询数据（称为函数声明）。函数声明提供 API 函数的名称，说明其用途、支持的所有参数以及这些参数的说明。将查询中的函数声明列表传递给模型后，模型会分析函数声明和查询的其余部分，以确定如何使用声明的 API 来响应请求。
然后，模型会返回一个 OpenAPI 兼容架构中的对象，其中指定了如何调用一个或多个已声明的函数以回答用户的问题。然后，您可以采用建议的函数调用参数，调用实际 API，获取响应，并将该响应提供给用户或执行进一步操作。请注意，模型实际上并不会调用声明的函数。而是使用返回的架构对象参数来调用该函数。Gemini API 还支持并行函数调用，其中模型会根据单个请求推荐多个 API 函数调用。
函数声明
在提示中实现函数调用时，您需要创建一个 tools 对象，其中包含一个或多个 function declarations。您可以使用 JSON 定义函数，具体而言，使用 OpenAPI 架构格式的部分子集。单个函数声明可以包含以下参数：
name（字符串）：API 调用中函数的唯一标识符。description（字符串）：全面说明该函数的用途和功能。parameters（对象）：定义函数所需的输入数据。type（字符串）：指定整体数据类型，例如object。properties（对象）：列出各个参数，每个参数均包含：type（字符串）：参数的数据类型，例如string、integer、boolean。description（字符串）：清晰说明参数的用途和预期格式。
required（数组）：一个字符串数组，用于列出函数运行所必需的参数名称。
如需查看使用 c网址 命令的函数声明的代码示例，请参阅函数调用示例。如需查看使用 Gemini API SDK 创建函数声明的示例，请参阅函数调用教程。
函数声明的最佳实践
在将函数集成到请求中时，准确定义函数至关重要。每个函数都依赖于特定参数，这些参数可指导其行为并与模型进行交互。以下列表提供了有关在 functions_declarations 数组中定义各个函数参数的指南。
name：使用清晰、描述性强的名称，不含空格、英文句点 (.) 或短划线 (-) 字符。请改用下划线 (_) 字符或驼峰式命名法。description：提供详细、清晰且具体的函数说明，并根据需要提供示例。例如，使用find theaters based on location and optionally movie title that is currently playing in theaters.取代find 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：模型不会预测函数调用。在这种情况下，模型行为与您不传递任何函数声明时一样。
只有 Gemini 1.5 Pro 和 Gemini 1.5 Flash 模型支持使用 ANY 模式（“强制函数调用”）。
您还可以传递一组 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网址 命令进行函数调用的示例提示。这些示例包括单轮和多轮场景，以及启用不同的函数调用模式。
将 c网址 命令与此功能搭配使用时，函数和参数信息会包含在 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 示例与单转弯示例类似，但它会将模式设置为 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 调用
如果模型建议调用一个会发送订单、更新数据库或以其他方式产生重大后果的函数，请在执行之前先向用户验证该函数调用。