Получить ответ модели на сообщения

Обновлено 16 декабря 2024

POST

/chat/completions

Возвращает ответ модели, сгенерированный на основе переданных сообщений.

При генерации ответа модель может учитывать текстовые докуметы и изображения, сохраненные в хранилище. Для этого передайте список идентификаторов файлов в массиве attachments. В одном сообщении (объект в массиве messages) можно передать только одно изображение. В одном запросе можно передать до 10 изображений, независимо от количества сообщений.

При этом общий размер запроса должен быть меньше 20 Мб.

Например, ваш запрос может включать текст промпта и два идентификатора изображений, которые ссылаются на файлы размерами 6 Мб и 12 Мб.

Подробнее — в разделе Обработка файлов.

Запрос на генерацию можно передавать моделям в раннем доступе. Для обращения к ним используйте адрес https://gigachat-preview.devices.sberbank.ru/, а к названию модели, которое передается в поле model, добавьте постфикс -preview.

Запрос

Header Parameters

X-Client-ID

string

X-Request-ID

string

X-Session-ID

string

application/json

Body

model

string

required

Возможные значения: [GigaChat, GigaChat-Pro, GigaChat-Max]

Название модели. Описание доступных моделей смотрите в разделе Модели GigaChat.

При обращении к моделям в раннем доступе к названию модели нужно добавлять постфикс -preview. Например, GigaChat-Pro-preview.

messages object[]required

Массив сообщений, которыми пользователь обменивался с моделью.

Array [

role

string

Возможные значения: [system, user, assistant, function]

Роль автора сообщения:

system — системный промпт, который задает роль модели, например, должна модель отвечать как академик или как школьник;
assistant — ответ модели;
user — сообщение пользователя;
function — сообщение с результатом работы пользовательской функции. В сообщении с этой ролью передавайте в поле content валидный JSON-объект с результатами работы функции.

Для сохранения контекста диалога с пользователем передайте несколько сообщений. Подробнее читайте в разделе Работа с историей чата.

content

Содержимое сообщения. Зависит от роли.

Если поле передается в сообщении с ролью function, то в нем указывается валидный JSON-объект с аргументами функции, указанной в поле function_call.name.

В остальных случаях содержит либо системный промпт (сообщение с ролью system), либо текст сообщения пользователя или модели.

functions_state_id

uuidv4

Идентификатор, который объединяет массив функций, переданных в запросе. Возвращается в ответе модели (сообщение с "role": "assistant") при вызове встроенных или собственных функций. Позволяет сохранить контекст вызова функции и повысить качество работы модели. Для этого нужно передать идентификатор в запросе на генерацию в сообщении с ролью assistant.

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

Сейчас поле работает только при обращении к моделям в раннем доступе.

data_for_context object[]

Массив сообщений, описывающих работу встроенных функций.

Для сохранения контекста, обязательно передавайте массив в запросе на генерацию, в сообщении с ролью assistant.

Целевое решение для работы с функциями — поле functions_state_id.

Array [

]

attachments

string[]

Массив идентификаторов файлов, которые нужно использовать при генерации. Идентификатор присваивается файлу при загрузке в хранилище. Посмотреть список файлов в хранилище можно с помощью метода GET /files.

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

В одном сообщении (объект в массиве messages) можно передать только одно изображение. В одной сессии можно передать до 10 изображений.

При этом общий размер запроса должен быть меньше 20 Мб.

Подробнее — в разделе Обработка файлов

]

function_call object

Поле, которое отвечает за то, как GigaChat будет работать с функциями. Может быть строкой или объектом.

Возможные значения:

