このページは Cloud Translation API によって翻訳されました。

関数呼び出し

概要

大規模言語モデル（LLM）は、さまざまな問題の解決に効果的です。ただし、次のような制限があります。

トレーニングが完了すると固定されるため、新しい知識で更新されません。
外部データのクエリや変更はできません。

関数呼び出しを使用すると、こうした欠点を補うことができます。関数呼び出しは、カスタム関数を定義して、生成 AI モデルに提供するために使用できます。たとえば、位置情報パラメータを受け取り、その場所の天候に関する情報を返す関数 get_weather を定義できます。

プロンプトの処理中に、指定された関数に特定のデータ処理タスクを委任できます。モデルは関数を直接呼び出しません。代わりに、呼び出す関数と使用するパラメータ値を含む構造化データの出力を提供します。たとえば、「What is the weather like in Boston?」というプロンプトの場合、モデルは処理を get_weather 関数に委任し、位置情報パラメータの値 Boston, MA を渡します。

モデルからの構造化出力を使用して、外部 API を呼び出すことができます。たとえば、天気予報サービスの API に接続し、場所 Boston, MA を渡して、気温、雲量、風の状態などの情報を取得できます。

その後、API の出力をモデルに提供し、プロンプトに対する回答を完成させることができます。この天気の例では、モデルは「It is currently 38 degrees Fahrenheit in Boston, MA with partly cloudy skies.」という回答を返す可能性があります。

関数呼び出しのインタラクション

次のモデルは関数呼び出しをサポートしています。

モデル	バージョン	関数呼び出しのリリースステージ	並列関数呼び出しのサポート	強制関数呼び出しのサポート
`Gemini 1.0 Pro`	`gemini-1.0-pro-001`	一般提供	×	×
`Gemini 1.0 Pro`	`gemini-1.0-pro-002`	一般提供	×	×
`Gemini 1.5 Flash`	`gemini-1.5-flash-001`	一般提供	はい	×
`Gemini 1.5 Pro`	`gemini-1.5-pro-001`	一般提供	はい	はい

関数呼び出しのユースケース

関数呼び出しは、次のようなタスクに使用できます。

ユースケース	記述例	リンクの例
自然言語のストーリーからエンティティを抽出する	ストーリーから登場人物、関係性、もの、場所のリストを抽出します。	関数呼び出しを使用した構造化データの抽出 [Vertex AI SDK for Python ノートブック]
自然言語を使用して SQL データベースをクエリして理解する	「`What percentage of orders are returned?`」などの質問を SQL クエリに変換し、それを BigQuery に送信する関数を作成するようにモデルに指示します。	Gemini で関数呼び出しを使用して、AI を活用した BigQuery Data Exploration App を構築する [ブログ投稿]
ユーザーが企業とやり取りできるようにする	企業の API に接続する関数を作成して、モデルがクエリ（`Do you have the Pixel 8 Pro in stock?` や `Is there a store in Mountain View, CA that I can visit to try it out?` など）に正確な回答を提供できるようにします。	Vertex AI Gemini API と Python SDK を使用した関数呼び出し [Vertex AI SDK for Python ノートブック]
		REST のサンプル
		Vertex AI SDK for Python チャットサンプル
公開 API に接続して生成 AI アプリケーションを構築する	通貨を変換する。通貨両替アプリに接続する関数を作成して、モデルがクエリ（`What's the exchange rate for euros to dollars today?`）に正確な回答を提供できるようにします。	Gemini で関数呼び出しを使用して API を操作する方法 [Codelab]
	指定した場所の天気を確認する。気象サービスの API に接続する関数を作成して、モデルがクエリ（`What's the weather like in Paris?`）に正確な回答を提供できるようにします。	Vertex AI Gemini API と Python SDK を使用した関数呼び出し [Vertex AI SDK for Python ノートブック]
		関数呼び出し: Gemini を外部システム、データ、API に接続するネイティブフレームワーク [ブログ投稿]
		Vertex AI SDK for Python と Node.js のテキストサンプル
		Node.js、Java、Go のチャットサンプル
	住所を緯度と経度の座標に変換する。構造化された位置情報を緯度と経度の座標に変換する関数を作成します。「`I want to get the lat/lon coordinates for the following address: 1600 Amphitheatre Pkwy, Mountain View, CA 94043, US.`」というクエリで番地、市町村、都道府県、郵便番号を認識するようにモデルに指示します。	Vertex AI Gemini API と Python SDK を使用した関数呼び出し [Vertex AI SDK for Python ノートブック]
音声コマンドを解釈する。	車内での操作に対応する関数を作成します。たとえば、ラジオをオンにする関数や、エアコンをつける関数を作成できます。ユーザーの音声コマンドの音声ファイルをモデルに送信し、音声をテキストに変換して、ユーザーが呼び出したい関数を特定するようにモデルに指示します。
環境センサーのトリガーに基づいてワークフローを自動化する。	自動化できるプロセスを表す関数を作成します。環境センサーからのデータをモデルに提供し、そのデータを解析、処理して、1 つ以上のワークフローを起動すべきかどうかを判断するように指示します。たとえば、モデルが倉庫内の温度データを処理してスプリンクラー機能を起動できるようにします。
サポートチケットの割り当てを自動化する。	サポートチケット、ログ、コンテキストアウェアルールをモデルに提供します。チケットを割り当てるユーザーを判断するために、これらの情報をすべて処理するようにモデルに指示します。モデルが提案した人にチケットを割り当てる関数を呼び出します。
ナレッジベースから情報を取得する。	特定のテーマに関する学術論文を取得して要約する関数を作成します。モデルが、学術的なテーマに関する質問に答え、その回答の引用元を提示できるようにします。

関数呼び出しのアプリケーションを作成する

ユーザーがモデルとインターフェースを接続して関数呼び出しを使用できるようにするには、次のタスクを実行するコードを作成する必要があります。

モデルを初期化する。
ユーザープロンプトを定義する。
関数宣言を使用して、使用可能な一連の関数を定義、記述する。
ユーザーのプロンプトと関数宣言をモデルに送信する。
モデルから出力された構造化データを使用して、関数を呼び出す。
関数の出力をモデルに提供する。

これらすべてのタスクを管理するアプリケーションを作成できます。このようなアプリケーションには、テキスト chatbot、音声エージェント、自動ワークフローなどがあります。

関数呼び出しを使用して、単一のテキストレスポンスを生成することや、チャットセッションをサポートすることが可能です。アドホックなテキストレスポンスは、コードの生成など、特定のビジネスタスクで役立ちます。チャットセッションは、ユーザーがフォローアップの質問をする可能性が高い自由形式の会話のシナリオで役立ちます。

