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

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

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

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

API 関数を定義する

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

async function setLightValues(brightness, colorTemp) {
  return {
    brightness: brightness,
    colorTemperature: colorTemp
  };
}

関数宣言を作成する

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

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"],
  },
};

// Put functions in a "map" keyed by the function name so it is easier to call
const functions = {
  controlLight: ({ brightness, colorTemperature }) => {
    return setLightValues( brightness, colorTemperature)
  }
};

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

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

const { GoogleGenerativeAI } = require("@google/generative-ai");

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

const generativeModel = genAI.getGenerativeModel({
  model: "gemini-2.0-flash",
  // Specify the function declaration.
  tools: {
    functionDeclarations: [controlLightFunctionDeclaration],
  },
});

関数呼び出しを生成する

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

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

const result = await chat.sendMessage(prompt);
const call = result.response.functionCalls()[0];

if (call) {
  // Call the executable function
  const apiResponse = await functions[call.name](call.args);

  // Send the API response back to the model
  const result2 = await chat.sendMessage([{functionResponse: {
    name: 'controlLight',
    response: apiResponse
  }}]);

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

関数呼び出しモード

関数呼び出しの mode パラメータを使用して、特徴の実行動作を変更できます。次の 3 つのモードがあります。

AUTO: デフォルトのモデル動作。モデルは、関数呼び出しまたは自然言語によるレスポンスのどちらを予測するかを決定します。
ANY: モデルは常に関数呼び出しを予測するように制約されています。allowed_function_names が指定されていない場合、モデルは使用可能なすべての関数宣言から選択します。allowed_function_names が指定されている場合、モデルは許可された関数のセットから選択します。
NONE: モデルは関数呼び出しを予測しません。この場合、モデルの動作は、関数宣言を渡さない場合と同じです。

allowed_function_names のセットを指定して、モデルが呼び出す関数を制限することもできます。allowed_function_names は、モードが ANY の場合にのみ含める必要があります。関数名は関数宣言名と一致する必要があります。モードを ANY に設定し、allowed_function_names を設定すると、モデルは指定された関数名のセットから関数呼び出しを予測します。

関数呼び出しモードを指定するには、生成モデルを初期化するときに toolConfig パラメータを設定します。

const generativeModel2 = genAI.getGenerativeModel({
  // Setting a function calling mode is only available in Gemini 1.5 Pro.
  model: "gemini-1.5-pro-latest",
  tools: {
    functionDeclarations: [getExchangeRateFunctionDeclaration],
  },
  toolConfig: {
    functionCallingConfig: {
      // Possible values are: Mode.AUTO, Mode.ANY, Mode.NONE
      mode: FunctionCallingMode.ANY
    }
  }
});