ym88659208ym87991671
Работа с функциями | Документация для разработчиков

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

Обновлено 24 апреля 2024

Функции позволяют расширить функциональность GigaChat с помощью использования сторонних инструментов.

GigaChat поддерживает два вида функций:

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

Для доступа к модели с поддержкой функций в поле "model" передавайте GigaChat-Pro, GigaChat-preview или GigaChat-Plus-preview.

Подробнее о моделях — в разделе Модели GigaChat.

Для работы с функциями используется запрос POST /chat/completions. А именно — необязательное поле function_call, которое задает режим работы с функциями и может принимать значения:

  • "none" — режим работы по умолчанию.

    Если запрос не содержит поля function_call или значение поля — none, модель не будет вызывать функции (в том числе встроенные), а просто сгенерирует ответ в соотвествии с полученными сообщениями.

  • "auto" — в зависимости от содержимого запроса, модель решает что нужно сделать: вызывать встроенные функции, сгенерировать аргументы для исполнения пользовательской функции или просто сгенерировать сообщение.

    Модель вызывает встроенные функции, только если отсутствует массив functions с описанием пользовательских функций.

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

  • {"name": "название_функции"} — принудительная генерация аргументов для указанной функции. Вы можете явно задать часть аргументов с помощью объекта partial_arguments. Остальные аргументы для вызова функции модель сгенерирует самостоятельно.

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

Ниже, на примере функции прогноза погоды, показано как работать с пользовательскими функциями с помощью GigaChat.

Работа с пользовательскими функциями

Функция, использованная для примера, возвращает данные о температуре в зависимости от аргументов, полученных на входе:

  • места, для которого запрашивается погода;
  • единиц измерения температуры;
  • периода в днях, которому должны соответствовать данные о температуре.

Описание функции

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

{
    "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, которые возвращает функция.
{
    "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 могут генерировать аргументы для вызова функций в автоматическом или в принудительном режиме.

Автоматически

В автоматическом режиме модель анализирует полученные сообщения (массив messages) и сама решает нужно использовать функции или нет.

Для работы в автоматическом режиме передавайте в запросе поле "function_call": "auto":

{
    "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"
                ]
            }
        }
    ],
}

При этом работа модели зависит от того содержит массив functions описание пользовательских функций или нет:

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

Принудительно

Если вы хотите, чтобы модель обязательно сгенерировала аргументы для определенной функции, передайте ее название в поле function_call.name.

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

{
    "model": "GigaChat",
    "messages": [
        {
            "role": "user",
            "content": "Погода в Москве на три дня"
        }
    ],
    "function_call": {
        "name": "weather_forecast",
        "partial_arguments": {
            "format": "celsius"
        }
    },
    "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.partial_arguments вы можете передать значения аргументов, которые генерировать не нужно.

Ответ модели

Когда модель решает, что нужно исполнить пользовательскую функцию, она возвращает ответ с результатом "finish_reason": "function_call". Сгенерированные аргументы для вызова вашей функции передаются в объекте message.function_call:

{
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "",
                "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"
}

Передача ответа функции в модель

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

Для этого используйте сообщение с ролью function в контексте диалога (массив messages):

{
    "model": "GigaChat",
    "messages": [
        {
            "role": "user",
            "content": "Какая погода в Москве сегодня?"
        },
        {
            "role": "assistant",
            "content": "",
            "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":{},"finish_reason":"function_call","index":0}],"created":1698850241,"model":"GigaChat","object":"chat.completion","usage":{"completion_tokens":1,"prompt_tokens":0,"total_tokens":1}}
  
data: [DONE]

Вызов встроенных функций

GigaChat поддерживает встроенные функции, например, для генерации изображений. Встроенные функции вызываются только в автоматическом режиме ("function_call": "auto") на основе запроса пользователя.

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

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

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": "Нарисуй корову"
    }
  ],
  "function_call": "auto",
}'

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

{
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "Вот что у меня получилось:<img \src="7wy0e9934sbjc09snz40c2gf1mej42ra0r00d8yz4d47r0adb17281t3096qpnamb4eqc1t3bd7qj1jman5q2mtzawfqrmgtbd7dv2bx54" func:"true"/> ",
                "data_for_context": [
                    {
                        "role": "assistant",
                            "content": "Вот что у меня получилось: ",
                            "function_call": {
                                "name": "text2image",
                                "arguments": {
                                    "query":
                                    "Корова"
                                    }
                            }
                    },
                    {
                        "role": "function",
                        "content": "{\"status\": \"success\"}"
                    },
                    {
                        "role": "assistant",
                        "content": ""
                    }
                ]
                 
            },
            "index": 0,
            "finish_reason": "stop"
        }
    ],
    "created": 1699620229,
    "model": "GigaChat",
    "usage": {
        "prompt_tokens": 195,
        "completion_tokens": 2,
        "total_tokens": 197
    },
    "object": "chat.completion"
}

Массив data_for_context содержит сообщения для работы модели в правильном контексте.

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

Для сохранения контекста после вызова встроенных функций, передавайте массив data_for_context в запросе в сообщениях с ролью assistant:

{
    "messages": [
        {
            "role": "user",
            "content": "Нарисуй корову"
        },
        {
            "role": "assistant",
            "content": "Вот что у меня получилось:<img src=\"7wy0e9934sbjc09snz40c2gf1mej42ra0r00d8yz4d47r0adb17281t3096qpnamb4eqc1t3bd7qj1jman5q2mtzawfqrmgtbd7dv2bx54\" fuse:\"true\"/>",
            "data_for_context": [
                {
                    "role": "assistant",
                    "content": "Вот что у меня получилось: ",
                    "function_call": {
                        "name": "text2image",
                        "arguments": {
                            "query": "Корова"
                            }
                    }
                },
                {
                    "role": "function",
                    "content": "{\"status\": \"success\"}"
                },
                {
                    "role": "assistant",
                    "content": ""
                }
            ]
        },
        {
            "role": "user",
            "content": "Дорисуй ей крылья"
        }
    ],
    "model": "GigaChat"
}

Потоковая передача токенов

Работа встроенных функций может занимать продолжительное время. Вы можете обрабатывать ответ модели по мере его генерации с помощью потоковой передачи токенов (параметр запроса "stream": true).

Пример запроса:

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": "Нарисуй корову"
    }
  ],
  "function_call": "auto",
  "stream": true,
}'

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

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

{
    "choices":
    [
        {
            "delta":
            {
                "content": "ready estimation seconds: 100",
                "role": "function_in_progress"
            },
            "index": 0
        }
    ]
}

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

ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.
Документация
SberJazzSaluteSpeechSaluteBotВся документация
Наши продукты
Витрина технологийБаза знанийСтань частью IT-команды
Юридические документы
Политика конфиденциальности Политика обработки данныхВсе соглашения и политики
© 1997–2024 ПАО СберБанк. Генеральная лицензия на осуществление банковских операций от 11 августа 2015 года. Регистрационный номер — 1481