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

Обновлено 4 августа 2025

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

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

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

Общая схема работы с функциями.

Виды функций

Все модели GigaChat поддерживают встроенные и пользовательские функции.

• Пользовательские
• Встроенные

Пользовательские функции — это функции, реализованные в вашем приложении или стороннем сервисе.

Модели GigaChat могут генерировать аргументы для таких функций на основе их описания, полученного в массиве functions, в запросе POST /chat/completions. Используйте полученные аргументы для вызова функции, а результаты ее работы возвращайте в модель в сообщении с ролью function.

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

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

Запрос

curl --location 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <токен_доступа>' \
--data '{
    "model": "GigaChat-2-Pro",
    "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",
                    "num_days"
                ]
            },
            "return_parameters": {
                "type": "object",
                "properties": {
                    "status": {
                        "description": "Статус",
                        "enum": [
                            "success",
                            "fail"
                        ],
                        "type": "string"
                    },
                    "location": {
                        "type": "string",
                        "description": "Местоположение, например, название города"
                    },
                    "temperature": {
                        "type": "integer",
                        "description": "Температура для заданного местоположения"
                    },
                    "forecast": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Описание погодных условий"
                    },
                    "error": {
                        "type": "string",
                        "description": "Возвращается при возникновении ошибки. Содержит описание ошибки"
                    }
                }
            }
        }
    ]
}'

Ответ

{
    "choices": [
        {
            "message": {
                "content": "",
                "role": "assistant",
                "function_call": {
                    "name": "weather_forecast",
                    "arguments": {
                        "format": "celsius",
                        "location": "Манжерок",
                        "num_days": 10
                    }
                },
                "functions_state_id": "9b26f2cd-5efc-4005-a156-6914bdb89ad6"
            },
            "index": 0,
            "finish_reason": "function_call"
        }
    ],
    "created": 1748505280,
    "model": "GigaChat-2-Pro:2.0.28.2",
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 127,
        "completion_tokens": 46,
        "total_tokens": 173,
        "precached_prompt_tokens": 0
    }
}

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

Встроенные функции — это функции, которые исполняются внутри сервиса GigaChat. Так, если после авторизации на giga.chat , вы попросите модель нарисовать картинку, она обратится к встроенной функции text2image. Модель покажет итоговое изображение, созданное этой функцией.

Моделям доступны функции:

• text2image

  Генерация изображения в формате JPEG.

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

• get_file_content

  Использование текстовых документов для генерации ответа.

  Функцию можно использовать, если передать в запросе массив functions и/или "function_call": "auto", а также идентификаторы файлов в массиве attachments. Посмотреть доступные в хранилище файлы можно с помощью метода GET /files. Подробнее — в разделе Обработка файлов.

• text2model3d

  Генерация модели в формате FBX.

  Для обращения к функции генерации 3D-модели запрос должен содержать ее название в массиве functions, а также поле "function_call": "auto".

Пример генерации изображений с помощью встроенной функции text2image:

Запрос

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

Ответ

{
    "choices": [
        {
            "message": {
                "content": "<img src=\"65a46abd-b487-4981-b969-f01a0d7fce32\" fuse=\"true\"/> Вот такой розовый слон у меня получился!",
                "role": "assistant",
                "functions_state_id": "fda7bf8a-5c1c-4faa-a11a-3830d5a359de"
            },
            "index": 0,
            "finish_reason": "stop"
        }
    ],
    "created": 1748506451,
    "model": "GigaChat-2-Max:2.0.28.2",
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 632,
        "completion_tokens": 41,
        "total_tokens": 673,
        "precached_prompt_tokens": 0
    }
}

Подробнее — в разделе Обращение к встроенным функциям.