Как взаимодействовать с API с помощью вызова функций в Gemini

1. Обзор

Что такое вызов функций в Gemini?

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

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

Как работает вызов функций

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

Что ты построишь

В этой лабораторной работе вы создадите генеративный конвейер ИИ с помощью API Vertex AI Gemini и Python. Используя ваше приложение, пользователи могут спрашивать о курсах валют, а система будет получать последние данные из внешнего API и отвечать пользователю.

Что вы узнаете

• Как взаимодействовать с моделью Gemini с помощью клиентской библиотеки Python
• Как определить объявление функции и зарегистрировать его как инструмент
• Как вызвать Gemini и получить ответ на вызов функции
• Как вернуть ответ функции Gemini и ответить пользователю

Что вам понадобится

• Облачный проект Google
• Браузер, такой как Chrome
• Среда разработки Python, такая как Colab или Colab Enterprise.

2. Настройка и требования

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

Включить API Vertex AI

Чтобы включить Vertex AI API, выполните следующие действия:

1. В браузере перейдите на страницу сведений об услуге Vertex AI API .
2. Нажмите кнопку «Включить» , чтобы включить API Vertex AI в вашем проекте Google Cloud.

Установите клиентскую библиотеку Python для Vertex AI.

Чтобы установить клиентские библиотеки Python для Vertex AI, выполните следующие действия:

1. Откройте терминал в вашей среде разработки.
2. Убедитесь, что у вас есть действующая среда разработки Python, и при необходимости обратитесь к этим рекомендациям .
3. Выполните следующую команду, чтобы установить клиентскую библиотеку Python для Vertex AI:

   pip install --upgrade google-cloud-aiplatform
   

4. Если вы работаете в среде ноутбука, вам может потребоваться перезапустить среду выполнения/ядро, чтобы использовать вновь установленные пакеты.

Теперь вы готовы использовать API Vertex AI!

3. Поймите проблему

Вы когда-нибудь взаимодействовали с большой языковой моделью или генеративной моделью искусственного интеллекта и задавали ей вопросы о текущей или текущей информации только для того, чтобы получить ответ с устаревшей или неточной информацией?

Давайте попробуем сейчас! Сначала мы импортируем соответствующие пакеты Python и инициализируем модель Gemini. Вы можете запустить следующий код в среде разработки Python, такой как Colab или Colab Enterprise , и установив последнюю версию Vertex AI SDK для Python :

import vertexai
from vertexai.generative_models import GenerativeModel
model = GenerativeModel("gemini-1.5-pro-001")

Теперь зададимся вопросом о курсе разных валют на сегодняшний день:

response = model.generate_content(
    "What's the exchange rate for euros to dollars today?"
)
print(response.text)

Модель должна генерировать для вас ограниченный или устаревший ответ, подобный:

As an AI language model, I don't have access to real-time currency exchange
rates. However, as of my last update in September 2021, the approximate exchange
rate between euros (EUR) and US dollars (USD) was:

1 EUR ≈ 1.18 USD

Please note that currency exchange rates constantly fluctuate and can vary
depending on various factors such as economic conditions, supply and demand,
political events, and more. To obtain the most up-to-date and accurate exchange
rate, I recommend using a reliable currency converter or financial website that
provides live rates.

[...]

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

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

4. Попробуйте распространенные обходные пути

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

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

Давайте вернемся к вопросу, который мы задали в предыдущем разделе, и добавим несколько дополнительных инструкций для модели. Попробуйте отправить следующий запрос модели Gemini:

user_prompt = "What's the exchange rate from euros to US dollars today?"

response = model.generate_content("""
Your task is to extract parameters from the user's input and return it as a
structured JSON payload. The user will ask about the exchange rate and which
currency they are converting from and converting to.

User input: {user_prompt}

Please extract the currencies as parameters and put them in a JSON object.
""".format(user_prompt=user_prompt))
print(response.text)

Результатом является следующий текстовый ответ, который не является допустимым JSON и с которым нам будет сложно работать:

```json
{
  "currency_from": "euros",
  "currency_to": "US dollars"
}
```

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

Мы могли бы попытаться использовать Python для постобработки этого текста в действительный JSON и словарь, добавить дополнительные инструкции в приглашение, предоставить один или несколько примеров желаемого результата, точно настроить модель или сделать еще один вызов генеративной модели с вопросом это для очистки JSON.

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

5. Как работает вызов функций

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

Пользовательский ввод в Gemini API

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

Пользовательский ввод -> Gemini API -> Вызов функции

Gemini API возвращает вызов функции

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

Gemini API → Вызов функции

Сделать запрос API

Затем вы будете использовать имя и параметры функции, чтобы сделать запрос API для получения информации из внешней системы или API. Этот запрос и ответ API реализуется разработчиком в коде приложения и выходит за рамки Gemini API и SDK. Например, вы можете использовать библиотеку requests в Python для вызова REST API и получения ответа в формате JSON. Или вы можете вызвать функцию, используя предпочитаемый вами подход и клиентскую библиотеку.

Параметры API -> Внешний API -> Ответ API

