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 Android, bao gồm cả việc thiết lập khoá API, thêm các phần phụ thuộc SDK vào dự án Android và khởi chạy mô hình.

// Access your API key as a Build Configuration variable
val apiKey = BuildConfig.apiKey

val generativeModel = GenerativeModel(

    // Use a model that supports function calling, like Gemini 1.0 Pro.
    // See "Supported models" in the "Introduction to function calling" page.
    modelName = "MODEL_NAME",

    // Access your API key as a Build Configuration variable (see "Set up your API key" above).
    apiKey = BuildConfig.apiKey
)

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ề.

suspend fun makeApiRequest(
    currencyFrom: String,
    currencyTo: String
): JSONObject {
    // This hypothetical API returns a JSON such as:
    // {"base":"USD","rates":{"SEK": 0.091}}
    return JSONObject().apply {
        put("base", currencyFrom)
        put("rates", hashMapOf(currencyTo to 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.

val getExchangeRate = defineFunction(
  name = "getExchangeRate",
  description = "Get the exchange rate for currencies between countries",
  Schema.str("currencyFrom", "The currency to convert from."),
  Schema.str("currencyTo", "The currency to convert to.")
) { from, to ->
    // Call the function that you declared above
    makeApiRequest(from, to)
}

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 truyền mô hình đó vào tham số tools của mô hình:

val generativeModel = GenerativeModel(
  // Use a model that supports function calling, like Gemini 1.0 Pro
  // (see "Supported models" in the "Introduction to function calling" page)
  modelName = "gemini-1.0-pro",
  // Access your API key as a Build Configuration variable (see "Set up your API key" above)
  apiKey = BuildConfig.apiKey,
  // Specify the function declaration.
  tools = listOf(Tool(listOf(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.

val chat = generativeModel.startChat()

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

// Send the message to the generative model
var response = chat.sendMessage(prompt)

// Check if the model responded with a function call
response.functionCall?.let { functionCall ->
  // Try to retrieve the stored lambda from the model's tools and
  // throw an exception if the returned function was not declared
  val matchedFunction = generativeModel.tools?.flatMap { it.functionDeclarations }
      ?.first { it.name == functionCall.name }
      ?: throw InvalidStateException("Function not found: ${functionCall.name}")

  // Call the lambda retrieved above
  val apiResponse: JSONObject = matchedFunction.execute(functionCall)

  // Send the API response back to the generative model
  // so that it generates a text response that can be displayed to the user
  response = chat.sendMessage(
    content(role = "function") {
        part(FunctionResponsePart(functionCall.name, apiResponse))
    }
  )
}

// Whenever the model responds with text, show it in the UI
response.text?.let { modelResponse ->
    println(modelResponse)
}