関数呼び出しを使用して単一のレスポンスを生成する場合は、やり取りの完全なコンテキストをモデルに提供する必要があります。一方、チャットセッションのコンテキストで関数呼び出しを使用する場合、セッションではコンテキストが保存され、すべてのモデルリクエストにそれが追加されます。どちらの場合も、Vertex AI はやり取りの履歴をクライアント側に保存します。

このガイドでは、関数呼び出しを使用して単一のテキストレスポンスを生成する方法について説明します。エンドツーエンドのサンプルについては、テキストの例をご覧ください。関数呼び出しを使用してチャットセッションをサポートする方法については、チャットの例をご覧ください。

モデルを初期化する

モデルを初期化する方法の例を次に示します。

Python

import vertexai
from vertexai.generative_models import (
    Content,
    FunctionDeclaration,
    GenerationConfig,
    GenerativeModel,
    Part,
    Tool,
)

# Initialize Vertex AI
# TODO(developer): Update and un-comment below lines
# project_id = 'PROJECT_ID'
vertexai.init(project=project_id, location="us-central1")

# Initialize Gemini model
model = GenerativeModel(model_name="gemini-1.0-pro-001")

ユーザープロンプトを定義する

ここでは、「What is the weather like in Boston?」というユーザープロンプトの例を示します。

このユーザープロンプトを次の例のように定義します。

Python

# Define the user's prompt in a Content object that we can reuse in model calls
user_prompt_content = Content(
    role="user",
    parts=[
        Part.from_text("What is the weather like in Boston?"),
    ],
)

ユーザープロンプトに関するベストプラクティスについては、ベストプラクティス - ユーザープロンプトをご覧ください。

使用可能な一連の関数を定義して記述する

アプリケーションでは、モデルがプロンプトを処理するために使用できる一連の関数を宣言する必要があります。各関数の宣言には、関数名と関数パラメータを記述する必要があります。各関数の宣言に関数の説明も含めることを強くおすすめします。

リクエストで指定できる関数宣言の最大数は 128 です。

関数名

アプリケーションとモデルは、関数を特定するために関数名を使用します。

関数名に関するベストプラクティスについては、ベストプラクティス - 関数名をご覧ください。

関数のパラメータ

関数パラメータは、OpenAPI スキーマと互換性のある形式で指定する必要があります。

Vertex AI は、OpenAPI スキーマを限定的にサポートしています。サポートされている属性は、type、nullable、required、format、description、properties、items、enum です。属性 default、optional、maximum、oneOf はサポートされていません。

curl を使用する場合は、JSON を使用してスキーマを指定します。Vertex AI SDK for Python を使用する場合は、Python 辞書を使用してスキーマを指定します。

関数パラメータに関するベストプラクティスについては、ベストプラクティス - 関数パラメータをご覧ください。

関数の説明

モデルは、関数の説明を使用して関数の目的を理解し、関数がユーザークエリの処理に役立つかどうかを判断します。

関数の説明に関するベストプラクティスについては、ベストプラクティス - 関数の説明をご覧ください。

関数宣言の例

Python: 単純な宣言

Python での単純な関数宣言の例を次に示します。

function_name = "get_current_weather"
get_current_weather_func = FunctionDeclaration(
    name=function_name,
    description="Get the current weather in a given location",
    parameters={
        "type": "object",
        "properties": {"location": {"type": "string", "description": "The city name of the location for which to get the weather."}},
    },
)

Python: 項目の配列

項目の配列がある関数宣言の例を次に示します。

extract_sale_records_func = FunctionDeclaration(
  name="extract_sale_records",
  description="Extract sale records from a document.",
  parameters={
      "type": "object",
      "properties": {
          "records": {
              "type": "array",
              "description": "A list of sale records",
              "items": {
                  "description": "Data for a sale record",
                  "type": "object",
                  "properties": {
        "id": {"type": "integer", "description": "The unique id of the sale."},
                      "date": {"type": "string", "description": "Date of the sale, in the format of MMDDYY, e.g., 031023"},
                      "total_amount": {"type": "number", "description": "The total amount of the sale."},
                      "customer_name": {"type": "string", "description": "The name of the customer, including first name and last name."},
                      "customer_contact": {"type": "string", "description": "The phone number of the customer, e.g., 650-123-4567."},
                  },
                  "required": ["id", "date", "total_amount"],
              },
          },
      },
      "required": ["records"],
  },
)

モデルにプロンプトと関数宣言を送信する

ユーザーがプロンプトを指定すると、アプリケーションはモデルにユーザープロンプトと関数宣言を渡す必要があります。モデルが結果を生成する方法を構成するには、アプリケーションでモデルに生成構成を指定します。モデルが関数宣言を使用する方法を構成するには、アプリケーションでモデルにツール構成を渡します。関数呼び出しは、マルチモーダル入力をサポートしていません。

生成構成

このモデルは、パラメータ値によって異なる結果を生成できます。温度パラメータは、この生成におけるランダム性の度合いを制御します。温度が低いほど、確定的なパラメータ値を必要とする関数に適しています。一方、温度が高いほど、より多様で創造的なパラメータ値を受け入れることができる関数に適しています。温度を 0 にすると、確定的になります。この場合、特定のプロンプトに対するレスポンスはほとんど確定的ですが、わずかに変動する可能性は残ります。詳細については、Gemini API をご覧ください。

このパラメータを設定するには、プロンプト、関数宣言とともに生成構成（generation_config）を送信します。Vertex AI API と更新された generation_config を使用して、チャットセッション中に temperature パラメータを更新できます。temperature パラメータの設定例については、プロンプトと関数宣言を送信する方法をご覧ください。

生成構成に関するベストプラクティスについては、ベストプラクティス - 生成構成をご覧ください。

ツール構成

モデルが提供する関数宣言の使用方法に制約を課すことができます。たとえば、モデルに自然言語によるレスポンスと関数呼び出しのどちらかを選択させるのではなく、関数呼び出しのみを予測するように強制できます（「強制関数呼び出し」）。関数宣言の全セットをモデルに提供し、そのレスポンスをこれらの関数のサブセットに制限することもできます。

これらの制約を適用するには、プロンプトと関数宣言とともにツール構成（tool_config）を送信します。構成では、次のいずれかのモードを指定できます。

モード	説明
AUTO	デフォルトのモデル動作。関数呼び出しと自然言語によるレスポンスのどちらを予測するかは、モデルが決定します。
ANY	モデルは関数呼び出しのみを予測する必要があります。モデルを関数のサブセットに制限するには、`allowed_function_names` で許可される関数名を定義します。
NONE	モデルは関数呼び出しを予測しません。この動作は、関連する関数宣言のないモデルリクエストと同じです。