Вернуть ответ API в Gemini

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

Ответ API -> Ответ функции -> Вывод модели

6. Выберите свой API

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

В нашем приложении обмена валюты мы будем использовать REST API по адресу https://www.frankfurter.app/ , чтобы получать самую свежую информацию о мировых обменных курсах.

Чтобы взаимодействовать с этим REST API, мы могли бы выполнить вызов REST API с requests на Python следующим образом:

import requests
url = "https://api.frankfurter.app/latest"
response = requests.get(url)
response.text

или запрос cURL , например:

curl https://api.frankfurter.app/latest

который возвращает ответ, подобный:

{
  "amount": 1,
  "base": "EUR",
  "date": "2023-12-20",
  "rates": {
    "AUD": 1.6186, "BGN": 1.9558, "BRL": 5.3287,
    "CAD": 1.4609, "CHF": 0.946, "CNY": 7.8121,
    "CZK": 24.538, "DKK": 7.4565, "GBP": 0.86555,
    "HKD": 8.5439, "HUF": 385.23, "IDR": 16994,
    "ILS": 3.9983, "INR": 91.06, "ISK": 150.3,
    "JPY": 157.12, "KRW": 1425.62, "MXN": 18.6867,
    "MYR": 5.0977, "NOK": 11.2895, "NZD": 1.7421,
    "PHP": 60.991, "PLN": 4.3413, "RON": 4.9699,
    "SEK": 11.129, "SGD": 1.4562, "THB": 38.252,
    "TRY": 31.883, "USD": 1.0944, "ZAR": 20.111
  }
}

Поскольку вызов функции в Gemini на самом деле не вызывает за вас вызов внешнего API, таких ограничений на тип API, который вы используете, нет! Вы можете использовать службу Cloud Run, облачную функцию, запрос API к облачной службе Google или любой внешний REST API.

7. Определите функцию и инструмент

Теперь, когда вы выбрали REST API для использования, мы можем определить спецификацию API и зарегистрировать функцию в инструменте.

Убедитесь, что вы установили последнюю версию Vertex AI SDK для Python .

Затем импортируйте необходимые модули из Python SDK и инициализируйте модель Gemini:

from vertexai.generative_models import (
    Content,
    FunctionDeclaration,
    GenerativeModel,
    Part,
    Tool,
)

model = GenerativeModel("gemini-1.5-pro-001")

Возвращаясь к REST API по адресу https://api.frankfurter.app/ , мы видим, что он принимает следующие входные параметры:

Параметр	Тип	Описание
from	Нить	Валюта для конвертации
to	Нить	Валюта для конвертации в
date	Нить	Дата получения обменного курса для

Используя эти параметры, частичная спецификация OpenAPI для этого REST API в формате YAML выглядит так:

openapi: 3.0.0
info:
  title: Frankfurter Exchange Rate API
  description: This API provides current and historical exchange rates
  version: 1.0.0
servers:
  - url: https://api.frankfurter.app
paths:
  /{date}:
    get:
      summary: Get the latest currency exchange rates.
      parameters:
        - name: date
          in: path
          description: Get currency rates for a specific date or 'latest' if a date is not specified
          required: true
          schema:
            type: string
        - name: from
          in: query
          description: The currency to convert from.
          required: true
          schema:
            type: string
        - name: to
          in: query
          description: The currency to convert to.
          schema:
            type: string

Теперь давайте зарегистрируем это как FunctionDeclaration , используя Python SDK для Gemini:

get_exchange_rate_func = FunctionDeclaration(
    name="get_exchange_rate",
    description="Get the exchange rate for currencies between countries",
    parameters={
    "type": "object",
    "properties": {
        "currency_date": {
            "type": "string",
            "description": "A date that must always be in YYYY-MM-DD format or the value 'latest' if a time period is not specified"
        },
        "currency_from": {
            "type": "string",
            "description": "The currency to convert from in ISO 4217 format"
        },
        "currency_to": {
            "type": "string",
            "description": "The currency to convert to in ISO 4217 format"
        }
    },
         "required": [
            "currency_from",
            "currency_date",
      ]
  },
)

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

Наконец, вы определите Tool , включающий объявление функции:

exchange_rate_tool = Tool(
    function_declarations=[get_exchange_rate_func],
)

Здесь вы используете одно объявление функции в инструменте, но учтите, что вы можете зарегистрировать в инструменте одно или несколько объявлений функций, и модель выберет подходящую функцию для использования во время выполнения. Обратитесь к документации по вызову функций в Gemini API для получения более подробной информации о FunctionDeclaration , Tool и связанных классах в Gemini SDK для Python.

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

8. Генерация вызова функции

Теперь вы можете запросить генеративную модель и включить определенный вами tool :

prompt = """What is the exchange rate from Australian dollars to Swedish krona?
How much is 500 Australian dollars worth in Swedish krona?"""

response = model.generate_content(
    prompt,
    tools=[exchange_rate_tool],
)

Давайте посмотрим на объект ответа:

print(response.candidates[0].content)

