教程：函数调用

函数调用可让您更轻松地从 Google Cloud 控制台获取结构化数据输出生成模型。然后，您可以使用这些输出来调用其他 API 并返回将相关的响应数据提供给模型。换句话说，函数调用有助于将生成模型连接到外部系统，可提供最新、最准确的信息。

您可以为 Gemini 模型提供函数说明。这些是以应用语言编写的函数（也就是说，它们 Google Cloud Functions）。模型可能会要求您调用一个函数并返回帮助模型处理您的查询。

如果您还没看过函数调用简介（用于学习相关知识）

照明控制示例 API

假设您有一个带有应用编程接口 (API) 的基本照明控制系统，并且希望允许用户通过简单的文本请求控制灯具。您可以使用函数调用功能来解读用户发来的照明更改请求，并将其转换为 API 调用以设置照明值。通过这个假想的照明控制系统，您可以控制灯的亮度和色温，这两个参数定义如下：

参数	类型	是否必需	说明
`brightness`	number	是	光级范围为 0 到 100。0 表示关闭，100 表示完整亮度。
`colorTemperature`	字符串	是	灯具的色温，可以是 `daylight`、`cool` 或 `warm`。

为简单起见，这个虚构的照明系统只有一个光源，因此用户不需要指定房间或地点。下面是一个 JSON 请求示例您可以发送到照明控制 API，将亮度更改为 50% 使用日光色温：

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

本教程介绍了如何为 Gemini API 设置函数调用，解释用户的照明请求，并将其映射到 API 设置，以控制亮度和色温值

开始前须知：设置项目和 API 密钥

在调用 Gemini API 之前，您需要设置项目并配置您的 API 密钥。

展开以查看如何设置项目和 API 密钥

获取 API 密钥并保护其安全

您需要 API 密钥才能调用 Gemini API。如果您还没有 API 密钥，请在 Google AI Studio 中创建一个。

获取 API 密钥

强烈建议不要将 API 密钥签入版本控制系统。

您应将 API 密钥存储在项目根目录下的 local.properties 文件中，并将此文件从版本控制中排除。对于生产部署使用 Android 版 Secrets Gradle 插件以构建配置变量的形式读取 API 密钥。

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

本教程中的所有代码段均采用了此最佳实践。此外，如果您想要查看 Secrets Gradle 插件的实现，您可以查看示例应用或使用 Android Studio 的最新预览版，该版本具有 Gemini API 入门版模板（其中包含 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 请求的函数。该函数应定义但可以在应用代码之外调用服务或 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)
}