Учебное пособие. Вызов функций с помощью Gemini API

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

Вызов функций упрощает получение структурированных выходных данных из генеративных моделей. Затем вы можете использовать эти выходные данные для вызова других API и возврата соответствующих данных ответа в модель. Другими словами, вызов функций помогает подключить генеративные модели к внешним системам, чтобы сгенерированный контент содержал самую актуальную и точную информацию.

Вы можете предоставить модели Gemini описания функций. Это функции, которые вы пишете на языке вашего приложения (то есть они не являются функциями Google Cloud). Модель может попросить вас вызвать функцию и отправить результат обратно, чтобы помочь модели обработать ваш запрос.

Если вы еще этого не сделали, ознакомьтесь с разделом «Введение в вызов функций», чтобы узнать больше.

Настройте свой проект

Прежде чем вызывать API Gemini, вам необходимо настроить проект Android, который включает в себя настройку ключа API, добавление зависимостей SDK в проект Android и инициализацию модели.

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

Настройка вызова функции

В этом руководстве модель будет взаимодействовать с гипотетическим API обмена валюты, который поддерживает следующие параметры:

Пример запроса API

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

Пример ответа API

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

Шаг 1. Создайте функцию, которая выполняет запрос API.

Если вы еще этого не сделали, начните с создания функции, которая отправляет запрос к API.

В демонстрационных целях в этом руководстве вместо отправки фактического запроса API вы будете возвращать жестко запрограммированные значения в том же формате, который возвращал бы реальный API.

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

Шаг 2. Создайте объявление функции.

Создайте объявление функции, которое вы передадите в генеративную модель (следующий шаг этого руководства).

Включите как можно больше подробностей в описания функций и параметров. Генеративная модель использует эту информацию, чтобы определить, какую функцию выбрать и как предоставить значения параметров при вызове функции.

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

Шаг 3. Укажите объявление функции во время инициализации модели.

Укажите объявление функции при инициализации генеративной модели, передав его в параметр tools модели:

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

Шаг 4. Создайте вызов функции.

Теперь вы можете запросить модель с определенной функцией.

Рекомендуемый способ использования вызова функций — через интерфейс чата, поскольку вызовы функций хорошо вписываются в многоходовую структуру чата.

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