カスタム関数を定義し、関数呼び出しを使用して生成 AI モデルに提供できます。モデルはこれらの関数を直接呼び出すのではなく、関数名と推奨される引数を指定する構造化データ出力を生成します。この出力により外部 API の呼び出しが可能になり、生成された API 出力をモデルに組み込めるため、より包括的なクエリ レスポンスが可能になります。関数呼び出しにより、LLM はリアルタイムの情報や、データベース、顧客関係管理システム、ドキュメント リポジトリなどのさまざまなサービスとやり取りできるようになり、関連性の高いコンテキストに応じた回答を提供する能力が強化されます。
関数呼び出しの仕組み
関数は、関数宣言を使用して記述します。クエリ内の関数宣言のリストを言語モデルに渡すと、モデルは関数の名前と引数を含むオブジェクトを OpenAPI 互換スキーマ形式で返し、返された関数のいずれかを使用してユーザークエリに応答しようとします。言語モデルは、関数宣言を分析することで関数の目的を理解します。モデルが実際に関数を呼び出すことはありません。代わりに、デベロッパーはレスポンスで OpenAPI 互換スキーマ オブジェクトを使用して、モデルが返す関数を呼び出します。
関数呼び出しを実装する場合、1 つ以上の関数宣言を作成し、モデルに渡される tools
オブジェクトに関数宣言を追加します。各関数宣言には、以下を含む 1 つの関数に関する情報が含まれます。
- 関数名
- OpenAPI 互換スキーマ形式の関数パラメータ。サブセットの選択がサポートされています。curl を使用する場合、スキーマは JSON 形式で指定します。
- 関数の説明(省略可)。最良の結果を得るために、説明を含めることをおすすめします。
Gemini API は並列関数呼び出しもサポートしており、1 回のターンで複数の関数を呼び出すことができます。
このドキュメントでは、GenerativeModel
クラスとそのメソッドを使用して REST 呼び出しを行う curl の例を紹介します。
サポートされているモデル
次のモデルは関数の呼び出しをサポートしています。
gemini-1.0-pro
gemini-1.0-pro-001
gemini-1.5-flash-latest
gemini-1.5-pro-latest
関数呼び出しモード
関数呼び出しモードを使用すると、関数呼び出しの実行動作を定義できます。次の 3 つのモードを使用できます。
AUTO
: デフォルトのモデルの動作。このモデルは、関数呼び出しまたは自然言語レスポンスのいずれかを予測します。ANY
: モデルは常に関数呼び出しを予測するように制約されています。allowed_function_names
が指定されていない場合、モデルは使用可能なすべての関数宣言からそれを選択します。allowed_function_names
が指定されている場合、モデルは使用可能な関数のセットから選択します。NONE
: モデルは関数呼び出しを予測しません。この場合、モデルの動作は、関数宣言を渡さない場合と同じです。
また、allowed_function_names
のセットを渡すこともできます。これは、指定すると、モデルが呼び出す関数を制限します。モードが ANY
の場合にのみ、allowed_function_names
を含める必要があります。関数名は、関数宣言名と一致する必要があります。モードを ANY
に設定し、allowed_function_names
を設定すると、モデルは指定された関数名のセットから関数呼び出しを予測します。
以下は、モードを ANY
に設定し、使用可能な関数のリストを指定するサンプル リクエストの一部です。
"tool_config": {
"function_calling_config": {
"mode": "ANY",
"allowed_function_names": ["find_theaters", "get_showtimes"]
},
}
cURL 呼び出しのサンプル
cURL を使用する場合、関数とパラメータの情報は tools
要素に含まれます。tools
要素内の各関数宣言には、関数名、OpenAPI 互換スキーマを使用して指定されたパラメータ、関数の説明が含まれます。次のサンプルは、関数の呼び出しで curl コマンドを使用する方法を示しています。
シングルターン curl のサンプル
シングルターンでは、言語モデルを 1 回呼び出します。関数呼び出しでは、モデルに自然言語クエリと関数のリストを提供する場合にシングルターン手法を採用する場合があります。この場合、モデルは関数名、パラメータ、説明を含む関数宣言を使用して、呼び出す関数と、関数を呼び出すために使用する引数を予測します。
次の curl サンプルは、ある映画が上映されている場所に関する情報を返す関数の説明を渡す例です。リクエストには、find_movies
や find_theaters
などの複数の関数宣言が含まれています。
シングルターン関数呼び出し curl のサンプル リクエスト
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": { "role": "user", "parts": { "text": "Which theaters in Mountain View show Barbie movie?" } }, "tools": [ { "function_declarations": [ { "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "string", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": [ "description" ] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" } }, "required": [ "location" ] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" }, "theater": { "type": "string", "description": "Name of the theater" }, "date": { "type": "string", "description": "Date for requested showtime" } }, "required": [ "location", "movie", "theater", "date" ] } } ] } ] }'
この curl の例に対するレスポンスは次のようになります。
シングルターン関数呼び出し curl のサンプル レスポンス
[{ "candidates": [ { "content": { "parts": [ { "functionCall": { "name": "find_theaters", "args": { "movie": "Barbie", "location": "Mountain View, CA" } } } ] }, "finishReason": "STOP", "safetyRatings": [ { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } ], "usageMetadata": { "promptTokenCount": 9, "totalTokenCount": 9 } }]
ANY モードを使用したシングルターンの例
次の curl の例は、シングルターンの例と似ていますが、mode を ANY
に設定します。
"tool_config": {
"function_calling_config": {
"mode": "ANY"
},
}
ANY モードを使用したシングルターン関数呼び出し(リクエスト)
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": { "role": "user", "parts": { "text": "What movies are showing in North Seattle tonight?" } }, "tools": [ { "function_declarations": [ { "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "string", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": [ "description" ] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" } }, "required": [ "location" ] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" }, "theater": { "type": "string", "description": "Name of the theater" }, "date": { "type": "string", "description": "Date for requested showtime" } }, "required": [ "location", "movie", "theater", "date" ] } } ] } ], "tool_config": { "function_calling_config": { "mode": "ANY" }, } }'
レスポンスは次のようになります。
ANY モードを使用したシングルターン関数呼び出し(レスポンス)
{ "candidates": [ { "content": { "parts": [ { "functionCall": { "name": "find_movies", "args": { "description": "", "location": "North Seattle, WA" } } } ], "role": "model" }, "finishReason": "STOP", "index": 0, "safetyRatings": [ { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" } ] } ], "promptFeedback": { "safetyRatings": [ { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } }
ANY モードと使用可能な関数を使用したシングルターンの例
次の curl の例は、シングルターンの例と似ていますが、mode が ANY
に設定され、使用可能な関数のリストが含まれています。
"tool_config": {
"function_calling_config": {
"mode": "ANY",
"allowed_function_names": ["find_theaters", "get_showtimes"]
},
}
ANY モードと使用可能な関数を使用したシングルターン関数呼び出し(リクエスト)
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": { "role": "user", "parts": { "text": "What movies are showing in North Seattle tonight?" } }, "tools": [ { "function_declarations": [ { "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "string", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": [ "description" ] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" } }, "required": [ "location" ] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "string", "description": "Any movie title" }, "theater": { "type": "string", "description": "Name of the theater" }, "date": { "type": "string", "description": "Date for requested showtime" } }, "required": [ "location", "movie", "theater", "date" ] } } ] } ], "tool_config": { "function_calling_config": { "mode": "ANY", "allowed_function_names": ["find_theaters", "get_showtimes"] }, } }'
このモデルは、許可された関数のリストに含まれていないため find_movies
関数を予測できません。そのため、代わりに別の関数を予測します。レスポンスは次のようになります。
ANY モードと使用可能な関数(レスポンス)を使用したシングルターン関数呼び出し
{ "candidates": [ { "content": { "parts": [ { "functionCall": { "name": "find_theaters", "args": { "location": "North Seattle, WA", "movie": null } } } ], "role": "model" }, "finishReason": "STOP", "index": 0, "safetyRatings": [ { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } ], "promptFeedback": { "safetyRatings": [ { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } }
マルチターン curl の例
マルチターン関数呼び出しのシナリオは、次の手順で実施できます。
- 言語モデルを呼び出して、関数呼び出しのレスポンスを取得します。これが最初のターンです。
- 最初のターンの関数呼び出しレスポンスと、その関数の呼び出しで取得した関数レスポンスを使用して、言語モデルを呼び出します。次は 2 回目のターンです。
2 回目のターンで得られるレスポンスは、最初のターンでクエリに応答するために結果を要約するか、クエリの詳細情報を取得するために使用できる 2 番目の関数呼び出しを格納します。
このトピックには、2 つのマルチターン curl の例が含まれています。
前のターンのレスポンスを使用する curl の例
次の curl サンプルは、前述のシングルターンの例で返された関数と引数を呼び出して、レスポンスを取得します。シングルターンの例から返されるメソッドとパラメータは、次の JSON に含まれています。
"functionCall": {
"name": "find_theaters",
"args": {
"movie": "Barbie",
"location": "Mountain View, CA"
}
}
マルチターン関数呼び出し curl のサンプル リクエスト
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": [{ "role": "user", "parts": [{ "text": "Which theaters in Mountain View show Barbie movie?" }] }, { "role": "model", "parts": [{ "functionCall": { "name": "find_theaters", "args": { "location": "Mountain View, CA", "movie": "Barbie" } } }] }, { "role": "function", "parts": [{ "functionResponse": { "name": "find_theaters", "response": { "name": "find_theaters", "content": { "movie": "Barbie", "theaters": [{ "name": "AMC Mountain View 16", "address": "2000 W El Camino Real, Mountain View, CA 94040" }, { "name": "Regal Edwards 14", "address": "245 Castro St, Mountain View, CA 94040" }] } } } }] }], "tools": [{ "functionDeclarations": [{ "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "STRING", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": ["description"] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "STRING", "description": "Any movie title" } }, "required": ["location"] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "STRING", "description": "Any movie title" }, "theater": { "type": "STRING", "description": "Name of the theater" }, "date": { "type": "STRING", "description": "Date for requested showtime" } }, "required": ["location", "movie", "theater", "date"] } }] }] }'
この curl の例に対するレスポンスには、find_theaters
メソッドを呼び出した結果が含まれます。レスポンスは次のようになります。
マルチターン関数呼び出し curl のサンプル レスポンス
{ "candidates": [ { "content": { "parts": [ { "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14." } ] } } ], "usageMetadata": { "promptTokenCount": 9, "candidatesTokenCount": 27, "totalTokenCount": 36 } }
言語モデルを複数回呼び出す curl の例
次の curl の例では、言語モデルを複数回呼び出して関数を呼び出します。モデルが関数を呼び出すたびに、異なる関数を使用して、リクエスト内の異なるユーザークエリに応答できます。
マルチターン関数呼び出し curl のサンプル リクエスト
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \ -H 'Content-Type: application/json' \ -d '{ "contents": [{ "role": "user", "parts": [{ "text": "Which theaters in Mountain View show Barbie movie?" }] }, { "role": "model", "parts": [{ "functionCall": { "name": "find_theaters", "args": { "location": "Mountain View, CA", "movie": "Barbie" } } }] }, { "role": "function", "parts": [{ "functionResponse": { "name": "find_theaters", "response": { "name": "find_theaters", "content": { "movie": "Barbie", "theaters": [{ "name": "AMC Mountain View 16", "address": "2000 W El Camino Real, Mountain View, CA 94040" }, { "name": "Regal Edwards 14", "address": "245 Castro St, Mountain View, CA 94040" }] } } } }] }, { "role": "model", "parts": [{ "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14." }] },{ "role": "user", "parts": [{ "text": "Can we recommend some comedy movies on show in Mountain View?" }] }], "tools": [{ "functionDeclarations": [{ "name": "find_movies", "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "description": { "type": "STRING", "description": "Any kind of description including category or genre, title words, attributes, etc." } }, "required": ["description"] } }, { "name": "find_theaters", "description": "find theaters based on location and optionally movie title which is currently playing in theaters", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "STRING", "description": "Any movie title" } }, "required": ["location"] } }, { "name": "get_showtimes", "description": "Find the start times for movies playing in a specific theater", "parameters": { "type": "OBJECT", "properties": { "location": { "type": "STRING", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616" }, "movie": { "type": "STRING", "description": "Any movie title" }, "theater": { "type": "STRING", "description": "Name of the theater" }, "date": { "type": "STRING", "description": "Date for requested showtime" } }, "required": ["location", "movie", "theater", "date"] } }] }] }'
マルチターン関数呼び出し curl のサンプル レスポンス
[{ "candidates": [ { "content": { "parts": [ { "functionCall": { "name": "find_movies", "args": { "description": "comedy", "location": "Mountain View, CA" } } } ] }, "finishReason": "STOP", "safetyRatings": [ { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_HATE_SPEECH", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "NEGLIGIBLE" }, { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "probability": "NEGLIGIBLE" } ] } ], "usageMetadata": { "promptTokenCount": 48, "totalTokenCount": 48 } } ]
ベスト プラクティス
関数呼び出しの精度と信頼性を向上させるには、次のベスト プラクティスに従ってください。
ファンクション キーのフィールド
関数をリクエストに統合する場合は、関数を正確に定義することが重要です。各関数は、その動作とモデルとのやり取りを左右する特定のパラメータに依存します。以下に、functions_declarations
配列で使用される主なパラメータの詳細を示します。
function_declarations
(配列):
- 1 つ以上のオブジェクトが含まれ、それぞれが個別の関数を表します。
各 function_declarations
オブジェクト内で、次の処理を行います。
name
(文字列): API 呼び出し内の関数の一意の識別子。- ベスト プラクティス: スペース、ピリオド(
.
)、ダッシュ(-
)などの文字を含まない、明確でわかりやすい名前を使用します。代わりに、アンダースコア(_
)文字またはキャメルケースを使用してください。
- ベスト プラクティス: スペース、ピリオド(
description
(文字列): 関数の目的と機能の包括的な説明。- おすすめの方法: 関数の説明は詳細、明確、具体的にし、必要に応じて例を提供します。たとえば、
find theaters
ではなくfind theaters based on location and optionally movie title that is currently playing in theaters.
を使用します。広すぎる説明や曖昧な説明は避けてください。
- おすすめの方法: 関数の説明は詳細、明確、具体的にし、必要に応じて例を提供します。たとえば、
parameters
(オブジェクト): 関数に必要な入力データを定義します。type
(文字列): 全体的なデータ型を指定します(例:object
).properties
(オブジェクト):- 個々のパラメータを列挙します。それぞれは次のとおりです。
type
(文字列): パラメータのデータ型(例:string
、integer
、boolean
)。- ベスト プラクティス: モデルのハルシネーションを減らすために、厳密に型指定されたパラメータを使用します。たとえば、パラメータ値が有限セットからのものである場合は、説明に値をリストする代わりに
enum
フィールドを使用します(例:"type": "enum", "values": ["now_playing", "upcoming"]
)。パラメータ値が常に整数の場合は、型をnumber
ではなくinteger
に設定します。
- ベスト プラクティス: モデルのハルシネーションを減らすために、厳密に型指定されたパラメータを使用します。たとえば、パラメータ値が有限セットからのものである場合は、説明に値をリストする代わりに
description
(文字列): パラメータの目的と想定される形式に関する明確な説明。- ベスト プラクティス: 具体的な例と制約を記載します。たとえば、
the location to search
ではなくThe city and state, e.g. San Francisco, CA or a zip code e.g. 95616
を使用します。
- ベスト プラクティス: 具体的な例と制約を記載します。たとえば、
- 個々のパラメータを列挙します。それぞれは次のとおりです。
required
(配列):- 関数の動作に必須のパラメータ名がリストされた文字列の配列。
ユーザーによるプロンプト
最適な結果を得るには、ユーザークエリの先頭に次の詳細を付加します。
- モデルに関する追加のコンテキスト。例:
You are a movie API assistant to help users find movies and showtimes based on their preferences.
- 関数をいつ、どのように使用するかに関する詳細や手順。例:
Don't make assumptions on showtimes. Always use a future date for showtimes.
- ユーザーの質問があいまいな場合に、明確にするための質問をする手順。例:
Ask clarifying questions if not enough information is available to complete the request.
サンプリング パラメータ
Temperature パラメータには、0
または別の小さい値を使用します。これにより、より確信度の高い結果を生成してハルシネーションを減らすようにモデルに指示します。
API 呼び出し
注文の送信やデータベースの更新など、重大な結果をもたらすような関数の呼び出しをモデルが提案する場合は、それを実行する前にユーザーにその関数呼び出しの妥当性を確認してください。