教學課程：使用 Gemini API 呼叫函式


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

您可以提供內含函式說明的 Gemini 模型。這些函式是以應用程式語言編寫的函式 (也就是非 Google Cloud Functions)。模型可能會要求您呼叫函式並傳回結果，協助模型處理您的查詢。

如果您尚未閱讀此課程，請參閱函式呼叫簡介以瞭解詳情。

設定專案

呼叫 Gemini API 之前，您需要先設定專案，包括取得 API 金鑰、匯入 SDK 及初始化模型。請展開以下各個區段，查看詳細操作說明。

設定函式呼叫

在本教學課程，您將讓模型與支援下列參數的假設貨幣交易平台 API 互動：

參數 類型 必要 說明
currencyFrom 字串 是 要用來轉換的貨幣
currencyTo 字串 是 要轉換成的貨幣

API 要求範例

{
  "currencyFrom": "USD",
  "currencyTo": "SEK"
}

API 回應範例

{
  "base": "USD",
  "rates": {"SEK": 0.091}
}

步驟 1：建立發出 API 要求的函式

如果您尚未建立發出 API 要求的函式，請先完成這項操作。

為了進行示範，系統將按照實際 API 傳回的格式傳回硬式編碼值，而非傳送實際的 API 要求。

async function makeApiRequest(currencyFrom, currencyTo) {
  // This hypothetical API returns a JSON such as:
  // {"base":"USD","rates":{"SEK": 0.091}}
  return {
    base: currencyFrom,
    rates: { [currencyTo]: 0.091 },
  };
}

步驟 2：建立函式宣告

建立要傳遞至生成式模型的函式宣告 (本教學課程的下一步)。

在函式和參數說明中，盡可能加入更多詳細資料。 生成式模型會使用這項資訊來決定要選取哪個函式，以及如何在函式呼叫中提供參數值。

// Function declaration, to pass to the model.
const getExchangeRateFunctionDeclaration = {
  name: "getExchangeRate",
  parameters: {
    type: "OBJECT",
    description: "Get the exchange rate for currencies between countries",
    properties: {
      currencyFrom: {
        type: "STRING",
        description: "The currency to convert from.",
      },
      currencyTo: {
        type: "STRING",
        description: "The currency to convert to.",
      },
    },
    required: ["currencyTo", "currencyFrom"],
  },
};

// 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 = {
  getExchangeRate: ({ currencyFrom, currencyTo }) => {
    return makeApiRequest( currencyFrom, currencyTo)
  }
};

步驟 3：在模型初始化期間指定函式宣告

在初始化生成式模型時指定函式宣告，方法是將函式傳入模型的 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 Gemini 1.0 Pro.
        // See "Supported models" in the "Introduction to function calling" page.
        model: "gemini-1.0-pro",

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

步驟 4：產生函式呼叫

現在，您可以使用已定義的函式提示模型。

函式呼叫的建議方式是透過即時通訊介面使用，因為函式呼叫可充分融入即時通訊的多輪結構。

const chat = generativeModel.startChat();
const prompt = "How much is 50 US dollars worth in Swedish krona?";

// 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: 'getExchangeRate',
    response: apiResponse
  }}]);

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