Описание методов

Обновлено 21 марта 2025

На этой странице вы найдете описание методов gRPC API GigaChat и примеры ответов.

Получить список моделей

Возвращает массив объектов с данными доступных моделей. Выполняется с пустым телом запроса.

Ответ:

Пример
Описание

{
  "data": [
    {
      "id": "GigaChat",
      "object": "model",
      "owned_by": "salutedevices",
      "type": "chat"
    }
  ],
  "object": "list"
}

data object[]

Array [

string

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

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

object

string

Тип сущности в ответе, например, модель.

owned_by

string

Владелец модели

type

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

Тип модели. Значение chat указывает, что модель используется для генерации.

]

object

string

Тип сущности в ответе, например, список.

Получить модель

Возвращает объект с описанием указанной модели.

Параметры запроса:

model

string

Ответ:

Пример
Описание

{
  "id": "GigaChat",
  "object": "model",
  "owned_by": "salutedevices",
  "type": "chat"
}

string

object

string

Тип сущности в ответе, например, модель.

owned_by

string

Владелец модели

type

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

Тип модели. Значение chat указывает, что модель используется для генерации.

Получить ответ модели

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

Параметры запроса:

model

string

required

messages object[]required

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

Array [

role

string

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

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

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

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

content

string

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

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

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

Передвайте текст в кодировке UTF8. Это позволит снизить расход токенов при обработке сообщения.

functions_state_id

uuidv4

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

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

attachments

string[]

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

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

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

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

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

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

]

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-объект в котором вы можете явно задать некоторые аргументы указанной функции. Остальные аргументы модель сгенерирует самостоятельно.

object

string

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

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

functions object[]

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

Array [

name

string

required

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

description

string

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

parameters objectrequired

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

object

few_shot_examples object[]

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

Array [

request

string

required

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

params objectrequired

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

object

]

return_parameters object

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

object

]

temperature

float

Температура выборки. Чем выше значение, тем более случайным будет ответ модели. Если значение температуры находится в диапазоне от 0 до 0.001, параметры temperature и top_p будут сброшены в режим, обеспечивающий максимально детерменированный (стабильный) ответ модели. При значениях температуры больше двух, набор токенов в ответе модели может отличаться избыточной случайностью.

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

top_p

float

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

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

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

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

stream

boolean

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

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

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

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

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

max_tokens

int32

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

repetition_penalty

float

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

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

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

update_interval

number

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

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

Ответ:

Пример
Описание

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

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

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

function_call object

name

string

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

arguments

object

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

index

int32

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

finish_reason

string

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

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

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

]

created

unix timestamp

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

model

string

usage object

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

prompt_tokens

int32

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

completion_tokens

int32

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

precached_prompt_tokens

int32

Количество ранее закэшированных токенов, которые были использованы при обработке запроса. Кэшированные токены вычитаются из общего числа оплачиваемых токенов (поле total_tokens).

Модели GigaChat в течение некоторого времени сохраняют контекст запроса (историю сообщений массива messages, описание функций) с помощью кэширования токенов. Это позволяет повысить скорость ответа моделей и снизить стоимость работы с GigaChat API.

Для повышения вероятности использования сохраненных токенов используйте кэширование запросов.

Подробнее о подсчете токенов.

total_tokens

int32

Общее число токенов, подлежащих тарификации, после вычитания кэшированных токенов (поле precached_prompt_tokens).

object

string

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

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

Примеры использования

Примеры использования библиотеки в репозитории

Получить список моделей﻿

Получить модель﻿

Получить ответ модели﻿

Получить список моделей

Получить модель

Получить ответ модели