Hướng dẫn gọi hàm

Python Node.js Bắt đầu Dart (Flutter) Android Swift Web

Lệnh gọi hàm giúp bạn dễ dàng nhận dữ liệu đầu ra từ dữ liệu có cấu trúc các mô hình tạo sinh. Sau đó, bạn có thể sử dụng những dữ liệu đầu ra này để gọi các API khác và trả về dữ liệu phản hồi phù hợp cho mô hình. Nói cách khác, lệnh gọi hàm giúp bạn kết nối các mô hình tạo sinh với các hệ thống bên ngoài để nội dung được tạo có thông tin mới nhất và chính xác 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à không phải là Hàm trên Google Cloud). Mô hình có thể yêu cầu bạn gọi một hàm rồi gửi lại kết quả để giúp mô hình xử lý truy vấn của bạn.

Nếu chưa, hãy xem bài viết Giới thiệu về lệnh gọi hàm để tìm hiểu thêm.

Ví dụ về API để điều khiển ánh sáng

Giả sử bạn có một hệ thống điều khiển ánh sáng cơ bản bằng một chương trình lập trình ứng dụng giao diện (API) và bạn muốn cho phép người dùng điều khiển đèn thông qua yêu cầu tin nhắn văn bản. Bạn có thể sử dụng tính năng Gọi hàm để diễn giải các yêu cầu thay đổi ánh sáng của người dùng và dịch các yêu cầu đó thành lệnh gọi API để đặt các giá trị ánh sáng. Hệ thống điều khiển ánh sáng giả định này cho phép bạn kiểm soát độ sáng của đèn và nhiệt độ màu, được định nghĩa là hai dải màu riêng biệt thông số:

Để đơn giản, hệ thống chiếu sáng tưởng tượng này chỉ có một đèn, vì vậy người dùng không phải chỉ định phòng hoặc vị trí. Dưới đây là một yêu cầu JSON mẫu mà bạn có thể gửi đến API điều khiển ánh sáng để thay đổi độ sáng thành 50% bằng cách sử dụng nhiệt độ màu ban ngày:

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

Hướng dẫn này chỉ cho bạn cách thiết lập Lệnh gọi hàm cho Gemini API để diễn giải các yêu cầu về chiếu sáng của người dùng và ánh xạ chúng tới chế độ cài đặt API để điều khiển các giá trị độ sáng và nhiệt độ màu của đèn.

Trước khi bắt đầu: Thiết lập dự án và khoá API của bạn

Trước khi gọi API Gemini, bạn cần thiết lập dự án và định cấu hình khoá 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
  }
}

Xác định hàm API

Tạo một hàm gửi yêu cầu API. Bạn nên xác định hàm này trong mã của ứng dụng, nhưng có thể gọi các dịch vụ hoặc API bên ngoài ứng dụng. API Gemini không gọi trực tiếp hàm này, vì vậy, bạn có thể kiểm soát cách thức và thời điểm thực thi hàm này thông qua mã ứng dụng. Nhằm mục đích minh hoạ, hướng dẫn này định nghĩa một hàm API mô phỏng chỉ trả về các giá trị ánh sáng được yêu cầu:

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

Tạo phần khai báo hàm

Tạo nội dung khai báo hàm mà bạn sẽ truyền vào mô hình tạo sinh. Thời gian khi khai báo một hàm để mô hình sử dụng, bạn nên cung cấp càng nhiều thông tin chi tiết càng tốt nhất có thể 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 nào cần chọn và cách cung cấp hàm cho các tham số trong lệnh gọi hàm. Đoạn mã sau đây cho biết cách khai báo hàm điều khiển ánh sáng:

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

Khai báo hàm trong quá trình khởi tạo mô hình

Khi muốn sử dụng lệnh gọi hàm bằng một mô hình, bạn phải cung cấp khai báo hàm khi bạn khởi tạo đối tượng mô hình. Bạn khai báo các hàm bằng cách đặt tham số tools của mô hình:

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

Tạo lệnh gọi hàm

Sau khi khởi chạy mô hình bằng các nội dung khai báo hàm, bạn có thể nhắc mô hình bằng hàm đã xác định. Bạn nên sử dụng lệnh gọi hàm bằng lời nhắc trò chuyện (sendMessage()), vì lệnh gọi hàm thường có lợi khi có ngữ cảnh của các lời nhắc và phản hồi trước đó.

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)