Gemini で関数呼び出しを使用して API を操作する方法

1. 概要

Gemini の関数呼び出しとは何ですか？

Vertex AI Gemini API は、Google DeepMind が開発した生成 AI モデルのファミリーであり、マルチモーダルユースケース用に設計されています。関数呼び出しは、開発者が生成モデルから構造化データ出力を簡単に取得できるようにする Gemini モデルの機能です。

デベロッパーは、これらの出力を使用して他の API を呼び出し、関連するレスポンスデータをモデルに返すことができます。つまり、関数呼び出しを使用すると、生成モデルを外部システムに接続して、生成されたコンテンツに最新かつ正確な情報を含めることができます。

関数呼び出しの仕組み

関数は関数宣言を使用して記述します。これにより、生成モデルは関数内の目的とパラメータを理解できます。クエリで関数宣言を生成モデルに渡すと、モデルはユーザーのクエリに基づいて、関連する関数の名前とその引数を含む構造化オブジェクトを返します。関数呼び出しでは、モデルが実際に関数を呼び出すわけではありません。代わりに、返された関数とパラメータを使用して、任意の言語、ライブラリ、フレームワークで関数を呼び出すことができます。

API インターフェース

作成するアプリの概要

この Codelab では、Vertex AI Gemini API と Python を使用して生成 AI パイプラインを構築します。ユーザーはアプリを使用して為替レートについて質問できます。システムは外部 API から最新のデータを取得し、ユーザーに回答を返します。

学習内容

Python クライアントライブラリを使用して Gemini モデルを操作する方法
関数宣言を定義してツールとして登録する方法
Gemini を呼び出して関数呼び出しのレスポンスを取得する方法
関数のレスポンスを Gemini に返し、ユーザーに応答する方法

必要なもの

Google Cloud プロジェクト
ブラウザ（Chrome など）
Colab や Colab Enterprise などの Python 開発環境

2. 設定と要件

Gemini で関数呼び出しを使用するには、Vertex AI API を有効にして、Vertex AI Python クライアントライブラリの最新バージョンをインストールする必要があります。

Vertex AI API を有効にする

Vertex AI API を有効にする手順は次のとおりです。

ブラウザで Vertex AI API サービスの詳細ページに移動します。
[有効にする] ボタンをクリックして、Google Cloud プロジェクトで Vertex AI API を有効にします。

Vertex AI 用 Python クライアントライブラリをインストールする

Vertex AI 用の Python クライアントライブラリをインストールする手順は次のとおりです。

開発環境でターミナルを開きます。
有効な Python 開発環境があることを確認します。必要に応じて、こちらのガイドラインを参照してください。
次のコマンドを実行して、Vertex AI 用の Python クライアントライブラリをインストールします。
```
pip install --upgrade google-cloud-aiplatform
```
ノートブック環境で実行している場合は、新しくインストールしたパッケージを使用するためにランタイム/カーネルを再起動する必要がある場合があります。

これで、Vertex AI API を使用する準備が整いました。

3. 問題を理解する

大規模言語モデルや生成 AI モデルとやり取りして、リアルタイムの情報や最新の情報について質問したところ、古い情報や不正確な情報が返ってきたことはありませんか？

さっそく試してみましょう。まず、関連する Python パッケージをインポートし、Gemini モデルを初期化します。次のコードは、Colab や Colab Enterprise などの Python 開発環境で、最新バージョンの Vertex AI SDK for Python をインストールして実行できます。

import vertexai
from vertexai.generative_models import GenerativeModel
model = GenerativeModel("gemini-1.5-pro-001")

それでは、今日のさまざまな通貨のレートについて質問してみましょう。

response = model.generate_content(
    "What's the exchange rate for euros to dollars today?"
)
print(response.text)

モデルは、次のような制限付きまたは古いレスポンスを生成します。

As an AI language model, I don't have access to real-time currency exchange
rates. However, as of my last update in September 2021, the approximate exchange
rate between euros (EUR) and US dollars (USD) was:

