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
Для обмена сообщениями нужно использовать сертификаты НУЦ Минцифры.
Для установки сертификатов:
Скачайте подходящие сертификаты с портала Госуслуг.
Укажите путь к сертификату в переменной среды GRPC_DEFAULT_SSL_ROOTS_FILE_PATH:
export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH="/путь-к-сертифкиату/cert.pem"
Авторизация
Запросы к сервису авторизуются с помощью токена доступа по протоколу OAuth 2.0. Токен доступа передается в заголовке authorization.
Пример:
Bearer <токен доступа>
Подробно о том, как получить токен доступа читайте в разделах Быстрый старт для физических лиц и Быстрый старт для ИП и юридических лиц.
Описание методов
Получить список моделей
Возвращает массив объектов с данными доступных моделей. Выполняется с пустым телом запроса.
Ответ:
- Пример
- Описание
Получить модель
Возвращает объект с описанием указанной модели.
Параметры запроса:
Ответ:
- Пример
- Описание
Получить ответ модели
Возвращает ответ модели с учетом переданных сообщений.
Параметры запроса:
Ответ:
- Пример
- Описание