ym88659208ym87991671
Работа с функциями | Документация для разработчиков

Функции позволяют расширить функциональность GigaChat с помощью использования сторонних инструментов.

GigaChat поддерживает два вида функций:

  • пользовательские — функции, которые вы реализуете и исполняете самостоятельно. Модель автоматически определяет необходимость вызова функции на основе ее описания. Для таких функций модель может сгенерировать объект с данными в подходящем вам формате, после чего вы сможете использовать их для дальнейших преобразований;
  • встроенные — функции, которые модель использует для выполнения различных задач, например, генерации изображений. Функции исполняются внутри сервиса.

Для доступа к модели с поддержкой функций в поле "model" передавайте GigaChat-Pro, GigaChat-preview или GigaChat-Plus-preview.

Подробнее о моделях — в разделе Модели GigaChat.

Для работы с функциями используется запрос POST /chat/completions. А именно — необязательное поле function_call, которое задает режим работы с функциями и может принимать значения:

  • "none" — режим работы по умолчанию.

    Если запрос не содержит поля function_call или значение поля — none, модель не будет вызывать функции (в том числе встроенные), а просто сгенерирует ответ в соотвествии с полученными сообщениями.

  • "auto" — в зависимости от содержимого запроса, модель решает что нужно сделать: вызывать встроенные функции, сгенерировать аргументы для исполнения пользовательской функции или просто сгенерировать сообщение.

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

    Если запрос содержит "function_call": "auto" и массив functions с описанием пользовательских функций, модель будет генерировать аргументы для описанных функций и не сможет вызвать встроенные функции независимо от содержимого запроса;

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

Работа с пользовательскими функциями

Функция, использованная для примера, возвращает данные о температуре в зависимости от аргументов, полученных на входе:

  • места, для которого запрашивается погода;
  • единиц измерения температуры;
  • периода в днях, которому должны соответствовать данные о температуре.

Описание функции

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

{
"name": "weather_forecast",
"description": "Возвращает температуру на заданный период",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"format": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
],
"description": "Единицы изменерия температуры"
},
"num_days": {
"type": "integer",
"description": "Период, для которого нужно вернуть"
}
},
"required": [
"location",
"num_days"
]
}
}

Для улучшения генерации аргументов в описании функции вы также можете передать:

  • few_shot_examples — массив с примерами запросов пользователя и ответов модели;
  • return_parameters — объект с описанием данных в формате JSON Schema, которые возвращает функция.

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

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

{
"name": "weather_forecast",
"description": "Возвращает температуру на заданный период",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"format": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
],
"description": "Единицы изменерия температуры"
},
"num_days": {
"type": "integer",
"description": "Период, для которого нужно вернуть"
}
},
"required": [
"location",
"num_days"
]
},
"few_shot_examples": [
{
"request": "Какая погода в Москве в ближайшие три дня",
"params": {
"location": "Moscow, Russia",
"format": "celsius",
"num_days": "3"
}
}
],
"return_parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"temperature": {
"type": "integer",
"description": "Температура для заданного местоположения"
},
"forecast": {
"type": "array",
"items": {
"type": "string"
},
"description": "Описание погодных условий"
},
"error": {
"type": "string",
"description": "Возвращается при возникновении ошибки. Содержит описание ошибки"
}
}
}
}

Примеры описания функций

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