1 EUR ≈ 1.18 USD

Please note that currency exchange rates constantly fluctuate and can vary
depending on various factors such as economic conditions, supply and demand,
political events, and more. To obtain the most up-to-date and accurate exchange
rate, I recommend using a reliable currency converter or financial website that
provides live rates.

[...]

エンドユーザーがこのタイプのレスポンスを受け取った場合、コンテキストを切り替えて、関心のある通貨を検索し、最新の換算レートを取得して、自分で換算を行う必要があります。

理想的には、生成モデルパイプラインがユーザーに代わってこれらのタスクの一部またはすべてを処理できます。次のセクションでは、外部システムを呼び出すために生成モデルから構造化されたレスポンスを取得する一般的な回避策を試します。

4. 一般的な回避策を試す

外部ソースからの最新の情報やデータが必要なシナリオで生成モデルを使用する場合は、外部 API を呼び出して、その結果を生成モデルにフィードし、レスポンスで使用できます。

外部システムを呼び出す前に、使用する適切な関数を特定し、ユーザーから関連するパラメータを抽出し、パラメータを構造化データオブジェクトに配置する必要があります。通常、これには、生成モデルに有効な構造化データを出力させるための徹底的なプロンプトエンジニアリングが必要です。

前のセクションで説明した質問をもう一度確認し、モデルに追加の指示を追加しましょう。Gemini モデルに次のリクエストを送信してみてください。

user_prompt = "What's the exchange rate from euros to US dollars today?"

response = model.generate_content("""
Your task is to extract parameters from the user's input and return it as a
structured JSON payload. The user will ask about the exchange rate and which
currency they are converting from and converting to.

User input: {user_prompt}

Please extract the currencies as parameters and put them in a JSON object.
""".format(user_prompt=user_prompt))
print(response.text)

この結果は次のテキストレスポンスになります。これは有効な JSON ではないため、操作が困難になります。

```json
{
  "currency_from": "euros",
  "currency_to": "US dollars"
}
```

特に、テキストレスポンスの最初と最後の行には、コードブロックを区切るバッククォートが含まれています。最初の行には言語指定子が含まれています。JSON オブジェクトの値は、通貨換算 API が入力パラメータとして想定する標準の 3 文字の通貨略称ではありません。

Python を使用してこのテキストを有効な JSON と辞書に後処理したり、プロンプトに指示を追加したり、目的の出力の例を 1 つ以上提供したり、モデルをファインチューニングしたり、生成モデルに JSON のクリーンアップを依頼する別の呼び出しを行ったりできます。

しかし、より決定論的な方法があります。Gemini で関数呼び出しを使用して外部サービスの情報をクエリし、関連性の高いレスポンスをエンドユーザーに返す方法について説明します。

5. 関数呼び出しの仕組み

パラメータの抽出と関数呼び出しを開始する前に、関数呼び出しの手順と、ランタイムで使用されるコンポーネントについて説明します。

Gemini の関数呼び出しの概要

Gemini API へのユーザー入力

ユーザーからのプロンプトが Gemini API に送信されます。Gemini モデルへの API 呼び出しで、デベロッパーはツール内に 1 つ以上の関数宣言を定義しています。これにより、Gemini モデルは呼び出すことができる関数とその呼び出し方法を認識します。

Gemini API が関数呼び出しを返す

Gemini は、ユーザー入力とプロンプトの内容に基づいて、呼び出す関数の名前と使用する対応するパラメータを含む構造化データを含む関数呼び出しレスポンスを返します。

API リクエストを発行する

次に、関数名とパラメータを使用して API リクエストを行い、外部システムまたは API から情報を取得します。この API リクエストとレスポンスは、デベロッパーがアプリケーションコードに実装するもので、Gemini API と SDK のスコープ外で発生します。たとえば、Python で requests ライブラリを使用して REST API を呼び出し、JSON レスポンスを受け取ることができます。または、任意のアプローチとクライアントライブラリを使用して関数を呼び出すこともできます。