ツール構成の ANY モード（「強制関数呼び出し」）は、Gemini 1.5 Pro モデルでのみサポートされています。

詳細については、Function Calling API をご覧ください。

プロンプトと関数の宣言を送信する方法

プロンプトと関数宣言をモデルに送信し、get_current_weather 関数呼び出しのみを予測するようにモデルを制限する方法の例を次に示します。

Python

# Define a tool that includes the function declaration get_current_weather_func
weather_tool = Tool(
    function_declarations=[get_current_weather_func],
)

# Send the prompt and instruct the model to generate content using the Tool object that you just created
response = model.generate_content(
    user_prompt_content,
    generation_config={"temperature": 0},
    tools=[weather_tool],
    tool_config=ToolConfig(
        function_calling_config=ToolConfig.FunctionCallingConfig(
            # ANY mode forces the model to predict a function call
            mode=ToolConfig.FunctionCallingConfig.Mode.ANY,
            # Allowed functions to call when the mode is ANY. If empty, any one of
            # the provided functions are called.
            allowed_function_names=["get_current_weather"],
    ))
)
response_function_call_content = response.candidates[0].content

モデルが特定の関数の出力が必要と判断した場合、アプリケーションがモデルから受け取るレスポンスには、関数名と、その関数を呼び出すためのパラメータ値が含まれます。

ユーザープロンプト「ボストンの天気は？」に対するモデルレスポンスの例を次に示します。モデルは、パラメータ Boston, MA を指定して get_current_weather 関数を呼び出すことを提案します。

candidates {
  content {
    role: "model"
    parts {
      function_call {
        name: "get_current_weather"
        args {
          fields {
            key: "location"
            value {
              string_value: "Boston, MA"
            }
          }
        }
      }
    }
  }
  ...
}

「Get weather details in New Delhi and San Francisco?」のようなプロンプトでは、モデルが複数の並列関数呼び出しを提案する場合があります。並列関数呼び出しはプレビュー版の機能です。Gemini 1.5 Pro モデルと Gemini 1.5 Flash モデルでサポートされています。詳細については、並列関数呼び出しの例をご覧ください。

外部 API を呼び出す

アプリケーションがモデルから関数名とパラメータ値を受け取った場合、アプリケーションは外部 API に接続して関数を呼び出す必要があります。

次の例では、擬似データを使用して外部 API からのレスポンスペイロードをシミュレートします。

Python

# Check the function name that the model responded with, and make an API call to an external system
if (
    response.candidates[0].content.parts[0].function_call.name
    == "get_current_weather"
):
    # Extract the arguments to use in your API call
    location = (
        response.candidates[0].content.parts[0].function_call.args["location"]
    )

    # Here you can use your preferred method to make an API request to fetch the current weather, for example:
    # api_response = requests.post(weather_api_url, data={"location": location})

    # In this example, we'll use synthetic data to simulate a response payload from an external API
    api_response = """{ "location": "Boston, MA", "temperature": 38, "description": "Partly Cloudy",
                    "icon": "partly-cloudy", "humidity": 65, "wind": { "speed": 10, "direction": "NW" } }"""

API 呼び出しに関するベストプラクティスについては、ベストプラクティス - API 呼び出しをご覧ください。

関数出力をモデルに提供する

アプリケーションが外部 API からレスポンスを受け取ったら、アプリケーションは、そのレスポンスをモデルに提供しなければなりません。Python を使用してこれを行う方法の例を次に示します。

Python

response = model.generate_content(
    [
        user_prompt_content,  # User prompt
        response_function_call_content,  # Function call response
        Content(
            parts=[
                Part.from_function_response(
                    name="get_current_weather",
                    response={
                        "content": api_response,  # Return the API response to Gemini
                    },
                )
            ],
        ),
    ],
    tools=[weather_tool],
)
# Get the model summary response
summary = response.candidates[0].content.parts[0].text

モデルが複数の並列関数呼び出しを提案した場合、アプリケーションはすべてのレスポンスをモデルに返す必要があります。並列関数呼び出しはプレビュー版の機能です。Gemini 1.5 Pro モデルと Gemini 1.5 Flash モデルでサポートされています。詳細については、並列関数呼び出しの例をご覧ください。

gemini-1.0-pro-001 モデルと gemini-1.0-pro-002 モデルは、プロンプトに応答するために別の関数の出力が必要であると判断する場合があります。この場合、アプリケーションがモデルから受信するレスポンスには、別の関数名と別のパラメータ値のセットが含まれます。

API のレスポンスがユーザーのプロンプトへの回答に十分であるとモデルが判断した場合、モデルは自然言語レスポンスを作成してアプリケーションに返します。この場合、ユーザーには、アプリケーションがレスポンスを返す必要があります。レスポンスの例を次に示します。

It is currently 38 degrees Fahrenheit in Boston, MA with partly cloudy skies. The humidity is 65% and the wind is blowing at 10 mph from the northwest.

テキストの例

関数呼び出しを使用して、単一のテキストレスポンスを生成できます。アドホックなテキストレスポンスは、コードの生成など、特定のビジネスタスクで役立ちます。

関数呼び出しを使用して単一のレスポンスを生成する場合は、やり取りの完全なコンテキストをモデルに提供する必要があります。Vertex AI は、やり取りの履歴をクライアント側に保存します。

Python

この例では、1 つの関数と 1 つのプロンプトを使用したテキストのシナリオを示します。GenerativeModel クラスとそのメソッドを使用します。Gemini マルチモーダルモデルで Vertex AI SDK for Python を使用する方法については、Vertex AI SDK for Python でのマルチモーダルクラスの概要をご覧ください。

Python

Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。詳細については、Python API リファレンスドキュメントをご覧ください。

import vertexai
from vertexai.generative_models import (
    Content,
    FunctionDeclaration,
    GenerationConfig,
    GenerativeModel,
    Part,
    Tool,
)

# Initialize Vertex AI
# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
vertexai.init(project=project_id, location="us-central1")

# Initialize Gemini model
model = GenerativeModel("gemini-1.5-flash-001")

# Define the user's prompt in a Content object that we can reuse in model calls
user_prompt_content = Content(
    role="user",
    parts=[
        Part.from_text("What is the weather like in Boston?"),
    ],
)

# Specify a function declaration and parameters for an API request
function_name = "get_current_weather"
get_current_weather_func = FunctionDeclaration(
    name=function_name,
    description="Get the current weather in a given location",
    # Function parameters are specified in OpenAPI JSON schema format
    parameters={
        "type": "object",
        "properties": {"location": {"type": "string", "description": "Location"}},
    },
)

