此页面由 Cloud Translation API 翻译。

教程：使用 Gemini API 进行函数调用

借助函数调用，您可以更轻松地从生成模型中获取结构化数据输出。然后，您可以使用这些输出调用其他 API，并将相关响应数据返回给模型。换言之，函数调用可帮助您将生成模型连接到外部系统，以使生成的内容包含最新且准确的信息。

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

请参阅函数调用简介了解详情（如果您尚未这样做）。

设置项目

在调用 Gemini API 之前，您需要设置 Xcode 项目，其中包括设置 API 密钥、将 SDK 软件包添加到 Xcode 项目以及初始化模型。

设置并保护您的 API 密钥

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

获取 API 密钥

保护您的 API 密钥

强烈建议您不要将 API 密钥签入版本控制系统。一种替代方法是将其存储在 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
  }
}

您也可以查看示例应用，了解如何将 API 密钥存储在 .plist 文件中。

本教程假定您从此按需资源 .plist 文件访问 API 密钥。

将 SDK 软件包添加到您的项目中

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

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

初始化生成模型

您需要先初始化生成模型，然后才能进行任何 API 调用。这是基本的初始化；在本教程的后面部分，您将更新它以进行函数调用。

导入 GoogleGenerativeAI 模块：
```
import GoogleGenerativeAI
```

初始化生成模型：

// Use a model that supports function calling, like a Gemini 1.5 model
// Access your API key from your on-demand resource .plist file
// (see "Set up your API key" above)
let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: APIKey.default)

设置函数调用

在本教程中，您将让模型与支持以下参数的假设货币交易所 API 进行交互：

参数	类型	必需	说明
`currencyFrom`	string	是	要换算的币种
`currencyTo`	string	是	要换算成的币种

API 请求示例

{
  "currencyFrom": "USD",
  "currencyTo": "SEK"
}

API 响应示例

{
  "base": "USD",
  "rates": {"SEK": 0.091}
}

第 1 步：创建用于发出 API 请求的函数

如果尚未创建用于发出 API 请求的函数，请先创建。

在本教程中出于演示目的，您不会发送实际 API 请求，而是以与实际 API 返回的格式相同的格式返回硬编码值。

func makeAPIRequest(currencyFrom: String,
                    currencyTo: String) -> JSONObject {
  // This hypothetical API returns a JSON such as:
  // {"base":"USD","rates":{"SEK": 0.091}}
  return [
    "base": .string(currencyFrom),
    "rates": .object([currencyTo: .number(0.091)]),
  ]
}

第 2 步：创建函数声明

创建要传递给生成模型的函数声明（本教程的下一步）。

在函数和参数说明中添加尽可能多的详细信息。生成模型使用这些信息来确定选择哪个函数，以及如何为函数调用中的形参提供值。

let getExchangeRate = FunctionDeclaration(
  name: "getExchangeRate",
  description: "Get the exchange rate for currencies between countries",
  parameters: [
    "currencyFrom": Schema(
      type: .string,
      description: "The currency to convert from."
    ),
    "currencyTo": Schema(
      type: .string,
      description: "The currency to convert to."
    ),
  ],
  requiredParameters: ["currencyFrom", "currencyTo"]
)

第 3 步：在模型初始化期间指定函数声明

在初始化生成模型时，通过设置模型的 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: [getExchangeRate])]
)

第 4 步：生成函数调用

现在，您可以使用定义的函数向模型发出提示。

建议使用聊天界面使用函数调用，因为函数调用非常适合聊天的多轮结构。

let chat = generativeModel.startChat()

let prompt = "How much is 50 US dollars worth in Swedish krona?"

// 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 == "getExchangeRate" else {
  fatalError("Unexpected function called: \(functionCall.name)")
}
// Verify that the names and types of the parameters match the declaration
guard case let .string(currencyFrom) = functionCall.args["currencyFrom"] else {
  fatalError("Missing argument: currencyFrom")
}
guard case let .string(currencyTo) = functionCall.args["currencyTo"] else {
  fatalError("Missing argument: currencyTo")
}

// Call the hypothetical API
let apiResponse = makeAPIRequest(currencyFrom: currencyFrom, currencyTo: currencyTo)

// 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)