使用 Gemini API 進行函式呼叫


生成式模型能有效解決多種問題,不過,這些限制會受到限制,例如:

  • 這些知識會在訓練後凍結,導致知識過時。
  • 無法查詢或修改外部資料。

函式呼叫可協助您克服部分限制。函式呼叫有時也稱為「工具使用」,因為可讓模型使用 API 和函式等外部工具產生最終回應。

您可以在 Google Cloud 說明文件中進一步瞭解函式呼叫,包括函式呼叫的用途實用的清單。

Gemini 1.0 Pro、Gemini 1.5 Pro 和 Gemini 1.5 Flash 支援函式呼叫。

本指南說明如何實作函式呼叫設定,類似於本頁下一節所述的範例。整體來說,以下是設定應用程式中函式呼叫的步驟:

  1. 撰寫一個函式,為模型提供產生最終回應所需的資訊 (例如函式可以呼叫外部 API)。

  2. 建立函式宣告,說明函式及其參數。

  3. 在模型初始化期間提供函式宣告,讓模型知道如何在必要時使用函式。

  4. 設定應用程式,讓模型能傳送必要資訊,讓應用程式呼叫函式。

  5. 將函式的回應傳回模型,以便模型產生最終回應。

跳至程式碼導入程序

函式呼叫範例總覽

向模型傳送要求時,您也可以為模型提供一組「工具」(例如函式),讓模型用於產生最終回應。為了使用這些函式並進行呼叫 (稱為「函式呼叫」),模型和應用程式需要彼此來回傳遞資訊,因此建議您透過多回合即時通訊介面使用函式呼叫功能。

假設您有一個應用程式,使用者可以輸入類似以下的提示:What was the weather in Boston on October 17, 2024?

Gemini 模型可能不知道這項天氣資訊,但請假設您知道某個外部天氣服務 API,可提供這類資料。您可以運用函式呼叫,為 Gemini 模型提供該 API 的路徑和天氣資訊。

首先,請在應用程式中編寫函式 fetchWeather,與這個假設的外部 API 互動,這個 API 的輸入和輸出內容如下:

參數 類型 必要 說明
輸入
location 物件 要取得天氣資訊的城市名稱和州。
僅支援美國境內的城市。一律必須是 citystate 的巢狀物件。
date 字串 要擷取天氣的日期 (必須一律採用 YYYY-MM-DD 格式)。
輸出
temperature 整數 溫度 (華氏)
chancePrecipitation 字串 降雨/降雪機率 (以百分比表示)
cloudConditions 字串 雲端條件 (clearpartlyCloudymostlyCloudycloudy 其中之一)

初始化模型時,您會告知模型這個 fetchWeather 函式存在,以及如何在必要時使用該函式處理傳入的要求。這稱為「函式宣告」。模型不會「直接」呼叫函式。相反地,當模型處理傳入的要求時,會決定 fetchWeather 函式是否可協助回應要求。如果模型判斷函式確實有用,就會產生結構化資料,協助應用程式呼叫函式

再次查看收到的要求:What was the weather in Boston on October 17, 2024?。模型可能會判定 fetchWeather 函式有助於產生回應。這個模型會查看 fetchWeather 所需的輸入參數,然後為函式產生結構化輸入資料,大致如下:

{
  functionName: fetchWeather,
  location: {
    city: Boston,
    state: Massachusetts  // the model can infer the state from the prompt
  },
  date: 2024-10-17
}

模型會將這項結構化輸入資料傳遞至您的應用程式,以便應用程式呼叫 fetchWeather 函式。應用程式從 API 收到天氣狀況後,就會將資訊傳送給模型。這些天氣資訊可讓模型完成最終處理程序,並產生回應 What was the weather in Boston on October 17, 2024? 的初始要求

模型可能會提供最終的自然語言回應,例如: On October 17, 2024, in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

圖表顯示函式呼叫如何涉及模型與應用程式中的函式互動 

實作函式呼叫

事前準備

如果您尚未完成 Vertex AI in Firebase SDK 入門指南,請先完成這項操作。 請確認您已完成下列所有操作:

  1. 設定新的或現有的 Firebase 專案,包括使用 Blaze 定價方案和啟用必要的 API。

  2. 將應用程式連結至 Firebase,包括註冊應用程式,以及將 Firebase 設定新增至應用程式。

  3. 新增 SDK,並在應用程式中初始化 Vertex AI 服務和生成式模型。

將應用程式連結至 Firebase、新增 SDK,並初始化 Vertex AI 服務和生成式模型後,就能呼叫 Gemini API

本指南的其餘步驟會說明如何實作函式呼叫設定,類似於「函式呼叫範例簡介」(請參閱本頁頂端部分) 所述的工作流程。

您可以在本頁稍後的部分查看此函式呼叫範例的完整程式碼範例

步驟 1:編寫函式

假設您有一款應用程式,可讓使用者輸入類似以下的提示: What was the weather in Boston on October 17, 2024?。Gemini 模型可能不知道這項天氣資訊,但假設您知道有可提供這項資訊的外部天氣服務 API。本指南中的範例依賴這個假設的外部 API。

