Вызов функций с использованием API Gemini,Вызов функций с использованием API Gemini

iOS+ Android Веб- флаттер

Генеративные модели эффективны при решении многих типов проблем. Однако они ограничены такими ограничениями, как:

• Они замораживаются после обучения, что приводит к устаревшим знаниям.
• Они не могут запрашивать или изменять внешние данные.

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

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

Режим вызова функций поддерживается всеми моделями Gemini (кроме моделей Gemini 1.0 ).

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

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

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

3. Предоставьте объявление функции во время инициализации модели, чтобы модель знала, как она может использовать эту функцию, если это необходимо.

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

5. Передайте ответ функции обратно в модель, чтобы модель могла сгенерировать окончательный ответ.

Перейти к реализации кода

Обзор примера вызова функции

Отправляя запрос модели, вы также можете предоставить модели набор «инструментов» (например, функций), которые она может использовать для генерации окончательного ответа. Чтобы использовать эти функции и вызывать их («вызов функций»), модель и ваше приложение должны передавать информацию друг другу, поэтому рекомендуемый способ использования вызова функций — через многоповоротный интерфейс чата.

Представьте, что у вас есть приложение, в котором пользователь может ввести запрос типа: What was the weather in Boston on October 17, 2024? .

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

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

Параметр	Тип	Необходимый	Описание
Вход
location	Объект	Да	Название города и его штат, для которого можно узнать погоду. Поддерживаются только города США. Всегда должен быть вложенным объектом city и state .
date	Нить	Да	Дата, для которой нужно получить прогноз погоды (всегда должна быть в формате YYYY-MM-DD ).
Выход
temperature	Целое число	Да	Температура (в градусах Фаренгейта)
chancePrecipitation	Нить	Да	Вероятность осадков (выражена в процентах)
cloudConditions	Нить	Да	Облачность (одна из clear , partlyCloudy , mostlyCloudy , cloudy )

При инициализации модели вы сообщаете модели, что эта функция fetchWeather существует и как ее можно использовать для обработки входящих запросов, если это необходимо. Это называется «объявлением функции». Модель не вызывает функцию напрямую . Вместо этого, пока модель обрабатывает входящий запрос, она решает, может ли функция fetchWeather помочь ей ответить на запрос. Если модель решает, что функция действительно может быть полезна, она генерирует структурированные данные, которые помогут вашему приложению вызвать функцию .

Посмотрите еще раз на входящий запрос: What was the weather in Boston on October 17, 2024? . Модель, скорее всего, решит, что функция fetchWeather может помочь ей сгенерировать ответ. Модель будет смотреть, какие входные параметры необходимы для fetchWeather , а затем генерировать структурированные входные данные для функции, которая выглядит примерно так:

{
  functionName: fetchWeather,
  location: {
    city: Boston,
    state: Massachusetts  // the model can infer the state from the prompt
  },
  date: 2024-10-17
}

Модель передает эти структурированные входные данные в ваше приложение, чтобы ваше приложение могло вызвать функцию fetchWeather . Когда ваше приложение получает данные о погодных условиях от API, оно передает эту информацию в модель. Эта информация о погоде позволяет модели завершить окончательную обработку и сгенерировать ответ на первоначальный запрос « What was the weather in Boston on October 17, 2024?

Модель могла бы дать окончательный ответ на естественном языке, например: On October 17, 2024, in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

Реализация вызова функции

iOS+ Android Веб- флаттер

Прежде чем начать

Если вы еще этого не сделали, прочтите руководство по началу работы , в котором описывается, как настроить проект Firebase, подключить приложение к Firebase, добавить SDK, инициализировать службу Vertex AI и создать экземпляр GenerativeModel .

Остальные шаги в этом руководстве показывают, как реализовать настройку вызова функции, аналогичную рабочему процессу, описанному в разделе «Обзор примера вызова функции» (см. верхний раздел этой страницы).

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

Шаг 1 : Напишите функцию

Представьте, что у вас есть приложение, в котором пользователь может ввести запрос типа: What was the weather in Boston on October 17, 2024? . Модели Gemini могут не знать эту информацию о погоде; однако представьте, что вы знаете API внешнего метеорологического сервиса, который может его предоставить. Пример в этом руководстве основан на этом гипотетическом внешнем API.

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

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

// This function calls a hypothetical external API that returns
// a collection of weather information for a given location on a given date.
func fetchWeather(city: String, state: String, date: String) -> JSONObject {

  // TODO(developer): Write a standard function that would call an external weather API.

  // For demo purposes, this hypothetical response is hardcoded here in the expected format.
  return [
    "temperature": .number(38),
    "chancePrecipitation": .string("56%"),
    "cloudConditions": .string("partlyCloudy"),
  ]
}

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

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

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

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

Модель использует информацию в объявлении функции, чтобы определить, какую функцию выбрать и как предоставить значения параметров для фактического вызова функции. См. раздел «Дополнительные варианты поведения и параметры» ниже на этой странице, чтобы узнать, как модель может выбирать между функциями, а также как вы можете контролировать этот выбор.

Обратите внимание на следующую информацию о предоставленной вами схеме:

• Вы должны предоставить объявления функций в формате схемы, совместимом со схемой OpenAPI . Vertex AI предлагает ограниченную поддержку схемы OpenAPI.

  • Поддерживаются следующие атрибуты: type , nullable , required , format , description , properties , items , enum .

  • Следующие атрибуты не поддерживаются: default , optional , maximum , oneOf .

• По умолчанию для Vertex AI в Firebase SDK все поля считаются обязательными , если вы не укажете их как необязательные в массиве optionalProperties . Для этих необязательных полей модель может заполнять поля или пропускать их. Обратите внимание, что это противоположно поведению по умолчанию для API Vertex AI Gemini .

