教程：函数调用

借助函数调用，您可以更轻松地从生成式模型获取结构化数据输出。然后，您可以使用这些输出来调用其他 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 函数，该函数只会返回请求的照明值：

Future<Map<String, Object?>> setLightValues(
  Map<String, Object?> arguments,
) async =>
    // This mock API returns the requested lighting values
    {
      'brightness': arguments['brightness'],
      'colorTemperature': arguments['colorTemp'],
    };

创建函数声明

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

final lightControlTool = FunctionDeclaration(
    'setLightValues',
    'Set the brightness and color temperature of a room light.',
    Schema(SchemaType.object, properties: {
      'brightness': Schema(SchemaType.number,
          description: 'Light level from 0 to 100. '
              'Zero is off and 100 is full brightness.'),
      'colorTemperature': Schema(SchemaType.string,
          description: 'Color temperature of the light fixture, '
              'which can be `daylight`, `cool` or `warm`.'),
    }, requiredProperties: [
      'brightness',
      'colorTemperature'
    ]));

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

当您想将函数调用与模型搭配使用时，必须在初始化模型对象时提供函数声明。您可以通过设置模型的 tools 参数来声明函数。Dart SDK 还支持将函数声明为 generateContent 或 generateContentStream API 的参数。

final model = GenerativeModel(
  model: 'gemini-1.5-flash',
  apiKey: apiKey,

  // Specify the function declaration.
  tools: [
    Tool(functionDeclarations: [lightControlTool])
  ],
);

生成函数调用

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

final chat = model.startChat(); final prompt =
  'Dim the lights so the room feels cozy and warm.';

// Send the message to the generative model.
var response = await chat.sendMessage(Content.text(prompt));

final functionCalls = response.functionCalls.toList();
// When the model response with a function call, invoke the function.
if (functionCalls.isNotEmpty) {
  final functionCall = functionCalls.first;
  final result = switch (functionCall.name) {
    // Forward arguments to the hypothetical API.
    'setLightValues' => await setLightValues(functionCall.args),
    // Throw an exception if the model attempted to call a function that was
    // not declared.
    _ => throw UnimplementedError(
        'Function not implemented: ${functionCall.name}')
  };
  // Send the response to the model so that it can use the result to generate
  // text for the user.
  response = await chat
      .sendMessage(Content.functionResponse(functionCall.name, result));
}
// When the model responds with non-null text content, print it.
if (response.text case final text?) {
  print(text);
}