函式呼叫教學課程

函式呼叫可讓您輕鬆取得結構化資料輸出內容 生成式模型接著,您可以使用這些輸出內容呼叫其他 API,並將相關回應資料傳回模型。換句話說,函式呼叫有助於 必須連結生成式模型與外部系統 內含最新且準確的資訊。

您可以為 Gemini 模型提供函式說明。這些函式是使用應用程式語言編寫的函式 (也就是說,它們不是 Google Cloud Functions)。模型可能會要求您呼叫函式,然後傳回 以便模型處理查詢

如果您還不瞭解 函式呼叫簡介: 詳情

照明控制 API 範例

假設您有一個基本的照明控制系統 搭配應用程式設計 介面 (API),並希望使用者能透過簡單的 文字要求您可以使用函式呼叫功能,解讀使用者提出的燈光變更要求,並將這些要求轉譯為 API 呼叫,以便設定燈光值。這個假設的照明控制系統可讓您控制燈光的亮度和色溫,這兩個參數分別定義如下:

參數 類型 必要 說明
brightness 數字 光線強度從 0 到 100。零關閉,100 為全彩。
colorTemperature 字串 燈具的色溫,可能是 daylightcoolwarm

為簡化說明,這個假想的照明系統只有一盞燈,因此使用者不必指定房間或位置。以下是您可以傳送至照明控制 API 的 JSON 要求範例,藉此使用日光色溫將燈光亮度變更為 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);
}