Рекомендации по использованию объявлений функций, включая советы по именам и описаниям, см. в разделе «Рекомендации» документации Google Cloud .

Вот как вы можете написать объявление функции:

let fetchWeatherTool = FunctionDeclaration(
  name: "fetchWeather",
  description: "Get the weather conditions for a specific city on a specific date.",
  parameters: [
    "location": .object(
      properties: [
        "city": .string(description: "The city of the location."),
        "state": .string(description: "The US state of the location."),
      ],
      description: """
      The name of the city and its state for which to get the weather. Only cities in the
      USA are supported.
      """
    ),
    "date": .string(
      description: """
      The date for which to get the weather. Date must be in the format: YYYY-MM-DD.
      """
    ),
  ]
)

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

Примечание. И Gemini 1.0 Pro, и Gemini 1.5 Pro поддерживают вызов функций. Принимая решение о том, какую модель использовать, обязательно ознакомьтесь с квотами для каждой модели .

Максимальное количество объявлений функций, которые вы можете предоставить вместе с запросом, — 128. См. раздел «Дополнительные варианты поведения и параметры» ниже на этой странице, чтобы узнать, как модель может выбирать между функциями, а также как вы можете контролировать этот выбор (с помощью toolConfig для установки режима вызова функции ).

import FirebaseVertexAI

// Initialize the Vertex AI service and the generative model.
let model = VertexAI.vertexAI().generativeModel(
  modelName: "gemini-2.0-flash",
  // Provide the function declaration to the model.
  tools: [.functionDeclarations([fetchWeatherTool])]
)

Узнайте, как выбрать модель и, при необходимости, местоположение, подходящее для вашего варианта использования и приложения.

Шаг 4. Вызовите функцию для вызова внешнего API.

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

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

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

В этом примере входящий запрос содержал подсказку What was the weather in Boston on October 17, 2024? . Из этого приглашения модель вывела входные параметры, необходимые для функции fetchWeather (то есть city , state и date ).

let chat = model.startChat()
let prompt = "What was the weather in Boston on October 17, 2024?"

// Send the user's question (the prompt) to the model using multi-turn chat.
let response = try await chat.sendMessage(prompt)

var functionResponses = [FunctionResponsePart]()

// When the model responds with one or more function calls, invoke the function(s).
for functionCall in response.functionCalls {
  if functionCall.name == "fetchWeather" {
    // TODO(developer): Handle invalid arguments.
    guard case let .object(location) = functionCall.args["location"] else { fatalError() }
    guard case let .string(city) = location["city"] else { fatalError() }
    guard case let .string(state) = location["state"] else { fatalError() }
    guard case let .string(date) = functionCall.args["date"] else { fatalError() }

    functionResponses.append(FunctionResponsePart(
      name: functionCall.name,
      // Forward the structured input data prepared by the model
      // to the hypothetical external API.
      response: fetchWeather(city: city, state: state, date: date)
    ))
  }
  // TODO(developer): Handle other potential function calls, if any.
}

Шаг 5. Предоставьте выходные данные функции модели для генерации окончательного ответа.

После того как функция fetchWeather вернет информацию о погоде, вашему приложению необходимо передать ее обратно в модель.

Затем модель выполняет окончательную обработку и генерирует окончательный ответ на естественном языке, например: On October 17, 2024 in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

// Send the response(s) from the function back to the model
// so that the model can use it to generate its final response.
let finalResponse = try await chat.sendMessage(
  [ModelContent(role: "function", parts: functionResponses)]
)

// Log the text response.
print(finalResponse.text ?? "No text in response.")

Дополнительные варианты поведения и параметры

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

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

Если ответа от одного вызова функции недостаточно для того, чтобы модель сгенерировала окончательный ответ, модель может запросить дополнительный вызов функции или запросить вызов совершенно другой функции. Последнее может произойти только в том случае, если вы предоставите модели более одной функции в списке объявлений функций.

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

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

Вы можете предоставить модели до 128 функций в списке объявлений функций. Учитывая это, модель может решить, что необходимо несколько функций, чтобы помочь ей сгенерировать окончательный ответ. И он может решить вызвать некоторые из этих функций одновременно — это называется вызовом параллельных функций .

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

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

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

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

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

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

Режим	Описание
AUTO	Поведение модели по умолчанию. Модель решает, использовать ли вызов функции или ответ на естественном языке.
ANY	Модель должна использовать вызовы функций («принудительный вызов функций»). Чтобы ограничить модель подмножеством функций, укажите разрешенные имена функций в allowedFunctionNames .
NONE	Модель не должна использовать вызовы функций. Такое поведение эквивалентно запросу модели без каких-либо связанных объявлений функций.

Что еще вы можете сделать?

Попробуйте другие возможности

• Стройте многоходовые разговоры (чат) .
• Генерация текста из текстовых подсказок .
• Генерируйте текст из мультимодальных подсказок (включая текст, изображения, PDF-файлы, видео и аудио).

Узнайте, как контролировать создание контента

• Понимание структуры подсказок , включая лучшие практики, стратегии и примеры подсказок.
• Настройте параметры модели , такие как температура и токены максимальной выходной мощности (для Gemini ) или соотношение сторон и поколение людей (для Imagen ).
• Используйте настройки безопасности , чтобы настроить вероятность получения ответов, которые могут быть расценены как вредные.

Вы также можете поэкспериментировать с подсказками и конфигурациями модели с помощью Vertex AI Studio .

Узнайте больше о поддерживаемых моделях

Узнайте о моделях, доступных для различных вариантов использования , а также об их квотах и ​​ценах .

Оставьте отзыв о своем опыте использования Vertex AI в Firebase.