Function Calling API

関数呼び出しにより、関連性の高いコンテキストに沿った回答を提供する LLM の能力が向上します。

Function Calling API を使用すると、生成 AI モデルにカスタム関数を提供できます。モデルは、これらの関数を直接呼び出すのではなく、関数名と推奨される引数を指定する構造化データ出力を生成します。この出力により、外部 API や情報システム（データベース、顧客管理システム、ドキュメント リポジトリなど）を呼び出すことができます。生成された API 出力は、LLM で使用してレスポンスの品質を向上させることができます。

サポートされているモデル:

  • Gemini 1.0 Pro
    • gemini-1.0-pro
    • gemini-1.0-pro-001
    • gemini-1.0-pro-002
  • Gemini 1.5 Pro
    • gemini-1.5-pro-preview-0409

制限事項:

  • 指定できる関数の最大数は 64 個です。
  • FunctionCallingConfig はプレビュー版であり、gemini-1.5-pro-preview-0409 でのみ使用できます。

構文

  • PROJECT_ID = PROJECT_ID
  • REGION = REGION
  • MODEL_ID = MODEL_ID

curl

https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      ...
    }],
    "tools": [{
      "function_declarations": [
        {
          ...
        }
      ]
    }]
  }'

Python

gemini_model = GenerativeModel(
    MODEL_ID,
    generation_config=generation_config,
    tools=[
        Tool(
            function_declarations=[
                FunctionDeclaration(
                    ...
                )
            ]
        )
    ],
)

パラメータ リスト

FunctionDeclaration

OpenAPI 3.0 仕様で定義されている関数宣言の構造化表現。モデルが JSON 入力を生成できる関数を表します。

パラメータ

name

string

呼び出す関数の名前。

description

省略可: string

関数の説明と目的。

parameters

省略可: Schema

この関数のパラメータを OpenAPI JSON スキーマ オブジェクト形式（OpenAPI 3.0 仕様）で記述します。

response

省略可: Schema

この関数からの出力を JSON スキーマ形式で記述します。

FunctionCallingConfig（プレビュー）

これは、関数呼び出し機能を使用する追加の構成です。この機能は gemini-1.5-pro-preview-0409 でのみ使用できます。

パラメータ

mode

省略可: enum/string[]

  • AUTO: デフォルトのモデルの動作。モデルは、関数呼び出しまたは自然言語によるレスポンスのどちらを予測するかを決定します。
  • NONE: モデルは関数呼び出しを予測しません。モデルの動作は、関数宣言を渡さない場合と同じです。
  • ANY: モデルは、常に単一の関数呼び出しを予測するように制約されています。

allowed_function_names が設定されている場合、予測された関数呼び出しは allowed_function_names に限定されます。デフォルトでは、予測された関数呼び出しは、指定された function_declarations のいずれかから行われます。

allowed_function_names

省略可: string[]

呼び出す関数名。mode が ANY の場合にのみ設定されます。関数名は [FunctionDeclaration.name] と一致する必要があります。モードを ANY に設定すると、モデルは指定された関数名のセットから関数呼び出しを予測します。

スキーマ

スキーマは、関数呼び出しで入力データと出力データの形式を定義するために使用されます。OpenAPI 3.0 スキーマ仕様で定義されている関数宣言の構造化表現。

パラメータ
type

string

列挙型。データの型。次のいずれかにする必要があります。

  • STRING
  • INTEGER
  • BOOLEAN
  • NUMBER
  • ARRAY
  • OBJECT
description

省略可: string

データの説明。
enum

省略可: string[]

Type.STRING の要素に可能な値（列挙型形式）。
items

省略可: Schema[]

Type.ARRAY の要素のスキーマ
properties

省略可: Schema

Type.OBJECT のプロパティのスキーマ
required

省略可: string[]

Type.OBJECT の必須プロパティ。
nullable

省略可: bool

値が null の可能性があるかどうかを示します。

例

  • PROJECT_ID = PROJECT_ID
  • REGION = REGION
  • MODEL_ID = MODEL_ID

基本的なユースケース

次に、クエリと関数宣言をモデルに送信する方法の例を示します。

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "What is the weather in Boston?"
      }]
    }],
    "tools": [{
      "function_declarations": [
        {
          "name": "get_current_weather",
          "description": "Get the current weather in a given 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"
            ]
          }
        }
      ]
    }]
  }'

Python

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

vertexai.init(project=PROJECT_ID, location=REGION)

# Specify a function declaration and parameters for an API request
get_current_weather_func = FunctionDeclaration(
    name="get_current_weather",
    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": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"}},
    },
)

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

gemini_model = GenerativeModel(
    MODEL_ID, generation_config={"temperature": 0}, tools=[weather_tool]
)
model_response = gemini_model.generate_content("What is the weather in Boston?")

print(model_response)

上級者向けのユースケース

次の例は、生成構成とツール構成をモデルに渡す方法を示しています。関数呼び出しの構成を使用すると、モデルの出力が常に特定の関数呼び出しになるようにできます。そのためには、関数呼び出しモードを ANY に設定し、allowed_function_names パラメータで許可される関数名を指定します。allowed_function_names が空の場合、指定された関数のいずれかが返される可能性があります。

  • MODEL_ID = gemini-1.5-pro-preview-0409

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Do you have the White Pixel 8 Pro 128GB in stock in the US?"
      }]
    }],
    "tools": [{
      "function_declarations": [
        {
          "name": "get_product_sku",
          "description": "Get the available inventory for a Google products, e.g: Pixel phones, Pixel Watches, Google Home etc",
          "parameters": {
            "type": "object",
            "properties": {
                "product_name": {"type": "string", "description": "Product name"}
            }
          }
        },
        {
          "name": "get_store_location",
          "description": "Get the location of the closest store",
          "parameters": {
            "type": "object",
            "properties": {"location": {"type": "string", "description": "Location"}},
          }
        }
      ]
    }],
    "tool_config": {
        "function_calling_config": {
            "mode":"ANY",
            "allowed_function_names": ["get_product_sku"]
       }
    },
    "generationConfig": {
      "temperature": 0.95,
      "topP": 1.0,
      "maxOutputTokens": 8192
    }
  }'

Python

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

vertexai.init(project=PROJECT_ID, location=REGION)

# Specify a function declaration and parameters for an API request
get_product_info_func = FunctionDeclaration(
    name="get_product_sku",
    description="Get the available inventory for a Google products, e.g: Pixel phones, Pixel Watches, Google Home etc",
    # 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_info_func,
        get_store_location_func,
    ],
)

# Define a tool config for the above functions
retail_tool_config = ToolConfig(
    function_calling_config=ToolConfig.FunctionCallingConfig(
        # ANY mode forces the model to predict a function call
        mode=ToolConfig.FunctionCallingConfig.Mode.ANY,
        # List of functions that can be returned when the mode is ANY.
        # If the list is empty, any declared function can be returned.
        allowed_function_names=["get_product_sku"],
    )
)

generation_config = GenerationConfig(
    temperature=0.95, top_p=1.0, max_output_tokens=8192
)

gemini_model = GenerativeModel(
    MODEL_ID,
    generation_config=generation_config,
    tools=[retail_tool],
    tool_config=retail_tool_config,
)
model_response = gemini_model.generate_content(
    "Do you have the White Pixel 8 Pro 128GB in stock in the US?"
)

print(model_response)

さらに詳しい情報

詳細なドキュメントについては、以下をご覧ください。