# Define a tool that includes the above get_current_weather_func
weather_tool = Tool(
    function_declarations=[get_current_weather_func],
)

# Send the prompt and instruct the model to generate content using the Tool that you just created
response = model.generate_content(
    user_prompt_content,
    generation_config=GenerationConfig(temperature=0),
    tools=[weather_tool],
)
function_call = response.candidates[0].function_calls[0]
print(function_call)

# Check the function name that the model responded with, and make an API call to an external system
if function_call.name == function_name:
    # Extract the arguments to use in your API call
    location = function_call.args["location"]  # noqa: F841

    # Here you can use your preferred method to make an API request to fetch the current weather, for example:
    # api_response = requests.post(weather_api_url, data={"location": location})

    # In this example, we'll use synthetic data to simulate a response payload from an external API
    api_response = """{ "location": "Boston, MA", "temperature": 38, "description": "Partly Cloudy",
                    "icon": "partly-cloudy", "humidity": 65, "wind": { "speed": 10, "direction": "NW" } }"""

# Return the API response to Gemini so it can generate a model response or request another function call
response = model.generate_content(
    [
        user_prompt_content,  # User prompt
        response.candidates[0].content,  # Function call response
        Content(
            parts=[
                Part.from_function_response(
                    name=function_name,
                    response={
                        "content": api_response,  # Return the API response to Gemini
                    },
                ),
            ],
        ),
    ],
    tools=[weather_tool],
)

# Get the model response
print(response.text)

C#

この例では、1 つの関数と 1 つのプロンプトを使用したテキストのシナリオを示します。

C#

このサンプルを試す前に、Vertex AI クイックスタート: クライアントライブラリの使用にある C# の設定手順を完了してください。詳細については、Vertex AI C# API のリファレンスドキュメントをご覧ください。

Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。


using Google.Cloud.AIPlatform.V1;
using System;
using System.Threading.Tasks;
using Type = Google.Cloud.AIPlatform.V1.Type;
using Value = Google.Protobuf.WellKnownTypes.Value;

public class FunctionCalling
{
    public async Task<string> GenerateFunctionCall(
        string projectId = "your-project-id",
        string location = "us-central1",
        string publisher = "google",
        string model = "gemini-1.5-flash-001")
    {
        var predictionServiceClient = new PredictionServiceClientBuilder
        {
            Endpoint = $"{location}-aiplatform.googleapis.com"
        }.Build();

        // Define the user's prompt in a Content object that we can reuse in
        // model calls
        var userPromptContent = new Content
        {
            Role = "USER",
            Parts =
            {
                new Part { Text = "What is the weather like in Boston?" }
            }
        };

        // Specify a function declaration and parameters for an API request
        var functionName = "get_current_weather";
        var getCurrentWeatherFunc = new FunctionDeclaration
        {
            Name = functionName,
            Description = "Get the current weather in a given location",
            Parameters = new OpenApiSchema
            {
                Type = Type.Object,
                Properties =
                {
                    ["location"] = new()
                    {
                        Type = Type.String,
                        Description = "Get the current weather in a given location"
                    },
                    ["unit"] = new()
                    {
                        Type = Type.String,
                        Description = "The unit of measurement for the temperature",
                        Enum = {"celsius", "fahrenheit"}
                    }
                },
                Required = { "location" }
            }
        };

        // Send the prompt and instruct the model to generate content using the tool that you just created
        var generateContentRequest = new GenerateContentRequest
        {
            Model = $"projects/{projectId}/locations/{location}/publishers/{publisher}/models/{model}",
            GenerationConfig = new GenerationConfig
            {
                Temperature = 0f
            },
            Contents =
            {
                userPromptContent
            },
            Tools =
            {
                new Tool
                {
                    FunctionDeclarations = { getCurrentWeatherFunc }
                }
            }
        };

        GenerateContentResponse response = await predictionServiceClient.GenerateContentAsync(generateContentRequest);

        var functionCall = response.Candidates[0].Content.Parts[0].FunctionCall;
        Console.WriteLine(functionCall);

        string apiResponse = "";

        // Check the function name that the model responded with, and make an API call to an external system
        if (functionCall.Name == functionName)
        {
            // Extract the arguments to use in your API call
            string locationCity = functionCall.Args.Fields["location"].StringValue;

            // Here you can use your preferred method to make an API request to
            // fetch the current weather

            // In this example, we'll use synthetic data to simulate a response
            // payload from an external API
            apiResponse = @"{ ""location"": ""Boston, MA"",
                    ""temperature"": 38, ""description"": ""Partly Cloudy""}";
        }

