Работа с функциями
Функции — внешние инструменты (фрагменты кода), к которым могут обращаться модели GigaChat для решения задач пользователей. Модель не исполняет функции, но самостоятельно принимает решение о том как, когда и с какими параметрами их следует вызвать. При принятии решения о вызове функции модель исходит из доступных знаний, данных текущего разговора и описания функции. После обращения к функции модель может обработать результат ее работы.
Несколько примеров функций:
- запрос на поиск информации в базе данных;
- поиск в интернете по запросу и параметрам;
- изменение статуса устройств умного дома;
- вычисление математической формулы;
- создание изображения по текстовому запросу с помощью сторонней нейронной сети.
Функции значительно повышают возможности языковых моделей, давая им возможности:
- получать и обрабатывать информацию из внешних источников;
- взаимодействовать с окружающей средой;
- обрабатывать результаты этого взаимодействия.
Функции — ключевой элемент для построения сложных решений с применением LLM, таких, как AI-агенты и ассистенты.
Все модели для генерации поддерживают два вида функций:
- пользовательские — функции, которые вы реализуете и исполняете самостоятельно. Модель автоматически определяет необходимость вызова функции на основе ее описания. Для таких функций модель может сгенерировать объект с данными в подходящем вам формате, после чего вы сможете использовать их для дальнейших преобразований;
- встроенные — функции, которые модель использует для выполнения различных задач, например, генерации изображений. Функции исполняются внутри сервиса GigaChat.
Для работы с функциями используется запрос POST /chat/completions
.
В зависимости от текста запроса, который предполагает использование функции, модель самостоятельно решает нужно ли использовать встроенную функцию (например, создание изображений) или сгенерировать аргументы для одной из пользовательских функций, описанных в массиве functions
.
Если массива нет или он пустой, модель сможет использовать только встроенные функции.
Примеры ответа модели в режиме работы по умолчанию.
- Без вызова
- Вызов функции
В этом примере, основываясь на сообщении пользователя, модель решила, что генерировать аргументы не нужно.
{
"model": "GigaChat-2-Max",
"messages": [
{
"role": "user",
"content": "расскажи в двух словах про Манжерок"
}
],
"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",
"format"
]
}
}
]
}
{
"choices": [
{
"message": {
"content": "Манжерок — живописная деревня на Алтае, известная своей природой и горнолыжным курортом.",
"role": "assistant",
"functions_state_id": "b4a6949c-b45d-4819-b1af-29bfd5473c06"
},
"index": 0,
"finish_reason": "stop"
}
],
"created": 1744802033,
"model": "GigaChat-2-Max:2.0.28.2",
"object": "chat.completion",
"usage": {
"prompt_tokens": 128,
"completion_tokens": 26,
"total_tokens": 154,
"precached_prompt_tokens": 0
}
}
Поля functions_state_id
и finish_reason
относятся к работе функций и могут возвращаться в ответе независимо от того, были сгенерированы аргументы или нет.
Например, при использовании автоматического режима использования функций "function_call": "auto"
.
В этом примере, основываясь на сообщении пользователя, модель решила, что нужно сгенерировать аргументы для функции weather_forecast
, описанной в массиве functions
.
{
"model": "GigaChat-2-Max",
"messages": [
{
"role": "user",
"content": "тепло ли в Манжероке"
}
],
"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",
"format"
]
}
}
]
}
{
"choices": [
{
"message": {
"content": "",
"role": "assistant",
"function_call": {
"name": "weather_forecast",
"arguments": {
"format": "celsius",
"location": "Манжерок"
}
},
"functions_state_id": "cd85b62a-c50d-4774-8065-64d9d6260713"
},
"index": 0,
"finish_reason": "function_call"
}
],
"created": 1744802404,
"model": "GigaChat-2-Max:2.0.28.2",
"object": "chat.completion",
"usage": {
"prompt_tokens": 125,
"completion_tokens": 36,
"total_tokens": 161,
"precached_prompt_tokens": 0
}
}
Вы также можете явно управлять режимом работы с функциями с помощью поля function_call
.
Поле может содержать значения:
-
"auto"
— в авторежиме модель, основываясь на тексте сообщений, решает нужно ли использовать одну из встроенных функций или сгенерировать аргументы для пользовательских функций, описанных в массивеfunctions
. При этом, если массив содержит описание хотя бы одной пользовательской функции, модель сможет вызвать встроенную функцию, только если ее название передано в массивеfunctions
;{
"function_call": "auto",
"functions": [
{
"name": "text2image"
},
{
"name": "weather_forecast",
"description": "Возвращает температуру на заданный период",
"parameters": {}
}
]
} -
"none"
— модель не будет вызывать встроенные функции или генерировать аргументы для пользовательских функций, а просто сгенерирует ответ в соответствии с полученными сообщениями; -
{"name": "название_функции"}
— принудительная генерация аргументов для указанной функции. При принудительной генерации аргументов для пользовательской функции ее описание нужно обязательно передавать в массивеfunctions
.
- Авторежим
- Запрет использования
- Принудительный вызов
Основываясь на полученном сообщении, модель решает, что генерировать аргументы или вызывать встроенные функции не нужно.
{
"model": "GigaChat-2-Max",
"messages": [
{
"role": "user",
"content": "Я слышал, что в Манжероке красиво"
}
],
"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",
"format"
]
}
}
]
}
{
"choices": [
{
"message": {
"content": "Манжерок — замечательное место! Расположенный в Республике Алтай, этот небольшой посёлок славится живописной природой и великолепными видами на Катунь и окрестности Телецкого озера. Здесь царит особая атмосфера гор и первозданной природы, привлекающая туристов круглый год.\n\n### Что стоит посмотреть?\n- **Гора Синюха**: Популярное туристическое направление рядом с посёлком. Высота около 1200 метров над уровнем моря, откуда открывается потрясающий вид на горы Алтая и долину Катуни.\n- **Катунская ГЭС**: Уникальное инженерное сооружение на реке Катунь. Особенно впечатляет во время сброса воды.\n- **Алтайский государственный природный заповедник**: Район вблизи посёлка богат флорой и фауной. Отличная возможность познакомиться с уникальной алтайской природой.\n- **Телецкое озеро**: Один из символов Алтая. До озера удобно добираться от Манжерока через перевал Чике-Таман.\n\n### Чем заняться?\n- Активный отдых (катание на лошадях, трекинг).\n- Рыбалка на реке Катунь.\n- Поход на гору Синюха и прогулка вдоль реки.\n- Посещение местных кафе и дегустация блюд алтайской кухни.\n\nПосещая Манжерок, вы получите незабываемые впечатления и зарядитесь энергией от удивительной красоты алтайских просторов.",
"role": "assistant",
"functions_state_id": "199d3db1-e59d-4077-9068-750975abe1d1"
},
"index": 0,
"finish_reason": "stop"
}
],
"created": 1744804169,
"model": "GigaChat-2-Max:2.0.28.2",
"object": "chat.completion",
"usage": {
"prompt_tokens": 15,
"completion_tokens": 285,
"total_tokens": 300,
"precached_prompt_tokens": 112
}
}
Модель не генерирует аргументы, несмотря на явное желание пользователя узнать температуру и наличие описания функции weather_forecast
.
{
"model": "GigaChat-2-Max",
"messages": [
{
"role": "user",
"content": "Какая температура в Манжероке"
}
],
"function_call": "none",
"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",
"format"
]
}
}
]
}
{
"choices": [
{
"message": {
"content": "У меня нет доступа к данным о текущей температуре в режиме реального времени. Для получения актуальной информации рекомендую воспользоваться специализированными погодными сервисами или приложениями.",
"role": "assistant"
},
"index": 0,
"finish_reason": "stop"
}
],
"created": 1744804304,
"model": "GigaChat-2-Max:2.0.28.2",
"object": "chat.completion",
"usage": {
"prompt_tokens": 19,
"completion_tokens": 31,
"total_tokens": 50,
"precached_prompt_tokens": 0
}
}
Модель генерирует аргументы для функции, хотя запрос пользователя не содержит явного намерения узнать температуру.
{
"model": "GigaChat-2-Max",
"messages": [
{
"role": "user",
"content": "Я слышал, что в Манжероке красиво"
}
],
"function_call": {
"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",
"format"
]
}
}
]
}
{
"choices": [
{
"message": {
"content": "",
"role": "assistant",
"function_call": {
"name": "weather_forecast",
"arguments": {
"format": "celsius",
"location": "Манжерок"
}
},
"functions_state_id": "b5ea59c4-b980-401c-995f-75175804dfcd"
},
"index": 0,
"finish_reason": "function_call"
}
],
"created": 1744804424,
"model": "GigaChat-2-Max:2.0.28.2",
"object": "chat.completion",
"usage": {
"prompt_tokens": 25,
"completion_tokens": 26,
"total_tokens": 51,
"precached_prompt_tokens": 112
}
}
На примере функции прогноза погоды ниже, мы показали, как работать с пользовательскими функциями с помощью GigaChat.
Работа с пользовательскими функциями
Функция, использованная для примера, возвращает данные о температуре в зависимости от аргументов, полученных на входе:
- места, для которого запрашивается погода;
- единиц измерения температуры;
- периода в днях, которому должны соответствовать данные о температуре.
Описание функции
Чтобы модель могла определить, что нужно исполнить пользовательскую функцию, а также могла сгенерировать для нее аргументы, подготовьте описание функции в формате JSON Schema.
Проверить описание функции на соответствие формату GigaChat API можно с помощью метода POST /functions/validate
.
{
"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, которые возвращает функция.
Пример описания блоков 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 значительно лучше работают с функциями, которые описаны согласно приведенным примерам. При описании функции уделяйте внимание подробному описанию структуры входных и выходных данных, не забывайте указывать краткое описание самой функции и примеры ее использования.
Представленные примеры описания функций используются в 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 могут использовать результаты работы одних функций для вызова других. О такой возможности нужно сообщать в описании соответствующих функций. В остальном они описываются так же, как и обычные функции. Функции, которые работают таким образом, называются составными.
Ниже — пример нескольких функций, в описании которых заданы инструкции для модели. Согласно этим инструкциям при недостатке данных модель должна самостоятельно вызвать соответствующую функцию, которая может дать недостающие данные.
Функция получения данных о напоминании
{
"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 могут генерировать аргументы для вызова функций в автоматическом режиме.
В этом режиме модель анализирует полученные сообщения (массив messages
) и сама решает нужно использовать функции или нет.
Д ля работы в автоматическом режиме достаточно передать в сообщение массив functions
с описанием функций:
{
"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"
]
}
}
],
}
Вы также можете передать поле "function_call": "auto"
и не передавать массив functions
или оставить его пустым.
В таком случае модель сможет обращаться только ко встроенным функциям.
Ответ модели
Когда модель решает, что нужно исполнить пользовательскую функцию, она возвращает ответ с результатом "finish_reason": "function_call"
.
Сгенерированные аргументы для вызова вашей функции передаются в объекте message.function_call
:
{
"choices": [
{
"message": {
"role": "assistant",
"content": "",
"functions_state_id": "77d3fb14-457a-46ba-937e-8d856156d003",
"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"
}
Значение поля "finish_reason": "error"
, сообщает о том, что ответ модели содержит невалидные аргументы функции.
Передача ответа функции в модель
После исполнения пользовательской функции со сгенерированными аргументами, передайте результат ее работы обратно в модель.
Для этого используйте сообщение с ролью function
в контексте диалога (массив messages
).
Поле content
должно содержать обернутый в строку валидный JSON-объект с результатом выполнения функции, имя которой указано в поле function_call.name
.
Пример:
{
"model": "GigaChat",
"messages": [
{
"role": "user",
"content": "Какая погода в Москве сегодня?"
},
{
"role": "assistant",
"content": "{\"temperature\": \"27\"}",
"functions_state_id": "77d3fb14-457a-46ba-937e-8d856156d003",
"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":{"content":"","functions_state_id":"77d3fb14-457a-46ba-937e-8d856156d003","created":1718801171,"model":"GigaChat","object":"chat.completion"}
data: [DONE]
Вызов встроенных функций
Встроенные функции вызываются на основе промпта пользователя. GigaChat поддерживает встроенные функции генерации изображений и 3D-моделей:
-
text2image
;Генерирует изображение в формате JPEG.
Для вызова функции генерации изображения запрос должен содержать поле
"function_call": "auto"
, а массив с описанием функцийfunctions
либо должен содержать название встроенной функции, либо отсутствовать в запросе или принимать значение null. -
text2model3d
.Генерирует модель в формате FBX.
Для вызова функции генерации 3D-модели запрос должен содержать поле
"function_call": "auto"
, а в массиве с описанием функцийfunctions
нужно обязательно передать название функции.
Сгенерированные файлы сохраняются в хранилище, а в ответе на запрос возвращается идентификатор файла, по которому его можно скачать с помощью метода GET /files/{file_id}/content
.
При обращении к встроенным функциям модель возвращает ответ с результатом "finish_reason": "stop"
.
Примеры запросов и ответов при вызове встроенных функций.
- Изображение
- 3D-модель
- GigaChat API
- Python
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",
"functions": [
{
"name": "text2image"
},
{
"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"
]
}
}
]
}'
- gigachat
- langchain-gigachat
from gigachat import GigaChat
from gigachat.models import Chat, Messages, MessagesRole
giga = GigaChat(credentials="ключ_авторизации", verify_ssl_certs=False)
payload = Chat(
messages=[Messages(role=MessagesRole.USER, content="Нарисуй космонавта верхом на лошади")],
function_call="auto",
)
# Запрос на создание изображения
print = giga.chat(payload)
from langchain_gigachat.chat_models import GigaChat
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
llm = GigaChat(
credentials="ключ_авторизации",
verify_ssl_certs=False,
)
# Метод `bind_tools(tools=[], tool_choice="auto")` сообщает модели, что нужно использовать встроенные функции.
llm = llm.bind_tools(tools=[], tool_choice="auto")
# Промпт для создания изображения
prompt = ChatPromptTemplate.from_messages(
[
(
"system",
"""Ты — Василий Кандинский.""",
),
("user", """{topic}"""),
]
)
# Цепочка для создания изобра жения
generate_image_chain = prompt | llm
response = generate_image_chain.invoke({"topic": "Нарисуй розового кота"})
print(response)
Пример ответа:
{
"choices": [
{
"message": {
"content": "Запускаю генерацию изображения. Ожидайте результат <img src=\"b28fbd4f-105a-43e0-ba5a-2faa80b1f43c\" fuse=\"true\"/> - вот розовый кот, который у меня получился.",
"role": "assistant",
"functions_state_id": "77d3fb14-457a-46ba-937e-8d856156d003"
},
"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
}
}
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": "user",
"content": "Сгенерируй 3D-модель шара"
}
],
"function_call": "auto",
"functions": [
{
"name": "text2model3d"
}
]
}'
Пример ответа:
{
"choices": [
{
"message": {
"content": "<div data-model-id=\"2dc37408-f70a-4225-8e0a-8da749ceffac\" fuse=\"true\"/> получилась такая 3D модель шара.",
"role": "assistant",
"functions_state_id": "7421eccb-f732-483b-9018-755233d3f3b7"
},
"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
}
}
При этом контекст выполнения функции, который нужен для качественной работы модели, сохраняется с помощью идентификатора functions_state_id
.
Идентификатор объединяет массив функций, переданных в запросе.
При работе в режиме потоковой передачи он передается в последнем фрагменте.
Сохранение контекста
Для сохранения контекста после вызова встроенных функций, передавайте поле functions_state_id
в запросе в сообщениях с ролью assistant
:
{
"messages": [
{
"role": "user",
"content": "нарисуй корову"
},
{
"content": "Добавил в очередь на генерацию изображения... <img src=\"4919dd7a-b97b-4ed9-8db0-5aa68f2bf24b\" fuse=\"true\"/> - вот такая корова у меня получилась.",
"role": "assistant",
"functions_state_id": "77d3fb14-457a-46ba-937e-8d856156d003"
},
{
"content": "а теперь нарисуй слона",
"role": "user"
}
],
"model": "GigaChat"
}
Потоковая передача токенов
Работа встроенных функций может занимать продолжительное время.
Вы можете обрабатывать ответ модели по мере его генерации с помощью потоковой передачи токенов (параметр запроса "stream": true
).
Пример запроса:
- GigaChat API
- Python
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-Pro",
"messages": [
{
"role": "system",
"content": "Ты — Василий Кандинский"
},
{
"role": "user",
"content": "Нарисуй розового кота"
}
],
"function_call": "auto",
"stream": true,
}'
Пример ответа:
data: {"choices":[{"delta":{"content":"осталось 00:11","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401362,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}
data: {"choices":[{"delta":{"content":"осталось 00:06","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401367,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}
data: {"choices":[{"delta":{"content":"осталось 00:03","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401370,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}
data: {"choices":[{"delta":{"content":"осталось 00:01","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401372,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}
data: {"choices":[{"delta":{"content":"осталось 00:01","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401373,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}
data: {"choices":[{"delta":{"content":"<img src=\"6fb0b045-e4c8-43b6-bd4d-06eb6cf267eb\" fuse=\"true\"/> вот иллюстрация Красной Шапочки.","role":"assistant"},"index":0}],"created":1733401374,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}
data: {"choices":[{"delta":{"content":"","functions_state_id":"1a7f916c-053b-4649-9c7d-0ce0f4a0f515"},"index":0,"finish_reason":"stop"}],"created":1733401374,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion","usage":{"prompt_tokens":24,"completion_tokens":48,"total_tokens":72,"precached_prompt_tokens":0}}
data: [DONE]
- gigachat
- langchain-gigachat
import asyncio
import time
from gigachat import GigaChat
from gigachat.models import Chat, Messages, MessagesRole
payload = Chat(
messages=[
Messages(
role=MessagesRole.SYSTEM,
content="Ты — Василий Кандинский.",
),
Messages(
role=MessagesRole.USER,
content="Нарисуй розового кота",
),
],
update_interval=0.1,
function_call="auto",
)
async def main():
async with GigaChat(credentials="ключ_авторизации", verify_ssl_certs=False) as giga:
async for chunk in giga.astream(payload):
print(time.time(), chunk, flush=True)
if __name__ == "__main__":
asyncio.run(main())
Пример ответа:
1738844827.437161 x_headers={'x-request-id': '732bef07-bbb6-4658-8739-5c79f0c53b13', 'x-session-id': '3a46eb04-eb73-4ed8-bd5e-3d106a8b32cd', 'x-client-id': None} choices=[ChoicesChunk(delta=MessagesChunk(role=<MessagesRole.ASSISTANT: 'assistant'>, content='<img src="7f1add5a-cf5e-4956-b2bc-2e113d220953" fuse="true"/> вот такой розовый кот у меня получился.', function_call=None), index=0, finish_reason=None)] created=1738844827 model='GigaChat:1.0.26.20' object_='chat.completion'
1738844827.437387 x_headers={'x-request-id': '732bef07-bbb6-4658-8739-5c79f0c53b13', 'x-session-id': '3a46eb04-eb73-4ed8-bd5e-3d106a8b32cd', 'x-client-id': None} choices=[ChoicesChunk(delta=MessagesChunk(role=None, content='', function_call=None), index=0, finish_reason='stop')] created=1738844827 model='GigaChat:1.0.26.20' object_='chat.completion'
from langchain_gigachat.chat_models import GigaChat
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
llm = GigaChat(
credentials="ключ_авторизации",
verify_ssl_certs=False,
)
# Метод `bind_tools(tools=[], tool_choice="auto")` сообщает модели, что нужно использовать встроенные функции.
llm = llm.bind_tools(tools=[], tool_choice="auto")
# Промпт для создания изображения
prompt = ChatPromptTemplate.from_messages(
[
(
"system",
"""Ты — Василий Кандинский.""",
),
("user", """{topic}"""),
]
)
# Цепочка для создания изобра жения
generate_image_chain = prompt | llm
for chunk in generate_image_chain.stream({"topic": "Нарисуй розового кота"}):
print(chunk)