Hướng dẫn: Gọi hàm bằng API Gemini

Python Node.js Go Dart (Flutter) Android Swift Web

Tính năng gọi hàm giúp bạn dễ dàng nhận được kết quả dữ liệu có cấu trúc từ các mô hình tạo sinh. Sau đó, bạn có thể sử dụng các kết quả đầu ra này để gọi các API khác và trả về dữ liệu phản hồi liên quan cho mô hình. Nói cách khác, tính năng gọi hàm giúp bạn kết nối các mô hình tạo sinh với hệ thống bên ngoài để nội dung được tạo bao gồm thông tin chính xác và mới nhất.

Bạn có thể cung cấp cho mô hình Gemini nội dung mô tả về các hàm. Đây là các hàm mà bạn viết bằng ngôn ngữ của ứng dụng (tức là các hàm này không phải là Google Cloud Functions). Mô hình này có thể yêu cầu bạn gọi một hàm và gửi lại kết quả để giúp mô hình đó xử lý truy vấn của bạn.

Nếu bạn chưa xem, hãy xem phần Giới thiệu về tính năng gọi hàm để tìm hiểu thêm.

Thiết lập dự án

Trước khi gọi API Gemini, bạn cần thiết lập dự án Xcode, bao gồm cả việc thiết lập khoá API, thêm gói SDK vào dự án Xcode và khởi động mô hình.

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
  }
}

Thiết lập lệnh gọi hàm

Trong hướng dẫn này, bạn sẽ yêu cầu mô hình tương tác với một API trao đổi tiền tệ giả định hỗ trợ các tham số sau:

Ví dụ về yêu cầu API

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

Ví dụ về phản hồi của API

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

Bước 1: Tạo hàm thực hiện yêu cầu API

Nếu bạn chưa có, hãy bắt đầu bằng cách tạo hàm đưa ra yêu cầu API.

Để minh hoạ trong hướng dẫn này, thay vì gửi yêu cầu API thực tế, bạn sẽ trả về các giá trị được cố định giá trị trong mã ở cùng một định dạng mà API thực tế sẽ trả về.

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)]),
  ]
}

Bước 2: Tạo phần khai báo hàm

Tạo phần khai báo hàm mà bạn sẽ truyền sang mô hình tạo sinh (bước tiếp theo của hướng dẫn này).

Cung cấp càng nhiều thông tin chi tiết càng tốt trong phần mô tả hàm và tham số. Mô hình tạo sinh sử dụng thông tin này để xác định hàm cần chọn và cách cung cấp giá trị cho các tham số trong lệnh gọi hàm.

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"]
)

Bước 3: Chỉ định khai báo hàm trong quá trình khởi tạo mô hình

Chỉ định khai báo hàm khi khởi chạy mô hình tạo sinh bằng cách đặt tham số tools của mô hình:

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

Bước 4: Tạo lệnh gọi hàm

Bây giờ, bạn có thể nhắc mô hình bằng hàm đã xác định.

Bạn nên sử dụng tính năng gọi hàm thông qua giao diện trò chuyện, vì các lệnh gọi hàm phù hợp với cấu trúc nhiều lượt của cuộc trò chuyện.

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)