教程：函数调用

<ph type="x-smartling-placeholder"></ph>

函数调用可让您更轻松地从 Google Cloud 控制台获取结构化数据输出 生成模型。然后，您可以使用这些输出来调用其他 API 并返回 将相关的响应数据提供给模型。换句话说，函数调用有助于 将生成模型连接到外部系统， 可提供最新、最准确的信息。

您可以为 Gemini 模型提供函数说明。这些是 以应用语言编写的函数（也就是说，它们 Google Cloud Functions）。模型可能会要求您调用一个函数并返回 帮助模型处理您的查询。

如果您还没看过 函数调用简介（用于学习相关知识）

照明控制示例 API

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

参数 类型 是否必需 说明
brightness number 是 光级范围为 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'
    ]));

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

当您想将函数调用与模型搭配使用时，必须在初始化模型对象时提供函数声明。您声明 函数。toolsDart 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);
}