使用 Gemini API 进行函数调用

iOS+ Android Web Flutter

生成式模型擅长解决许多类型的问题。但是，它们受到以下限制：

• 模型在训练后被冻结，导致知识过时。
• 无法查询或修改外部数据。

函数调用可以帮助您克服其中一些限制。函数调用有时称为“工具使用”，因为它允许模型使用外部工具（如 API 和函数）生成其最终响应。

您可以在 Google Cloud 文档中详细了解函数调用，包括函数调用的应用场景实用列表。

Gemini 1.0 Pro、Gemini 1.5 Pro 和 Gemini 1.5 Flash 均支持函数调用。

本指南介绍了如何实现类似于本页面下一部分中所述示例的函数调用设置。概括来讲，在应用中设置函数调用的步骤如下：

1. 编写一个函数，为模型提供生成最终响应所需的信息（例如，函数可以调用外部 API）。

2. 创建一个函数声明，描述该函数及其参数。

3. 在模型初始化期间提供函数声明，以便模型知道如何使用该函数（如果需要）。

4. 请设置您的应用，以便模型可以发送所需的信息，以便您的应用调用函数。

5. 将函数的响应传回给模型，以便模型生成最终响应。

跳转到代码实现

函数调用示例概览

向模型发送请求时，您还可以为模型提供一组“工具”（例如函数），以便模型用来生成最终响应。为了使用这些函数并调用它们（称为“函数调用”），模型和您的应用需要相互传递信息，因此建议通过多轮聊天界面使用函数调用。

假设您有一个应用，用户可以在其中输入类似以下的提示：What was the weather in Boston on October 17, 2024?。

Gemini 模型可能不知道这些天气信息；但是，假设您知道一个可以提供这些信息的外部天气服务 API。您可以使用函数调用为 Gemini 模型提供指向该 API 及其天气信息的路径。

首先，在您的应用中编写一个函数 fetchWeather，用于与这个假设的外部 API 进行交互，该 API 包含以下输入和输出：

参数	类型	必需	说明
输入
location	对象	是	要获取其天气信息的城市及其所在的州的名称。 仅支持美国的城市。必须始终是 city 和 state 的嵌套对象。
date	字符串	是	要获取该日期的天气信息（必须始终采用 YYYY-MM-DD 格式）。
输出
temperature	整数	是	温度（华氏度）
chancePrecipitation	字符串	是	降水概率（以百分比表示）
cloudConditions	字符串	是	Cloud 条件（clear、partlyCloudy、mostlyCloudy、cloudy 之一）

初始化模型时，您需要告知模型此 fetchWeather 函数的存在以及如何使用该函数处理传入请求（如果需要）。这称为“函数声明”。模型不会直接调用函数。而是在模型处理传入请求时，决定 fetchWeather 函数能否帮助它响应请求。如果模型确定该函数确实有用，则会生成有助于应用调用该函数的结构化数据。

再次查看传入请求：What was the weather in Boston on October 17, 2024?。模型可能会决定 fetchWeather 函数可以帮助其生成回答。该模型会查看 fetchWeather 需要哪些输入参数，然后为该函数生成结构化输入数据，大致如下所示：

{
  functionName: fetchWeather,
  location: {
    city: Boston,
    state: Massachusetts  // the model can infer the state from the prompt
  },
  date: 2024-10-17
}

模型会将这些结构化输入数据传递给您的应用，以便您的应用调用 fetchWeather 函数。当您的应用收到来自 API 的天气状况信息时，会将该信息传递给模型。借助此天气信息，模型可以完成最终处理，并生成对 What was the weather in Boston on October 17, 2024? 的初始请求的响应

模型可能会提供最终的自然语言回答，例如：On October 17, 2024, in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

 

实现函数调用

iOS+ Android Web Flutter

准备工作

请完成 Vertex AI in Firebase SDK 使用入门指南（如果尚未完成）。请确保您已完成以下所有操作：

1. 设置一个新的 Firebase 项目或一个现有的 Firebase 项目，包括使用 Blaze 定价方案并启用所需的 API。

2. 将您的应用与 Firebase 相关联，包括注册应用并将 Firebase 配置添加到应用中。

3. 添加 SDK，并在应用中初始化 Vertex AI 服务和生成式模型。

将应用连接到 Firebase、添加 SDK 并初始化 Vertex AI 服务和生成式模型后，您就可以调用 Gemini API 了。

本指南的其余步骤将向您展示如何实现与函数调用示例概览（请参阅本页顶部部分）中所述工作流类似的函数调用设置。

您可以在本页稍后部分查看此函数调用示例的完整代码示例。

第 1 步：编写函数

假设您有一个应用，用户可以在其中输入类似以下的提示：What was the weather in Boston on October 17, 2024?。Gemini 模型可能不知道此天气信息；但是，假设您知道一个可以提供此信息的外部天气服务 API。本指南中的示例依赖于此假设的外部 API。

在应用中编写将与假设的外部 API 进行交互的函数，并为模型提供生成最终请求所需的信息。在此天气示例中，将是 fetchWeather 函数调用此假设的外部 API。

注意：您向模型提供的函数无需调用外部 API。它们还可以执行其他操作，例如提供用于计算值的公式、查询数据库、返回文档中的搜索结果等。

第 2 步：创建函数声明

创建您稍后要提供给模型的函数声明（本指南的下一步）。

