Работа с функциями

Обновлено 14 апреля 2025

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

Несколько примеров функций:

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

Функции значительно повышают возможности языковых моделей, давая им возможности:

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

Функции — ключевой элемент для построения сложных решений с применением LLM, таких, как AI-агенты и ассистенты.

Все модели GigaChat для генерации поддерживают два вида функций:

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

Для работы с функциями используется запрос POST /chat/completions.

Модели обращаются к функциям, если в запросе, в массиве functions, есть описание пользовательских функций или указаны названия встроенных функций. При этом поле "function_call": "auto" может отсутствовать.

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

Вы также можете запретить модели обращаться к функциям, если передадите поле "function_call": "none". В этом случае модель не будет пытаться вызвать встроенные функции или функции, описанные в массиве functions.

На примере функции прогноза погоды ниже, мы показали, как работать с пользовательскими функциями с помощью 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 поддерживает встроенные функции, например, для генерации изображений. Встроенные функции вызываются на основе промпта пользователя, когда запрос содержит имена в массиве functions или передано поле "function_call": "auto".

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

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

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",
}'

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
    }
}

При этом контекст выполнения функции, который нужен для качественной работы модели, сохраняется с помощью идентификатора 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)

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

content='<img src="b62726bb-0cf5-4980-a8c4-70f3e4a6cc9b" fuse="true"/> вот рисунок розового кота.' additional_kwargs={'image_uuid': 'b62726bb-0cf5-4980-a8c4-70f3e4a6cc9b', 'postfix_message': ' вот рисунок розового кота.'} response_metadata={'x_headers': {'x-request-id': '4c723683-053d-4568-84cc-6cf1307f2742', 'x-session-id': 'f1f874cb-4d29-4ae1-9d5b-b17b70ffa86f', 'x-client-id': None}} id='4c723683-053d-4568-84cc-6cf1307f2742'
content='' additional_kwargs={} response_metadata={'finish_reason': 'stop'} id='4c723683-053d-4568-84cc-6cf1307f2742'

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

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

POST /chat/completions

Описание запроса на генерацию

Генерация изображений

Создание изображений в формате JPG с помощью встроенной функции

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

Работа с историей чата в GigaChat