Учебное пособие по вызову функций

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

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

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

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

Пример API для управления освещением

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

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

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

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

Прежде чем начать: настройте проект и ключ API.

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

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

Определить функцию API

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

suspend fun setLightValues(
    brightness: Int,
    colorTemp: String
): JSONObject {
    // This mock API returns the requested lighting values
    return JSONObject().apply {
        put("brightness", brightness)
        put("colorTemperature", colorTemp)
    }
}

Создание объявлений функций

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

val lightControlTool = defineFunction(
  name = "setLightValues",
  description = "Set the brightness and color temperature of a room light.",
  Schema.int("brightness", "Light level from 0 to 100. Zero is off and 100" +
    " is full brightness."),
  Schema.str("colorTemperature", "Color temperature of the light fixture" +
    " which can be `daylight`, `cool` or `warm`.")
) { brightness, colorTemp ->
    // Call the function you declared above
    setLightValues(brightness.toInt(), colorTemp)
}

Объявляйте функции во время инициализации модели

Если вы хотите использовать вызов функций с моделью, вы должны предоставить объявления функций при инициализации объекта модели. Вы объявляете функции, устанавливая параметр tools модели:

val generativeModel = GenerativeModel(
    modelName = "gemini-1.5-flash",

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

    // Specify the function declaration.
    tools = listOf(Tool(listOf(lightControlTool)))
)

Создать вызов функции

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

val chat = generativeModel.startChat()

val prompt = "Dim the lights so the room feels cozy and warm."

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