カスタム関数は、Functions API を使用して定義し、Gemini モデルに提供できます 通話機能。モデルはこれらの関数を直接呼び出すのではなく、 関数名と推奨する関数を指定して、構造化データの出力を生成する 渡します。この出力を使用すると、構造化された形式を 外部 API の呼び出しを行えます。さらに、この API 出力を モデル プロンプトに組み込まれているため、より包括的なクエリが可能 できます。関数呼び出しにより、ユーザーはリアルタイムで 情報、各種サービス(データベース、顧客関係管理、 ドキュメント リポジトリなど、さまざまなシステムへの依存を強化し、 コンテキストに沿った関連性の高い回答を提供します。
関数呼び出しの仕組み
関数呼び出し機能を使用するには、クエリの内容を記述する構造化クエリデータを追加します。 プログラミング インターフェース(関数宣言)をモデル プロンプトに追加します。「 関数宣言では、API 関数の名前、その目的、 パラメータとその説明。合格後 クエリ内の関数宣言のリストをモデルに送信すると、 それからクエリの残りの部分を使用して、宣言された API を返します。
その後、このモデルは OpenAPI 互換スキーマ 応答するために宣言された 1 つ以上の関数を呼び出す方法を指定する と回答します。その後、推奨される関数呼び出しを使用して、 実際の API を呼び出してレスポンスを取得し、そのレスポンスを ユーザーに配信してもらうことができます。なお、このモデルでは、実際の呼び出しは 使用できます。代わりに、返されたスキーマ オブジェクト パラメータを使用して、 関数を呼び出します。Gemini API は、並列関数呼び出しもサポートしています。 モデルは、1 つのリクエストに基づいて複数の API 関数呼び出しを推奨しています。
サポートされているモデル
次のモデルは、関数呼び出し機能をサポートしています。
gemini-1.0-pro
gemini-1.0-pro-001
gemini-1.5-flash-latest
gemini-1.5-pro-latest
関数宣言
プロンプトで関数呼び出しを実装する場合は、tools
オブジェクトを作成します。
これには 1 つ以上の function declarations
が含まれます。お客様が関数を定義する
具体的には JSON 形式での
サブセットを選択
OpenAPI スキーマ
使用できます。1 つの関数宣言には、次のパラメータを含めることができます。
name
(文字列): API 内の関数の一意の識別子 あります。description
(文字列): 関数の包括的な説明 説明します。parameters
(オブジェクト): 関数に必要な入力データを定義します。type
(文字列): 全体的なデータ型を指定します(object
など)。properties
(オブジェクト): 次のパラメータを持つ、個々のパラメータをリストします。type
(文字列): パラメータのデータ型。例:string
、integer
、boolean
。description
(文字列): パラメータのわかりやすい説明 適切な形式を指定します。
required
(配列): パラメータ名をリストした文字列の配列 必須の引数です。
cURL コマンドを使用した関数宣言のコード例については、 関数呼び出しの例。例 他のプラットフォーム用の関数宣言を作成する方法については、 関数呼び出しプラットフォームのガイド
関数宣言のベスト プラクティス
関数を正確に定義することは、
できます。各関数は、その動作を導く特定のパラメータに依存します
モデルとやり取りできます次のリストは、
functions_declarations
で個々の関数のパラメータを定義する
あります。
name
: スペースやピリオドを付けずに、明確でわかりやすい名前を使用します。 (.
)、ダッシュ(-
)を使用できます。代わりに、アンダースコア(_
)文字を使用してください。 キャメルケースも使用できます。description
: 詳細かつ明確で具体的な機能を提供する 説明を入力し、必要に応じて例を提供します。たとえば、find theaters
:find theaters based on location and optionally movie title that is currently playing in theaters.
を使用し、過度に広範囲またはあいまいな表現は避ける 説明があります。properties
件 >type
: 厳密に型指定されたパラメータを使用して、 モデルハルシネーションですたとえば、パラメータ値が有限 説明に値を記載するのではなく、enum
フィールドを使用してください。 (例:"type": "enum", "values": ["now_playing", "upcoming"]
)。もし パラメータの値は常に整数なので、型をinteger
に設定しますnumber
。properties
件 >description
: 具体的な例と制約を示します。 たとえば、the location to search
ではなくThe city and state, e.g. San Francisco, CA or a zip code e.g. 95616
を使用します。
関数呼び出しを使用する際のベスト プラクティスについては、 ベスト プラクティス セクションをご覧ください。
関数呼び出しモード
関数呼び出しの mode
パラメータを使用して、実行内容を変更できます。
制御できます。次の 3 つのモードがあります。
AUTO
: モデルのデフォルトの動作。モデルは、予測を行うか、 自然言語レスポンスを使って処理できます。ANY
: モデルは常に関数呼び出しを予測するように制約されます。条件allowed_function_names
が指定されていない場合、モデルはすべての あります。allowed_function_names
が指定されている場合は、 モデルは使用可能な関数のセットから選択しNONE
: モデルは関数呼び出しを予測しません。この場合、モデルは 動作は、関数宣言を渡しない場合と同じです。
また、指定された場合、その制限を allowed_function_names
のセットに渡すこともできます。
モデルが呼び出す関数を定義します。説明に
モードが ANY
の場合は allowed_function_names
。関数名は一致している必要があります
関数宣言名を指定します。モードを ANY
に設定し、
allowed_function_names
が設定されている場合、モデルは
関数名のセットが提供されます。次のコード スニペットは、
リクエストの例では、
mode
を ANY
に設定し、使用できる関数のリストを指定します。
"tool_config": {
"function_calling_config": {
"mode": "ANY",
"allowed_function_names": ["find_theaters", "get_showtimes"]
},
}
関数呼び出しの例
このセクションでは、cURL コマンドを使用して関数呼び出しを行うプロンプトの例を示します。 たとえば、シングルターンとマルチターンのシナリオ、 関数呼び出しモードごとに異なります
この機能で cURL コマンドを使用する場合、
情報は tools
要素に含まれています。Deployment に含まれる各関数宣言
tools
要素には関数名が含まれます。パラメータは、
OpenAPI 互換スキーマ
関数の説明を入力します
シングルターンの例
シングルターンでは、言語モデルを 1 回呼び出します。関数呼び出しでは、モデルに自然言語クエリと関数のリストを提供する場合にシングルターン手法を採用する場合があります。この場合、モデルは関数名、パラメータ、説明を含む関数宣言を使用して、呼び出す関数と、関数を呼び出すために使用する引数を予測します。
次の curl サンプルは、ある映画が上映されている場所に関する情報を返す関数の説明を渡す例です。複数
リクエストに関数宣言が含まれている(find_movies
や
find_theaters
。
シングルターン関数呼び出しのリクエスト例
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" } ] } }
マルチターンの例
マルチターン関数呼び出しのシナリオは、次の手順で実施できます。
- 言語モデルを呼び出して、関数呼び出しのレスポンスを取得します。これが最初のターンです。
- 最初のターンの関数呼び出しレスポンスと、その関数の呼び出しで取得した関数レスポンスを使用して、言語モデルを呼び出します。次は 2 回目のターンです。
2 回目のターンで得られるレスポンスは、最初のターンでクエリに応答するために結果を要約するか、クエリの詳細情報を取得するために使用できる 2 番目の関数呼び出しを格納します。
このトピックには、2 つのマルチターン 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 の例では、生成 AI モデルを複数回呼び出して、 作成します。モデルが関数を呼び出すたびに、異なる関数を使用できます。 関数を使用して、リクエスト内の別のユーザークエリに応答します。
マルチターン関数呼び出し 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 } } ]
ベスト プラクティス
これらのベスト プラクティスに従って、 関数呼び出しの信頼性を維持できます。
ユーザーによるプロンプト
最適な結果を得るには、ユーザークエリの先頭に次の詳細を付加します。
- モデルの追加コンテキスト。例:
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 呼び出し
注文の送信やデータベースの更新など、重大な結果をもたらすような関数の呼び出しをモデルが提案する場合は、それを実行する前にユーザーにその関数呼び出しの妥当性を確認してください。