注意：本指南的示例演示了仅向模型提供一个函数声明，但您可以向模型提供最多 128 个函数声明，供其进行选择。

在声明中，为函数及其参数添加尽可能详细的信息。

模型会使用函数声明中的信息来确定要选择哪个函数，以及如何为对函数的实际调用提供参数值。请参阅本页后面的其他行为和选项，了解模型如何在函数中选择以及如何控制该选择。

请注意有关您提供的架构的以下事项：

• 您必须以与 OpenAPI 架构兼容的架构格式提供函数声明。Vertex AI 对 OpenAPI 架构提供有限支持。

  • 支持以下属性：type、nullable、required、format、description、properties、items、enum。

  • 不支持以下属性：default、optional、maximum、oneOf。

• 默认情况下，对于 Vertex AI in Firebase SDK，除非您在 optionalProperties 数组中将其指定为可选，否则所有字段都被视为必填字段。对于这些选填字段，模型可以填充或跳过这些字段。请注意，这与 Vertex AI Gemini API 的默认行为相反。

如需了解与函数声明相关的最佳实践（包括名称和说明方面的提示），请参阅 Google Cloud 文档中的最佳实践。

您可以按以下方式编写函数声明：

第 3 步：在模型初始化期间提供函数声明

注意：Gemini 1.0 Pro 和 Gemini 1.5 Pro 都支持函数调用。在确定要使用哪种模型时，请务必查看每种模型的配额。

请求中可提供的函数声明的最大数量为 128 个。如需了解模型如何从这些函数中进行选择，以及如何控制该选择（使用 toolConfig 设置函数调用模式），请参阅本页下文中的其他行为和选项。

了解如何选择适合您的用例和应用的 Gemini 模型和（可选）位置。

第 4 步：调用该函数以调用外部 API

如果模型确定 fetchWeather 函数确实可以帮助其生成最终回答，您的应用需要使用模型提供的结构化输入数据实际调用该函数。

由于需要在模型和应用之间来回传递信息，因此建议通过多轮聊天界面使用函数调用。

以下代码段展示了如何告知您的应用模型要使用 fetchWeather 函数。它还显示，模型为函数调用（及其底层外部 API）提供了必要的输入参数值。

在此示例中，传入请求包含提示 What was the weather in Boston on October 17, 2024?。从此提示中，模型推断出 fetchWeather 函数所需的输入参数（即 city、state 和 date）。

第 5 步：向模型提供函数的输出以生成最终回答

fetchWeather 函数返回天气信息后，您的应用需要将其传递回模型。

然后，模型会执行最终处理，并生成最终的自然语言回答，例如：On October 17, 2024 in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

其他行为和选项

以下是您需要在代码中适应的函数调用的一些其他行为，以及您可以控制的选项。

模型可能会要求再次调用一个函数或其他函数。

如果一个函数调用的响应不足以让模型生成最终响应，则模型可能会请求进行额外的函数调用，或者请求调用完全不同的函数。只有在函数声明列表中为模型提供了多个函数时，才会出现后一种情况。

您的应用需要考虑到模型可能会请求进行其他函数调用。

模型可能会要求同时调用多个函数。

您可以在函数声明列表中向模型提供最多 128 个函数。因此，模型可能会决定需要多个函数来帮助其生成最终回答。它可能会决定同时调用其中的一些函数，这称为并行函数调用。

您的应用需要适应模型可能要求同时运行多个函数的情况，并且您的应用需要将函数的所有响应提供回给模型。

Gemini 1.5 Pro 和 Gemini 1.5 Flash 支持并行函数调用。

您可以控制模型是否可以请求调用函数以及调用方式。

您可以对模型应如何以及是否应使用所提供的函数声明施加一些约束条件。这称为设置函数调用模式。下面是一些示例：

• 您可以强制模型始终使用函数调用，而不是允许模型在即时自然语言回答和函数调用之间进行选择。这称为强制函数调用。

• 如果您提供了多个函数声明，则可以限制模型仅使用所提供函数的一部分。

您可以通过添加工具配置 (toolConfig) 以及提示和函数声明来实现这些约束条件（或模式）。在工具配置中，您可以指定以下某种模式。最实用的模式是 ANY。

Mode	说明
AUTO	默认的模型行为。模型决定是使用函数调用还是自然语言回答。
ANY	模型必须使用函数调用（“强制函数调用”）。如需将模型限制为仅使用部分函数，请在 allowedFunctionNames 中指定允许的函数名称。
NONE	模型不得使用函数调用。此行为等同于没有任何关联函数声明的模型请求。

Gemini 1.5 Pro 和 Gemini 1.5 Flash 支持函数调用模式。

您还可以执行哪些操作？

试用 Gemini API 的其他功能

• 构建多轮对话（聊天）。
• 根据纯文本提示生成文本。
• 从多模态提示（包括文本、图片、PDF、视频和音频）生成文本。

了解如何控制内容生成

• 了解提示设计，包括最佳实践、策略和示例提示。
• 配置模型参数，例如温度和输出 token 数上限。
• 使用安全设置来调整收到可能被视为有害的回答的可能性。

您还可以使用 Vertex AI Studio 对提示和模型配置进行实验。

详细了解 Gemini 模型

了解适用于各种用例的模型及其配额和价格。

就您使用 Vertex AI in Firebase 的体验提供反馈