gRPC API

Обновлено 19 февраля 2025

Для обмена данными с сервисом 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 будет работать с функциями. 
   Может быть строкой или объектом.
   *
   * Возможные режимы работы функций определяются в 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-объект с результатами работы функции.
   * Для сохранения контекста диалога с пользователем передайте несколько сообщений. Подробнее читайте в разделе Работа с историей чата.
   */
  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 изображений.
   * Подробнее — в разделе Генерация с помощью файлов изображений.
   */
  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;
  // Версия модели. Подробнее о версиях — в разделе Обновления моделей.
  string version = 2;
}

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

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

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

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

// Описание модели
message Model {
  // Название модели. Описание доступных моделей смотрите в разделе Модели GigaChat.
  // При обращении к моделям в раннем доступе к названию модели нужно добавлять постфикс `-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 <токен доступа>

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

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

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

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

Ответ:

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

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

data

object[]

Array [

string

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

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

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

object

string

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

owned_by

string

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

type

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

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

]

object

string

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

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

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

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

model

string

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

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

Ответ:

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

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

string

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

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

object

string

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

owned_by

string

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

type

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

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

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

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

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

model

string

required

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

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

messages

object[]

required

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

Array [

role

string

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

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

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

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

content

string

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

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

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

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

Possible values: [auto, none]

functions

object[]

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

Array [

name

string

required

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

description

string

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

parameters

object

required

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

object

few_shot_examples

object[]

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

Array [

request

string

required

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

params

object

required

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

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

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

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

usage

object

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

prompt_tokens

int32

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

completion_tokens

int32

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

total_tokens

int32

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

object

string

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

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

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

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

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

Авторизация﻿

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

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

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

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

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

Авторизация

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

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

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

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