函式呼叫教學課程

函式呼叫可讓您更輕鬆地從生成式模型取得結構化資料輸出內容。您可以運用這些輸出內容呼叫其他 API，並傳回 傳送給模型的相關回應資料換句話說，函式呼叫可協助您將生成式模型連結至外部系統，讓產生的內容包含最新且正確的資訊。

您可以為 Gemini 模型提供函式說明。這些 您以應用程式語言編寫的函式 (換句話說，非 Google Cloud Functions)。模型可能會要求您呼叫函式並傳回結果，以便模型處理您的查詢。

如果您還不熟悉，請參閱「函式呼叫簡介」一文，進一步瞭解相關資訊。

燈光控制 API 範例

假設您有一個基本的照明控制系統 搭配應用程式設計 介面 (API)，並希望使用者能透過簡單的 文字要求您可以使用函式呼叫功能解讀光線 將來自使用者的要求轉譯為 API 呼叫，藉此設定亮度 輕鬆分配獎金這款假設性的照明控制系統 光線的亮度以及色溫，定義為兩個分開的 參數：

參數 類型 必要 說明
brightness 數字 是 光線強度從 0 到 100。0 代表關閉狀態，100 則為全彩。
colorTemperature 字串 是 燈具的色溫，可能是 daylight、cool 或 warm。

簡單來說，這個虛構的照明系統只有一盞燈，因此使用者 也不必指定會議室或地點以下是您可以傳送至照明控制 API 的 JSON 要求範例，藉此使用日光色溫將光線亮度變更為 50%：

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

本教學課程將說明如何為 Gemini API 設定函式呼叫，以便解讀使用者的照明要求，並將這些要求對應至 API 設定，以便控制燈光的亮度和色溫值。

事前準備：設定專案和 API 金鑰

呼叫 Gemini API 前，請先設定專案並設定 您的 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
  };
}

建立函式宣告

建立您要傳遞至生成式模型的函式宣告。時間 您宣告用於模型的函式，應盡量加入詳細資料 並在函式和參數說明中盡可能顯示這項資訊生成式模型 會依據這些資訊決定要選取哪個函式，以及如何提供 值。以下程式碼說明如何 宣告亮度控制功能：

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, colorTemperature }) => {
    return setLightValues( brightness, colorTemperature)
  }
};

在模型初始化期間宣告函式

如要使用函式呼叫功能，您必須在初始化模型物件時提供函式宣告。您可以設定模型的 tools 參數來宣告函式：

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

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.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],
  },
});

產生函式呼叫

使用函式宣告來初始化模型後， 以已定義的函式提示模型請改用函式呼叫 使用即時通訊提示 (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 result2 = await chat.sendMessage([{functionResponse: {
    name: 'controlLight',
    response: apiResponse
  }}]);

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