函式呼叫教學課程

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

您可以為 Gemini 模型提供函式說明。這些函式是使用應用程式語言編寫的函式 (也就是說，它們不是 Google Cloud Functions)。模型可能會要求您呼叫函式，然後傳回以便模型處理查詢

如果您還不瞭解函式呼叫簡介：詳情

照明控制 API 範例

假設您有一個基本的照明控制系統搭配應用程式設計介面 (API)，並希望使用者能透過簡單的文字要求您可以使用函式呼叫功能，解讀使用者提出的燈光變更要求，並將這些要求轉譯為 API 呼叫，以便設定燈光值。這個假設的照明控制系統可讓您控制燈光的亮度和色溫，這兩個參數分別定義如下：

參數	類型	必要	說明
`brightness`	數字	是	光線強度從 0 到 100。零關閉，100 為全彩。
`colorTemperature`	字串	是	燈具的色溫，可能是 `daylight`、`cool` 或 `warm`。

為簡化說明，這個假想的照明系統只有一盞燈，因此使用者不必指定房間或位置。以下是您可以傳送至照明控制 API 的 JSON 要求範例，藉此使用日光色溫將燈光亮度變更為 50%：

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

本教學課程將說明如何設定函式呼叫，供 Gemini API 執行下列操作：解讀使用者的光源要求並對應至 API 設定，亮度和色溫值。

事前準備：設定專案和 API 金鑰

呼叫 Gemini API 前，請先設定專案並設定您的 API 金鑰。

展開查看如何設定專案和 API 金鑰

取得並保護 API 金鑰

您需要 API 金鑰才能呼叫 Gemini API。如果您還沒有帳戶建立金鑰

取得 API 金鑰

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

您應使用 Google Cloud 等密鑰存放區做為 API 金鑰 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 範例應用程式瞭解如何將 API 金鑰儲存在 .plist 檔案中。本教學課程假設透過這個隨選資源 .plist 檔案存取 API 金鑰。

匯入 SDK 套件並設定 API 金鑰

如要在您自己的 Swift 應用程式中使用 Gemini API，請將 GoogleGenerativeAI 套件新增至 Xcode 應用程式開發專案：

在 Xcode 中的專案導覽器專案上按一下滑鼠右鍵。
在內容選單中選取「Add Packages」。
在「Add Packages」對話方塊中，將套件網址貼到搜尋列中：
```
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)