API レスポンスを Gemini に返す

最後に、API レスポンスを Gemini モデルに渡します。これにより、エンドユーザーの最初のプロンプトに対するレスポンスを生成したり、Gemini モデルが追加情報を必要と判断した場合は別の関数呼び出しレスポンスを呼び出したりできます。

6. API を選択する

関数呼び出しの全体的なフローと具体的な手順を理解したところで、最新の通貨換算レートを取得する生成 AI パイプラインを構築します。まず、情報のソースとして使用する API を選択する必要があります。

通貨換算アプリでは、https://www.frankfurter.app/ の REST API を使用して、世界の為替レートに関する最新情報を取得します。

この REST API を操作するために、Python で requests を使用して次のように REST API 呼び出しを行うことがあります。

import requests
url = "https://api.frankfurter.app/latest"
response = requests.get(url)
response.text

または、次のような cURL リクエスト。

curl https://api.frankfurter.app/latest

次のようなレスポンスが返されます。

{
  "amount": 1,
  "base": "EUR",
  "date": "2023-12-20",
  "rates": {
    "AUD": 1.6186, "BGN": 1.9558, "BRL": 5.3287,
    "CAD": 1.4609, "CHF": 0.946, "CNY": 7.8121,
    "CZK": 24.538, "DKK": 7.4565, "GBP": 0.86555,
    "HKD": 8.5439, "HUF": 385.23, "IDR": 16994,
    "ILS": 3.9983, "INR": 91.06, "ISK": 150.3,
    "JPY": 157.12, "KRW": 1425.62, "MXN": 18.6867,
    "MYR": 5.0977, "NOK": 11.2895, "NZD": 1.7421,
    "PHP": 60.991, "PLN": 4.3413, "RON": 4.9699,
    "SEK": 11.129, "SGD": 1.4562, "THB": 38.252,
    "TRY": 31.883, "USD": 1.0944, "ZAR": 20.111
  }
}

Gemini の関数呼び出しでは、外部 API 呼び出しが実際に行われないため、使用する API の種類に制限はありません。Cloud Run サービス、Cloud Functions、Google Cloud サービスへの API リクエスト、外部 REST API を使用できます。

7. 関数とツールを定義する

使用する REST API を選択したので、API 仕様を定義して、ツールに関数を登録します。

最新バージョンの Vertex AI SDK for Python がインストールされていることを確認します。

次に、Python SDK から必要なモジュールをインポートし、Gemini モデルを初期化します。

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

model = GenerativeModel("gemini-1.5-pro-001")

https://api.frankfurter.app/ の REST API を参照すると、次の入力パラメータを受け入れることがわかります。

パラメータ	型	説明
`from`	文字列	換算元の通貨
`to`	文字列	換算先の通貨
`date`	文字列	為替レートを取得する日付

これらのパラメータを使用すると、この REST API の部分的な OpenAPI 仕様は YAML 形式で次のようになります。

openapi: 3.0.0
info:
  title: Frankfurter Exchange Rate API
  description: This API provides current and historical exchange rates
  version: 1.0.0
servers:
  - url: https://api.frankfurter.app
paths:
  /{date}:
    get:
      summary: Get the latest currency exchange rates.
      parameters:
        - name: date
          in: path
          description: Get currency rates for a specific date or 'latest' if a date is not specified
          required: true
          schema:
            type: string
        - name: from
          in: query
          description: The currency to convert from.
          required: true
          schema:
            type: string
        - name: to
          in: query
          description: The currency to convert to.
          schema:
            type: string

次に、Gemini 用 Python SDK を使用して、これを FunctionDeclaration として登録します。

get_exchange_rate_func = FunctionDeclaration(
    name="get_exchange_rate",
    description="Get the exchange rate for currencies between countries",
    parameters={
    "type": "object",
    "properties": {
        "currency_date": {
            "type": "string",
            "description": "A date that must always be in YYYY-MM-DD format or the value 'latest' if a time period is not specified"
        },
        "currency_from": {
            "type": "string",
            "description": "The currency to convert from in ISO 4217 format"
        },
        "currency_to": {
            "type": "string",
            "description": "The currency to convert to in ISO 4217 format"
        }
    },
         "required": [
            "currency_from",
            "currency_date",
      ]
  },
)

