Работа с функциями
Функции — внешние инструменты (фрагменты кода), к которым могут обращаться модели 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": "Санкт-Петербург"
}
}
]
}