関数呼び出しのチュートリアル

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

Gemini モデルに関数の説明を指定できます。これらは、アプリの言語で記述する関数です（Google Cloud Functions ではありません）。モデルがクエリの処理に役立つ関数を呼び出して結果を返すよう求める場合があります。

まだ確認していない場合は、関数呼び出しの概要で詳細を確認してください。

照明制御の API の例

アプリケーション プログラミング インターフェース（API）を備えた基本的な照明制御システムがあり、ユーザーが簡単なテキスト リクエストで照明を制御できるようにしたいとします。関数呼び出し機能を使用すると、ユーザーからの照明変更リクエストを解釈し、API 呼び出しに変換して照明値を設定できます。この架空の照明制御システムでは、ライトの明るさと色温度を 2 つの個別のパラメータとして制御できます。

パラメータ タイプ 必須 / 省略可 説明
brightness 数値 あり 明るさレベル（0 ～ 100）。0 はオフ、100 は最大の明るさです。
colorTemperature 文字列 あり 照明器具の色温度（daylight、cool、warm のいずれか）。

わかりやすくするために、この架空の照明システムにはライトが 1 つしかなく、ユーザーは部屋や場所を指定する必要はありません。照明制御 API に送信して、昼光色温度を使用して照明レベルを 50% に変更する JSON リクエストの例を次に示します。

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

このチュートリアルでは、Gemini API の関数呼び出しを設定して、ユーザーの照明リクエストを解釈し、API 設定にマッピングして、照明の明るさと色温度の値を制御する方法について説明します。

始める前に: プロジェクトと API キーを設定する

Gemini API を呼び出す前に、プロジェクトを設定して API キーを構成する必要があります。

API 関数を定義する

API リクエストを行う関数を作成します。この関数はアプリケーションのコード内で定義する必要がありますが、アプリケーション外のサービスを呼び出すこともできます。Gemini API は、この関数を直接呼び出しません。そのため、この関数の実行方法と実行タイミングをアプリケーション コードで制御できます。このチュートリアルでは、デモ用に、リクエストされた照明値のみを返すモック API 関数を定義します。

async function setLightValues(brightness, colorTemp) {
  // This mock API returns the requested lighting values
  return {
    brightness: brightness,
    colorTemperature: colorTemp
  };
}

関数宣言を作成する

生成モデルに渡す関数宣言を作成します。モデルで使用する関数を宣言する場合は、関数とパラメータの説明にできるだけ多くの詳細を含める必要があります。生成モデルは、この情報を使用して、選択する関数と、関数呼び出しでパラメータに値を指定する方法を決定します。次のコードは、照明制御関数を宣言する方法を示しています。

// Function declaration, to pass to the model.
const controlLightFunctionDeclaration = {
  name: "controlLight",
  parameters: {
    type: "OBJECT",
    description: "Set the brightness and color temperature of a room light.",
    properties: {
      brightness: {
        type: "NUMBER",
        description: "Light level from 0 to 100. Zero is off and 100 is full brightness.",
      },
      colorTemperature: {
        type: "STRING",
        description: "Color temperature of the light fixture which can be `daylight`, `cool` or `warm`.",
      },
    },
    required: ["brightness", "colorTemperature"],
  },
};

// Executable function code. Put it in a map keyed by the function name
// so that you can call it once you get the name string from the model.
const functions = {
  controlLight: ({ brightness, colorTemp }) => {
    return setLightValues( brightness, colorTemp)
  }
};

モデルの初期化中に関数を宣言する

モデルで関数呼び出しを使用する場合は、モデル オブジェクトを初期化するときに関数宣言を指定する必要があります。関数を宣言するには、モデルの tools パラメータを設定します。

<html>
  <body>
    <!-- ... Your HTML and CSS -->

    <script type="importmap">
      {
        "imports": {
          "@google/generative-ai": "https://esm.run/@google/generative-ai"
        }
      }
    </script>
    <script type="module">
      import { GoogleGenerativeAI } from "@google/generative-ai";

      // Fetch your API_KEY
      const API_KEY = "...";

      // Access your API key (see "Set up your API key" above)
      const genAI = new GoogleGenerativeAI(API_KEY);

      // ...

      const generativeModel = genAI.getGenerativeModel({
        // Use a model that supports function calling, like a Gemini 1.5 model
        model: "gemini-1.5-flash",

        // Specify the function declaration.
        tools: {
          functionDeclarations: [controlLightFunctionDeclaration],
        },
      });
    </script>
  </body>
</html>

関数呼び出しを生成する

関数宣言でモデルを初期化したら、定義した関数でモデルにプロンプトを表示できます。通常、関数呼び出しでは、以前のプロンプトとレスポンスのコンテキストが役立つため、チャット プロンプト（sendMessage()）を使用した関数呼び出しを使用する必要があります。

const chat = generativeModel.startChat();
const prompt = "Dim the lights so the room feels cozy and warm.";

// Send the message to the model.
const result = await chat.sendMessage(prompt);

// For simplicity, this uses the first function call found.
const call = result.response.functionCalls()[0];

if (call) {
  // Call the executable function named in the function call
  // with the arguments specified in the function call and
  // let it call the hypothetical API.
  const apiResponse = await functions[call.name](call.args);

  // Send the API response back to the model so it can generate
  // a text response that can be displayed to the user.
  const result = await chat.sendMessage([{functionResponse: {
    name: 'controlLight',
    response: apiResponse
  }}]);

  // Log the text response.
  console.log(result.response.text());
}