生成モデルはこの情報を使用して、選択する関数と、関数呼び出しでパラメータをどのように入力するかを決定するため、関数とパラメータの説明はできるだけ詳細に記述してください。

最後に、関数宣言を含む Tool を定義します。

exchange_rate_tool = Tool(
    function_declarations=[get_exchange_rate_func],
)

ここでは、ツール内で 1 つの関数宣言を使用していますが、ツールに 1 つ以上の関数宣言を登録できます。モデルは、実行時に使用する適切な関数を選択します。Gemini SDK for Python の FunctionDeclaration、Tool、関連クラスの詳細については、Gemini API の関数呼び出しに関するドキュメントをご覧ください。

関数とツールの定義の構成が完了しました。次のセクションでは、このツールを使用して生成モデルを呼び出し、REST API の呼び出しに使用できる関数呼び出しを取得します。

8. 関数呼び出しを生成する

これで、生成モデルにプロンプトを表示し、定義した tool を含めることができます。

prompt = """What is the exchange rate from Australian dollars to Swedish krona?
How much is 500 Australian dollars worth in Swedish krona?"""

response = model.generate_content(
    prompt,
    tools=[exchange_rate_tool],
)

レスポンスオブジェクトを見てみましょう。

print(response.candidates[0].content)

role: "model"
parts {
  function_call {
    name: "get_exchange_rate"
    args {
      fields {
        key: "currency_to"
        value {
          string_value: "SEK"
        }
      }
      fields {
        key: "currency_from"
        value {
          string_value: "AUD"
        }
      }
      fields {
        key: "currency_date"
        value {
          string_value: "latest"
        }
      }
    }
  }
}

モデルが使用可能な関数を 1 つ選択し、get_exchange_rate 関数の関数呼び出しをパラメータとともに返したようです。パラメータは、必要な形式になっています。生成モデルから構造化されたレスポンスを取得できるようになりました。

次のセクションでは、レスポンスの情報を使用して API リクエストを行います。

9. API リクエストを行う

Gemini の関数呼び出しでは、外部 API 呼び出しは実際には行われません。任意の言語、ライブラリ、フレームワークを自由に使用できます。

ここでは、Python の requests ライブラリを使用して、為替レートの REST API を呼び出します。

レスポンスを Python 辞書にアンパックします。

params = {}
for key, value in response.candidates[0].content.parts[0].function_call.args.items():
    params[key[9:]] = value
params

これで、requests または他のメソッドを呼び出すことができます。

import requests
url = f"https://api.frankfurter.app/{params['date']}"
api_response = requests.get(url, params=params)
api_response.text

次のようなレスポンスが返されます。

'{"amount":1.0,"base":"AUD","date":"2024-01-16","rates":{"SEK":6.8682}}'

REST API からのレスポンスには、今日の最新のレート情報が含まれています。次のセクションでは、この情報をモデルに渡して、ユーザーに関連性の高いレスポンスを生成できるようにします。

10. 回答を生成する

最後に、次の会話ターンで関数レスポンスをモデルに渡して、ユーザーへのレスポンスを生成します。

response = model.generate_content(
    [
    Content(role="user", parts=[
        Part.from_text(prompt + """Give your answer in steps with lots of detail
            and context, including the exchange rate and date."""),
    ]),
    Content(role="function", parts=[
        Part.from_dict({
            "function_call": {
                "name": "get_exchange_rate",
            }
        })
    ]),
    Content(role="function", parts=[
        Part.from_function_response(
            name="get_exchange_rate",
            response={
                "content": api_response.text,
            }
        )
    ]),
    ],
    tools=[exchange_rate_tool],
)