        // Return the API response to Gemini so it can generate a model response or request another function call
        generateContentRequest = new GenerateContentRequest
        {
            Model = $"projects/{projectId}/locations/{location}/publishers/{publisher}/models/{model}",
            Contents =
            {
                userPromptContent, // User prompt
                response.Candidates[0].Content, // Function call response,
                new Content
                {
                    Parts =
                    {
                        new Part
                        {
                            FunctionResponse = new()
                            {
                                Name = functionName,
                                Response = new()
                                {
                                    Fields =
                                    {
                                        { "content", new Value { StringValue = apiResponse } }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            Tools =
            {
                new Tool
                {
                    FunctionDeclarations = { getCurrentWeatherFunc }
                }
            }
        };

        response = await predictionServiceClient.GenerateContentAsync(generateContentRequest);

        string responseText = response.Candidates[0].Content.Parts[0].Text;
        Console.WriteLine(responseText);

        return responseText;
    }
}

Node.js

この例では、1 つの関数と 1 つのプロンプトを使用したテキストのシナリオを示します。

Node.js

このサンプルを試す前に、Vertex AI クイックスタート: クライアントライブラリの使用で説明している Node.js の設定手順を完了してください。詳細については、Vertex AI Node.js API のリファレンスドキュメントをご覧ください。

const {
  VertexAI,
  FunctionDeclarationSchemaType,
} = require('@google-cloud/vertexai');

const functionDeclarations = [
  {
    function_declarations: [
      {
        name: 'get_current_weather',
        description: 'get weather in a given location',
        parameters: {
          type: FunctionDeclarationSchemaType.OBJECT,
          properties: {
            location: {type: FunctionDeclarationSchemaType.STRING},
            unit: {
              type: FunctionDeclarationSchemaType.STRING,
              enum: ['celsius', 'fahrenheit'],
            },
          },
          required: ['location'],
        },
      },
    ],
  },
];

const functionResponseParts = [
  {
    functionResponse: {
      name: 'get_current_weather',
      response: {name: 'get_current_weather', content: {weather: 'super nice'}},
    },
  },
];

/**
 * TODO(developer): Update these variables before running the sample.
 */
async function functionCallingStreamContent(
  projectId = 'PROJECT_ID',
  location = 'us-central1',
  model = 'gemini-1.5-flash-001'
) {
  // Initialize Vertex with your Cloud project and location
  const vertexAI = new VertexAI({project: projectId, location: location});

  // Instantiate the model
  const generativeModel = vertexAI.getGenerativeModel({
    model: model,
  });

  const request = {
    contents: [
      {role: 'user', parts: [{text: 'What is the weather in Boston?'}]},
      {
        role: 'model',
        parts: [
          {
            functionCall: {
              name: 'get_current_weather',
              args: {location: 'Boston'},
            },
          },
        ],
      },
      {role: 'user', parts: functionResponseParts},
    ],
    tools: functionDeclarations,
  };
  const streamingResp = await generativeModel.generateContentStream(request);
  for await (const item of streamingResp.stream) {
    console.log(item.candidates[0].content.parts[0].text);
  }
}

REST

この例では、3 つの関数と 1 つのプロンプトを使用するテキストのシナリオを示します。

この例では、生成 AI モデルを 2 回呼び出します。

最初の呼び出しでは、モデルにプロンプトと関数宣言を提供します。
2 番目の呼び出しでは、モデルに API レスポンスを提供します。

最初のモデルリクエスト

リクエストでは、text パラメータにプロンプトを定義する必要があります。この例では、「Which theaters in Mountain View show the Barbie movie?」というプロンプトを定義します。

リクエストでは、ツール（tools）と一連の関数宣言（functionDeclarations）も定義する必要があります。これらの関数宣言は、OpenAPI スキーマと互換性のある形式で指定する必要があります。この例では、次の関数を定義します。

find_movies は、映画館で上映されている映画のタイトルを検索します。
find_theatres は、場所に基づいて映画館を検索します。
get_showtimes は、特定の映画館で上映される映画の開始時間を検索します。

モデルリクエストのパラメータの詳細については、Gemini API をご覧ください。

my-project は、Google Cloud プロジェクトの名前で置き換えます。

最初のモデルリクエスト

PROJECT_ID=my-project
MODEL_ID=gemini-1.0-pro
API=streamGenerateContent
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"  https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/publishers/google/models/${MODEL_ID}:${API} -d '{
"contents": {
  "role": "user",
  "parts": {
    "text": "Which theaters in Mountain View show the 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 are 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"
          ]
        }
      }
    ]
  }
]
}'

「マウンテンビューのどの映画館でバービー映画が上映されていますか？」というプロンプトに対して、モデルはパラメータ Barbie と Mountain View, CA を使用して関数 find_theatres を返します。

最初のモデルリクエストに対するレスポンス

[{
"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
}
}]

2 番目のモデルリクエスト

この例では、外部 API を呼び出す代わりに合成データを使用します。2 つの結果があり、それぞれに 2 つのパラメータ（name と address）があります。

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

my-project は、Google Cloud プロジェクトの名前で置き換えます。

2 番目のモデルリクエスト

PROJECT_ID=my-project
MODEL_ID=gemini-1.0-pro
API=streamGenerateContent
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"  https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/publishers/google/models/${MODEL_ID}:${API} -d '{
"contents": [{
  "role": "user",
  "parts": [{
    "text": "Which theaters in Mountain View show the Barbie movie?"
  }]
}, {
  "role": "model",
  "parts": [{
    "functionCall": {
      "name": "find_theaters",
      "args": {
        "location": "Mountain View, CA",
        "movie": "Barbie"
      }
    }
  }]
}, {
  "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 are 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"]
    }
  }]
}]
}'

モデルのレスポンスは次のようになります。

2 番目のモデルリクエストに対するレスポンス

{
"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
}
}

チャットの例

関数呼び出しを使用して、チャットセッションをサポートできます。チャットセッションは、ユーザーがフォローアップの質問をする可能性が高い、自由形式の会話のシナリオで役立ちます。

チャットセッションのコンテキストで関数呼び出しを使用する場合、セッションでコンテキストが保存され、すべてのモデルリクエストにそれが追加されます。Vertex AI は、やり取りの履歴をクライアント側に保存します。

Python

次の例では、2 つの関数と 2 つの連続したプロンプトを使用したチャットのシナリオを示します。GenerativeModel クラスとそのメソッドを使用します。マルチモーダルモデルで Vertex AI SDK for Python を使用する方法については、Vertex AI SDK for Python でのマルチモーダルクラスの概要をご覧ください。

Python をインストールまたは更新する方法については、Vertex AI SDK for Python をインストールするをご覧ください。詳細については、Python API リファレンスドキュメントをご覧ください。

import vertexai
from vertexai.generative_models import (
    FunctionDeclaration,
    GenerationConfig,
    GenerativeModel,
    Part,
    Tool,
)

# Initialize Vertex AI
# project_id = "PROJECT_ID"
# TODO(developer): Update and un-comment below lines
vertexai.init(project=project_id, location="us-central1")

# Specify a function declaration and parameters for an API request
get_product_sku = "get_product_sku"
get_product_sku_func = FunctionDeclaration(
    name=get_product_sku,
    description="Get the SKU for a product",
    # Function parameters are specified in OpenAPI JSON schema format
    parameters={
        "type": "object",
        "properties": {
            "product_name": {"type": "string", "description": "Product name"}
        },
    },
)

# Specify another function declaration and parameters for an API request
get_store_location_func = FunctionDeclaration(
    name="get_store_location",
    description="Get the location of the closest store",
    # Function parameters are specified in OpenAPI JSON schema format
    parameters={
        "type": "object",
        "properties": {"location": {"type": "string", "description": "Location"}},
    },
)

# Define a tool that includes the above functions
retail_tool = Tool(
    function_declarations=[
        get_product_sku_func,
        get_store_location_func,
    ],
)

# Initialize Gemini model
model = GenerativeModel(
    model_name="gemini-1.5-flash-001",
    generation_config=GenerationConfig(temperature=0),
    tools=[retail_tool],
)

# Start a chat session
chat = model.start_chat()

# Send a prompt for the first conversation turn that should invoke the get_product_sku function
response = chat.send_message("Do you have the Pixel 8 Pro in stock?")

function_call = response.candidates[0].function_calls[0]
print(function_call)

# Check the function name that the model responded with, and make an API call to an external system
if function_call.name == get_product_sku:
    # Extract the arguments to use in your API call
    product_name = function_call.args["product_name"]  # noqa: F841

    # Here you can use your preferred method to make an API request to retrieve the product SKU, as in:
    # api_response = requests.post(product_api_url, data={"product_name": product_name})

    # In this example, we'll use synthetic data to simulate a response payload from an external API
    api_response = {"sku": "GA04834-US", "in_stock": "yes"}

