函式呼叫教學課程

函式呼叫可讓您更輕鬆地從生成式模型取得結構化資料輸出內容。您可以運用這些輸出內容呼叫其他 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。如果您還沒有金鑰，請在 Google AI 工作室中建立金鑰。

取得 API 金鑰

強烈建議您不要將 API 金鑰登錄到版本管控系統。

您應將 API 金鑰儲存在位於專案根目錄的 local.properties 檔案中，並將此檔案排除在版本管控之外。如要進行實際部署，請使用 Secrets Gradle 外掛程式，將 API 金鑰讀取為建構設定變數。

// Access your API key as a Build Configuration variable
val apiKey = BuildConfig.apiKey

本教學課程中的所有程式碼片段都採用這種最佳做法。此外，如要查看 Secrets Gradle 外掛程式的實作方式，您可以查看此 SDK 的範例應用程式，或是使用 Android Studio 的最新預先發布版，其中包含 Gemini API Starter 範本 (內含可讓您開始使用 local.properties 檔案)。

在專案中新增 SDK 依附元件

在應用程式開發環境中，執行下列操作：

在模組 (應用程式層級) Gradle 設定檔中，新增 Google AI SDK for Android 的依附元件：

Kotlin

// add to <project>/<app-module>/build.gradle.kts
dependencies {
  // ... other androidx dependencies

  // add the dependency for the Google AI client SDK for Android
  implementation("com.google.ai.client.generativeai:generativeai:0.7.0")
}

Java

// add to <project>/<app-module>/build.gradle
dependencies {
  // ... other androidx dependencies

  // add the dependency for the Google AI client SDK for Android
  implementation("com.google.ai.client.generativeai:generativeai:0.7.0")

  // Required for one-shot operations to use `ListenableFuture` from Guava Android
  implementation("com.google.guava:guava:31.0.1-android")

  // Required for streaming operations to use `Publisher` from Reactive Streams
  implementation("org.reactivestreams:reactive-streams:1.0.4")

}

將 Android 專案與 Gradle 檔案同步處理。

定義 API 函式

建立可提出 API 要求的函式。應定義這個函式程式碼，但可以在應用程式Gemini API 不會直接呼叫這個函式，因此你可以控制透過應用程式執行此函式的方式和時間再也不是件繁重乏味的工作為了示範，本教學課程會定義模擬 API 函式，只傳回要求的照明值：

suspend fun setLightValues(
    brightness: Int,
    colorTemp: String
): JSONObject {
    // This mock API returns the requested lighting values
    return JSONObject().apply {
        put("brightness", brightness)
        put("colorTemperature", colorTemp)
    }
}

建立函式宣告

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

val lightControlTool = defineFunction(
  name = "setLightValues",
  description = "Set the brightness and color temperature of a room light.",
  Schema.int("brightness", "Light level from 0 to 100. Zero is off and 100" +
    " is full brightness."),
  Schema.str("colorTemperature", "Color temperature of the light fixture" +
    " which can be `daylight`, `cool` or `warm`.")
) { brightness, colorTemp ->
    // Call the function you declared above
    setLightValues(brightness.toInt(), colorTemp)
}

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

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

val generativeModel = GenerativeModel(
    modelName = "gemini-1.5-flash",

    // Access your API key as a Build Configuration variable
    apiKey = BuildConfig.apiKey,

    // Specify the function declaration.
    tools = listOf(Tool(listOf(lightControlTool)))
)

產生函式呼叫

使用函式宣告初始化模型後，您可以使用定義的函式提示模型。您應使用聊天提示 (sendMessage()) 進行函式呼叫，因為函式呼叫通常會受益於先前提示和回應的內容。

val chat = generativeModel.startChat()

val prompt = "Dim the lights so the room feels cozy and warm."

// Send the message to the generative model
var response = chat.sendMessage(prompt)

// Check if the model responded with a function call
response.functionCall?.let { functionCall ->
  // Try to retrieve the stored lambda from the model's tools and
  // throw an exception if the returned function was not declared
  val matchedFunction = generativeModel.tools?.flatMap { it.functionDeclarations }
      ?.first { it.name == functionCall.name }
      ?: throw InvalidStateException("Function not found: ${functionCall.name}")

  // Call the lambda retrieved above
  val apiResponse: JSONObject = matchedFunction.execute(functionCall)

  // Send the API response back to the generative model
  // so that it generates a text response that can be displayed to the user
  response = chat.sendMessage(
    content(role = "function") {
        part(FunctionResponsePart(functionCall.name, apiResponse))
    }
  )
}

// Whenever the model responds with text, show it in the UI
response.text?.let { modelResponse ->
    println(modelResponse)
}