gRPC API
Обновлено 26 марта 2025
gRPC-протокол — это протокол для обмена данными с сервисом GigaChat. Подробнее о нем — в официальной документации.
Преимущества 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 будет работать с функциями.
Может быть строкой или объектом.
* Возможные режимы работы функций определяются в 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` — сообщение с результатом работы пользовательской функции. В сообщении с этой ролью передавайте в поле `content` валидный JSON-объект с результатами работы функции.
* Для сохранения контекста диалога с пользователем передайте несколько сообщений. Подробнее читайте в разделе [Работа с историей чата](/ru/gigachat/guides/keeping-context).
*/
string role = 1;
/**
* Содержимое сообщения. Зависит от роли.
* Если поле передается в сообщении с ролью `function`, то в нем указывается валидный JSON-объект с результатом выполнения функции.
* В остальных случаях содержит либо системный промпт (сообщение с ролью `system`), либо текст сообщения пользователя или модели.
*/
string content = 2;
optional FunctionCall function_call = 5;
// Название функции, которое передается в сообщение с ролью `function`.
optional string function_name = 6;
/**
* Идентификатор, который объединяет массив функций, переданных в запросе.
* Возвращается в ответе модели (сообщение с `"role": "assistant"`) если сообщение к модели содержало функции.
* Позволяет сохранить контекст вызова функции и повысить качество работы модели.
* Для этого нужно передать идентификатор в запросе на генерацию в сообщении с ролью `assistant`.
*/
optional string functions_state_id = 8;
/**
* Массив идентификаторов файлов, которые нужно использовать при генерации.
* Идентификатор присваивается файлу при загрузке в хранилище. Посмотреть список файлов в хранилище можно с помощью метода `GET /files`.
* В одном запросе можно передать только одно изображение. В одной сессии можно передать до 10 изображений.
* Подробнее — в разделе [Генерация с помощью файлов изображений](/ru/gigachat/guides/images-generation).
*/
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;
}