# Return the API response to Gemini, so it can generate a model response or request another function call
response = chat.send_message(
    Part.from_function_response(
        name=get_product_sku,
        response={
            "content": api_response,
        },
    ),
)
# Extract the text from the model response
print(response.text)

# Send a prompt for the second conversation turn that should invoke the get_store_location function
response = chat.send_message(
    "Is there a store in Mountain View, CA that I can visit to try it out?"
)

function_call = response.candidates[0].function_calls[0]
print(function_call)

# Check the function name that the model responded with, and make an API call to an external system
if function_call.name == "get_store_location":
    # Extract the arguments to use in your API call
    location = function_call.args["location"]  # noqa: F841

    # Here you can use your preferred method to make an API request to retrieve store location closest to the user, as in:
    # api_response = requests.post(store_api_url, data={"location": location})

    # In this example, we'll use synthetic data to simulate a response payload from an external API
    api_response = {"store": "2000 N Shoreline Blvd, Mountain View, CA 94043, US"}

# Return the API response to Gemini, so it can generate a model response or request another function call
response = chat.send_message(
    Part.from_function_response(
        name="get_store_location",
        response={
            "content": api_response,
        },
    ),
)

# Extract the text from the model response
print(response.text)

Java

このサンプルを試す前に、Vertex AI クイックスタート: クライアントライブラリの使用にある Java の設定手順を完了してください。詳細については、Vertex AI Java API のリファレンスドキュメントをご覧ください。

import com.google.cloud.vertexai.VertexAI;
import com.google.cloud.vertexai.api.Content;
import com.google.cloud.vertexai.api.FunctionDeclaration;
import com.google.cloud.vertexai.api.GenerateContentResponse;
import com.google.cloud.vertexai.api.Schema;
import com.google.cloud.vertexai.api.Tool;
import com.google.cloud.vertexai.api.Type;
import com.google.cloud.vertexai.generativeai.ChatSession;
import com.google.cloud.vertexai.generativeai.ContentMaker;
import com.google.cloud.vertexai.generativeai.GenerativeModel;
import com.google.cloud.vertexai.generativeai.PartMaker;
import com.google.cloud.vertexai.generativeai.ResponseHandler;
import java.io.IOException;
import java.util.Arrays;
import java.util.Collections;

public class FunctionCalling {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-google-cloud-project-id";
    String location = "us-central1";
    String modelName = "gemini-1.5-flash-001";

    String promptText = "What's the weather like in Paris?";

    whatsTheWeatherLike(projectId, location, modelName, promptText);
  }

  // A request involving the interaction with an external tool
  public static String whatsTheWeatherLike(String projectId, String location,
                                           String modelName, String promptText)
      throws IOException {
    // Initialize client that will be used to send requests.
    // This client only needs to be created once, and can be reused for multiple requests.
    try (VertexAI vertexAI = new VertexAI(projectId, location)) {

      FunctionDeclaration functionDeclaration = FunctionDeclaration.newBuilder()
          .setName("getCurrentWeather")
          .setDescription("Get the current weather in a given location")
          .setParameters(
              Schema.newBuilder()
                  .setType(Type.OBJECT)
                  .putProperties("location", Schema.newBuilder()
                      .setType(Type.STRING)
                      .setDescription("location")
                      .build()
                  )
                  .addRequired("location")
                  .build()
          )
          .build();

      System.out.println("Function declaration:");
      System.out.println(functionDeclaration);

      // Add the function to a "tool"
      Tool tool = Tool.newBuilder()
          .addFunctionDeclarations(functionDeclaration)
          .build();

      // Start a chat session from a model, with the use of the declared function.
      GenerativeModel model = new GenerativeModel(modelName, vertexAI)
          .withTools(Arrays.asList(tool));
      ChatSession chat = model.startChat();

      System.out.println(String.format("Ask the question: %s", promptText));
      GenerateContentResponse response = chat.sendMessage(promptText);

      // The model will most likely return a function call to the declared
      // function `getCurrentWeather` with "Paris" as the value for the
      // argument `location`.
      System.out.println("\nPrint response: ");
      System.out.println(ResponseHandler.getContent(response));

      // Provide an answer to the model so that it knows what the result
      // of a "function call" is.
      Content content =
          ContentMaker.fromMultiModalData(
              PartMaker.fromFunctionResponse(
                  "getCurrentWeather",
                  Collections.singletonMap("currentWeather", "sunny")));
      System.out.println("Provide the function response: ");
      System.out.println(content);
      response = chat.sendMessage(content);

      // See what the model replies now
      System.out.println("Print response: ");
      String finalAnswer = ResponseHandler.getText(response);
      System.out.println(finalAnswer);

      return finalAnswer;
    }
  }
}

Go

このサンプルを試す前に、Vertex AI クイックスタート: クライアントライブラリの使用にある Go の設定手順を完了してください。詳細については、Vertex AI Go API のリファレンスドキュメントをご覧ください。

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"io"

	"cloud.google.com/go/vertexai/genai"
)