none — режим работы по умолчанию. Если запрос не содержит function_call или значение поля — none, GigaChat не вызовет функции, а просто сгенерирует ответ в соответствии с полученными сообщениями;
auto — в зависимости от содержимого запроса, модель решает сгенерировать сообщение или вызвать функцию. Модель вызывает встроенные функции, если отсутствует массив functions с описанием пользовательских функций. Если запрос содержит "function_call": "auto" и массив functions с описанием пользовательских функций, модель будет генерировать аргументы для описанных функций и не сможет вызвать встроенные функции независимо от содержимого запроса;
{"name": "название_функции"} — принудительная генерация аргументов для указанной функции. Вы можете явно задать часть аргументов с помощью объекта partial_arguments. Остальные аргументы модель сгенерирует самостоятельно. При принудительной генерации, массив functions обязан содержать объект с описанием указанной функции. В противном случае вернется ошибка.

oneOf

function_call_custom_function
function_call_none_auto

name

string

Название функции.

partial_arguments object

JSON-объект в котором вы можете явно задать некоторые аргументы указанной функции. Остальные аргументы модель сгенерирует самостоятельно.

string

Possible values: [auto, none]

Режим работы с функциями

functions object[]

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

Array [

name

string

required

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

description

string

Текстовое описание функции.

parameters objectrequired

Валидный JSON-объект с набором пар ключ-значение, которые описывают аргументы функции.

few_shot_examples object[]

Объекты с парами запрос_пользователя-параметры_функции, которые будут служить модели примерами ожидаемого результата.

Array [

request

string

required

Запрос пользователя.

params objectrequired

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

]

return_parameters object

JSON-объект с описанием параметров, которые может вернуть ваша функция.

]

temperature

float

Температура выборки. Значение температуры должно быть больше ноля. Чем выше значение, тем более случайным будет ответ модели. При значениях температуры больше двух, набор токенов в ответе модели может отличаться избыточной случайностью.

Значение по умолчанию зависит от выбранной модели (поле model) и может изменяться с обновлениями модели.

top_p

float

Возможные значения: >= 0 и <= 1

Параметр используется как альтернатива температуре (поле temperature). Задает вероятностную массу токенов, которые должна учитывать модель. Так, если передать значение 0.1, модель будет учитывать только токены, чья вероятностная масса входит в верхние 10%.

Значение по умолчанию зависит от выбранной модели (поле model) и может изменяться с обновлениями модели.

Значение изменяется в диапазоне от 0 до 1 включительно.

int64

deprecated

Возможные значения: >= 1 и <= 4

По умолчанию: 1

Количество вариантов ответов, которые нужно сгенерировать для каждого входного сообщения.

Количество вариантов может изменяться от одного до четырех. По умолчанию модель возвращает один вариант ответа.

stream

boolean

По умолчанию: false

Указывает что сообщения надо передавать по частям в потоке.

Сообщения передаются по протоколу SSE.

Поток завершается событием data: [DONE].

Подробнее читайте в разделе Потоковая генерация токенов.

max_tokens

int32

Максимальное количество токенов, которые будут использованы для создания ответов.

repetition_penalty

float

Количество повторений слов:

Значение 1.0 — нейтральное значение.
При значении больше 1 модель будет стараться не повторять слова.

Значение по умолчанию зависит от выбранной модели (поле model) и может изменяться с обновлениями модели.

update_interval

number

Параметр потокового режима ("stream": "true"). Задает минимальный интервал в секундах, который проходит между отправкой токенов. Например, если указать 1, сообщения будут приходить каждую секунду, но размер каждого из них будет больше, так как за секунду накапливается много токенов.

Ответы

application/json

Схема
Пример из схемы

Schema

choices object[]

Массив ответов модели.

