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

gRPC API

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

Для обмена данными с сервисом GigaChat вы можете использовать gRPC-протокол. Подробнее о нем читайте в официальной документации.

Совершать запросы по протоколу gRPC удобно, если нужно:

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

Адрес для передачи запросов по протоколу gRPC:

gigachat.devices.sberbank.ru

Для работы с API используйте proto-файл.

gigachatv1.proto
syntax = "proto3";

package gigachat.v1;

option go_package = "./;protocol";

// Возвращает ответ модели на сообщение в формате ChatRequest
service ChatService {
// Возврат ответа одним фрагментов
rpc Chat (ChatRequest) returns (ChatResponse);
// Потоковая передача фрагментов ответа
rpc ChatStream (ChatRequest) returns (stream ChatResponse);
}

// Сообщение, на которое ответит модель
message ChatRequest {
// Параметры сообщения
ChatOptions options = 1;
// [Модель](https://developers.sber.ru/docs/ru/gigachat/models), которая будет генерировать ответ.
string model = 2;
// Массив сообщений. Передавайте сообщения с ролями user и assistant, чтобы сохранить контекст разговора с моделью.
repeated Message messages = 3;
}

// Параметры запроса, которые учитываются при генерировании ответа
message ChatOptions {
reserved 3;
/**
* Температура выборки. Значение температуры должно быть больше ноля. Чем выше значение, тем более случайным будет ответ модели. При значениях температуры больше двух, набор токенов в ответе модели может отличаться избыточной случайностью.
* Значение по умолчанию зависит от выбранной модели (поле `model`) и может изменяться с обновлениями модели.
*/
optional float temperature = 1;
/**
* Параметр используется как альтернатива температуре (поле `temperature`). Задает вероятностную массу токенов, которые должна учитывать модель.
* Так, если передать значение 0.1, модель будет учитывать только токены, чья вероятностная масса входит в верхние 10%.
* Значение по умолчанию зависит от выбранной модели (поле `model`) и может изменяться с обновлениями модели.
* Значение изменяется в диапазоне от 0 до 1 включительно.
*/
optional float top_p = 2;
// Максимальное количество токенов, которые будут использованы для создания ответов. По умолчанию используется 2048 токенов.
optional int32 max_tokens = 4;
/**
* Количество повторений слов. Должно быть больше ноля. Возможные значения:
* - При значении от 0 до 1 модель повторять уже использованные слова.
* - Значение 1.0 — нейтральное значение.
* - При значении больше 1 модель будет стараться не повторять слова.
* Значение по умолчанию зависит от выбранной модели (поле `model`) и может изменяться с обновлениями модели.
*/
optional float repetition_penalty = 5;
/**
* Параметр потокового режима (`"stream": "true"`).
* Задает минимальный интервал в секундах, который проходит между отправкой токенов.
* Например, если указать `1`, сообщения будут приходить каждую секунду, но размер каждого из них будет больше, так как за секунду накапливается много токенов.
* По умолчанию 0.
*/
optional float update_interval = 6;
repeated string flags = 7;
/**
* Поле, которое отвечает за то, как GigaChat будет [работать с функциями](/ru/gigachat/api/function-calling). Может быть строкой или объектом.
*
* Возможные режимы работы функций определяются в FunctionCallPolicy
*/
FunctionCallPolicy function_call = 8;
// Массив с описанием пользовательских функций.
repeated Function functions = 9;
}

// Режимы работы пользовательских функций
message FunctionCallPolicy {
// Перечисление возможных режимов вызовов функций.
// В зависимости от содержимого запроса, модель решает сгенерировать сообщение или вызвать функцию. Модель вызывает встроенные функции, если отсутствует массив `functions` с описанием пользовательских функций.
enum Mode {
undefined = 0;
// Если запрос содержит `"function_call": "auto"` и массив `functions` с описанием пользовательских функций, модель будет генерировать аргументы для описанных функций и не сможет вызвать встроенные функции независимо от содержимого запроса;
auto = 1;
// Режим работы по умолчанию. Если запрос не содержит массив функций `functions` или значение поля — `none`, GigaChat не вызовет функции, а просто сгенерирует ответ в соответствии с полученными сообщениями.
none = 2;
}
// Выбранный режим работы функции
Mode mode = 1;
}