// functionCallsChat opens a chat session and sends 4 messages to the model:
// - convert a first text question into a structured function call request
// - convert the first structured function call response into natural language
// - convert a second text question into a structured function call request
// - convert the second structured function call response into natural language
func functionCallsChat(w io.Writer, projectID, location, modelName string) error {
	// location := "us-central1"
	// modelName := "gemini-1.5-flash-001"
	ctx := context.Background()
	client, err := genai.NewClient(ctx, projectID, location)
	if err != nil {
		return fmt.Errorf("unable to create client: %w", err)
	}
	defer client.Close()

	model := client.GenerativeModel(modelName)

	// Build an OpenAPI schema, in memory
	paramsProduct := &genai.Schema{
		Type: genai.TypeObject,
		Properties: map[string]*genai.Schema{
			"productName": {
				Type:        genai.TypeString,
				Description: "Product name",
			},
		},
	}
	fundeclProductInfo := &genai.FunctionDeclaration{
		Name:        "getProductSku",
		Description: "Get the SKU for a product",
		Parameters:  paramsProduct,
	}
	paramsStore := &genai.Schema{
		Type: genai.TypeObject,
		Properties: map[string]*genai.Schema{
			"location": {
				Type:        genai.TypeString,
				Description: "Location",
			},
		},
	}
	fundeclStoreLocation := &genai.FunctionDeclaration{
		Name:        "getStoreLocation",
		Description: "Get the location of the closest store",
		Parameters:  paramsStore,
	}
	model.Tools = []*genai.Tool{
		{FunctionDeclarations: []*genai.FunctionDeclaration{
			fundeclProductInfo,
			fundeclStoreLocation,
		}},
	}
	model.SetTemperature(0.0)

	chat := model.StartChat()

	// Send a prompt for the first conversation turn that should invoke the getProductSku function
	prompt := "Do you have the Pixel 8 Pro in stock?"
	fmt.Fprintf(w, "Question: %s\n", prompt)
	resp, err := chat.SendMessage(ctx, genai.Text(prompt))
	if err != nil {
		return err
	}
	if len(resp.Candidates) == 0 ||
		len(resp.Candidates[0].Content.Parts) == 0 {
		return errors.New("empty response from model")
	}

	// The model has returned a function call to the declared function `getProductSku`
	// with a value for the argument `productName`.
	jsondata, err := json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.MarshalIndent: %w", err)
	}
	fmt.Fprintf(w, "function call generated by the model:\n\t%s\n", string(jsondata))

	// Create a function call response, to simulate the result of a call to a
	// real service
	funresp := &genai.FunctionResponse{
		Name: "getProductSku",
		Response: map[string]any{
			"sku":      "GA04834-US",
			"in_stock": "yes",
		},
	}
	jsondata, err = json.MarshalIndent(funresp, "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.MarshalIndent: %w", err)
	}
	fmt.Fprintf(w, "function call response sent to the model:\n\t%s\n\n", string(jsondata))

	// And provide the function call response to the model
	resp, err = chat.SendMessage(ctx, funresp)
	if err != nil {
		return err
	}
	if len(resp.Candidates) == 0 ||
		len(resp.Candidates[0].Content.Parts) == 0 {
		return errors.New("empty response from model")
	}

	// The model has taken the function call response as input, and has
	// reformulated the response to the user.
	jsondata, err = json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.MarshalIndent: %w", err)
	}
	fmt.Fprintf(w, "Answer generated by the model:\n\t%s\n\n", string(jsondata))

	// Send a prompt for the second conversation turn that should invoke the getStoreLocation function
	prompt2 := "Is there a store in Mountain View, CA that I can visit to try it out?"
	fmt.Fprintf(w, "Question: %s\n", prompt)

	resp, err = chat.SendMessage(ctx, genai.Text(prompt2))
	if err != nil {
		return err
	}
	if len(resp.Candidates) == 0 ||
		len(resp.Candidates[0].Content.Parts) == 0 {
		return errors.New("empty response from model")
	}

	// The model has returned a function call to the declared function `getStoreLocation`
	// with a value for the argument `store`.
	jsondata, err = json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.MarshalIndent: %w", err)
	}
	fmt.Fprintf(w, "function call generated by the model:\n\t%s\n", string(jsondata))

	// Create a function call response, to simulate the result of a call to a
	// real service
	funresp = &genai.FunctionResponse{
		Name: "getStoreLocation",
		Response: map[string]any{
			"store": "2000 N Shoreline Blvd, Mountain View, CA 94043, US",
		},
	}
	jsondata, err = json.MarshalIndent(funresp, "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.MarshalIndent: %w", err)
	}
	fmt.Fprintf(w, "function call response sent to the model:\n\t%s\n\n", string(jsondata))

	// And provide the function call response to the model
	resp, err = chat.SendMessage(ctx, funresp)
	if err != nil {
		return err
	}
	if len(resp.Candidates) == 0 ||
		len(resp.Candidates[0].Content.Parts) == 0 {
		return errors.New("empty response from model")
	}

	// The model has taken the function call response as input, and has
	// reformulated the response to the user.
	jsondata, err = json.MarshalIndent(resp.Candidates[0].Content.Parts[0], "\t", "  ")
	if err != nil {
		return fmt.Errorf("json.MarshalIndent: %w", err)
	}
	fmt.Fprintf(w, "Answer generated by the model:\n\t%s\n\n", string(jsondata))
	return nil
}

Node.js

このサンプルを試す前に、Vertex AI クイックスタート: クライアントライブラリの使用にある Node.js の設定手順を完了してください。詳細については、Vertex AI Node.js API のリファレンスドキュメントをご覧ください。

const {
  VertexAI,
  FunctionDeclarationSchemaType,
} = require('@google-cloud/vertexai');

const functionDeclarations = [
  {
    function_declarations: [
      {
        name: 'get_current_weather',
        description: 'get weather in a given location',
        parameters: {
          type: FunctionDeclarationSchemaType.OBJECT,
          properties: {
            location: {type: FunctionDeclarationSchemaType.STRING},
            unit: {
              type: FunctionDeclarationSchemaType.STRING,
              enum: ['celsius', 'fahrenheit'],
            },
          },
          required: ['location'],
        },
      },
    ],
  },
];

const functionResponseParts = [
  {
    functionResponse: {
      name: 'get_current_weather',
      response: {name: 'get_current_weather', content: {weather: 'super nice'}},
    },
  },
];

/**
 * TODO(developer): Update these variables before running the sample.
 */
async function functionCallingStreamChat(
  projectId = 'PROJECT_ID',
  location = 'us-central1',
  model = 'gemini-1.5-flash-001'
) {
  // Initialize Vertex with your Cloud project and location
  const vertexAI = new VertexAI({project: projectId, location: location});

  // Instantiate the model
  const generativeModel = vertexAI.getGenerativeModel({
    model: model,
  });

  // Create a chat session and pass your function declarations
  const chat = generativeModel.startChat({
    tools: functionDeclarations,
  });

  const chatInput1 = 'What is the weather in Boston?';

  // This should include a functionCall response from the model
  const result1 = await chat.sendMessageStream(chatInput1);
  for await (const item of result1.stream) {
    console.log(item.candidates[0]);
  }
  await result1.response;

  // Send a follow up message with a FunctionResponse
  const result2 = await chat.sendMessageStream(functionResponseParts);
  for await (const item of result2.stream) {
    console.log(item.candidates[0]);
  }

  // This should include a text response from the model using the response content
  // provided above
  const response2 = await result2.response;
  console.log(response2.candidates[0].content.parts[0].text);
}

並列関数呼び出しの例

REST

この例では、1 つの get_current_weather 関数を使用するシナリオを示します。ユーザープロンプトは「ニューデリーとサンフランシスコの天気の詳細情報を取得しますか？」です。モデルは、パラメータ New Delhi を指定した場合と、パラメータ San Francisco を指定した場合の get_current_weather 関数の 2 つの並列呼び出しを提案しています。並列関数呼び出しはプレビュー版の機能です。Gemini 1.5 Pro モデルと Gemini 1.5 Flash モデルでサポートされています。