Функция расчета расстояния
{
"name": "calculate_trip_distance",
"description": "Рассчитать расстояние между двумя местоположениями",
"parameters": {
"type": "object",
"properties": {
"start_location": {
"type": "string",
"description": "Начальное местоположение"
},
"end_location": {
"type": "string",
"description": "Конечное местоположение"
}
},
"required": [
"start_location",
"end_location"
]
},
"return_parameters": {
"type": "object",
"properties": {
"distance": {
"description": "Расстояние между начальным и конечным местоположением в километрах",
"type": "integer"
}
},
"required": [
"distance"
]
},
"few_shot_examples": [
{
"request": "Насколько далеко от Москвы до Санкт-Петербурга?",
"params": {
"start_location": "Москва",
"end_location": "Санкт-Петербург"
}
}
]
}
Функция отправки SMS-сообщения
{
"name": "send_sms",
"description": "Отправить SMS-сообщение",
"parameters": {
"type": "object",
"properties": {
"recipient": {
"type": "string",
"description": "Номер телефона получателя"
},
"message": {
"type": "string",
"description": "Содержимое сообщения"
}
},
"required": [
"recipient",
"message"
]
},
"return_parameters": {
"type": "object",
"properties": {
"status": {
"description": "Статус отправки сообщения",
"type": "string"
},
"message": {
"description": "Сообщение о результате отправки SMS",
"type": "string"
}
},
"required": [
"status",
"message"
]
},
"few_shot_examples": [
{
"request": "Можешь ли ты отправить SMS-сообщение на номер 123456789 с содержимым 'Привет, как дела?'",
"params": {
"recipient": "123456789",
"message": "Привет, как дела?"
}
}
]
}
Функция поиска фильмов
{
"name": "search_movies",
"description": "Поиск фильмов на основе заданных критериев",
"parameters": {
"type": "object",
"properties": {
"genre": {
"type": "string",
"description": "Жанр фильма"
},
"year": {
"type": "integer",
"description": "Год выпуска фильма"
},
"actor": {
"type": "string",
"description": "Имя актера, снимавшегося в фильме"
}
},
"required": []
},
"return_parameters": {
"type": "object",
"properties": {
"movies": {
"description": "Список названий фильмов, соответствующих заданным критериям поиска",
"type": "array",
"items": {
"description": "Название фильма",
"type": "string"
}
}
},
"required": [
"movies"
]
},
"few_shot_examples": [
{
"request": "\"Найди все фильмы жанра комедия\".",
"params": {
"genre": "комедия"
}
}
]
}

Генерация аргументов

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

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

В этом режиме модель анализирует полученные сообщения (массив messages) и сама решает нужно использовать функции или нет.

Для работы в автоматическом режиме передавайте в запросе поле "function_call": "auto":

{
"model": "GigaChat",
"messages": [
{
"role": "user",
"content": "Погода в Москве на три дня"
}
],
"function_call": "auto",
"functions": [
{
"name": "weather_forecast",
"description": "Возвращает температуру на заданный период",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"format": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
],
"description": "Единицы изменерия температуры"
},
"num_days": {
"type": "integer",
"description": "Период, для которого нужно вернуть прогноз"
}
},
"required": [
"location",
"num_days"
]
}
}
],
}

При этом работа модели зависит от того содержит массив functions описание пользовательских функций или нет:

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

Ответ модели

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

{
"choices": [
{
"message": {
"role": "assistant",
"content": "",
"function_call": {
"name": "weather_forecast",
"arguments": {
"location": "Москва",
"format": "celsius"
}
}
},
"index": 0,
"finish_reason": "function_call"
}
],
"created": 1700471392,
"model": "GigaChat",
"usage": {
"prompt_tokens": 150,
"completion_tokens": 35,
"total_tokens": 185
},
"object": "chat.completion"
}

Передача ответа функции в модель

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

Для этого используйте сообщение с ролью function в контексте диалога (массив messages):

{
"model": "GigaChat",
"messages": [
{
"role": "user",
"content": "Какая погода в Москве сегодня?"
},
{
"role": "assistant",
"content": "",
"function_call": {
"name": "weather_forecast",
"arguments": {
"location": "Москва",
"format": "celsius"
}
}
},
{
"role": "function",
"content": "{\"temperature\": \"27\"}",
"name": "weather_forecast"
}
],
"functions": [
{
"name": "weather_forecast",
"description": "Возвращает температуру на заданный период",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"format": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
],
"description": "Единицы изменерия температуры"
},
"num_days": {
"type": "integer",
"description": "Период, для которого нужно вернуть прогноз"
}
},
"required": [
"location",
"num_days"
]
}
},
],
}

Подробнее о работе с контекстом диалога — в разделе Работа с историей чата.

Потоковая генерация аргументов

При генерации аргументов в потоковом режиме ("stream": true) название функции (function_call.name) и ее аргументы всегда передаются в одной порции:

data: {"choices":[{"delta":{"content":"Мне нужно посмотреть погоду в Москве","role":"assistant"},"index":0}],"created":1698850241,"model":"GigaChat","object":"chat.completion","usage":{"completion_tokens":50,"prompt_tokens":152,"total_tokens":202}}

