Описание пользовательских функций
Обновлено 4 августа 2025
Чтобы модель могла сгенерировать аргументы для вашей функции, опишите ее в формате JSON Schema , и передайте описание в массиве functions, в запросе POST /chat/completions.
При принятии решения о генерации аргументов модель ориентируется на описание функции в поле description.
Чем подробнее описана функция, тем лучше будет результат работы модели при работе с ней.
Пример описания функции прогноза погоды:
{
"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"
]
},
"return_parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"temperature": {
"type": "integer",
"description": "Температура для заданного местоположения"
},
"forecast": {
"type": "array",
"items": {
"type": "string"
},
"description": "Описание погодных условий"
},
"error": {
"type": "string",
"description": "Возвращается при возникновении ошибки. Содержит описание ошибки"
}
}
},
"status": {
"description": "Статус",
"enum": [
"success",
"fail"
],
"type": "string"
}
}
Описание функции включает поля:
-
name— обязательное поле с названием функции; -
description— подробное текстовое описание того, как работает функция. Модель анализирует запрос и доступные описания, после чего принимает решение о генерации параметров для подходящей функции. -
parameters— обязательное поле. Содержит массив с описанием аргументов функции, которые может сгенерировать модель. -
few_shot_examples— массив, в котором вы можете описать примеры того, как модель должна сгенерировать аргументы. Наличие примеров повышает качество генерации аргументов. -
return_parameters— объект с описанием ответа, который модель будет ожидать в ответе от функции.Хотя поле
return_parameters— необязательное, его использование помогает моделям лучше генерировать аргументы для пользовательских функций.
Описание результата работы функции
С помощью объекта return_parameters можно явно указать какие поля должен содержать результат работы функции.
Описанные поля нужно передать в модель при следующем запросе.
{
"return_parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Местоположение, например, название города"
},
"temperature": {
"type": "integer",
"description": "Температура для заданного местоположения"
},
"forecast": {
"type": "array",
"items": {
"type": "string"
},
"description": "Описание погодных условий"
},
"error": {
"type": "string",
"description": "Возвращается при возникновении ошибки. Содержит описание ошибки"
}
}
}
}
Использование примеров
Для повышения качества генерации в описании функции можно передать примеры аргументов, которые ожидаются от модели.
Для этого используйте поле few_shot_examples — массив объектов, каждый из которых содержит запрос пользователя (поле request) и аргументы, сгенерированные на его основе (объект params).
Пример описания блоков few_shot_examples и return_parameters:
{
"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": "Возвращается при возникновении ошибки. Содержит описание ошибки"
}
}
}
}
Составные функции
Модели GigaChat могут использовать результаты работы одних функций для вызова других. Функции, которые работают таким образом, называются составными.
О такой возможности нужно сообщать в описании соответствующих функций. В остальном составные функции описываются так же, как и обычные.
Ниже — пример нескольких функций, в описании которых заданы инстру кции для модели. Согласно этим инструкциям при недостатке данных модель должна самостоятельно обратиться к соответствующей функции, которая может дать недостающие данные.
{
"name": "get_reminder",
"description": "Получить метаинформацию обо всех установленных напоминаниях. Вызови эту функцию перед удалением или изменением напоминаний, чтобы получить ID напоминаний. В случае, если пользователь хочет удалить или изменить напоминание и в контексте диалога нет необходимых ID, то сначала вызови эту функцию для получения идентификатора ID и ответь пустым сообщением, а далее, при необходимости, вызови следующую функцию для выполнения запроса пользователя.\nПосле вызова данной функции ответь пользователю в следующем стиле: \"У вас установлено 2 напоминания. Через 10 минут выключить духовку на кухне, а завтра в 3 часа сходить в гости.\"",
"parameters": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Текст напоминания"
},
"date_time": {
"type": "string",
"description": "Относительное время и дата напоминания на русском языке"
},
"device_name": {
"type": "string",
"description": "Название устройства, на котором следует проверить напоминание"
},
"room": {
"type": "string",
"description": "Название комнаты в которой следует проверить напоминание"
}
},
"required": []
},
"few_shot_examples": [
{
"request": "Мои напоминания",
"params": {}
},
{
"request": "Удали напоминалку на завтра в пять",
"params": {}
},
{
"request": "Перенеси напоминание поздравить маму на шесть вечера",
"params": {}
},
{
"request": "Какое у меня количество напоминаний",
"params": {}
},
{
"request": "Озвучь напоминалки",
"params": {}
}
],
"return_parameters": {
"type": "object",
"description": "Ответ на get_reminder",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"fail"
],
"description": "Статус — удалось ли найти список установленных напоминаний"
},
"error": {
"type": "string",
"description": "Текст ошибки в случае, если status == fail"
},
"items": {
"type": "array",
"description": "Список установленных напоминаний. В списке перечислены идентификаторы напоминаний (ID), дата и время старта напоминания (reminderTime), периодичность напоминания в человекочитаемом формате (cron), название напоминания (title), дата и время создания напоминания (createdAt).",
"items": {
"type": "object",
"description": "Метаинформация напоминания.",
"properties": {
"id": {
"type": "string",
"description": "Идентификатор напоминания."
},
"cron": {
"type": "string",
"description": "Описание периодичности напоминания. Здесь будет передано человекочитаемое описание переодичности напоминания. Если поле отсутствует, то у напоминания нет периодичности (единоразовое)."
},
"title": {
"type": "string",
"description": "Название напоминания, о чем надо напомнить."
},
"devices": {
"type": "array",
"description": "Словарь устройств, к которым привязаны напоминания",
"items": {
"type": "string",
"description": "Название устройства"
}
},
"reminderTime": {
"type": "string",
"description": "Дата и время старта напоминания."
},
"createdAt": {
"type": "string",
"description": "Дата и время создания напоминания."
}
}
}
}
},
"required": [
"status"
]
}
}
{
"name": "delete_reminder",
"description": "Удалить напоминания по ID. Если пользователь явно не передал ID напоминания, то получи метаинформацию о напоминаниях, вызвав сначала соответствующую функцию, и только затем используй функцию удаления напоминания по ID.\nЕсли в контексте беседы с пользователем у тебя есть необходимый ID, то перед запуском этой функции тебе необходимо переспросить пользователя, точно ли он хочет удалить данное напоминание и только после согласия удалять. Если пользователь просит удалить все напоминания и в контексте диалога есть необходимые ID или пользователь явно передает ID напоминания, которое надо удалить, то вызови эту функцию, переспрашивать пользователя не нужно. В остальных случаях, при наличии необходимых ID в контексте диалога и готовности удалить напоминание, сначала переспроси пользователя, подтверждает ли он удаление напоминания и вызывай функцию только при наличии подтверждения от пользователя.",
"parameters": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string",
"description": "Идентификатор ID напоминания, которое нужно удалить"
},
"description": "Список идентификаторов ID напоминаний, которые нужно удалить"
}
},
"required": [
"ids"
]
},
"few_shot_examples": [],
"return_parameters": {
"type": "object",
"description": "Ответ на delete_reminder",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"fail"
],
"description": "Статус — удалось ли удалить напоминание."
},
"error": {
"type": "string",
"description": "Текст ошибки в случае, если status == fail"
}
},
"required": [
"status"
]
}
}
{
"name": "change_reminder",
"description": "Изменить напоминание по ID.\nЕсли пользователь просит изменить напоминание, но не указывает какое и какие изменения надо внести, то в ответе попроси предоставить дополнительную информацию.\nЕсли просит изменить напоминание и не указывает какое, но указывает какие изменения внести, то сначала получи метаинформацию о напоминаниях, вызвав нужную функцию, перечисли их в ответе и уточни, какое из них изменить.\nЕсли просит изменить напоминание, указывая какое, но не указывая изменения, то сначала получи метаинформацию обо всех напоминаниях, вызвав нужную функцию, перечисли их в ответе и при наличии ID, соответствующего запросу, уточни какие изменения надо внести.\nЕсли просит изменить напоминание, указывая какое и какие изменения внести, то получи метаинформацию обо всех напоминаниях, вызвав нужную функцию, и при наличии ID, соответствующего запросу пользователя, вызови функцию изменения напоминания по ID.\n\nВызывай данную функцию только при наличии нужного ID и информации о том, как надо изменить напоминание.",
"parameters": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID напоминания"
},
"title": {
"type": "string",
"description": "Новый текст напоминания"
},
"date_time": {
"type": "string",
"description": "Новые время и дата напоминания на ру сском языке. Передай только то, что сказал пользователь, не меняя формат."
},
"device_name": {
"type": "string",
"description": "Новое название устройства, на которое следует поставить напоминание"
}
},
"required": [
"id"
]
},
"few_shot_examples": [
{
"request": "Изменить напоминание с ID 123 на сегодня в 19 30",
"params": {
"id": "123",
"date_time": "сегодня в 19 30"
}
}
],
"return_parameters": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"fail"
],
"description": "Статус — удалось ли изменить напоминание."
},
"error": {
"type": "string",
"description": "Текст ошибки в случае, если status == fail"
},
"reminder": {
"type": "object",
"description": "Параметры созданного напоминания",
"properties": {
"id": {
"type": "string",
"description": "Идентификатор напоминания."
},
"cron": {
"type": "string",
"description": "Описание периодичности напоминания. Здесь будет передано человекочитаемое описание переодичности напоминания. Если поле отсутствует, то у напоминания нет периодичности (единоразовое)."
},
"title": {
"type": "string",
"description": "Название напоминания, о чем надо напомнить."
},
"devices": {
"type": "array",
"description": "Словарь устройств, к которым привязаны напоминания",
"items": {
"type": "string",
"description": "Название устройства"
}
},
"reminderTime": {
"type": "string",
"description": "Дата и время старта напоминания."
},
"createdAt": {
"type": "string",
"description": "Дата и время создания напоминания."
}
}
}
},
"required": [
"status"
]
}
}
Валидация описания функции
Проверить описание функции на соответствие формату GigaChat API можно с помощью метода POST /functions/validate.
В ответ на запрос метод возвращает список ошибок и предупреждений. Ошибки нужно исправить обязательно, а исправление предупреждений позволит модели точнее обращаться к функции и повысит качество сгенерированных аргументов.
Запрос
curl --location 'https://gigachat.devices.sberbank.ru/api/v1/functions/validate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <токен_доступа>' \
--data '{
"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",
"format"
]
}
}'
Ответ
{
"status": 200,
"message": "Function is valid",
"json_ai_rules_version": "1.0.5",
"warnings": [
{
"description": "Value is null but should be object",
"schema_location": "#/properties/return_parameters"
},
{
"description": "Value is null but should be array",
"schema_location": "#/properties/few_shot_examples"
}
]
}
Примеры описания функций
При описании функции уделяйте внимание подробному описанию структуры входных и выходных данных, не забывайте указывать краткое описание самой функции и примеры ее использования.
Ниже представлены несколько примеров, на которые можно ориентироваться при описании собственных функций.
{
"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": "Санкт-Петербург"
}
}
]
}
{
"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": "комедия"
}
}
]
}