モデルリクエストのパラメータの詳細については、Gemini API をご覧ください。

candidates {
content {
  role: "model"
  parts: [
    {
      function_call {
        name: "get_current_weather"
        args {
          fields {
            key: "location"
            value {
              string_value: "New Delhi"
            }
          }
        }
      }
    },
    {
      function_call {
        name: "get_current_weather"
        args {
          fields {
            key: "location"
            value {
              string_value: "San Francisco"
            }
          }
        }
      }
    }
  ]
}
...
}

次のコマンドは、関数の出力をモデルに提供する方法を示しています。my-project は、Google Cloud プロジェクトの名前で置き換えます。

モデルのリクエスト

PROJECT_ID=my-project
MODEL_ID=gemini-1.5-pro-001
VERSION="v1"
LOCATION="us-central1"
ENDPOINT=${LOCATION}-aiplatform.googleapis.com
API="generateContent"
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"  https://${ENDPOINT}/${VERSION}/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:${API} -d '{
"contents": [
    {
        "role": "user",
        "parts": {
            "text": "What is difference in temperature in New Delhi and San Francisco?"
        }
    },
    {
        "role": "model",
        "parts": [
            {
                "functionCall": {
                    "name": "get_current_weather",
                    "args": {
                        "location": "New Delhi"
                    }
                }
            },
            {
                "functionCall": {
                    "name": "get_current_weather",
                    "args": {
                        "location": "San Francisco"
                    }
                }
            }
        ]
    },
    {
        "role": "user",
        "parts": [
            {
                "functionResponse": {
                    "name": "get_current_weather",
                    "response": {
                        "temperature": 30.5,
                        "unit": "C"
                    }
                }
            },
            {
                "functionResponse": {
                    "name": "get_current_weather",
                    "response": {
                        "temperature": 20,
                        "unit": "C"
                    }
                }
            }
        ]
    }
],
"tools": [
    {
        "function_declarations": [
            {
                "name": "get_current_weather",
                "description": "Get the current weather in a specific location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
                        }
                    },
                    "required": [
                        "location"
                    ]
                }
            }
        ]
    }
]
}'

モデルによって作成された自然言語のレスポンスは次のようになります。

モデルのレスポンス

[
{
    "candidates": [
        {
            "content": {
                "parts": [
                    {
                        "text": "The temperature in New Delhi is 30.5C and the temperature in San Francisco is 20C. The difference is 10.5C. \n"
                    }
                ]
            },
            "finishReason": "STOP",
            ...
        }
    ]
    ...
}
]

ベストプラクティス

関数名

関数名にピリオド（.）、ダッシュ（-）、スペース文字は使用しないでください。代わりに、アンダースコア（_）か他の文字を使用します。

関数のパラメータ

パラメータの説明は、希望する形式や値などの詳細を含めて、明確かつ詳細に記述します。たとえば、book_flight_ticket 関数の場合:

departure パラメータの適切な説明の例: Use the 3 char airport code to represent the airport. For example, SJC or SFO. Don't use the city name.
departure パラメータの不適切な説明の例: the departure airport

可能であれば、モデルのハルシネーションを減らすために、厳密に型指定されたパラメータを使用してください。たとえば、パラメータ値が有限集合の場合、値の集合を説明に入れるのではなく、enum フィールドを追加します。パラメータ値が常に整数の場合は、型を number ではなく integer に設定します。

関数の説明

関数の説明はわかりやすく丁寧に記述します。たとえば、book_flight_ticket 関数の場合:

関数の適切な説明の例: book flight tickets after confirming users' specific requirements, such as time, departure, destination, party size and preferred airline
関数の不適切な説明の例: book flight ticket

ユーザープロンプト

最適な結果を得るには、ユーザープロンプトの先頭に次の詳細を付加します。

モデルの追加コンテキスト（例: You are a flight API assistant to help with searching flights based on user preferences.）
関数の使用方法と使用のタイミングに関する詳細や手順（例: Don't make assumptions on the departure or destination airports. Always use a future date for the departure or destination time.）
ユーザーからの質問があいまいな場合に、質問を明確にするための指示（例: Ask clarifying questions if not enough information is available.）

生成構成

温度パラメータには、0 または別の小さい値を使用します。これにより、より確信度の高い結果を生成してハルシネーションを減らすようにモデルに指示します。

API 呼び出し

注文の送信やデータベースの更新など、重大な結果をもたらすような関数の呼び出しをモデルが提案する場合は、それを実行する前にユーザーにその関数呼び出しの妥当性を確認してください。

料金

関数呼び出しの料金は、テキストの入力と出力の文字数に基づいて決まります。詳細については、Vertex AI の料金をご覧ください。

ここで、テキスト入力（プロンプト）は、現在の会話ターンのユーザープロンプト、現在の会話ターンの関数宣言、会話の履歴を参照します。会話の履歴には、以前の会話ターンのクエリ、関数呼び出し、関数レスポンスが含まれます。Vertex AI は、会話の履歴を 32,000 文字で切り捨てます。

テキスト出力（レスポンス）は、現在の会話ターンの関数呼び出しとテキストレスポンスを表します。

関数呼び出し

概要

関数呼び出しのユースケース

関数呼び出しのアプリケーションを作成する

モデルを初期化する

Python

ユーザー プロンプトを定義する

Python

使用可能な一連の関数を定義して記述する

関数名

関数のパラメータ

関数の説明

関数宣言の例

Python: 単純な宣言

Python: 項目の配列

モデルにプロンプトと関数宣言を送信する

生成構成

ツール構成

プロンプトと関数の宣言を送信する方法

Python

外部 API を呼び出す

Python

関数出力をモデルに提供する

Python

テキストの例

Python

Python

C#

C#

Node.js

Node.js

REST

最初のモデル リクエスト

最初のモデル リクエスト

最初のモデル リクエストに対するレスポンス

2 番目のモデル リクエスト

2 番目のモデル リクエスト

2 番目のモデル リクエストに対するレスポンス

チャットの例

Python

Java

Go

Node.js

並列関数呼び出しの例

REST

モデルのリクエスト

モデルのレスポンス

ベスト プラクティス

関数名

関数のパラメータ

関数の説明

ユーザー プロンプト

生成構成

API 呼び出し

料金

ユーザープロンプトを定義する

最初のモデルリクエスト

最初のモデルリクエスト

最初のモデルリクエストに対するレスポンス

2 番目のモデルリクエスト

2 番目のモデルリクエスト

2 番目のモデルリクエストに対するレスポンス

ベストプラクティス

ユーザープロンプト