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

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

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

まだご覧になっていない場合は、関数呼び出しの概要で学習するできます。

照明制御用の API の例

基本的な照明制御システムとアプリケーションプログラミングインターフェース（API）を使用していて、ユーザーがシンプルなテキストリクエスト。関数呼び出し機能を使用してライティングを解釈できる API 呼び出しに変換して照明を設定する API 呼び出しに変換し、使用できます。この架空の照明制御システムを使用して、明るさと色温度です parameters:

パラメータ	タイプ	必須 / 省略可	説明
`brightness`	数値	あり	明るさレベル（0～100）。ゼロがオフで、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 キーが必要です。まだお持ちでない場合は作成することもできます。

API キーを取得する

API キーをバージョンにチェックインしないことを強くおすすめします。制御システムです。

Google Cloud Secret Manager など、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());
}