Array [

message object

Сгенерированное сообщение.

role

string

Возможные значения: [assistant, function_in_progress]

Роль автора сообщения.

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

content

string

Содержимое сообщения, например, результат генерации.

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

created

unix timestamp

Передается в сообщениях с рольюfunction_in_progress. Содержит информацию о том, когда был создан фрагмент сообщения.

name

string

Название вызванной встроенной функции. Передается в сообщениях с рольюfunction_in_progress.

functions_state_id

uuidv4

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

Сейчас поле работает только при обращении к моделям в раннем доступе.

function_call object

name

string

Название функции.

arguments

object

Аргументы для вызова функции в виде пар ключ-значение.

data_for_context object[]

Массив сообщений, описывающих работу встроенных функций.

Для сохранения контекста, обязательно передавайте массив в запросе на генерацию, в сообщении с ролью assistant.

Целевое решение для работы с функциями — поле functions_state_id.

Array [

]

index

int32

Индекс сообщения в массиве, начиная с ноля.

finish_reason

string

Возможные значения: [stop, length, function_call, blacklist, error]

Причина завершения гипотезы. Возможные значения:

stop — модель закончила формировать гипотезу и вернула полный ответ;
length — достигнут лимит токенов в сообщении;
function_call — указывает, что при запросе была вызвана встроенная функция или сгенерированы аргументы для пользовательской функции;
blacklist — запрос попадает под тематические ограничения.
error — ответ модели содержит невалидные аргументы пользовательской функции.

]

created

unix timestamp

Дата и время создания ответа в формате unix timestamp.

model

string

Возможные значения: [GigaChat, GigaChat-Pro, GigaChat-Max]

Название модели. Описание доступных моделей смотрите в разделе Модели GigaChat.

usage object

Данные об использовании модели.

prompt_tokens

int32

Количество токенов во входящем сообщении (роль user).

completion_tokens

int32

Количество токенов, сгенерированных моделью (роль assistant).

total_tokens

int32

Общее количество токенов.

object

string

Название вызываемого метода.

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Здравствуйте! К сожалению, я не могу дать точный ответ на этот вопрос, так как это зависит от многих факторов. Однако обычно релиз новых функций и обновлений в GigaChat происходит постепенно и незаметно для пользователей. Рекомендую следить за новостями и обновлениями проекта в официальном сообществе GigaChat или на сайте разработчиков.",
        "created": 1625284800,
        "name": "text2image",
        "functions_state_id": "77d3fb14-457a-46ba-937e-8d856156d003",
        "function_call": {
          "name": "string",
          "arguments": {}
        },
        "data_for_context": [
          {}
        ]
      },
      "index": 0,
      "finish_reason": "stop"
    }
  ],
  "created": 1678878333,
  "model": "GigaChat",
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 68,
    "total_tokens": 86
  },
  "object": "chat.completion"
}

Ошибка авторизации.

application/json

Схема
Пример из схемы

Schema

status

integer

По умолчанию: 401

HTTP-код сообщения.

message

string

По умолчанию: Unauthorized

Описание ошибки.

{
  "status": 401,
  "message": "Unauthorized"
}

Указан неверный идентификатор модели.

Список доступных моделей и их идентификаторов — в разделе Модели GigaChat.

application/json

Схема
Пример из схемы

Schema

status

integer

По умолчанию: 404

HTTP-код сообщения.

message

string

По умолчанию: No such model

Описание ошибки.

{
  "status": 404,
  "message": "No such model"
}

Ошибка валидации параметров запроса. Проверьте названия полей и значения параметров.

application/json

Схема
Пример из схемы

Schema

status

integer

По умолчанию: 422

HTTP-код сообщения.

message

string

Описание ошибки.

{
  "status": 422,
  "message": "Invalid params: repetition_penalty must be in range (0, +inf)"
}

Слишком много запросов в единицу времени.

application/json

Схема
Пример из схемы

Schema

status

integer

По умолчанию: 429

HTTP-код сообщения.

message

string

По умолчанию: Too many requests

Описание ошибки.

{
  "status": 429,
  "message": "Too many requests"
}

Внутренняя ошибка сервера.

application/json

Схема
Пример из схемы

Schema

status

integer

По умолчанию: 500

HTTP-код сообщения.

message

string

По умолчанию: Internal Server Error

Описание ошибки.

{
  "status": 500,
  "message": "Internal Server Error"
}

Получить ответ модели на сообщения

Запрос﻿

Header Parameters

Body

Ответы﻿

Запрос

Ответы