你可以使用 Functions 函数定义自定义函数并将其提供给 Gemini 模型, 通话功能。这些模型不会直接调用这些函数,而是 生成用于指定函数名称和建议函数的结构化数据输出 参数。此输出可让您编写采用结构化 然后调用外部 API,然后就可以将生成的 API 输出 合并到进一步的模型提示中,以便进行更全面的查询 响应。函数调用让用户能够与实时交互 信息和各种服务,例如数据库、客户关系 管理系统和文档存储库,增强其 根据上下文给出相关回答。
函数调用的工作原理
要使用函数调用功能,您可以添加描述 编程接口(称为函数声明)。通过 函数声明会提供 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 中函数的唯一标识符 调用。description
(字符串):对函数的 用途和功能。parameters
(对象):定义函数所需的输入数据。type
(字符串):指定总体数据类型,例如object
。properties
(对象):列出各个参数,每个参数都包含以下内容:type
(字符串):参数的数据类型,例如string
、integer
、boolean
。description
(字符串):参数的明确说明 用途和预期格式。
required
(数组):列出参数名称的字符串数组 它们是函数运行所必需的。
如需查看使用 c网址 命令进行函数声明的代码示例,请参阅 函数调用示例。示例 有关为其他平台创建函数声明的信息,请参阅 函数调用平台指南。
函数声明最佳实践
将函数集成到
请求。每个函数都依赖于特定的参数来指导其行为
及其交互方式。以下列表提供了有关
在 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
,如果提供这组 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 示例与
单轮示例,但它将
将 mode 设置为 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": "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 } }
多次调用模型
以下 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": "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 调用
如果模型建议调用一个会发送订单、更新数据库或以其他方式产生重大后果的函数,请在执行之前先向用户验证该函数调用。