// Описание пользовательской функции
message Function {
// Название пользовательской функции, для которой будут сгенерированы аргументы
string name = 1;
// Текстовое описание функции
string description = 2;
// Валидный JSON-объект с набором пар ключ-значение, которые описывают аргументы функции
string parameters = 3;
// Массив примеров работы функции в виде объектами с парами `запрос_пользователя`-`параметры_функции`, которые будут служить модели примерами ожидаемого результата.
repeated AnyExample few_shot_examples = 4;
// JSON-объект с описанием параметров, которые может вернуть ваша функция
optional string return_parameters = 5;
}

// Описание примера работы функции
message AnyExample {
// Запрос пользователя
string request = 1;
// Массив примеров заполнения параметров пользовательской функции
Params params = 2;
}

// Массив параметров пользовательской функции
message Params {
// Параметры функции, представленные объектами с парами `название_параметра`-`значение_параметра`, которые будут служить модели примерами ожидаемого результата.
repeated Pair pairs = 1;
}

// Параметры фукнции, сгенерированные моделью в формате ключ-значение.
message Pair {
// Название параметра
string key = 1;
// Значение параметра
string value = 2;
}


// Описывает сообщение, которое можно передавать в запросе
message Message {
reserved 3,4;
/**
* Роль автора сообщения:
* - `system` — системный промпт, который задает роль модели, например, должна модель отвечать как академик или как школьник;
* - `assistant` — ответ модели;
* - `user` — сообщение пользователя;
* - `function` — сообщение с результатом работы [пользовательской функции](/ru/gigachat/api/function-calling#rabota-s-sobstvennymi-funktsiyami). В сообщении с этой ролью передавайте в поле `content` валидный JSON-объект с результатами работы функции.
* Для сохранения контекста диалога с пользователем передайте несколько сообщений. Подробнее читайте в разделе [Работа с историей чата](/ru/gigachat/api/keeping-context).
*/
string role = 1;
/**
* Содержимое сообщения. Зависит от роли.
* Если поле передается в сообщении с ролью `function`, то в нем указывается валидный JSON-объект с результатом выполнения функции.
* В остальных случаях содержит либо системный промпт (сообщение с ролью `system`), либо текст сообщения пользователя или модели.
*/
string content = 2;
optional FunctionCall function_call = 5;
// Название функции, которое передается в сообщение с ролью `function`.
optional string function_name = 6;
bytes data_for_context = 7 [deprecated=true];
/**
* Идентификатор, который объединяет массив функций, переданных в запросе.
* Возвращается в ответе модели (сообщение с `"role": "assistant"`) если сообщение к модели содержало функции.
* Позволяет сохранить [контекст вызова функции](/ru/gigachat/api/function-calling#sohranenie-konteksta) и повысить качество работы модели.
* Для этого нужно передать идентификатор в запросе на генерацию в сообщении с ролью `assistant`.
*/
optional string functions_state_id = 8;
/**
* Массив идентификаторов файлов, которые нужно использовать при генерации.
*
* Идентификатор присваивается файлу при [загрузке в хранилище](/ru/gigachat/api/reference/rest/post-file). Посмотреть список файлов в хранилище можно с помощью метода [`GET /files`](/ru/gigachat/api/reference/rest/get-files).
*
* В одном запросе можно передать только одно изображение. В одной сессии можно передать до 10 изображений.
* Подробнее — в разделе [Генерация с помощью файлов изображений](/ru/gigachat/api/working-with-files)
*/
repeated string attachments = 11;
}

// Описание ответа модели
message ChatResponse {
reserved 5;
repeated Alternative alternatives = 1;
// Данные об использовании модели.
Usage usage = 2;
// Данные о модели
ModelInfo model_info = 3;
// Время ответа.
int64 timestamp = 4;
}

// Сгенерированное сообщение
message Alternative {
Message message = 1;
string finish_reason = 2;
int32 index = 3;
}

// Информация о количестве токенов, потраченных при генерации ответа
message Usage {
reserved 4;
// Количество токенов во входящем сообщении (роль `user`)
int32 prompt_tokens = 1;
// Количество токенов, сгенерированных моделью (роль `assistant`)
int32 completion_tokens = 2;
// Общее количество токенов
int32 total_tokens = 3;
}

