関数呼び出し

概要

関数呼び出しは、カスタム関数を定義して、生成 AI モデルに提供するために使用できます。クエリの処理中に、特定のデータ処理タスクをこれらの関数に委任できます。関数の呼び出しは行わず、選択した関数の名前と、モデルが関数を呼び出す際の引数を含む構造化データの出力を提供します。この出力を使用して、外部 API を呼び出すことができます。その後、API の出力をモデルに提供して、クエリに対する回答を完成させることができます。この方法で関数呼び出しを使用すると、LLM はリアルタイムの情報にアクセスし、SQL データベース、顧客管理システム、ドキュメントリポジトリなどのさまざまなサービスとやり取りできます。

次の図では、関数呼び出しの仕組みを示します。関数呼び出しのインタラクション

関数呼び出しのユースケースについては、関数呼び出しのユースケースをご覧ください。関数呼び出しのアプリケーションを作成する方法については、関数呼び出しのアプリケーションを作成するをご覧ください。ベストプラクティスについては、ベストプラクティスをご覧ください。

関数呼び出しは gemini-1.0-pro-001 モデルの機能であり、gemini-1.0-pro-002 モデルのプレビュー版の機能です。

関数呼び出しは Gemini 1.5 Pro（プレビュー版）モデルの機能です。

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

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

自然言語のストーリーからエンティティを抽出する: ストーリーから登場人物、関係性、もの、場所のリストを抽出します。
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 SDK for Python ノートブック - Vertex AI Gemini API と Python SDK を使用した関数呼び出し
 REST サンプル | Vertex AI SDK for Python チャットサンプル
次のような公開 API に接続して、生成 AI アプリケーションを構築する:
- 通貨を変換する: 通貨両替アプリに接続する関数を作成して、モデルがクエリ（What's the exchange rate for euros to dollars today?）に正確な回答を提供できるようにします。
  Codelab - Gemini で関数呼び出しを使用して API とやりとりする方法
- 特定の場所の天気を取得する: 気象サービスの API に接続する関数を作成します。これにより、モデルは「What's the weather like in Paris?」といったクエリに対して正確な回答を提供できるようになります。
  Vertex AI SDK for Python ノートブック - Vertex AI Gemini API と Python SDK を使用した関数呼び出し
   ブログ投稿 - 関数呼び出し: 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 SDK for Python ノートブック - Vertex AI Gemini API と Python SDK を使用した関数呼び出し
音声コマンドを解釈する: 車載タスクに対応する機能を作成します。たとえば、ラジオをオンにする関数や、エアコンを起動する関数を作成できます。ユーザーの音声コマンドの音声ファイルをモデルに送信し、音声をテキストに変換して、ユーザーが呼び出したい機能を特定するようにモデルに指示します。
環境的なトリガーに基づいてワークフローを自動化する: 自動化できるプロセスを表す関数を作成します。環境センサーからのデータをモデルに提供し、そのデータを解析、処理して、1 つ以上のワークフローを起動すべきかどうかを判断するように指示します。たとえば、モデルが倉庫内の温度データを処理してスプリンクラー機能を起動できるようにします。
サポートチケットの割り当てを自動化する: サポートチケット、ログ、コンテキストアウェアルールをモデルに提供します。チケットを割り当てるユーザーを判断するために、これらの情報をすべて処理するようにモデルに指示します。モデルが提案した人にチケットを割り当てる関数を呼び出します。
ナレッジベースから情報を取得する: 特定のテーマに関する学術論文を取得して要約する関数を作成します。モデルが、学術的なテーマに関する質問に答え、その回答の引用元を提示できるようにします。

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

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

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

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

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

アプリケーションでは、モデルがクエリを処理するために使用できる一連の関数を宣言する必要があります。各関数の宣言には、関数名と関数パラメータを含めなければなりません。各関数の宣言には、関数の説明も含めることを強く推奨します。

関数名

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

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

関数のパラメータ

関数パラメータは、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 での単純な関数宣言の例を次に示します。

get_current_weather_func = FunctionDeclaration(
    name="get_current_weather",
    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."}},
    },
)

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

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 関数呼び出しのみを予測するようにモデルを制限する方法の例を次に示します。

# Initialize Vertex AI
from vertexai.preview.generative_models import ToolConfig

vertexai.init(project=project_id, location=location)

# Initialize Gemini model
model = GenerativeModel("Gemini 1.5 Pro")

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

# 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(prompt),
    ],
)

# 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"
              }
            }
          }
        }
      }
    }
    ...
}

外部 API を呼び出す

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

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

# 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 を使用してこれを行う方法の例を次に示します。

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

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.」

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

ベストプラクティス

関数名

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

関数のパラメータ

パラメータの説明は、希望する形式や値などの詳細を含めて、明確かつ詳細に記述します。たとえば、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 文字で切り捨てます。

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

関数呼び出しのサンプル

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

関数呼び出しを使用して単一のレスポンスを生成する場合は、やり取りの完全なコンテキストをモデルに提供する必要があります。一方、チャットセッションのコンテキストで関数呼び出しを使用する場合、セッションではコンテキストが保存され、すべてのモデルリクエストにそれが追加されます。どちらの場合も、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(model_name="gemini-1.0-pro-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)

Node.js

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

Node.js

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

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

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.0-pro-002'
) {
  // 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 パラメータにクエリを定義する必要があります。この例では、「マウンテンビューのどの映画館でバービーの映画を上映していますか？」というクエリを定義します。

リクエストでは、ツール（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
}
}

チャットの例

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.0-pro-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)

Node.js

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.0-pro-002'
) {
  // 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);
}

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.0-pro-002";

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

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

  public static String whatsTheWeatherLike(String projectId, String location,
                                           String modelName, String promptText)
      throws IOException {

    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.0-pro-002"
	ctx := context.Background()
	client, err := genai.NewClient(ctx, projectID, location)
	if err != nil {
		return fmt.Errorf("unable to create client: %v", 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.Marshal: %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.Marshal: %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.Marshal: %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.Marshal: %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.Marshal: %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.Marshal: %w", err)
	}
	fmt.Fprintf(w, "Answer generated by the model:\n\t%s\n\n", string(jsondata))
	return nil
}

関数呼び出し

概要

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

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

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

関数名

関数のパラメータ

関数の説明

関数宣言の例

クエリと関数宣言をモデルに送信する

ユーザー プロンプト

生成構成

ツール構成

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

外部 API を呼び出す

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

ベスト プラクティス

関数名

関数のパラメータ

関数の説明

ユーザー プロンプト

生成構成

API 呼び出し

料金

関数呼び出しのサンプル

テキストの例

Python

Python

Node.js

Node.js

REST

最初のモデル リクエスト

最初のモデル リクエスト

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

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

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

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

チャットの例

Python

Node.js

Java

Go

ユーザープロンプト

ベストプラクティス

ユーザープロンプト

最初のモデルリクエスト

最初のモデルリクエスト

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

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

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

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