使用 Gemini API 进行函数调用


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

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

函数调用可以帮助您克服其中一些限制。函数调用有时也称为“工具使用”，因为它允许模型使用 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.

显示函数调用如何涉及模型与应用中的函数交互的示意图 

实现函数调用

准备工作

请完成 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。

第 2 步：创建函数声明

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

在声明中，请在函数及其参数的说明中尽可能多添加一些详细信息。

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

对于您提供的架构，请注意以下事项：

  • 您必须以与 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 步：在模型初始化期间提供函数声明

请求中可提供的函数声明的最大数量为 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 的其他功能

了解如何控制内容生成

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

详细了解 Gemini 模型

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


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