1. Обзор
Что такое вызов функции в Gemini?
API Vertex AI Gemini — это семейство генеративных моделей искусственного интеллекта, разработанных Google DeepMind и предназначенных для многомодальных сценариев использования. Функция вызова функций в моделях Gemini упрощает разработчикам получение структурированных данных из генеративных моделей.
Затем разработчики могут использовать эти выходные данные для вызова других API и возврата соответствующих данных модели. Другими словами, вызов функций помогает связать ваши генеративные модели с внешними системами, чтобы сгенерированный контент содержал самую актуальную и точную информацию.
Как работает вызов функций
Функции описываются с помощью объявлений функций, что помогает генеративной модели понять назначение и параметры функции. После передачи объявлений функций в запросе генеративной модели, модель возвращает структурированный объект, содержащий имена соответствующих функций и их аргументы в зависимости от запроса пользователя. Обратите внимание, что при вызове функции модель фактически не вызывает саму функцию. Вместо этого вы можете использовать возвращенную функцию и параметры для вызова функции в любом языке программирования, библиотеке или фреймворке по вашему выбору!
Что вы построите
В этом практическом занятии вы создадите конвейер генеративного ИИ с использованием API Vertex AI Gemini и Python. С помощью вашего приложения пользователи смогут запрашивать информацию об обменных курсах, а система будет получать последние данные из внешнего API и отправлять пользователю ответ.
Что вы узнаете
- Как взаимодействовать с моделью Gemini с помощью клиентской библиотеки Python.
- Как определить объявление функции и зарегистрировать её в качестве инструмента.
- Как вызвать Gemini и получить ответ от вызова функции
- Как вернуть ответ функции в Gemini и ответить пользователю?
Что вам понадобится
- Проект Google Cloud
- Браузер, например, Chrome
- Среда разработки Python, такая как Colab или Colab Enterprise.
2. Настройка и требования
Прежде чем начать использовать вызовы функций в Gemini, необходимо включить API Vertex AI и установить последнюю версию клиентской библиотеки Vertex AI для Python.
Включить API Vertex AI
Чтобы активировать API Vertex AI, выполните следующие действия:
- В браузере перейдите на страницу с подробной информацией о сервисе Vertex AI API .
- Нажмите кнопку «Включить» , чтобы активировать API Vertex AI в вашем проекте Google Cloud.
Установите клиентскую библиотеку Python для Vertex AI.
Для установки клиентских библиотек Python для Vertex AI выполните следующие действия:
- Откройте терминал в среде разработки.
- Убедитесь, что у вас установлена корректная среда разработки Python, и при необходимости обратитесь к этим рекомендациям .
- Выполните следующую команду, чтобы установить клиентскую библиотеку Python для Vertex AI:
pip install --upgrade google-cloud-aiplatform - Если вы работаете в среде ноутбука, вам может потребоваться перезапустить среду выполнения/ядро, чтобы использовать недавно установленные пакеты.
Теперь вы готовы использовать 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. Как работает вызов функций
Прежде чем приступить к извлечению параметров и вызову функций, давайте рассмотрим этапы вызова функций и компоненты, используемые во время выполнения.
Ввод данных пользователем в API Gemini
Запрос от пользователя отправляется в API Gemini, и в этом вызове API к модели Gemini разработчик определяет одно или несколько объявлений функций в инструменте, чтобы модель Gemini знала, какие функции она может вызывать и как это делать.
API Gemini возвращает вызов функции.
На основе введенных пользователем данных и запроса Gemini вернет ответ в виде вызова функции со структурированными данными, включающими имя вызываемой функции и соответствующие параметры для использования.
Выполните API-запрос
Затем вы используете имя функции и параметры для выполнения запроса к API с целью получения информации из внешней системы или API. Этот запрос и ответ к API реализуются разработчиком в коде приложения и происходят вне области действия API и SDK Gemini. Например, вы можете использовать библиотеку requests в Python для вызова REST API и получения ответа в формате JSON. Или вы можете вызвать функцию, используя предпочитаемый вами подход и клиентскую библиотеку.
Верните ответ API в Gemini.
Наконец, вы передадите ответ API обратно модели Gemini, чтобы она могла сгенерировать ответ на первоначальный запрос конечного пользователя или вызвать другой ответ функции, если модель Gemini определит, что ей необходима дополнительная информация.
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 Service, Cloud Function, запрос API к сервису Google Cloud или любой внешний 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/ , мы видим, что он принимает следующие входные параметры:
Параметр | Тип | Описание |
| Нить | Валюта для конвертации |
| Нить | Валюта для конвертации |
| Нить | Дата для получения обменного курса |
Используя эти параметры, частичная спецификация 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],
)
Здесь вы используете одно объявление функции внутри инструмента, но обратите внимание, что вы можете зарегистрировать одно или несколько объявлений функций в инструменте, и модель выберет соответствующую функцию для использования во время выполнения. Для получения более подробной информации о классах FunctionDeclaration , Tool и связанных с ними классах в Gemini SDK для Python обратитесь к документации по вызову функций в API Gemini .
Вы завершили настройку определений функций и инструментов. В следующем разделе мы вызовем генеративную модель с помощью этого инструмента и получим в ответ вызов функции, которую мы сможем использовать для вызова 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, Cloud Function или другой облачный сервис, и развернуть фронтенд-приложение, которое будет использовать этот бэкэнд-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 и подсказками в вашем конвейере и изучать другие возможности, доступные в API Vertex AI Gemini .
Уборка
Чтобы избежать списания средств с вашего аккаунта Google Cloud за ресурсы, использованные в этом практическом задании, вы можете выполнить следующую очистку:
- Чтобы избежать ненужных расходов на Google Cloud, используйте консоль Google Cloud для удаления проекта, если он вам не нужен.
- Чтобы отключить API для Vertex AI, перейдите на страницу с подробными сведениями о службе API Vertex AI , нажмите «Отключить API» и подтвердите действие.
Узнать больше
Продолжите изучение разговорного и генеративного искусственного интеллекта с помощью этих руководств и ресурсов:
- Обзор моделей Gemini
- Документация по вызову функций в Gemini
- Пример блокнота для вызова функций в Gemini.
- Примеры блокнотов для Близнецов
- Генеративный ИИ в облаке Google
Лицензия
Данная работа распространяется под лицензией Creative Commons Attribution 2.0 Generic.