在應用程式中編寫函式,以便與假設的外部 API 互動,並為模型提供產生最終要求所需的資訊。在這個天氣範例中,會是 fetchWeather 函式呼叫這個假設的外部 API。

步驟 2:建立函式宣告

建立稍後會提供給模型的函式宣告 (本指南的下一個步驟)。

在宣告中,請盡可能為函式及其參數提供詳細說明。

模型會使用函式宣告中的資訊,判斷要選取哪個函式,以及如何為實際函式呼叫提供參數值。請參閱本頁稍後的「其他行為與選項」,瞭解模型如何從函式中選擇,以及如何控制該選項。

以下是您提供的結構定義相關注意事項:

  • 您必須提供與 OpenAPI 結構定義相容的結構定義格式來提供函式宣告。Vertex AI 提供有限的 OpenAPI 結構定義支援。

    • 支援的屬性如下:typenullablerequiredformatdescriptionpropertiesitemsenum

    • 系統支援下列屬性:defaultoptionalmaximumoneOf

  • 根據預設,Vertex AI in Firebase SDK 會將所有欄位視為「必填」,除非您在 optionalProperties 陣列中將這些欄位指定為「選填」。 對於這些選用欄位,模型可以填入欄位或略過欄位。請注意,這與 Vertex AI Gemini API 的預設行為相反

如要瞭解函式宣告的最佳做法,包括名稱和說明的提示,請參閱 Google Cloud 說明文件中的「最佳做法」。

以下說明如何編寫函式宣告:

步驟 3:在模型初始化期間提供函式宣告

您透過要求提供的函式宣告數量上限為 128 個。請參閱本頁後續章節的「其他行為與選項」,瞭解模型如何從函式中選擇,以及如何控制該選項 (使用 toolConfig 設定函式呼叫模式)。

瞭解如何選擇適合用途和應用程式的 Gemini 模型,以及選用位置

步驟 4:呼叫函式以叫用外部 API

如果模型判斷 fetchWeather 函式確實可協助產生最終回應,則應用程式需要使用模型提供的結構化輸入資料,實際呼叫該函式。

由於資訊必須在模型和應用程式之間來回傳遞,因此建議您透過多輪對話介面使用函式呼叫。

以下程式碼片段說明如何告知應用程式模型想要使用 fetchWeather 函式。這也表示模型已為函式呼叫 (及其基礎外部 API) 提供必要的輸入參數值。

在這個例子中,傳入的要求包含提示 What was the weather in Boston on October 17, 2024?。根據這個提示,模型推斷出 fetchWeather 函式所需的輸入參數 (即 citystatedate)。

步驟 5:將函式的輸出內容提供給模型,以產生最終回覆

fetchWeather 函式傳回天氣資訊後,應用程式需要將其傳回模型。

接著,模型會執行最終處理作業,並產生最終自然語言回應,例如:On October 17, 2024 in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

其他行為和選項

以下是函式呼叫的其他行為,您需要配合程式碼和可以控制的選項。

模型可能會要求再次呼叫函式或其他函式。

如果單一函式呼叫的回應不足,無法讓模型產生最終回應,則模型可能會要求額外的函式呼叫,或要求呼叫完全不同的函式。後者只有在您在函式宣告清單中為模型提供多個函式時才會發生。

您的應用程式需要因應模型可能會要求額外的函式呼叫。

模型可能會要求同時呼叫多個函式。

您可以在函式宣告清單中向模型提供最多 128 個函式。有鑑於此,模型可能會判定需要多個函式來協助產生最終回應。而之後可能會決定同時呼叫其中幾個函式,這就稱為「平行函式呼叫」

您的應用程式需要因應模型可能會要求同時執行的多個函式,且應用程式需要將函式的所有回應傳回模型。

Gemini 1.5 Pro 和 Gemini 1.5 Flash 支援並行函式呼叫。

您可以控制模型可以要求呼叫函式的方式和方式。

您可以對模型應如何使用提供的函式宣告,以及是否使用這些宣告設定限制。這稱為設定函式呼叫模式例如:

  • 您可以強制模型一律使用函式呼叫,而非允許模型選擇立即的自然語言回應和函式呼叫。這就是所謂的強制函式呼叫

  • 如果您提供多個函式宣告,可以限制模型只使用提供的函式子集。

如要實作這些限制 (或模式),您可以新增工具設定 (toolConfig) 以及提示和函式宣告。可以在工具設定中指定下列任一模式。最實用的模式是 ANY

模式 說明
AUTO 預設模型行為。模型會決定是否使用函式呼叫或自然語言回應。
ANY 模型必須使用函式呼叫 (「強制函式呼叫」)。如要將模型限制為部分函式,請在 allowedFunctionNames 中指定允許的函式名稱。
NONE 模型不得使用函式呼叫。這個行為等同模型要求,且不含任何相關函式宣告。

Gemini 1.5 Pro 和 Gemini 1.5 Flash 支援函式呼叫模式。

其他功能

試用 Gemini API 的其他功能

瞭解如何控管內容生成功能

您也可以使用 Vertex AI Studio 測試提示和模型設定。

進一步瞭解 Gemini 模型

瞭解不同用途適用的模型配額與定價


提供有關 Vertex AI in Firebase 使用體驗的意見回饋