関数呼び出しを使用すると、生成モデルから構造化データの出力を簡単に取得できます。これらの出力を使用して他の API を呼び出し、関連するレスポンス データをモデルに返すことができます。つまり、関数呼び出しを使用すると、生成モデルを外部システムに接続し、生成されたコンテンツに最新かつ正確な情報を含めることができます。
Gemini モデルに関数の説明を提供できます。これらは、アプリの言語で記述する関数です（Google Cloud Functions ではありません）。モデルがクエリを処理できるように、関数を呼び出して結果を返信するようモデルから求められることがあります。
まだ利用していない場合は、関数呼び出しの概要で詳細をご確認ください。
照明制御用の API の例
アプリケーション プログラミング インターフェース（API）を備えた基本的な照明制御システムがあり、ユーザーが単純なテキスト リクエストを通じて照明を制御できるようにするとします。関数呼び出し機能を使用すると、ユーザーからの照明の変更リクエストを解釈し、API 呼び出しに変換して照明値を設定できます。この架空の照明制御システムを使用すると、照明の明るさと色温度を 2 つの個別のパラメータとして制御できます。
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
brightness |
数値 | あり | 光レベル（0 ～ 100）。ゼロがオフで、100 が最大の明るさです。 |
colorTemperature |
string | あり | 照明器具の色温度（daylight、cool、warm）。 |
わかりやすくするため、この架空の照明システムにはライトが 1 つしかないため、ユーザーは部屋や場所を指定する必要はありません。次に示す JSON リクエストの例を照明制御 API に送信し、昼光色温度を使用して照明レベルを 50% に変更します。
{
"brightness": "50",
"colorTemperature": "daylight"
}
このチュートリアルでは、ユーザーの照明リクエストを解釈し、それらを API 設定にマッピングしてライトの明るさと色温度の値を制御するために、Gemini 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 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);
}