data: {"choices":[{"delta":{"content":" на"},"index":0}],"created":1698850241,"model":"GigaChat","object":"chat.completion","usage":{"completion_tokens":1,"prompt_tokens":0,"total_tokens":1}}

data: {"choices":[{"delta":{"content":" завтра"},"index":0}],"created":1698850241,"model":"GigaChat","object":"chat.completion","usage":{"completion_tokens":1,"prompt_tokens":0,"total_tokens":1}}

data: {"choices":[{"delta":{"function_call": {"name": "weather_forecast", "arguments": {"location": "Moscow","num_days": 1}}},"index":0}],"created":1698850241,"model":"GigaChat","object":"chat.completion","usage":{"completion_tokens":1,"prompt_tokens":0,"total_tokens":1}}

data: {"choices":[{"delta":{},"finish_reason":"function_call","index":0}],"created":1698850241,"model":"GigaChat","object":"chat.completion","usage":{"completion_tokens":1,"prompt_tokens":0,"total_tokens":1}}

data: [DONE]

Вызов встроенных функций

GigaChat поддерживает встроенные функции, например, для генерации изображений. Встроенные функции вызываются только в автоматическом режиме ("function_call": "auto") на основе запроса пользователя.

При вызове встроенных функций модель возвращает ответ с результатом "finish_reason": "stop".

Пример запроса на генерацию изображения:

curl -L -X POST 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <токен_доступа>' \
--data-raw '{
"model": "GigaChat",
"messages": [
{
"role": "system",
"content": "Ты — Василий Кандинский"
},
{
"role": "user",
"content": "Нарисуй розового кота"
}
],
"function_call": "auto",
}'

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

{
"choices": [
{
"message": {
"content": "Запускаю генерацию изображения. Ожидайте результат <img src=\"b28fbd4f-105a-43e0-ba5a-2faa80b1f43c\" fuse=\"true\"/> - вот розовый кот, который у меня получился.",
"role": "assistant",
"data_for_context": [
{
"content": "Запускаю генерацию изображения. Ожидайте результат",
"role": "assistant",
"function_call": {
"name": "text2image",
"arguments": {
"query": "pink cat, cartoon, colorful, drawing"
}
}
},
{
"content": "{\"status\":\"success\"}",
"role": "function",
"name": "text2image"
},
{
"content": " - вот розовый кот, который у меня получился.",
"role": "assistant"
}
]
},
"index": 0,
"finish_reason": "stop"
}
],
"created": 1716367703,
"model": "GigaChat:3.1.25.3",
"object": "chat.completion",
"usage": {
"prompt_tokens": 372,
"completion_tokens": 48,
"total_tokens": 420
}
}

Массив data_for_context содержит сообщения для работы модели в правильном контексте.

Сохранение контекста

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

{
"messages": [
{
"role": "user",
"content": "Нарисуй розового кота"
},
{
"role": "assistant",
"content": "Запускаю генерацию изображения. Ожидайте результат <img src=\"b28fbd4f-105a-43e0-ba5a-2faa80b1f43c\" fuse=\"true\"/> - вот розовый кот, который у меня получился.",
"data_for_context": [
{
"content": "Запускаю генерацию изображения. Ожидайте результат",
"role": "assistant",
"function_call": {
"name": "text2image",
"arguments": {
"query": "pink cat, cartoon, colorful, drawing"
}
}
},
{
"content": "{\"status\":\"success\"}",
"role": "function",
"name": "text2image"
},
{
"content": " - вот розовый кот, который у меня получился.",
"role": "assistant"
}
]
},
{
"role": "user",
"content": "Дорисуй ему крылья"
}
],
"model": "GigaChat"
}

Потоковая передача токенов

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

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

curl -L -X POST 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <токен_доступа>' \
--data-raw '{
"model": "GigaChat",
"messages": [
{
"role": "system",
"content": "Ты — Василий Кандинский"
},
{
"role": "user",
"content": "Нарисуй розового кота"
}
],
"function_call": "auto",
"stream": true,
}'

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

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

{
"choices":
[
{
"delta":
{
"content": "ready estimation seconds: 100",
"role": "function_in_progress"
},
"index": 0
}
]
}

Смотрите также

ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.