使用 Gemini API 進行函式呼叫

iOS+ Android 網頁版 Flutter

生成式模型可有效解決許多類型的問題。不過，這類服務受到下列限制：

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

函式呼叫可協助您克服部分限制。函式呼叫有時會被稱為「工具使用」，因為這項功能可讓模型使用外部工具 (例如 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	物件	是	要取得天氣資訊的城市名稱和州。 僅支援美國的城市。必須一律為 city 和 state 的巢狀物件。
date	字串	是	擷取天氣資料的日期 (一律須為 YYYY-MM-DD 格式)。
輸出
temperature	整數	是	溫度 (華氏)
chancePrecipitation	字串	是	降雨/降雪機率 (以百分比表示)
cloudConditions	字串	是	雲端條件 (clear、partlyCloudy、mostlyCloudy、cloudy 其中之一)

初始化模型時，您會告知模型這個 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.

 

實作函式呼叫

iOS+ Android 網頁版 Flutter

事前準備

如果您尚未完成，請完成 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。

注意： 您提供給模型的函式不需要呼叫外部 API。還可以提供公式來計算值、查詢資料庫、傳回跨文件的搜尋結果等。

步驟 2：建立函式宣告

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

注意： 本指南的範例示範只為模型提供一個函式宣告，但您可以為模型提供最多 128 項函式宣告，供模型選擇。

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

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

請注意下列提供的結構定義事項：

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

  • 支援的屬性如下：type、nullable、required、format、description、properties、items、enum。

  • 不支援下列屬性：default、optional、maximum、oneOf。

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

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

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

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

注意： Gemini 1.0 Pro 和 Gemini 1.5 Pro 都支援函式呼叫功能。決定要使用的模型時，請務必查看每個模型的配額。

您透過要求提供的函式宣告數量上限為 128 個。請參閱本頁後續的其他行為和選項，瞭解模型如何在函式之間進行選擇，以及如何控制該選擇 (使用 toolConfig 設定函式呼叫模式)。

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

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

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

由於資訊需要在模型和應用程式之間來回傳遞，因此建議您透過多輪對話即時通訊介面使用函式呼叫功能。

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

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

步驟 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 的其他功能

• 建構多輪對話 (即時通訊)。
• 使用文字提示來生成文字。
• 使用多模態提示 (包括文字、圖片、PDF、影片和音訊) 來生成文字。

瞭解如何控管內容產生

• 瞭解提示設計，包括最佳做法、策略和提示範例。
• 設定模型參數，例如溫度和輸出符記數量上限。
• 使用安全性設定，調整可能會收到有害回應的機率。

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

進一步瞭解 Gemini 模型

瞭解可用於各種用途的模型，以及相關配額和定價。

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