// Информация о модели
message ModelInfo {
// Название модели
string name = 1;
// Версия модели. Подробнее о версиях — в разделе [Обновления моделей](/ru/gigachat/models/updates).
string version = 2;
}

// Сгенерированный моделью вызов функции.
message FunctionCall {
// Название функции
string name = 1;
//Аргументы функции. Содержат описание в JSON-формате.
string arguments = 2;
}

// Возвращает массив объектов с данными доступных моделей. Описание доступных моделей в разделе [Модели GigaChat](/ru/gigachat/models).
service ModelsService {
rpc ListModels (ListModelsRequest) returns (ListModelsResponse);
rpc RetrieveModel (RetrieveModelRequest) returns (RetrieveModelResponse);
}

// Запрос списка доступных моделей
message ListModelsRequest {}

// Список с описанием доступных моделей
message ListModelsResponse {
repeated Model models = 1;
}

// Описание модели
message Model {
// Название модели. Описание доступных моделей смотрите в разделе [Модели GigaChat](/ru/gigachat/models).
// При обращении к моделям в раннем доступе к названию модели нужно добавлять постфикс `-preview`. Например, `GigaChat-Pro-preview`.
string name = 1;
// Тип сущности в ответе, например, модель
string object = 2;
// Владелец модели
string owned_by = 3;
// Тип модели. При запросах на генерацию передается тип chat.
string type = 8;
}

// Запрос модели по конекретному имени
message RetrieveModelRequest {
string name = 1;
}

message RetrieveModelResponse {
Model model = 1;
}

Установка сертификатов для соединений gRPC

Для обмена сообщениями нужно использовать сертификаты НУЦ Минцифры.

Для установки сертификатов:

  1. Скачайте подходящие сертификаты с портала Госуслуг.

  2. Укажите путь к сертификату в переменной среды GRPC_DEFAULT_SSL_ROOTS_FILE_PATH:

    export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH="/путь-к-сертифкиату/cert.pem"

Авторизация

Запросы к сервису авторизуются с помощью токена доступа по протоколу OAuth 2.0. Токен доступа передается в заголовке authorization. Пример:

Bearer <токен доступа>

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

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

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

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

Ответ:

Array of objects (Model) [ items ]
object
string

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

{
  • "data": [
    ],
  • "object": "list"
}

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

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

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

model
string
Enum: "GigaChat" "GigaChat-Pro" "GigaChat-Max"

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

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

{
  • "model": "GigaChat"
}

Ответ:

id
string
Enum: "GigaChat" "GigaChat-Pro" "GigaChat-Max"

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

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

object
string

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

owned_by
string

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

type
any
Default: "chat"

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

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

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

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

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

model
required
string
Enum: "GigaChat" "GigaChat-Pro" "GigaChat-Max"

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

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

required
Array of objects (message) [ items ]

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

function_call_custom_function (object) or function_call_none_auto (string)

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

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

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

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

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

Array of objects[ items ]

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

temperature
number <float> > 0

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

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

top_p
number <float> [ 0 .. 1 ]

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

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

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

n
integer <int64> [ 1 .. 4 ]
Deprecated
Default: 1

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

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

stream
boolean
Default: false

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

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

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

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

max_tokens
integer <int32>

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

repetition_penalty
number <float>

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

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

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

update_interval
number
Default: 0

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

{
  • "model": "GigaChat",
  • "messages": [
    ],
  • "function_call": {
    },
  • "functions": [
    ],
  • "temperature": 0,
  • "top_p": 1,
  • "n": 1,
  • "stream": false,
  • "max_tokens": 0,
  • "repetition_penalty": 1,
  • "update_interval": 0
}

Ответ:

Array of objects (Choices) [ items ]

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

created
integer <unix timestamp>

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

model
string
Enum: "GigaChat" "GigaChat-Pro" "GigaChat-Max"

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

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

object (Usage)

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

object
string

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

{
  • "choices": [
    ],
  • "created": 1678878333,
  • "model": "GigaChat",
  • "usage": {
    },
  • "object": "chat.completion"
}

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

ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.