教程：函数调用

函数调用可让您更轻松地从 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 密钥签入版本控制系统。

您应该使用 Secret 存储区来存储 API 密钥，例如 Google Cloud Secret Manager。

另一种替代方案是将其存储在 GenerativeAI-Info.plist 文件中，然后从 .plist 文件中读取 API 密钥。请务必添加此.plist 文件，并将其从版本控制系统中排除。以下代码展示了如何从 .plist 文件检索 API 密钥：

enum APIKey {
  // Fetch the API key from `GenerativeAI-Info.plist`
  static var `default`: String {
    guard let filePath = Bundle.main.path(forResource: "GenerativeAI-Info", ofType: "plist")
    else {
      fatalError("Couldn't find file 'GenerativeAI-Info.plist'.")
    }
    let plist = NSDictionary(contentsOfFile: filePath)
    guard let value = plist?.object(forKey: "API_KEY") as? String else {
      fatalError("Couldn't find key 'API_KEY' in 'GenerativeAI-Info.plist'.")
    }
    if value.starts(with: "_") {
      fatalError(
        "Follow the instructions at https://ai.google.dev/tutorials/setup to get an API key."
      )
    }
    return value
  }
}

您还可以查看 Swift 生成式 AI 示例应用，了解如何在 .plist 文件中存储 API 密钥。本教程假设您正在通过这个按需资源 .plist 文件访问 API 密钥。

导入 SDK 软件包并配置您的 API 密钥

如需在您自己的 Swift 应用中使用 Gemini API，请将 GoogleGenerativeAI 软件包添加到 Xcode 应用开发项目中：

在 Xcode 中的项目导航器中，右键点击您的项目。
从上下文菜单中选择添加软件包。
在添加软件包对话框中，将软件包网址粘贴到搜索栏中：
```
https://github.com/google/generative-ai-swift
```
点击 Add Package 使 Xcode 添加 GoogleGenerativeAI 软件包添加到您的项目中。

定义 API 函数

创建一个发出 API 请求的函数。该函数应定义但可以在应用代码之外调用服务或 API 部署应用Gemini API 不会直接调用此函数，因此您可以通过应用代码控制此函数的执行方式和时间。出于演示目的，本教程定义了一个模拟 API 函数，该函数只会返回请求的照明值：

func setLightValues(brightness: String,
                    colorTemp: String) -> JSONObject {
  // This mock API returns the requested lighting values
  return [
    "brightness": .string(brightness),
    "colorTemperature": .string(colorTemp)
  ]
}

创建函数声明

创建将传递给生成模型的函数声明。时间声明一个函数以供模型使用，则应尽可能多地提供函数和参数说明中提供的信息。生成模型根据这些信息确定要选择的函数以及如何提供函数调用中参数的值。以下代码展示了如何声明照明控制函数：

let controlLightFunctionDeclaration = FunctionDeclaration(
  name: "controlLight",
  description: "Set the brightness and color temperature of a room light.",
  parameters: [
    "brightness": Schema(
      type: .string,
      description: "Light level from 0 to 100. Zero is off and 100 is full brightness."
    ),
    "colorTemperature": Schema(
      type: .string,
      description: "Color temperature of the light fixture which can be `daylight`, `cool` or `warm`."
    ),
  ],
  requiredParameters: ["brightness", "colorTemperature"]
)

在模型初始化期间声明函数

如果要对模型使用函数调用，则必须提供函数声明。你声明函数方法是设置模型的 tools 参数：

// Use a model that supports function calling, like a Gemini 1.5 model
let generativeModel = GenerativeModel(
  name: "gemini-1.5-flash",
  apiKey: apiKey,
  // Specify the function declaration.
  tools: [Tool(functionDeclarations: [controlLightFunctionDeclaration])]
)

生成函数调用

使用函数声明初始化模型后，您可以使用定义的函数向模型提示问题。您应使用聊天提示 (sendMessage()) 进行函数调用，因为函数调用通常会受益于拥有先前提示和响应的上下文。

let chat = generativeModel.startChat()

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

// Send the message to the generative model
let response1 = try await chat.sendMessage(prompt)

// Check if the model responded with a function call
guard let functionCall = response1.functionCalls.first else {
  fatalError("Model did not respond with a function call.")
}
// Print an error if the returned function was not declared
guard functionCall.name == "controlLight" else {
  fatalError("Unexpected function called: \(functionCall.name)")
}
// Verify that the names and types of the parameters match the declaration
guard case let .string(brightness) = functionCall.args["brightness"] else {
  fatalError("Missing argument: brightness")
}
guard case let .string(colorTemp) = functionCall.args["colorTemperature"] else {
  fatalError("Missing argument: colorTemperature")
}

// Call the hypothetical API
let apiResponse = setLightValues(brightness: brightness, colorTemperature: colorTemp)

// Send the API response back to the model so it can generate a text response that can be
// displayed to the user.
let response = try await chat.sendMessage([ModelContent(
  role: "function",
  parts: [.functionResponse(FunctionResponse(
    name: functionCall.name,
    response: apiResponse
  ))]
)])

// Log the text response.
guard let modelResponse = response.text else {
  fatalError("Model did not respond with text.")
}
print(modelResponse)