role: "model"
parts {
  function_call {
    name: "get_exchange_rate"
    args {
      fields {
        key: "currency_to"
        value {
          string_value: "SEK"
        }
      }
      fields {
        key: "currency_from"
        value {
          string_value: "AUD"
        }
      }
      fields {
        key: "currency_date"
        value {
          string_value: "latest"
        }
      }
    }
  }
}

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

В следующем разделе вы будете использовать информацию из ответа для выполнения запроса API.

9. Сделайте запрос API

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

Здесь вы будете использовать библиотеку requests на Python для вызова REST API обменного курса.

Давайте распакуем ответ в словарь Python:

params = {}
for key, value in response.candidates[0].content.parts[0].function_call.args.items():
    params[key[9:]] = value
params

Теперь мы можем вызывать requests или любой другой метод:

import requests
url = f"https://api.frankfurter.app/{params['date']}"
api_response = requests.get(url, params=params)
api_response.text

Что приводит к ответу, похожему на:

'{"amount":1.0,"base":"AUD","date":"2024-01-16","rates":{"SEK":6.8682}}'

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

10. Создайте ответ

Наконец, давайте сгенерируем ответ для пользователя, передав ответ функции модели в следующем раунде разговора:

response = model.generate_content(
    [
    Content(role="user", parts=[
        Part.from_text(prompt + """Give your answer in steps with lots of detail
            and context, including the exchange rate and date."""),
    ]),
    Content(role="function", parts=[
        Part.from_dict({
            "function_call": {
                "name": "get_exchange_rate",
            }
        })
    ]),
    Content(role="function", parts=[
        Part.from_function_response(
            name="get_exchange_rate",
            response={
                "content": api_response.text,
            }
        )
    ]),
    ],
    tools=[exchange_rate_tool],
)


response.candidates[0].content.parts[0].text

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

The exchange rate from Australian dollars to Swedish krona on January 16, 2024,
is 1 Australian dollar is equal to 6.8663 Swedish krona.

So, 500 Australian dollars would be worth 500 * 6.8663 = 3,433.15 Swedish krona.

11. Посмотреть полный пример кода

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

Вот полный пример кода для нашего окончательного решения:

import requests
from vertexai.generative_models import (
    Content,
    FunctionDeclaration,
    GenerativeModel,
    Part,
    Tool,
)

model = GenerativeModel("gemini-1.5-pro-001")

get_exchange_rate_func = FunctionDeclaration(
    name="get_exchange_rate",
    description="Get the exchange rate for currencies between countries",
    parameters={
    "type": "object",
    "properties": {
        "currency_date": {
            "type": "string",
            "description": "A date that must always be in YYYY-MM-DD format or the value 'latest' if a time period is not specified"
        },
        "currency_from": {
            "type": "string",
            "description": "The currency to convert from in ISO 4217 format"
        },
        "currency_to": {
            "type": "string",
            "description": "The currency to convert to in ISO 4217 format"
        }
    },
         "required": [
            "currency_from",
            "currency_date",
      ]
  },
)

exchange_rate_tool = Tool(
    function_declarations=[get_exchange_rate_func],
)

prompt = """What is the exchange rate from Australian dollars to Swedish krona?
How much is 500 Australian dollars worth in Swedish krona?"""

response = model.generate_content(
    prompt,
    tools=[exchange_rate_tool],
)

response.candidates[0].content

params = {}
for key, value in response.candidates[0].content.parts[0].function_call.args.items():
    params[key[9:]] = value
params

import requests
url = f"https://api.frankfurter.app/{params['date']}"
api_response = requests.get(url, params=params)
api_response.text

response = model.generate_content(
    [
    Content(role="user", parts=[
        Part.from_text(prompt + """Give your answer in steps with lots of detail
            and context, including the exchange rate and date."""),
    ]),
    Content(role="function", parts=[
        Part.from_dict({
            "function_call": {
                "name": "get_exchange_rate",
            }
        })
    ]),
    Content(role="function", parts=[
        Part.from_function_response(
            name="get_exchange_rate",
            response={
                "content": api_response.text,
            }
        )
    ]),
    ],
    tools=[exchange_rate_tool],
)


response.candidates[0].content.parts[0].text

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

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

12. Поздравления

Используя вызов функций в Gemini, вы успешно создали конвейер генеративного ИИ, который используется с API Vertex AI Gemini и Python! Пользователи могут спрашивать о курсах валют, и система получит последние данные из внешнего API и ответит.

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

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

Очистить

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

• Чтобы избежать ненужных расходов на Google Cloud, используйте консоль Google Cloud для удаления проекта, если он вам не нужен.
• Если вы хотите отключить API для Vertex AI, перейдите на страницу сведений об услуге Vertex AI API , нажмите « Отключить API» и подтвердите.

Узнать больше

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

• Обзор моделей Gemini
• Документация по вызову функций в Gemini
• Пример блокнота для вызова функций в Gemini
• Образцы тетрадей для Близнецов
• Генеративный искусственный интеллект в Google Cloud

Лицензия

Эта работа распространяется под лицензией Creative Commons Attribution 2.0 Generic License.