response.candidates[0].content.parts[0].text

関数レスポンスをモデルに渡すと、モデルは API レスポンスから関連情報を取得し、ユーザーのプロンプトに応答します。

The exchange rate from Australian dollars to Swedish krona on January 16, 2024,
is 1 Australian dollar is equal to 6.8663 Swedish krona.

So, 500 Australian dollars would be worth 500 * 6.8663 = 3,433.15 Swedish krona.

11. コード例の全文を表示する

この時点で、Cloud Run サービス、Cloud Functions、または別の Cloud サービスを使用して Python コードをバックエンド API に配置し、このバックエンド API を使用してモデルクエリと API 呼び出しを実行するフロントエンドアプリをデプロイできます。

最終的なソリューションの完全なコード例は次のとおりです。

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

model = GenerativeModel("gemini-1.5-pro-001")

get_exchange_rate_func = FunctionDeclaration(
    name="get_exchange_rate",
    description="Get the exchange rate for currencies between countries",
    parameters={
    "type": "object",
    "properties": {
        "currency_date": {
            "type": "string",
            "description": "A date that must always be in YYYY-MM-DD format or the value 'latest' if a time period is not specified"
        },
        "currency_from": {
            "type": "string",
            "description": "The currency to convert from in ISO 4217 format"
        },
        "currency_to": {
            "type": "string",
            "description": "The currency to convert to in ISO 4217 format"
        }
    },
         "required": [
            "currency_from",
            "currency_date",
      ]
  },
)

exchange_rate_tool = Tool(
    function_declarations=[get_exchange_rate_func],
)

prompt = """What is the exchange rate from Australian dollars to Swedish krona?
How much is 500 Australian dollars worth in Swedish krona?"""

response = model.generate_content(
    prompt,
    tools=[exchange_rate_tool],
)

response.candidates[0].content

params = {}
for key, value in response.candidates[0].content.parts[0].function_call.args.items():
    params[key[9:]] = value
params

import requests
url = f"https://api.frankfurter.app/{params['date']}"
api_response = requests.get(url, params=params)
api_response.text

response = model.generate_content(
    [
    Content(role="user", parts=[
        Part.from_text(prompt + """Give your answer in steps with lots of detail
            and context, including the exchange rate and date."""),
    ]),
    Content(role="function", parts=[
        Part.from_dict({
            "function_call": {
                "name": "get_exchange_rate",
            }
        })
    ]),
    Content(role="function", parts=[
        Part.from_function_response(
            name="get_exchange_rate",
            response={
                "content": api_response.text,
            }
        )
    ]),
    ],
    tools=[exchange_rate_tool],
)


response.candidates[0].content.parts[0].text

この実装では、生成モデルに 2 つのリクエストを使用しました。1 つは関数呼び出しを生成するリクエスト、もう 1 つは関数レスポンスを返すリクエストです。これは、Gemini で関数呼び出しと関数レスポンスを処理する 1 つの方法にすぎません。追加の関数呼び出しを行ってクエリの詳細情報を取得したり、チャットや非同期メソッドで関数呼び出しを使用したりすることもできます。

その他のコードサンプルについては、Gemini の関数呼び出しのサンプルノートブックをご覧ください。

12. 完了

Gemini で関数呼び出しを使用して、Vertex AI Gemini API と Python を使用する生成 AI パイプラインを構築できました。ユーザーが為替レートについて質問すると、システムは外部 API から最新のデータを取得し、回答を返します。

Gemini の関数呼び出しでは、エンドユーザーからのプロンプトに基づいて、適切な関数を選択し、プロンプトからパラメータを抽出し、外部 API 呼び出しを行うための構造化データオブジェクトを返します。

Gemini の関数呼び出しの設計は、パラメータを決定論的に抽出する際の利点と、要約とコンテンツ作成を生成モデルに任せる際の利点の両方を実現することを目的としています。パイプラインで他の API とプロンプトを試したり、Vertex AI Gemini API に関連するその他の機能を試したりしてみてください。