教程：函数调用

借助函数调用，您可以更轻松地从生成式模型获取结构化数据输出。然后，您可以使用这些输出来调用其他 API，并将相关响应数据返回给模型。换句话说，函数调用可帮助您将生成式模型连接到外部系统，以便生成的内容包含最新、最准确的信息。

您可以为 Gemini 模型提供函数说明。这些函数是使用应用所用语言编写的（即它们不是 Google Cloud Functions 函数）。模型可能会要求您调用函数并发回结果，以帮助模型处理您的查询。

如果您尚未了解，请参阅函数调用简介了解详情。

用于照明控制的 API 示例

假设您有一个带有应用编程接口 (API) 的基本照明控制系统，并且希望允许用户通过简单的文本请求控制灯具。您可以使用函数调用功能来解读用户发来的照明更改请求，并将其转换为 API 调用以设置照明值。通过这个假想的照明控制系统，您可以控制灯的亮度和色温，这两个参数定义如下：

参数 类型 是否必需 说明
brightness 数值 是 亮度级别，介于 0 到 100 之间。0 表示关闭，100 表示全亮度。
colorTemperature 字符串 是 灯具的色温，可以是 daylight、cool 或 warm。

为简单起见，这个虚构的照明系统只有一个灯，因此用户无需指定房间或位置。以下是一个 JSON 请求示例，您可以将其发送到照明控制 API，以使用日光色温将亮度更改为 50%：

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

本教程介绍了如何为 Gemini API 设置函数调用，以解读用户的照明请求并将其映射到 API 设置，从而控制灯具的亮度和色温值。

开始前须知：设置项目和 API 密钥

在调用 Gemini API 之前，您需要设置项目并配置 API 密钥。

定义 API 函数

创建用于发出 API 请求的函数。此函数应在应用代码中定义，但可以调用应用之外的服务或 API。Gemini API 不会直接调用此函数，因此您可以通过应用代码控制此函数的执行方式和时间。出于演示目的，本教程定义了一个模拟 API 函数，该函数只会返回请求的照明值：

async function setLightValues(brightness, colorTemp) {
  // This mock API returns the requested lighting values
  return {
    brightness: brightness,
    colorTemperature: colorTemp
  };
}

创建函数声明

创建要传递给生成式模型的函数声明。声明供模型使用的函数时，您应在函数和参数说明中尽可能提供详细信息。生成式模型会使用这些信息来确定要选择哪个函数，以及如何为函数调用中的参数提供值。以下代码展示了如何声明照明控制函数：

// Function declaration, to pass to the model.
const controlLightFunctionDeclaration = {
  name: "controlLight",
  parameters: {
    type: "OBJECT",
    description: "Set the brightness and color temperature of a room light.",
    properties: {
      brightness: {
        type: "NUMBER",
        description: "Light level from 0 to 100. Zero is off and 100 is full brightness.",
      },
      colorTemperature: {
        type: "STRING",
        description: "Color temperature of the light fixture which can be `daylight`, `cool` or `warm`.",
      },
    },
    required: ["brightness", "colorTemperature"],
  },
};

// Executable function code. Put it in a map keyed by the function name
// so that you can call it once you get the name string from the model.
const functions = {
  controlLight: ({ brightness, colorTemp }) => {
    return setLightValues( brightness, colorTemp)
  }
};

在模型初始化期间声明函数

当您想将函数调用与模型搭配使用时，必须在初始化模型对象时提供函数声明。您可以通过设置模型的 tools 参数来声明函数：

<html>
  <body>
    <!-- ... Your HTML and CSS -->

    <script type="importmap">
      {
        "imports": {
          "@google/generative-ai": "https://esm.run/@google/generative-ai"
        }
      }
    </script>
    <script type="module">
      import { GoogleGenerativeAI } from "@google/generative-ai";

      // Fetch your API_KEY
      const API_KEY = "...";

      // Access your API key (see "Set up your API key" above)
      const genAI = new GoogleGenerativeAI(API_KEY);

      // ...

      const generativeModel = genAI.getGenerativeModel({
        // Use a model that supports function calling, like a Gemini 1.5 model
        model: "gemini-1.5-flash",

        // Specify the function declaration.
        tools: {
          functionDeclarations: [controlLightFunctionDeclaration],
        },
      });
    </script>
  </body>
</html>

生成函数调用

使用函数声明初始化模型后，您可以使用定义的函数向模型提示问题。您应使用聊天提示 (sendMessage()) 进行函数调用，因为函数调用通常会受益于拥有先前提示和响应的上下文。

const chat = generativeModel.startChat();
const prompt = "Dim the lights so the room feels cozy and warm.";

// Send the message to the model.
const result = await chat.sendMessage(prompt);

// For simplicity, this uses the first function call found.
const call = result.response.functionCalls()[0];

if (call) {
  // Call the executable function named in the function call
  // with the arguments specified in the function call and
  // let it call the hypothetical API.
  const apiResponse = await functions[call.name](call.args);

  // Send the API response back to the model so it can generate
  // a text response that can be displayed to the user.
  const result = await chat.sendMessage([{functionResponse: {
    name: 'controlLight',
    response: apiResponse
  }}]);

  // Log the text response.
  console.log(result.response.text());
}