教學課程：使用 Gemini API 呼叫函式

函式呼叫可讓您更輕鬆地從生成式模型中取得結構化資料輸出。接著，您可以使用這些輸出內容呼叫其他 API，並將相關回應資料傳回模型。換句話說，函式呼叫可協助您將生成式模型連結至外部系統，讓生成的內容獲得最新且準確的資訊。

您可以提供內含函式說明的 Gemini 模型。這些函式是以應用程式語言編寫的函式 (也就是非 Google Cloud Functions)。模型可能會要求您呼叫函式並傳回結果，協助模型處理您的查詢。

如果您尚未閱讀此課程，請參閱函式呼叫簡介以瞭解詳情。

設定專案

呼叫 Gemini API 之前，您需要設定 Xcode 專案，包括設定 API 金鑰、將 SDK 套件新增至 Xcode 專案，以及初始化模型。

設定並保護 API 金鑰

如要使用 Gemini API，您必須具備 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」。
在「Add Packages」對話方塊中，將套件網址貼到搜尋列中：
```
https://github.com/google/generative-ai-swift
```
按一下「Add Package」。Xcode 現在會在專案中新增 GoogleGenerativeAI 套件。

初始化生成式模型

您必須先初始化生成式模型，才能呼叫任何 API 呼叫。這是基本初始化，稍後在本教學課程中，您將更新函式呼叫。

匯入 GoogleGenerativeAI 模組：
```
import GoogleGenerativeAI
```

初始化生成式模型：

// Access your API key from your on-demand resource .plist file
// (see "Set up your API key" above)
// Use a model that supports function calling, like Gemini 1.0 Pro.
// See "Supported models" in the "Introduction to function calling" page.
let model = GenerativeModel(name: "MODEL_NAME", apiKey: APIKey.default)

設定函式呼叫

在本教學課程，您將讓模型與支援下列參數的假設貨幣交易平台 API 互動：

參數	類型	必要	說明
`currencyFrom`	字串	是	要用來轉換的貨幣
`currencyTo`	字串	是	要轉換成的貨幣

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 Gemini 1.0 Pro.
// See "Supported models" in the "Introduction to function calling" page.
let generativeModel = GenerativeModel(
  name: "gemini-1.0-pro",
  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)