関数呼び出しのチュートリアル

関数呼び出しを使用すると、生成モデルから構造化データの出力を簡単に取得できます。これらの出力を使用して他の API を呼び出し、関連するレスポンス データをモデルに返すことができます。つまり、関数呼び出しにより、生成モデルを外部システムに接続して、生成されたコンテンツに最新かつ正確な情報を含めることができます。

Gemini モデルに関数の説明を指定できます。これらは、アプリの言語で記述する関数です（Google Cloud Functions ではありません）。モデルがクエリの処理に役立つ関数を呼び出して結果を返すよう求める場合があります。

まだ確認していない場合は、関数呼び出しの概要で詳細を確認してください。

照明制御の API の例

アプリケーション プログラミング インターフェース（API）を備えた基本的な照明制御システムがあり、ユーザーが簡単なテキスト リクエストで照明を制御できるようにしたいとします。関数呼び出し機能を使用すると、ユーザーからの照明変更リクエストを解釈し、API 呼び出しに変換して照明値を設定できます。この架空の照明制御システムでは、ライトの明るさと色温度を 2 つの個別のパラメータとして制御できます。

パラメータ タイプ 必須 / 省略可 説明
brightness 数値 あり 明るさレベル（0 ～ 100）。0 はオフ、100 は最大の明るさです。
colorTemperature 文字列 あり 照明器具の色温度（daylight、cool、warm のいずれか）。

わかりやすくするために、この架空の照明システムにはライトが 1 つしかなく、ユーザーは部屋や場所を指定する必要はありません。照明制御 API に送信して、昼光色温度を使用して照明レベルを 50% に変更する JSON リクエストの例を次に示します。

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

このチュートリアルでは、Gemini API の関数呼び出しを設定して、ユーザーの照明リクエストを解釈し、API 設定にマッピングして、照明の明るさと色温度の値を制御する方法について説明します。

始める前に: プロジェクトと API キーを設定する

Gemini 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 API または 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);
}