使用 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 的體驗提供意見回饋